Retrieve SVC Session (RTVSVCSSN)

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

Parameters
Examples
Error messages

The Retrieve SAN Volume Controller (SVC) Session (RTVSVCSSN) command is used to retrieve one or more of the values that are stored and associated with an SVC session. The values returned are in the specified variables. If any CL variables are passed in that are not valid (such as parms only valid for FlashCopy sessions) then these variables will be filled with blanks.

Restrictions:

You must have use (*USE) authority to the ASP device descriptions of the session that is being retrieved.
You must have read authority to the secure shell key file specified in the preferred source and preferred target copy descriptions.

Parameters

Keyword	Description	Choices	Notes
SSN	Session	Name, *ALL	Required, Positional 1
SSNLST	CL var for SSNLST (2012)	Character value	Optional
TYPE	CL var for TYPE (10)	Character value	Optional
ASPCPYLST	CL var for ASPCPYLST (2572)	Character value	Optional
INCR	CL var for INCR (4)	Character value	Optional
CPYRATE	CL var for CPYRATE (4)	Decimal number	Optional
CLNRATE	CL var for CLNRATE (4)	Decimal number	Optional
GRAINSIZE	CL var for GRAINSIZE (4)	Decimal number	Optional
CNSGRP	CL var for CNSGRP (17)	Character value	Optional
RVSCNSGRP	CL var for RVSCNSGRP (17)	Character value	Optional
SWTRVSREPL	CL var for SWTRVSREPL (4)	Character value	Optional
FLVRVSREPL	CL var for FLVRVSREPL (4)	Character value	Optional
CRG	CL var for CRG (10)	Character value	Optional
SRCSITE	CL var for SRCSITE (8)	Character value	Optional
TGTSITE	CL var for TGTSITE (8)	Character value	Optional
SRCCLU	CL var for SRCCLU (20)	Character value	Optional
TGTCLU	CL var for TGTCLU (20)	Character value	Optional
ASPCPY	CL var for ASPCPY (31232)	Character value	Optional

Session (SSN)

Specifies the name of the session to be started.

This is a required parameter.

*ALL: Returns a list of all SVC sessions on the system. When SSN(*ALL) is specified, the SSNLST parameter must be specified, and only the SSNLST parameter is returned; all other fields are ignored.
name: Specify the name of the SVC session to be retrieved. When a specific SVC session is requested, the SSNLST parameter is not valid.

CL var for SSNLST (2012) (SSNLST)

Specifies the name of a variable that is used to return the list of all sessions in the device domain that the requesting node is calling from. The session contains a 12-byte header composed of the following, which is then followed by zero to one hundred 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
1         10 characters          Session type

CL var for TYPE (10) (TYPE)

Specifies the name of the variable us to return the type of SVC session. Possible types are:

*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) (APSCPYLST)

Specifies the name of the variable used to return the list of SVC ASP copy descriptions associated with the SVC Session being retrieved. 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 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 SVC ASP copy description.

Position  Length                 Field
1         10 characters          Preferred source
                                 copy description
11        10 characters          Preferred target
                                 copy description

CL var for INCR (4) (INCR)

Specifies the name of the variable used to return if the FlashCopy is incremental. This parameter is only valid for FlashCopy sessions.

*NO: The FlashCopy session is not incremental.
*YES: The FlashCopy session is incremental.

CL var for CPYRATE (4) (CPYRATE)

Specifies the name of the variable used to return the copy rate (the rate at which data is copied from the source virtual disks (VDisks) of a FlashCopy to the target VDisks).

This parameter is only valid for a FlashCopy session.

0-100: The copy rate for the FlashCopy.

CL var for CLNRATE (4) (CLNRATE)

Specifies the name of the variable used to return the cleaning rate (the rate at which the cleaning process is done on the FlashCopy mapping. The cleaning process copies data from the target virtual disk (VDisk) of a mapping to the target VDisks of other mappings that are dependent on this data).

This parameter is only valid for a FlashCopy session.

0-100: The cleaning rate for the FlashCopy.

CL var for GRAINSIZE (4) (GRAINSIZE)

Specifies the name of the variable used to return the FlashCopy grain size in kilobytes (KB).

This parameter is only valid for a FlashCopy session.

