Retrieve ASP Session (RTVASPSSN)

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 Session (RTVASPSSN) command is used in a control language (CL) program or a REXX procedure to get one or more of the values that are stored and associated with an auxiliary storage pool session. The values are returned in the specified variables.

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 for which session information is being retrieved.

Parameters

Keyword	Description	Choices	Notes
SSN	Session	Name	Required, Positional 1
TYPE	CL var for TYPE (10)	Character value	Optional
ASPCPYLST	CL var for ASPCPYLST (4472)	Character value	Optional
SWTRVSREPL	CL var for SWTRVSREPL (4)	Character value	Optional
FLVRVSREPL	CL var for FLVRVSREPL (4)	Character value	Optional
DELIVERY	CL var for DELIVERY (8)	Character value	Optional
MODE	CL var for MODE (8)	Character value	Optional
INTRANSIT	CL var for INTRANSIT (10 0)	Decimal number	Optional
TIMEOUT	CL var for TIMEOUT (4 0)	Decimal number	Optional
PRIORITY	CL var for PRIORITY (8)	Character value	Optional
TRACKSPACE	CL var for TRACKSPACE (3 0)	Decimal number	Optional
PERSISTENT	CL var for PERSISTENT (8)	Character value	Optional
FLASHTYPE	CL var for FLASHTYPE (8)	Character value	Optional
ASPCPY	CL var for ASPCPY (31232)	Character value	Optional

Session (SSN)

Specifies the name of the ASP session to be retrieved.

This is a required parameter.

name: Specify the name of the ASP session to be retrieved.

CL var for TYPE (10) (TYPE)

Specifies the name of the variable used to return the type of session. Possible values are:

*GEOMIR: The session is a Geographic mirroring session.
*METROMIR: The session is a Metro Mirror session
*GLOBALMIR: The session is a Global Mirror session.
*FLASHCOPY: The session is a FlashCopy session.

CL var for ASPCPYLST (4472) (ASPCPYLST)

Specifies the name of the variable used to return the list of ASP copy descriptions associated with the session.

The ASP copy list contains a 12-byte header composed of the following, which is followed by one 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          Preferred source copy description
11        10 characters          Preferred target copy description

CL var for SWTRVSREPL (4) (SWTRVSREPL)

Specifies whether reverse replication of the Metro Mirror or Global Mirror is to be started after a switchover.

Use of this keyword is not valid for Geographic Mirroring or FlashCopy sessions.

*YES: Replication is reversed after a switchover.
*NO: Replication is not reversed after a switchover.

CL var for FLVRVSREPL (4) (FLVRVSREPL)

Specifies whether reverse replication of the Metro Mirror or Global Mirror is to be started after a failover.

Use of this keyword is not valid for Geographic Mirroring or FlashCopy sessions.

*YES: Replication is reversed after a failover.
*NO: Replication is not reversed after a failover.

CL var for DELIVERY (8) (DELIVERY)

Specifies the name of the variable used to return the transmission delivery method for this ASP session. This attribute only applies to Geographic Mirroring sessions. Possible values are:

*UNKNOWN: Geographic mirroring is not configured, or the transmission delivery method could not be determined.
*SYNC: Synchronous transmission delivery
*ASYNC: Asynchronous transmission delivery

CL var for MODE (8) (MODE)

Specifies the name of the variable used to return the mirroring mode for this ASP session. This attribute only applies to Geographic Mirroring sessions. Possible values are:

*UNKNOWN: Geographic mirroring is not configured, or the mirroring mode could not be determined.
*SYNC: Synchronous mirroring mode
*ASYNC: Asynchronous mirroring mode

CL var for INTRANSIT (10 0) (INTRANSIT)

Specifies the name of the variable used to return the total data in transit in megabytes.

CL var for TIMEOUT (4 0) (TIMEOUT)

Specifies the name of the variable used to return the suspend timeout in seconds. Possible values range from 0 to 3600 seconds.

CL var for PRIORITY (8) (MODE)

Specifies the name of the variable used to return the synchronization priority for the ASP session. This attribute only applies to Geographic mirroring sessions. Possible values are:

*UNKNOWN: Geographic mirroring is not configured, or the priority could not be determined.
*LOW: The synchronization priority is low.
*MEDIUM: The synchronization priority is medium.
*HIGH: The synchronization priority is high.

CL var for TRACKSPACE (3 0) (TRACKSPACE)

Specifies the name of the variable used to return the percentage of the maximum assignable tracking space currently allocated. This attribute only applies to Geographic Mirroring sessions.

CL var for PERSISTENT (8) (PERSISTENT)

Specifies the name of the variable used to return the persistence of the FlashCopy session. This attribute only applies to FlashCopy sessions. Possible values are:

*UNKNOWN: The FlashCopy persistence could not be determined.
*NO: The FlashCopy relationship is not persistent.
*YES: The FlashCopy relationship is persistent.

CL var for FLASHTYPE (8) (FLASHTYPE)

Specifies the name of the variable used to return the type of the FlashCopy session. This attribute only applies to FlashCopy sessions. Possible values are: :

*UNKNOWN: The FlashCopy type could not be determined.
*COPY: The FlashCopy session is of type *COPY.
*NOCOPY: The FlashCopy session is of type *NOCOPY.

CL var for ASPCPY (31232) (ASPCPY)

