Start DASD Management Operation (QYASSDMO) API

The Start DASD Management Operation (QYASSDMO) API performs various disk management operations as indicated by the Operation key input parameter.

A session handle must be obtained prior to using this API by starting a disk management session using the Start DASD Management Session (QYASSDMS) API. Subsequent QYASSDMS API calls pass this session handle as an input parameter.

Disk management operations that can be requested are:

• Change the storage threshold percentage of an ASP
• Add disk units to an ASP
• Suspend mirrored protection on a disk unit
• Resume mirrored protection on a disk unit
• Include a disk unit in device parity protection
• Rebuild data on a disk unit after a device parity fault
• Replace mirrored disk unit
• Start device parity protection on a new parity set
• Enable remote load source mirroring
• Disable remote load source mirroring
• Power off a disk unit
• Power on a disk unit
• Format a disk unit
• Clear a disk unit
• Scan surface of a disk unit
• Change multiple connection unit
• Suspend geographic mirroring
• Resume geographic mirroring
• Write changes to disk

Most operations require that an operation variable be specified. There are various operation formats associated with the operation that need to be placed in the operation variable. When an operation variable is required, the input parameters Length of operation variable and Format name of operation variable also need to be specified. If the operation does not need an operation variable to be supplied, then enter a value of zero in the Length of operation variable parameter and enter a value of all blanks for Format name of operation variable. When the parameter Length of operation variable is set to zero and the parameter Format name of operation variable is all blanks, the parameter operation variable is ignored.

Authorities and Locks

To use this API you must have *SERVICE special authority or be authorized to the Service Disk Units function of Operating System/400 through iSeries Navigator's Application Administration support. The Change Function Usage Information (QSYCHFUI) API, with a function ID of QIBM_QYAS_SERVICE_DISKMGMT, also can be used to change the list of users who are allowed to work with disk units.

Required Parameter Group

Session handle

INPUT; CHAR(8)

The unique ID that was returned to the client on a preceding Start DASD Management Session (QYASSDMS) API. The session handle contains arbitrary binary data and should not be interpreted as character data.

If the session handle is not used to perform an operation using this API or is not used to check the status of an operation using the QYASRDMS API within 5 minutes after a session is started or an operation has completed, the session of the associated handle will be ended and the associated handle will be invalidated if a call is made to start another disk management session.

Operation key

INPUT; BINARY(4)

An integer value indicating which disk management operation is to be performed. Valid operation key values are:

1	Change the storage threshold percentage of an ASP
2	Add disk units to an ASP
3	Suspend mirrored protection on a disk unit
4	Resume mirrored protection on a disk unit
5	Include a disk unit in device parity protection
6	Rebuild data on a disk unit after a device parity fault
7	Replace mirrored disk unit
8	Start device parity protection on a new parity set
9	Enable remote load source mirroring
10	Disable remote load source mirroring
11	Power off a disk unit
12	Power on a disk unit
13	Format a disk unit
14	Clear a disk unit
15	Scan surface of a disk unit
16	Change multiple connection unit
17	Suspend geographic mirroring
18	Resume geographic mirroring
19	Write changes to disk

The following is a description of each operation:

Change the storage threshold percentage of an ASP

The storage threshold for an ASP determines when the system warns you that the space allocated for the ASP is almost full. It specifies a percentage of used ASP storage space. This operation changes the storage threshold percentage.

Add disk units to an ASP

This operation allows you to add disk units to an ASP. If the ASP does not exist, it will be created. The ASP balancing function can be called optionally. The ASP balancing function improves disk performance by balancing disk utilization across all of the disk units in an ASP.

Suspend mirrored protection on a disk unit

When mirrored protection is configured for an ASP, this operation suspends mirrored protection on a disk unit in the ASP. This operation is required to replace a disk unit in an ASP that is mirrored protected.

Sometimes mirrored protection may be suspended automatically when a disk unit fails. In the situation where mirrored protection is already suspended and this operation is called, a successful completion code will still be returned.

Resume mirrored protection on a disk unit

This operation synchronizes data in a mirrored pair of disk units where mirrored protection has been suspended and then resumes mirrored protection.

If mirrored protection has already been resumed and this operation is called, a successful completion code will still be returned.

Include a disk unit in device parity protection

This operation includes an unconfigured disk unit in a device parity set. When attaching a new disk unit to an existing IOP which controls disk units that have device parity protection, the disk unit can be included in the device parity set.

Rebuild data on a disk unit after a device parity fault

After replacement of a failed disk unit in a device parity set, this operation rebuilds data that existed on the failed disk unit onto the new disk unit.

Replace a mirrored disk unit

When a disk unit in a mirrored pair has failed, it can be replaced using this operation.

A disk unit selected to replace the failed mirrored disk unit must satisfy all of the mirrored protection configuration rules and restrictions when it is paired with the remaining disk unit in the mirrored pair.

