Retrieve ASP Copy Description (RTVASPCPYD)

Where allowed to run: Compiled CL program or interpreted REXX (*BPGM *IPGM *BREXX *IREXX)
Threadsafe: Yes

Parameters
Examples
Error messages

The Retrieve Auxiliary Storage Pool Copy Description (RTVASPCPYD) command is used to in a control language (CL) program or a REXX procedure to retrieve one or more of the values that are stored in and associated with an auxiliary storage pool copy description. Auxiliary storage pool copy descriptions are used to describe a single physical copy of an auxiliary storage pool (ASP). ASP copy descriptions are used by IBM PowerHA for i to manage geographic mirroring, Metro Mirror, Global Mirror and FlashCopy copies.

The parameter prompt text lists the minimum length for the variables next to the appropriate parameters you want to retrieve.

Restrictions: You must have use (*USE) authority to the ASP device description from which values are being retrieved.

Parameters

Keyword	Description	Choices	Notes
ASPCPY	ASP copy	Name, *ALL	Required, Positional 1
ASPCPYLST	CL var for ASPCPYLST (2572)	Character value	Optional
ASPDEV	CL var for ASPDEV (10)	Character value	Optional
CRG	CL var for CRG (10)	Character value	Optional
SITE	CL var for SITE (10)	Character value	Optional
STGHOST	CL var for STGHOST (106)	Character value	Optional
STGHOST2	CL var for STGHOST2 (106)	Character value	Optional
LOCATION	CL var for LOCATION (8)	Character value	Optional
LUNSTGDEV	CL var for LUNSTGDEV (16)	Character value	Optional
LUNSTGDEV2	CL var for LUNSTGDEV2 (16)	Character value	Optional
LUNRNG	CL var for LUNRNG (1036)	Character value	Optional
LUNRNG2	CL var for LUNRNG2 (1036)	Character value	Optional
LUNCGRNG	CL var for LUNCGRNG (1036)	Character value	Optional
LUNCGRNG2	CL var for LUNCGRNG2 (1036)	Character value	Optional
RCYDMN	CL var for RCYDMN (32767)	Character value	Optional
RCYDMN2	CL var for RCYDMN2 (32767)	Character value	Optional
SSNLST	CL var for SSNLST (142)	Character value	Optional

ASP copy (ASPCPY)

Specifies the name of the ASP copy description to be retrieved.

This is a required parameter.

*ALL: Returns a list of all ASP copy descriptions on the system. When ASPCPY(*ALL) is specified, the ASPCPYLST parameter must be specified, and only the ASPCPYLST parameter is returned.
name: Specify the name of the ASP copy description to be retrieved. When a specific ASP copy description is requested, the ASPCPYLST parameter is not valid.

CL var for ASPCPYLST (2572) (ASPCPYLST)

Specifies the name of the variable used to return the list of ASP copy descriptions. This parameter is only valid when ASPCPY(*ALL) is specified.

The ASP copy list contains a 12-byte header composed of the following, which is followed by zero or more copy description entries.

Position  Length                 Field
1         4-byte integer number  Offset from beginning of
                                 ASPCPYLST
                                 to first ASP copy
                                 description list entry
5         4-byte integer number  Length of each ASP copy
                                 description list entry
9         4-byte integer number  Number of ASP copy
                                 description entries

The following field repeats for each ASP copy description.

Position  Length                 Field
1         10 characters          ASP Copy Description name

CL var for ASPDEV (10) (ASPDEV)

Specifies the name of the variable used to return the name of the ASP device description associated with the ASP copy description.

CL var for CRG (10) (CRG)

Specifies the name of the variable used to return the cluster resource group (CRG) that identifies the nodes among which the copy can switch. Possible values are:

*NONE: No cluster resource group is associated with the copy.
name: The name of the cluster resource group.

CL var for SITE (10) (SITE)

Specifies the name of a variable that is used to retrieve the name of the cluster resource group (CRG) site that identifies the nodes among which the copy can switch. Possible values are:

*NONE: The copy will not exist on any of the nodes that form a CRG site.
name: The name of the cluster resource group site associated with this copy description.

CL var for STGHOST (106) (STGHOST)

Specifies the name of a variable that is used to retrieve the storage host information. The password will not be retrieved. The storage host information consists of the following data:

Position  Length                 Field
1         16 characters          User name
17        45 characters          Internet address 1
62        45 characters          Internet address 2

If any of the fields are not specified in the copy description, the value will contain blanks.

CL var for STGHOST2 (106) (STGHOST2)

Specifies the name of a variable that is used to retrieve the second storage host information. This field is only applicable for HyperSwap switchable LUNs. The password will not be retrieved. The storage host information consists of the following data:

Position  Length                 Field
1         16 characters          User name
17        45 characters          Internet address 1
62        45 characters          Internet address 2

If any of the fields are not specified in the copy description, the value will contain blanks.

