ACTIVATE_SESSION

The ACTIVATE_SESSION verb requests activation of a session between the local LU and a specified partner LU using the characteristic of a particular mode.

VCB Structure

Format 1

typedef struct activate_session
{
        unsigned short  opcode;         /* verb operation code     */
        unsigned char   reserv2;        /* reserved                */
        unsigned char   format;         /* format                  */
        unsigned short  primary_rc;     /* primary return code     */
        unsigned long   secondary_rc;   /* secondary return code   */
        unsigned char   lu_name[8];     /* local LU name           */
        unsigned char   lu_alias[8];    /* local LU alias          */
        unsigned char   plu_alias[8];   /* partner LU alias        */
        unsigned char   mode_name[8];   /* mode name               */
        unsigned char   fqplu_name[17]; /* fully qualified partner */
                                        /* LU name                 */
        unsigned char   polarity;       /* requested session       */
                                        /* polarity                */
        unsigned char   session_id[8];  /* session identifier      */
        unsigned char   cnos_permitted; /* is implicit CNOS        */
                                        /* permitted?              */
        unsigned char   reserv4[15];    /* reserved                */
} ACTIVATE_SESSION;

Format 0 (back-level)

typedef struct activate_session
{
        unsigned short  opcode;         /* verb operation code     */
        unsigned char   reserv2;        /* reserved                */
        unsigned char   format;         /* format                  */
        unsigned short  primary_rc;     /* primary return code     */
        unsigned long   secondary_rc;   /* secondary return code   */
        unsigned char   lu_name[8];     /* local LU name           */
        unsigned char   lu_alias[8];    /* local LU alias          */
        unsigned char   plu_alias[8];   /* partner LU alias        */
        unsigned char   mode_name[8];   /* mode name               */
        unsigned char   fqplu_name[17]; /* fully qualified partner */
                                        /* LU name                 */
        unsigned char   polarity;       /* requested session       */
                                        /* polarity                */
        unsigned char   session_id[8];  /* session identifier      */
} ACTIVATE_SESSION;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_ACTIVATE_SESSION

format

Identifies the format of the VCB. Set this field to zero or one to specify the version of the VCB listed above.

lu_name

LU name of the local LU requested to activate a session. This name is an 8-byte type-A EBCDIC character string. If this field is set to all zeros, the lu_alias field will be used for determining the local LU.

lu_alias

Alias of the local LU requested to activate a session. This is an 8-byte string in a locally displayable character set. This field is only significant if the lu_name field is set to all zeros, in which case all 8 bytes are significant and must be set. If both the lu_alias and the lu_name are set to all zeros then the verb is forwarded to the LU associated with the control point (the default LU).

plu_alias

Alias by which the partner LU is known to the local LU. This name must match the name of a partner LU established during configuration. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant and must be set. If this field is set to all zeros, the fqplu_name field is used to specify the required partner LU.

mode_name

Name of a set of networking characteristics defined during configuration. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.

fqplu_name

Fully qualified LU name for the partner LU. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.) This field is only significant if the plu_alias field is set to all zeros.

polarity

The polarity requested for the session. Possible values are:

AP_POL_EITHER
AP_POL_FIRST_SPEAKER
AP_POL_BIDDER

If AP_POL_EITHER is selected, ACTIVATE_SESSION activates a first speaker session if available; otherwise, a bidder session is activated. For AP_POL_FIRST_SPEAKER or AP_POL_BIDDER, ACTIVATE_SESSION only succeeds if a session of the requested polarity is available.

cnos_permitted

This field may be set to AP_YES or AP_NO. If the activation of a new session is not possible because the session limits for the specified mode are reset, and this field is set to AP_YES, then the Program initiates implicit CNOS processing to initialize the session limits. Execution of this verb will be suspended while CNOS processing takes place.

Returned Parameters

If the verb executes successfully, the Program returns the following parameter:

primary_rc: AP_OK
secondary_rc: AP_AS_SPECIFIED
AP_AS_NEGOTIATED
session_id: 8-byte identifier of the activated session.

If the verb does not execute because of a parameter error, the Program returns the following parameters:

primary_rc: AP_PARAMETER_CHECK
secondary_rc: AP_EXCEEDS_MAX_ALLOWED
AP_INVALID_CNOS_PERMITTED
AP_INVALID_LU_NAME
AP_INVALID_LU_ALIAS
AP_INVALID_MODE_NAME
AP_INVALID_PLU_NAME

If the verb exceeds the session limit for the mode, the Program returns the following parameters:

primary_rc: AP_PARAMETER_CHECK
Secondary_rc: AP_EXCEEDS_MAX_ALLOWED

If the verb does not execute because the node has not yet been started, the Program returns the following parameter:

primary_rc: AP_NODE_NOT_STARTED

If the verb does not execute because the node is stopping, the Program returns the following parameter:

primary_rc: AP_NODE_STOPPING

If the verb does not execute because of a system error, the Program returns the following parameter:

primary_rc: AP_UNEXPECTED_SYSTEM_ERROR

If the verb does not execute because of other errors, the Program returns one of the following parameters:

primary_rc: AP_ACTIVATION_FAIL_NO_RETRY
AP_ACTIVATION_FAIL_RETRY