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.

Top

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
LOCATION CL var for LOCATION (8) Character value Optional
LUNSTGDEV CL var for LUNSTGDEV (16) Character value Optional
LUNRNG CL var for LUNRNG (1036) Character value Optional
LUNCGRNG CL var for LUNCGRNG (1036) Character value Optional
RCYDMN CL var for RCYDMN (32767) Character value Optional
SSNLST CL var for SSNLST (142) Character value Optional
Top

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

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

Top

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.

Top

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

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

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.

Top

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 Geographic mirroring, Metro Mirror, and Global Mirror ASP sessions.
*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 target.
Top

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

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 repeate for each LUN range entry

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

Top

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 repeate for each consistency group range entry

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

Top

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

Top

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 recovery domain
                                 entries

The following field repeats for each session entry.

Position  Length                 Field
1         10 characters          Session name

Top

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'

Top

Error messages

*ESCAPE Messages

HAD0016
ASP copy description &1 does not exist.
HAE004E
Length of CL program variable not valid.
HAE004F
&1 command failed.
Top