CL var for LOCATION (8) (LOCATION)

Specifies the name of a variable that is used to retrieve the location that will own the independent ASP. Possible values are:

*DEFAULT: The CRG site identifies the node locations of the I/O adapter. This value will be returned for copy descriptions used with Geographic mirroring, Metro Mirror, or Global Mirror ASP sessions. This may also be returned for copy descriptions used as a FlashCopy source.
*NONE: The copy of the ASP will never be brought online on any system. This is only valid if the copy description will be used for a FlashCopy target.
name: Identifies the single cluster node that uses the I/O adapter. This value is only valid if the description will be used for a FlashCopy source or FlashCopy target.

CL var for LUNSTGDEV (16) (LUNSTGDEV)

Specifies the name of a variable that is used to retrieve the storage device name. Possible values are:

*NONE: The copy description is not associated with a storage device.
name: The name of the storage device associated with this copy description.

CL var for LUNSTGDEV2 (16) (LUNSTGDEV2)

Specifies the name of a variable that is used to retrieve the second storage device name. This field is only applicable for HyperSwap switchable LUNs. Possible values are:

*NONE: The copy description is not associated with a second storage device.
name: The name of the storage device associated with this copy description.

CL var for LUNRNG (1036) (LUNRNG)

Specifies the name of a variable that is used to retrieve the list of logical unit number (LUN) ranges. The LUNRNG contains a 12-byte header composed of the following, which is then followed by zero or more logical unit number range entries.

Position  Length                 Field
1         4-byte integer number  Offset from beginning of
                                 LUNRNG to the first logical
                                 unit number range entry
5         4-byte integer number  Length of each logical unit
                                 number range entry
9         4-byte integer number  Number of logical unit
                                 number range entries

The following fields repeat for each LUN range entry

Position  Length                 Field
1         4 characters           Start of LUN range
5         4 characters           End of LUN range

CL var for LUNRNG2 (1036) (LUNRNG2)

Specifies the name of a variable that is used to retrieve the list of logical unit number (LUN) ranges for STGHOST2. This field is only applicable for HyperSwap switchable LUNs. The LUNRNG contains a 12-byte header composed of the following, which is then followed by zero or more logical unit number range entries.

Position  Length                 Field
1         4-byte integer number  Offset from beginning of
                                 LUNRNG2 to the first logical
                                 unit number range entry
5         4-byte integer number  Length of each logical unit
                                 number range entry
9         4-byte integer number  Number of logical unit
                                 number range entries

The following fields repeat for each LUN range entry

Position  Length                 Field
1         4 characters           Start of LUN range
5         4 characters           End of LUN range

CL var for LUNCGRNG (1036) (LUNCGRNG)

Specifies the name of a variable that is used to retrieve the list of Consistency Group ranges. The LUNCGRNG contains a 12-byte header composed of the following, which is followed by zero or more logical unit number range entries.

Position  Length                 Field
1         4-byte integer number  Offset from beginning of
                                 LUNCGRNG to the first
                                 consistency group range entry
5         4-byte integer number  Length of each consistency
                                 group range entry
9         4-byte integer number  Number of consistency
                                 group range entries

The following fields repeat for each consistency group range entry

Position  Length                 Field
1         4 characters           Start of CG range
5         4 characters           End of CG range

CL var for LUNCGRNG2 (1036) (LUNCGRNG2)

Specifies the name of a variable that is used to retrieve the list of Consistency Group ranges for the second storage host. The LUNCGRNG contains a 12-byte header composed of the following, which is followed by zero or more logical unit number range entries.

Position  Length                 Field
1         4-byte integer number  Offset from beginning of
                                 LUNCGRNG2 to the first
                                 consistency group range entry
5         4-byte integer number  Length of each consistency
                                 group range entry
9         4-byte integer number  Number of consistency
                                 group range entries

The following fields repeat for each consistency group range entry

Position  Length                 Field
1         4 characters           Start of CG range
5         4 characters           End of CG range

CL var for RCYDMN (32767) (RCYDMN)

Specifies the name of a variable that is used to retrieve the connection information for each node in the CRG site recovery domain. This field is only applicable for switchable LUNs. The recovery domain contains an 8-byte header composed of the following, which is then followed by zero or more recovery domain entries. Each domain entry contains one or more host identifier entries.

Position  Length                 Field
1         4-byte integer number  Offset from beginning of
                                 RCYDMN to first recovery
                                 domain entry
5         4-byte integer number  Number of recovery domain
                                 entries

The following fields repeat for each recovery domain entry.

Position  Length                 Field
1         4-byte integer number  Length of this recovery
                                 domain entry
5         8 characters           Cluster node
13        4-byte integer number  Offset from beginning of
                                 this recovery domain
                                 entry to first host identifier
                                 information entry
17        4-byte integer number  Number of host identifier
                                 information entries
21        4-byte integer number  Length of host identifier
                                 information entry