256: The grain size for the FlashCopy is 256 KB.
64: The grain size for the FlashCopy is 64 KB.

CL var for CNSGRP (17) (CNSGRP)

Specifies the name of the variable used to return the name of the consistency group to use when creating the FlashCopy session.

This parameter is only valid for FlashCopy sessions.

name: The name of the consistency group to use for the FlashCopy session.

CL var for RVSCNSGRP (17) (RVSCNSGRP)

Specifies the name of the variable used to return the name of the reverse consistency group to use when creating the FlashCopy session.

This parameter is only valid for FlashCopy sessions.

name: The name of the reverse consistency group to use for the FlashCopy session.

CL var for SWTRVSREPL (4) (SWTRVSREPL)

Specifies the name of the variable used to return if reverse replication of the Metro Mirror or Global Mirror is to be started after a switchover.

This parameter is only valid for FlashCopy sessions.

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

CL var for FLVRVSREPL (4) (FLVRVSREPL)

Specifies the name of the variable used to return if reverse replication of the Metro Mirror or Global Mirror is to be started after a failover.

This parameter is only valid for FlashCopy sessions.

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

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 SRCSITE (8) (SRCSITE)

Specifies the name of the variable used to return the source CRG recovery domain site name.

name: The name of the source CRG recovery domain site.

CL var for TGTSITE (8) (TGTSITE)

Specifies the name of the variable used to return the target CRG recovery domain site name.

name: The name of the target CRG recovery domain site.

CL var for SRCCLU (20) (SRCCLU)

Specifies the name of the variable used to return the source storage cluster name.

name: The name of the source storage cluster name.

CL var for TGTCLU (20) (TGTCLU)

Specifies the name of the variable used to return the target storage cluster name.

name: The name of the target storage cluster name.

CL var for ASPCPY (31232) (ASPCPY)

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

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

The following field repeats for each SVC ASP copy description.

Position  Length                 Field
1      10 characters       SVC ASP Copy Description
11     10 characters       ASP device
21     10 characters       Role
31     8 characters        Node
39     10 characters       Vary State
49     10 characters       Replication State
59     4 characters        Progress
63     24 characters       Storage State

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

SOURCE: The node owns the source copy.
TARGET: The node owns the target copy.
UNKNOWN: The role could not be determined. This can occur if RTVSVCSSN is run on a node that is not currently the source or target node.

The Vary State parameter retrieves the current state ofthe 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.
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 replication state of the session. Possible states are:

ACTIVE: The target ASP is current with the source ASP and replication is active.
RESUMING: The ASP copy is resuming. The target copy of the ASP is not synchronized with its production copy but synchronization is currently active.
REVERSED: The source is not the CRG primary or the target is not the CRG backup.
SUSPENDED: The ASP copy is suspended.
DETACHED: The target ASP can become available.
INVALID: The ASP is in an invalid state.
NOTCONFIG: The source and target are not configured in a relationship on the SVC controller.
UNKNOWN: The state is unknown. This can occur if RTVSVCSSN is run on a node that is not currently the source or target node.

The node parameter retrives the name of the node that currently owns the ASP copy.

Examples

Example 1: Retrieving values for an SVC session named "SVCFSH"

STRSVCSSN SSN(SVCFSH)
          TYPE(*FLASHCOPY)
          ASPCPY((SVCSRC SVCTGT))
          CPYRATE(100)
          CLNRATE(100)
DCL     VAR(&TYPE)            TYPE(*CHAR) LEN(10)
DCL     VAR(&CPYRATE)         TYPE(*DEC) LEN(4 0)
DCL     VAR(&CLNRATE)         TYPE(*DEC) LEN (4 0)
RTVSVCSSN   SSN(SVCFSH)
            TYPE(&TYPE)
            CPYRATE(&CPYRATE)
            CLNRATE(&CLNRATE)

If the above commands had been run to start an SVC session named "SVCFSH" and then retrieve it, then the following information about the SVC session would be returned:

&TYPE           '*FLASHCOPY'
&CPYRATE        100
&CLNRATE        100

It is clear from the returned variables that the SVC session is a FlashCopy session with a copy rate and cleaning rate of 100.

Error messages

*ESCAPE Messages

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