Specifies the name of a variable that is used to retrieve the ASP copy description information for each ASP copy in the session. The ASP copy description contains a 12-byte header composed of the following, which is then followed by two or more ASP copy description entries.

Position  Length                 Field
1         4 byte integer         Offset from beginning of
                                 ASPCPY to the first ASP copy
                                 description entry
5         4 byte integer         Number of ASP copy
                                 description entries
9         4 byte integer         Length of an ASP copy
                                 description entry

The following fields repeat for each ASP copy description entry.

Position  Length                 Field
1         10 characters          ASP copy description
11        10 characters          ASP device
21        10 characters          Role
31        10 characters          State
41        10 characters          Data state
51        8 characters           Node
59        4 byte integer         Percent tracking space used
63        4 byte integer         Total data out of sync
67        4 byte integer         Synchronization progress

The Role parameter retrieves the current roles for the ASP. Possible Role values are:

PRODUCTION: the node owns the production copy.
SOURCE: the node owns the source copy.
MIRROR: the node owns the mirror copy.
TARGET: the node owns the target copy.
DETACHED: the node owns the detached copy.
UNKNOWN: the role could not be determined. This can occur if RTVASPSSN is run on a node that is not currently the source or target node.

The State parameter retrieves the current state of the ASP. For the production or source copy, the vary configuration state is retrieved. For the mirror or target copy, the mirroring state is retrieved. Possible values are:

VARYOFF: the configuration state of the ASP is Varyoff.
VARYON: the configuration state of the ASP is Varyon.
VARYONPEND: the configuration state of the ASP is Vary on Pending.
ACTIVE: the configuration state of the ASP is Active.
AVAILABLE: the configuration state of the ASP is Available.
RESUMEPEND: The configuration state of the production copy of the ASP is Varyoff and synchronization has been requested or in progress (the production copy has changes that the mirror copy does not.) Until a vary on is initiated, the mirror copy state is Resumepend.
RESUMING: The ASP copy is resuming. The mirror copy of the ASP is not synchronized with its production copy but synchronization is currently active.
SUSPENDED: The ASP copy is suspended.
UNKNOWN: the state could not be determined. For example, the configuration state of the source copy cannot be determined by from the target node.

The Data state parameter retrieves the current data state of the ASP. This parameter is only valid for Geographic Mirroring sessions. Possible values are:

INSYNC: The target ASP copy has been fully synchronized with its source. The two copies are identical to each other. This can only occur when the source copy has been varied off.
USABLE: The data in the ASP copy is in a usable state. If *SYNC mode has been selected, the data state is usable and the mirror copy can be used after an abnormal termination of the mirror copy node.
UNUSABLE: The data in the ASP copy is not in a usable state. Either synchronization has not yet been completed, or some data has not been written to disk on the mirror copy node. if *ASYNC mode has been selected, the data state is unusable and the mirror copy must be resynchronized before it can be used after an abnormal termination of the mirror copy node.

Examples

ADDASPCPYD  ASPCPY(COPY1)
            ASPDEV(IASP001)
            CRG(CRG)
            SITE(SITE1)
ADDASPCPYD  ASPCPY(COPY2)
            ASPDEV(IASP001)
            CRG(CRG)
            SITE(SITE2)
STRASPSSN   SSN(GEOSSN)  TYPE(*GEOMIR)
            ASPCPY((COPY1 COPY2))

If Geographic mirroring had been configured for IASP001, 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(&TYPE)        TYPE(*CHAR) LEN(10)
DCL     VAR(&ASPCPYLST)   TYPE(*CHAR) LEN(32)
DCL     VAR(&DELIVERY)    TYPE(*CHAR) LEN(8)
DCL     VAR(&MODE)        TYPE(*CHAR) LEN(8)
DCL     VAR(&INTRANSIT)   TYPE(*DECIMAL) LEN(10 0)
DCL     VAR(&TIMEOUT)     TYPE(*DECIMAL) LEN(4 0)
DCL     VAR(&PRIORITY)    TYPE(*CHAR) LEN(7)
DCL     VAR(&TRACKSPACE)  TYPE(*DECIMAL) LEN(3 0)
DCL     VAR(&ASPCPY)      TYPE(*CHAR) LEN(256)
RTVASPSSN  SSN(GEOSSN)
           TYPE(&TYPE)
           ASPCPYLST(&ASPCPY)
           DELIVERY(&DELIVERY)
           MODE(&MODE)
           INTRANSIT(&INTRANSIT)
           TIMEOUT(&TIMEOUT)
           PRIORITY(&PRIORITY)
           TRACKSPACE(&TRACKSPACE)
           ASPCPY(&ASPCPY)

The following information about the ASP session would be returned:

&TYPE           '*GEOMIR   '
&ASPCPYLST      '001300200001COPY1     COPY2     '
&DELIVERY       '*SYNC   '
&MODE           '*SYNC   '
&INTRANSIT      '0000000013'
&TIMEOUT        '0120'
&PRIORITY       '*MEDIUM '
&TRACKSPACE     '0005'
&ASPCPY         '001300020067COPY1     IASP001   PRODUCTION'
                'AVAILABLEUSABLE  NODE1     00000000'
                'COPY2     IASP001   MIRROR    ACTIVE    '
                'USABLE  NODE2     00000000'

Error messages

*ESCAPE Messages

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