Start Disk Management Operation (QYASSDMO) API


  Required Parameter Group:


  Default Public Authority: *USE

  Threadsafe: Yes

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

Before you use this API, a session handle must be obtained by starting a disk management session using the Start Disk Management Session (QYASSDMS) API. Subsequent QYASSDMS API calls pass this session handle as an input parameter.

Disk management operations that can be requested are:

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 must be authorized to the Service Disk Units function of the IBM® i operating system through System i™ 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 Disk 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:

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 zeros 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 cross-site mirroring
This operation is used to suspend cross-site mirroring of an ASP.

Resume cross-site mirroring
This operation is used to resume cross-site 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.

Detach ASP
This operation is used to detach an ASP target copy.

Reattach ASP
This operation is used to reattach an ASP copy.

Release ASP IO
This operation is used to release ASP's IO hardware. This causes the disk units under an IOA to disappear from the configuration and prevents them from being used for something other than their ultimate intended use.

Reset ASP IO
This operation is used to reset an ASP's IO hardware. It reloads the IOA's IOP and all hardware under the IOP. Either IPL or reset is required after a release operation.

Define ASP IO
This operation is used to define the IO hardware of one or more ASP's.

Reverse ASP
This operation is used to reverse the direction of an ASP copy operation.

Connect to host
This operation is used to connect to a host external storage unit.

Disconnect from host
This operation is used to disconnect from a host external storage unit.

Change cross-site mirroring attributes
This operation is used to cross-site mirroring attributes.

Remove IASP disk configuration information
This operation is used to remove IASP disk configuration information.

Delete IASP
This operation is used to delete an IASP.

Deconfigure geographic mirroring
This operation is used to deconfigure geographic mirroring.

Change IASP unit acceptance
This operation is used to change IASP unit acceptance.

Operation variable
INPUT; CHAR(*)

The operation variable that is to be sent to the Start Disk 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 Disk Management Operation (QYASSDMO) API. The DMOP0100, DMOP0200, DMOP0300, DMOP0400, DMOP0500, DMOP0600, DMOP0700, DMOP0800, DMOP0900, DMOP1000 and DMOP1100 formats are used by this API for the operation variable.

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 cross-site mirroring
Resume cross-site mirroring
Detach ASP
Reattach ASP
Change multiple connection unit
Write changes to disk
Remove IASP disk configuration information
Delete IASP
Deconfigure geographic mirroring
Change IASP unit acceptance

DMOP0800
Define ASP IO
Release ASP IO
Reset ASP IO

DMOP0900
Define ASP IO
Connect to host
Disconnect from host

DMOP1000
Define ASP IO
Reverse ASP

DMOP1100
Change cross-site mirroring attributes

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.


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 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.


DMOP0200 Format

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


Field Descriptions

ASP name. The resource name to be assigned to the IASP that is to be created or have disks added to it.

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 usage. Indicates which type of ASP to add disks added to. Valid values are:

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

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.

Encrypt disk units flag. A boolean flag used to indicate if the disk units being added to the ASP should be encrypted. Valid values are:

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

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

Primary ASP name. The resource name of the primary IASP for which a secondary IASP is to be created or have disks added to it.

Tracking resources. The maximum number of pages of assignable tracking space to use for tracking changes to the ASP while geographic mirroring is detached or suspended. If the number of pages is larger than the total number of pages of assignable tracking space, then the maximum number of pages of assignable tracking space will not be changed.

Reserved. The field is reserved and must be binary zeros.


DMOP0300 Format

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


Field Descriptions

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.


DMOP0400 Format

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


Field Descriptions

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 disk unit resource names. The number of Disk unit resource names specified in the Disk unit resource name array.

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

Reserved. The field is reserved and must be binary zeros.


DMOP0500 Format

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


Field Descriptions

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

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


DMOP0600 Format

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


Field Descriptions

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.

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.


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:

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

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

Reserved. The field is reserved and must be binary zeros.


DMOP0800 Format

The following shows the information sent for the DMOP0800 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.

Cluster resource group name. The name of the cluster resource group associated with the ASP IO.

IOA resource name. The resource name of an IOA.

