1 | Session handle | Input | Char(8) |
2 | Operation key | Input | Binary(4) |
3 | Operation variable | Input | Char(*) |
4 | Length of operation variable | Input | Binary(4) |
5 | Format name of operation variable | Input | Char(8) |
6 | Error code | I/O | Char(*) |
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.
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.
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.
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 cross-site mirroring |
18 | Resume cross-site mirroring |
19 | Write changes to disk |
20 | Detach ASP |
21 | Reattach ASP |
22 | Release ASP IO |
23 | Reset ASP IO |
24 | Define ASP IO |
25 | Reverse ASP |
26 | Connect to host |
27 | Disconnect from host |
28 | Change cross-site mirroring attributes |
The following is a description of each operation:
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.
If mirrored protection has already been resumed and this operation is called, a successful completion code will still be returned.
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.
The operation variable that is to be sent to the Start Disk Management Operation (QYASSDMO) API.
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.
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.
The structure in which to return error information. For the format of the structure, see Error code parameter.
The following shows the information sent for the DMOP0100 format. For detailed descriptions of the fields in the table, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | ASP number |
4 | 4 | BINARY(4) | ASP storage threshold |
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.
The following shows the information sent for the DMOP0200 format. For detailed descriptions of the fields in the table, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | ASP number |
4 | 4 | CHAR(1) | Balance disk units flag |
5 | 5 | CHAR(3) | Reserved |
8 | 8 | BINARY(4) | Offset to disk unit resource names |
12 | C | BINARY(4) | Number of disk unit resource names |
16 | 10 | BINARY(4) | Reserved (must be set to 0) |
NOTE: The following fields repeat the number of time specified in the Number of disk unit resource name records field. | |||
CHAR(10) | Disk unit resource name |
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.
Balance disk units flag. A boolean flag used to indicate if the ASP capacity balancing function is to be applied. Valid values are:
0 | Do not apply the ASP capacity balancing function |
1 | Apply the ASP capacity balancing function |
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.
The following shows the information sent for the DMOP0300 format. For detailed descriptions of the fields in the table, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | CHAR(10) | Disk unit resource name |
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.
The following shows the information sent for the DMOP0400 format. For detailed descriptions of the fields in the table, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Offset to disk unit resource names |
4 | 4 | BINARY(4) | Number of disk unit resource names |
8 | 8 | BINARY(4) | Reserved (must be set to 0) |
NOTE: The following fields repeat the number of time specified in the number of disk unit resource name records field. | |||
CHAR(10) | Disk unit resource name |
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.
The following shows the information sent for the DMOP0500 format. For detailed descriptions of the fields in the table, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | CHAR(10) | Resource name of disk unit to be replaced |
10 | A | CHAR(10) | Resource name of new disk unit |
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.
The following shows the information sent for the DMOP0600 format. For detailed descriptions of the fields in the table, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | CHAR(10) | Disk unit resource name |
10 | A | CHAR(4) | Tower number |
14 | E | CHAR(5) | Device position |
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.
The following shows the information sent for the DMOP0700 format. For detailed descriptions of the fields in the table, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Offset to ASP numbers |
4 | 4 | BINARY(4) | Number of ASP numbers |
8 | 8 | BINARY(4) | ASP operation option |
12 | C | BINARY(4) | Reserved (must be set to 0) |
NOTE: The following fields repeat the number of times specified in the number of ASP numbers field. | |||
BINARY(4) | ASP number |
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 and detach cross-site 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 and detach geographic mirroring copy. For suspend geographic mirroring, changes to data on the production copy are not to be tracked while geographic mirroring is suspended. For detach geographic mirroring copy, changes to the mirror copy are not to be tracked while the copy is detached. |
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.
The following shows the information sent for the DMOP0800 format. For detailed descriptions of the fields in the table, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Offset to ASP IO lists |
4 | 4 | BINARY(4) | Number of ASP IO lists |
8 | 8 | CHAR(10) | Cluster resource group name |
18 | 12 | CHAR(14) | Reserved |
NOTE: The following fields repeat the number of times specified in the number of ASP lists field. | |||
BINARY(4) | ASP number | ||
4 | 4 | BINARY(4) | Offset to ASP IOA resources |
8 | 8 | BINARY(4) | Number of ASP IOA resources |
12 | C | BINARY(4) | Reserved (must be set to 0) |
NOTE: The following fields repeat the number of times specified in the number of IO resources field. | |||
CHAR(10) | IOA resource name | ||
10 | A | CHAR(8) | Location |
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.
The following shows the information sent for the DMOP0900 format. For detailed descriptions of the fields in the table, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | CHAR(16) | Handle |
16 | 10 | CHAR(16) | User name |
32 | 20 | CHAR(16) | Password |
48 | 30 | BINARY(4) | Offset to internet addresses |
52 | 34 | BINARY(4) | Number of internet addresses |
56 | 38 | CHAR(8) | Reserved |
NOTE: The following fields repeat the number of times specified in the number of internet addresses field. | |||
CHAR(45) | Internet address |
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.
The following shows the information sent for the DMOP1000 format. For detailed descriptions of the fields in the table, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | CHAR(16) | Handle |
16 | 10 | BINARY(4) | Offset to options |
20 | 14 | BINARY(4) | Number of options |
24 | 18 | BINARY(4) | Offset to ranges |
28 | 1C | BINARY(4) | Number of ranges |
32 | 20 | CHAR(10) | Cluster resource group name |
42 | 2A | CHAR(8) | Cluster resource group site name |
50 | 32 | BINARY(4) | ASP number |
54 | 36 | CHAR(16) | TotalStorage® device |
70 | 46 | CHAR(8) | Location |
78 | 4E | CHAR(2) | Reserved |
80 | 50 | BINARY(4) | Offset to consistency group ranges |
84 | 54 | BINARY(4) | Number of consistency group ranges |
88 | 58 | CHAR(8) | Reserved |
NOTE: The following fields repeat the number of times specified in the number of options field. | |||
BINARY(4) | ASP operation option | ||
NOTE: The following fields repeat the number of times specified in the number of disks field. | |||
CHAR(4) | Start of LUN range | ||
4 | 4 | CHAR(4) | End of LUN range |
NOTE: The following fields repeat the number of times specified in the number of consistency groups field. | |||
CHAR(4) | Start of consistency group range | ||
4 | 4 | CHAR(4) | End of consistency group range |
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:
0 | No operation option exists. This is valid for all operations except suspend and detach 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 and detach geographic mirroring copy. For suspend geographic mirroring, changes to data on the production copy are not to be tracked while geographic mirroring is suspended. For detach geographic mirroring copy, changes to the mirror copy are not to be tracked while the copy is detached. |
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.
The following shows the information sent for the DMOP1100 format. For detailed descriptions of the fields in the table, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Offset to ASP attribute entries |
4 | 4 | BINARY(4) | Number of ASP attribute entries |
8 | 8 | BINARY(4) | Length of an ASP attribute entry |
NOTE: The following fields repeat the number of times specified in the number of ASP attribute entries field. | |||
0 | 0 | BINARY(4) | ASP number |
4 | 4 | BINARY(4) | Suspend timeout |
8 | 8 | BINARY(4) | Mirroring mode |
12 | C | BINARY(4) | Synchronization priority |
16 | 10 | BINARY(4) | Tracking space |
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. Valid values are:
-1 | The cross-site mirroring mode is not changed. |
1 | Use synchronous cross-site mirroring. |
2 | Use asynchronous cross-site mirroring. |
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 cross-site mirroring, Metro Mirror or Global Mirror before suspending due to lack of a response. Valid values are:
-1 | The suspend timeout is not changed. |
1 to 7200 | The number of seconds to wait before suspending. |
Synchronization priority. The geographic mirroring synchronization priority. Valid values are:
-1 | The synchronization priority is not changed. |
1 | Use low priority. |
2 | Use medium priority. |
3 | Use high priority. |
Tracking space. The percent of the maximum assignable tracking space to use. The maximum assignable tracking space is 2 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:
-1 | The tracking space percent is not changed. |
0 to 100 | The percent of the maximum assignable tracking space to reserve for tracking changes. |
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 disk 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 | Disk 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. |