The following fields repeat for each host identifier entry

Position  Length                 Field
1         4 characters           Host identifier
5         5 characters           Volume group

CL var for RCYDMN2 (32767) (RCYDMN2)

Specifies the name of a variable that is used to retrieve the connection information for each node in the CRG site recovery domain for the second storage host. This field is only applicable for HyperSwap switchable LUNs. The recovery domain contains an 8-byte header composed of the following, which is then followed by zero or more recovery domain entries. Each domain entry contains one or more host identifier entries.

Position  Length                 Field
1         4-byte integer number  Offset from beginning of
                                 RCYDMN2 to first recovery
                                 domain entry
5         4-byte integer number  Number of recovery domain
                                 entries

The following fields repeat for each recovery domain entry.

Position  Length                 Field
1         4-byte integer number  Length of this recovery
                                 domain entry
5         8 characters           Cluster node
13        4-byte integer number  Offset from beginning of
                                 this recovery domain
                                 entry to first host identifier
                                 information entry
17        4-byte integer number  Number of host identifier
                                 information entries
21        4-byte integer number  Length of host identifier
                                 information entry

The following fields repeat for each host identifier entry

Position  Length                 Field
1         4 characters           Host identifier
5         5 characters           Volume group

CL var for SSNLST (142) (SSNLST)

Specifies the name of a variable that is used to retrieve the list of sessions for the specified copy description. The session contains a 12-byte header composed of the following, which is then followed by zero or more session entries.

Position  Length                 Field
1         4-byte integer number  Offset from beginning of
                                 SSNLST to first session
                                 entry
5         4-byte integer number  Length of each session entry
5         4-byte integer number  Number of recovery domain
                                 entries

The following field repeats for each session entry.

Position  Length                 Field
1         10 characters          Session name

Examples

ADDASPCPYD  ASPCPY(COPY1)
            ASPDEV(IASP001)
            CRG(CRG)
            SITE(SITE1)
            STGHOST(stguser passw0rd ('1.2.3.4'))
            LOCATION(SITE1
            LUN('IBM.2107-1234567' ('10A0-10A1' '10B0-10B1')
                ('10C0-10C1' '10D0-10D1'))
ADDASPCPYD  ASPCPY(COPY2)
            ASPDEV(IASP001)
            CRG(CRG)
            SITE(SITE2)
            STGHOST(stguser passw0rd ('1.2.3.4'))
            LOCATION(SITE2)
            LUN('IBM.2107-7654321' ('10A0-10A1' '10B0-10B1')
                ('10C0-10C1' '10D0-10D1'))
STRASPSSN  SSN(METROSSN)  TYPE(*METROMIR)
           ASPCPY((COPY1 COPY2))

If two copy descriptions and an ASP session had been created using the above commands, and a CL program was run containing the following:

DCL VAR(&ASPCPYLST)   TYPE(*CHAR) LEN(32)
DCL VAR(&ASPDEV)      TYPE(*CHAR) LEN(10)
DCL VAR(&CRG)         TYPE(*CHAR) LEN(8)
DCL VAR(&SITE)        TYPE(*CHAR) LEN(10)
DCL VAR(&STGHOST)     TYPE(*CHAR) LEN(122)
DCL VAR(&LOCATION)    TYPE(*CHAR) LEN(8)
DCL VAR(&LUNSTGDEV)   TYPE(*CHAR) LEN(16)
DCL VAR(&LUNRANGE)    TYPE(*CHAR) LEN(256)
DCL VAR(&CGRANGE)     TYPE(*CHAR) LEN(256)
DCL VAR(&SSNLST)      TYPE(*CHAR) LEN(128)

Example 1: Retrieve a list of all copy descriptions

RTVASPCPYD ASPCPY(*ALL) ASPCPYLST(&ASPCPYLST)

Information for the ASP copy on the system where the CL program was run would return the following:

&ASPCPYLST     '0002COPY1     COPY2     '

Example 2: Retrieve information about a specific copy description

RTVASPCPYD   ASPCPY(COPY1)
             CRG(&CRG)
             SITE(&SITE)
             STGHOST(&STGHOST)
             LOCATION(&LOCATION)
             LUNSTGDEV(&LUNSTGDEV)
             LUNRANGE(&LUNRANGE)
             CGRANGE(&CGRANGE)
             SESSION(&SESSION)

Information for the ASP copy on the system where the CL program was run would return the following:

&ASPDEV         'IASP001   '
&CRG            'CRG       '
&SITE           'SITE1     '
&STGHOST        'stguser         1.2.3.4           '
&LOCATION       'SITE1   '
&LUNSTGDEV      'IBM.2107-1234567'
&LUNRANGE       '0013000800021000100110101011'
&CGRANGE        '00130008000110201022'
&SSNLST         '001300010008METROSSN'

Error messages

*ESCAPE Messages

HAE002B: &1 command failed.