Location. The name of the node that has the IO resource or *DEFAULT if there is a CRG associated with the IO.

Number of ASP IO lists. The number of ASP IO lists.

Number of ASP IOA resources. The number of ASP IOA resources for an ASP number.

Offset to ASP IO lists. The offset in bytes from the start of the operation variable to the first ASP IO list.

Offset to ASP IOA resources. The offset in bytes from the start of the operation variable to the first ASP IOA resource.

Reserved. The field is reserved and must be binary zeros.


DMOP0900 Format

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


Field Descriptions

Handle. A user specified and defined identifier to relate a DMOP1000 format to a DMOP0900 format. Any hexadecimal data can be specified.

Internet address. An IPv4 or IPv6 address.

Number of internet addresses. The number of internet addresses that follow. A maximum of two can be specified.

Offset to internet addresses. The offset in bytes from the start of the operational variable to the first internet address. A maximum of two can be specified.

Password. The password needed to signon to an external storage unit. The password is treated as hexadecimal data. The disconnect operation does not require that a password be specified.

Reserved. The field is reserved and must be binary zeros.

User name. The user name needed to signon to an external storage unit. The user name is treated as hexadecimal data.


DMOP1000 Format

The following shows the information sent for the DMOP1000 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. The option applies to every ASP that can be accessed using the specified IOAs. Valid values are:

Cluster resource group name. The name of the cluster resource group associated with the ASP IO.

Cluster resource group site name. The name of the cluster resource group site associated with the ASP IO.

End of consistency group range. The logical unit (LUN) number of the last LUN in a range that consists of consecutive LUN numbers to be used for the consistency group.

End of LUN range. The logical unit (LUN) number of the last LUN in a range that consists of consecutive LUN numbers.

Handle. An identifier to link a DMOP1000 format to a DMOP0900 format.

Location. The name of the node that owns an IOA device. If a cluster resource group is used to change the node on which the IOA device is located, *DEFAULT must be specified as the node name.

Number of options. The number of ASP operation options in the ASP operation option array.

Number of consistency group ranges. The number of LUN number ranges to be used for the consistency group.

Number of ranges. The number of LUN number ranges.

Offset to consistency group ranges. The offset in bytes from the start of the operation variable to the first LUN number range to be used for the consistency group.

Offset to options. The offset in bytes from the start of the operation variable to the first ASP operation option.

Offset to ranges. The offset in bytes from the start of the operation variable to the first LUN number range.

Reserved. The field is reserved and must be binary zeros.

Start of consistency group range. The LUN number of the first LUN in a range that consists of consecutive LUN numbers to be used for the consistency group.

Start of LUN range. The logical unit (LUN) number of the first LUN in a range that consists of consecutive LUN numbers.

TotalStorage device. The name of the TotalStorage device in which the LUNs can be found.


DMOP1100 Format

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


Field Descriptions

ASP number. A number that identifies an independent Auxiliary Storage Pool (ASP). Valid values range from 33 through 255.

Length of an ASP attribute entry. The length of each ASP attribute entry.

Mirroring mode. The cross-site mirroring mode. This refers to the way data is written to the target system after it arrives. Valid values are:

Number of ASP attribute entries. The number of ASP attribute entries.

Offset to ASP attribute entries. The offset in bytes from the start of the operation variable to the first ASP attribute entry.

Suspend timeout. The number of seconds to wait for a response when doing geographic mirroring before suspending due to lack of a response. Valid values are:

Synchronization priority. The geographic mirroring synchronization priority. Valid values are:

Tracking space. The percent of the maximum assignable tracking space to use. The maximum assignable tracking space is 1 percent of the total space within an independent ASP. For example, a 100 gigabyte independent ASP has a maximum tracking space of 1 gigabyte. A tracking space parameter value of 5 would specify that 5 percent of 1 gigabyte (50 megabytes) should be reserved for tracking changes. Valid values are:

Start of change Transmission delivery. The type of communication to the mirror system. Valid values are:

Transmission compression. Indicates whether transmitted data is compressed. Valid values are:


Error Messages



API introduced: V4R5

[ Back to top | Configuration APIs | APIs by category ]