Retrieve SVC Copy Description (RTVSVCCPYD)

The Retrieve SAN Volume Controller (SVC) Auxiliary Storage Pool (ASP) Copy Description (RTVSVCCPYD) command is used to retrieve SVC copy description(s).

The values returned are in the specified variables.

Restrictions:

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 (8) Character value Optional
NODE CL var for NODE (8) Character value Optional
SSNLST CL var for SSNLST (142) Character value Optional
SVCHOST CL var for SVCHOST (5065) Character value Optional
VRTDSKRNG CL var for VRTDSKRNG (32767) Character value Optional
RCYDMN CL var for RCYDMN (32767) Character value Optional

ASP copy (APSCPY)

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; all other fields are ignored.
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
                           SVC ASP copy
                           description list entry
5   4-byte integer number  Length of each SVC ASP copy
                           description list entry
9   4-byte integer number  Number of SVC ASP copy
                           description entries

The following field repeats for each ASP copy description. 

Position  Length                 Field
1         10 characters          SVC ASP Copy
                                 Description name

CL var for ASPDEV (10) (ASPDEV)

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

name
Specifies the name of the ASP device 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 (8) (SITE)

Specifies the name of the variable used to return 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 NODE (8) (NODE)

Specifies the name of the variable used to return the node identifier. Possible values are:

*CRG
The cluster resource group (CRG) site identifies the owning cluster node.
*NONE
The copy of the ASP is not owned by any cluster node.
name
The name of the cluster node that owns the copy.

CL var for SSNLST (142) (SSNLST)

Specifies the name of a variable that is used to return 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
9         4-byte integer number  Number of session
                                 entries

The following field repeats for each session entry. 

Position  Length                 Field
1         10 characters          Session name

CL var for SVCHOST (5065) (SVCHOST)

Specifies the name of the variable used to return the SAN Volume Controller cluster for the ASP copy. 

Position  Length                 Field
1         16 characters          User name
17        45 characters          Internet address
62        4-byte integer number  Length of SSH
                                 keyfile location
66        5000 characters        SSH keyfile location

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

The SSH keyfile location is variable length with the max length being 5000 characters. The length parameter will specify the length of the SSH keyfile location.

CL var for VRTDSKRNG (32767) (VRTDSKRNG)

Specifies the name of the variable used to return the virtual disks (VDisks) that are associated with the copy description. The VRTDSKRNG contains a 12- byte header composed of the following, which is then followed by zero or more virtual disk ranges and host identifiers. Up to 128 ranges can be specified. 

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

Offset to first Vdisk range entry
The offset from the beginning of VRTDSKRNG to the first Vdisk range entry.
Length of Vdisk entry
The length of each Vdisk entry.
Number of vDisk entries
The total number of Vdisk entries.

The following fields repeat for each Vdisk range entry. 

Position  Length                 Field
1    4-byte integer number  Vdisk range start
5    4-byte integer number  Vdisk range end
9    4-byte integer number  Offset from beginning
                            of this Vdisk range
                            entry to first host
                            identifier information
                            entry
13   4-byte integer number  Length of host identifier
                            information entries
17   4-byte integer number  Number of host identifier
                            information entry

Vdisk range start
The start of the Vdisk range. Will be an integer between 0-8191.
Vdisk range end
The end of the Vdisk range. Will be an integer between 0-8191.
Offset to first host identifier info
The offset from the beginning of this Vdisk range entry to the first host identifier information entry.
Length of host identifier info entry
The length of a host identifier information entry.
Number of host identifier info entries
The number of host identifier information entries.

The following fields repeat for each host identifier entry. 

Position  Length                 Field
1         4-byte integer number  Host identifier

Host identifier
The host identifier value will be an integer between 0-512 or -1 if the host identifier is *ALL. If the host identifier is *ALL, the structure will not repeat.

CL var for RCYDMN (32767) (RCYDMN)

Specifies name of the variable used to return the connection information for each node in the cluster resource group site recovery domain. 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  Length of host
                              identifier information
                              entries
21     4-byte integer number  Number of host
                              identifier information
                              entry

The following fields repeat for each host identifier entry 

Position  Length                 Field
1         4-byte integer number  Host identifier

Examples

Example 1: Retrieving a Copy Description for "SVCCPY" 

ADDSVCCPYD ASPCPY(SVCCPY)
           ASPDEV(SVCCPYDEV)
           CRG(SVCCRG)
           SITE(SVCSITE)
           NODE(*CRG)
           SVCHOST(user1 '/path/to/ssh/keyfile' '192.168.1.16')
           VRTDSKRNG((0 100 *ALL))
DCL     VAR(&ASPDEV)          TYPE(*CHAR) LEN(10)
DCL     VAR(&CRG)             TYPE(*CHAR) LEN(10)
DCL     VAR(&SITE)            TYPE(*CHAR) LEN(8)
DCL     VAR(&NODE)            TYPE(*CHAR) LEN(8)
DCL     VAR(&SVCHOST)         TYPE(*CHAR) LEN(5065)
DCL     VAR(&VRTDSKRNG)       TYPE(*CHAR) LEN(32767)
RTVSVCCPYD  ASPCPY(SVCCPY)
            ASPDEV(&ASPDEV)
            CRG(&CRG)
            SITE(&SITE)
            NODE(&NODE)
            SVCHOST(&SVCHOST)
            VRTDSKRNG(&VRTDSKRNG)

If the above commands had been run to create an SVC copy description named "SVCCPY" and then retrieve it, then the following information about the SVC ASP copy description would be returned: 

&ASPDEV         'SVCCPYDEV '
&CRG            'SVCCRG    '
&SITE           'SVCSITE '
&NODE           '*CRG    '
&SVCHOST        'user1           192.168.1.16
                            20/path/to/ssh/keyfile'
&VRTDSKRNG      '0 100 *ALL'

Error messages

*ESCAPE Messages

HAE002B
&1 command failed.
HAE000A
All cluster command user spaces busy.