Start device parity protection on a new parity set

This operation starts device parity protection on a controller that has no configured disks.

Enable remote load source mirroring

This operation enables mirroring of the load source disk unit to a disk unit in a position that is not IPL capable.

Disable remote load source mirroring

This operation disables the function of mirroring of the load source disk unit to a disk unit in a slot which is not IPL capable.

Power off a disk unit

This operation powers off a disk unit. The bus, IOP, and controller also may be powered off, depending on the hardware configuration.

Power on a disk unit

This operation powers on a disk unit. The bus, IOP, and controller also may be powered on, depending on the hardware configuration.

Format a disk unit

This operation formats a disk unit.

Clear a disk unit

This operation clears a disk unit. The entire disk unit will have binary zeroes written to it.

Scan surface of a disk unit

This operation is used to check the disk surface for problems that could affect the data.

Change multiple connection unit

This operation is used to change the multiple connection unit identifier for disk units so that they are correct for the system that owns the disk units.

Suspend geographic mirroring

This operation is used to suspend geographic mirroring of an ASP.

Resume geographic mirroring

This operation is used to resume geographic mirroring of an ASP.

Write changes to disk

This operation is used to write to disk changed objects in a UDFS ASP or in an ASP group.

Operation variable

INPUT; CHAR(*)

The operation variable that is to be sent to the Start DASD Management Operation (QYASSDMO) API.

Length of operation variable

INPUT; BINARY(4)

The length of the operation variable, in bytes. The length of the operation variable must be equal to or greater than the length of the associated operation variable format.

Format name of operation variable

INPUT; CHAR(8)

The format of the information that is sent to the Start DASD Management Operation (QYASSDMO) API. The DMOP0100, DMOP0200, DMOP0300, DMOP0400, DMOP0500, DMOP0600 and DMOP0700 formats are used by this API for the operation variable. For detailed descriptions of the formats, see Format Descriptions.

A value of all blanks indicates that no format is used. The Length of operation variable parameter must be set to 0.

The following indicates the operations that use each of the operation formats.

All blanks (no format used)

Enable remote load source mirroring
Disable remote load source mirroring

DMOP0100

Change the storage threshold percentage of an ASP

DMOP0200

Add disk units to an ASP

DMOP0300

Suspend mirrored protection on a disk unit
Resume mirrored protection on a disk unit
Rebuild data on a disk unit after a device parity fault

DMOP0400

Include a disk unit in device parity protection
Format a disk unit
Clear a disk unit
Scan surface of a disk unit
Start device parity protection on a new parity set
Change multiple connection unit

DMOP0500

Replace mirrored disk unit

DMOP0600

Power off a disk unit
Power on a disk unit

DMOP0700

Suspend geographic mirroring
Resume geographic mirroring
Change multiple connection unit
Write changes to disk

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Format Descriptions

DMOP0100 Format

The following shows the information sent for the DMOP0100 format. For detailed descriptions of the fields in the table, see Field Descriptions.

DMOP0200 Format

The following shows the information sent for the DMOP0200 format. For detailed descriptions of the fields in the table, see Field Descriptions.

DMOP0300 Format

The following shows the information sent for the DMOP0300 format. For detailed descriptions of the fields in the table, see Field Descriptions.

DMOP0400 Format

The following shows the information sent for the DMOP0400 format. For detailed descriptions of the fields in the table, see Field Descriptions.

DMOP0500 Format

The following shows the information sent for the DMOP0500 format. For detailed descriptions of the fields in the table, see Field Descriptions.

DMOP0600 Format

The following shows the information sent for the DMOP0600 format. For detailed descriptions of the fields in the table, see Field Descriptions.

DMOP0700 Format

The following shows the information sent for the DMOP0700 format. For detailed descriptions of the fields in the table, see Field Descriptions.

Field Descriptions

ASP number. The number identifying the Auxiliary Storage Pool (ASP). Valid values range from 1 through 255. A value of 1 indicates the System ASP. Values 2 through 32 indicate basic user ASPs. Values 33 through 255 indicate independent ASPs.

ASP operation option. An option that is operation dependent. Valid values are:

0	No operation option exists. This is valid for all operations except suspend geographic mirroring.
1	Valid only for suspend geographic mirroring. Changes to data on the production copy are to be tracked while geographic mirroring is suspended. Tracking changes should result in less data being sent to the mirror copy when geographic mirroring is resumed.
2	Valid only for suspend geographic mirroring. Changes to data on the production copy are not to be tracked while geographic mirroring is suspended.

ASP storage threshold. A percentage of used ASP storage space that when reached will cause the system to issue a warning indicating the space allocated to an ASP is almost full. Valid values range from 1 to 100 percent.

Balance disk units flag. A boolean flag used to indicate if the ASP capacity balancing function is to be applied. Valid values are:

Device position. The physical location of a device within a tower. It is used with the Tower number field to identify the slot where a device resides. These two fields combined may be used as an alternative to the Disk unit resource name field for power on and power off operations. If these two fields are used as an alternative to the disk unit resource name, then the disk unit resource name field must be all blanks.

Disk unit resource name. A disk unit. The system resource manager assigns a resource name to every hardware device that is physically attached to the system. If the Tower number and the Device positions fields are to be used as an alternative to the disk unit resource name, then the Disk unit resource name field must be all blanks.

Number of ASP numbers. The quantity of ASP numbers specified in the ASP number array.

Number of disk unit resource names. The number of Disk unit resource names specified in the Disk unit resource name array.

Offset to ASP numbers. The offset in bytes from the start of the operation variable to the first ASP number.

Offset to disk unit resource names. The offset in bytes from the start of the operation variable to the first disk unit resource name.

Resource name of disk unit to be replaced. The disk unit resource name of the disk unit that is to be replaced with a nonconfigured disk unit.

Resource name of new disk unit. The disk unit resource name of the disk unit that is to replace a disk unit.

Tower number. Uniquely identifies a tower on the system. It is used with the Device position field to identify the slot in which a device resides. These two fields combined may be used as an alternative to the Disk unit resource name field for power on and power off operations. If these two fields are used as an alternative to the disk unit resource name, then the Disk unit resource name field must be all blanks.

Error Messages

Message ID	Error Message Text
CPF2277 E	User &1 not allowed to use function &2.
CPFBA20 E	Session handle not valid.
CPFBA22 E	A save storage operation is in progress.
CPFBA23 E	Operation failed.
CPFBA24 E	Operation in progress.
CPFBA25 E	A general DASD management error occurred.
CPFBA26 E	ASP event threshold out of range.
CPFBA27 E	Could not restore mirrored data.
CPFBA28 E	Could not resume mirroring on disk unit &1.
CPFBA29 E	Could not suspend mirroring on disk unit &1.
CPFBA2A E	Disk unit &1 not part of a mirrored set.
CPFBA2B E	Replacement disk unit &1 still active.
CPFBA2C E	Replacement disk unit &1 wrong type or model.
CPFBA2D E	Replacement disk unit &1 wrong capacity.
CPFBA2E E	Replacement disk unit &1 already configured.
CPFBA2F E	Disk unit &1 could not be powered off.
CPFBA30 E	Disk unit &1 could not be powered on.
CPFBA32 E	Disk unit &1 not found.
CPFBA33 E	Tower not found.
CPFBA34 E	Device position not found.
CPFBA35 E	Disk unit &1 configured.
CPFBA36 E	Add mirrored ASP failed - cannot pair units.
CPFBA37 E	Cannot add disk unit &1 - already configured.
CPFBA38 E	Cannot add unprotected disk unit &1 to protected ASP.
CPFBA39 E	Cannot add disk unit. This system has the maximum number of disk units allowed.
CPFBA3A E	Create new ASP failed.
CPFBA3B E	ASP number out of range.
CPFBA3C E	Cannot replace parity disk unit &1 - old disk unit &1 not in parity set.
CPFBA3D E	Cannot replace parity disk unit &1 - new disk unit in wrong position.
CPFBA3E E	Cannot replace parity disk unit &1 - new disk unit is wrong capacity.
CPFBA3F E	Cannot rebuild parity information.
CPFBA40 E	Disk unit &1 not part of parity set.
CPFBA41 E	Device parity set not operational.
CPFBA42 E	Disk unit &1 not eligible to be added to device parity protection.
CPFBA43 F	Required fields not provided.
CPFBA44 E	Operation key not valid.
CPFBA47 E	Session not active.
CPFBA48 E	Operation failed with unrecognized return code, &1.
CPFBA4A E	Format &1 for operation key &2 not valid.
CPFBA4B E	Length of operation variable not valid.
CPFBA4C E	Value for balance disk units flag not valid.
CPFBA4D E	ASP number not valid.
CPFBA4E E	ASP storage threshold value not valid.
CPFBA4F E	Offset to disk unit resource name array not valid.
CPFBA50 E	Number of disk unit resource names is out of range.
CPFBA51 E	Array of disk unit resource names was not provided.
CPFBA52 E	Wrong number of disk unit resource names.
CPFBA53 E	Unexpected authority validation error has occurred.
CPFBA54 E	CRG not in correct state for operation.
CPFBA55 E	Geographic mirroring operation failed.
CPFBA56 E	DASD management operation failed.
CPF3C21 E	Format name, &1, is not valid.
CPF3C36 E	Number of parameters, &1, entered for this API was not valid.
CPF3CF1 E	Error code parameter not valid.
CPF3CF2 E	Error(s) occurred during running of &1 API.