CHANGE_SESSION

The CHANGE_SESSION_LIMIT verb requests SNAplus2 to change the session limits for a particular LU-LU-mode combination. Sessions may be activated or deactivated as a result of processing this verb.

This verb must be issued to a running node.

VCB Structure

typedef struct change_session_limit
{
   AP_UINT16       opcode;                   /* verb operation code          */
   unsigned char   reserv2;                  /* reserved                     */
   unsigned char   format;                   /* reserved                     */
   AP_UINT16       primary_rc;               /* primary return code          */
   AP_UINT32       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   fqplu_name[17];           /* fully qualified partner      */
                                             /*  LU name                     */
   unsigned char   reserv3;                  /* reserved                     */
   unsigned char   mode_name[8];             /* mode name                    */
   unsigned char   reserv3a;                 /* reserved                     */
   unsigned char   set_negotiable;           /* set max negotiable limit?    */
   AP_UINT16       plu_mode_session_limit;   /* session limit                */
   AP_UINT16       min_conwinners_source;    /* minimum source contention    */
                                             /*  winner sessions             */
   AP_UINT16       min_conwinners_target;    /* minimum target contention    */
                                             /*  winner sessions             */
   AP_UINT16       auto_act;                 /* auto activation limit        */
   unsigned char   responsible;              /* who is responsible for       */
                                             /*  deactivating                */
   unsigned char   reserv4[3];               /* reserved                     */
   AP_UINT32       sense_data;               /* sense data                   */
} CHANGE_SESSION_LIMIT;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_CHANGE_SESSION_LIMIT

lu_name

LU name of the local LU, as defined to SNAplus2. This is an 8-byte type-A EBCDIC string, padded on the right with spaces if the name is shorter than 8 bytes. To indicate that the LU is defined by its LU alias instead of its LU name, set this parameter to 8 binary zeros.

lu_alias

LU alias of the local LU, as defined to SNAplus2. This is an 8-byte ASCII string, using any locally displayable characters, padded on the right with spaces if the name is shorter than 8 bytes. It is used only if lu_name is set to zeros.

To indicate the LU associated with the CP (the default LU), set both lu_name and lu_alias to 8 binary zeros.

plu_alias

LU alias of the partner LU.

This is an 8-byte ASCII string, using any locally displayable characters, padded on the right with spaces if the name is shorter than 8 bytes. To indicate that the partner LU is defined by its fully qualified LU name instead of its LU alias, set this parameter to 8 binary zeros.

fqplu_name

Fully qualified LU name for the partner LU, as defined to SNAplus2. This parameter is used only if the plu_alias field is set to zeros; it is ignored if plu_alias is specified.

The name is a 17-byte EBCDIC string, right-padded with EBCDIC spaces. It consists of a network ID of up to 8 A-string characters, an EBCDIC dot (period) character, and a network name of up to 8 A-string characters.

mode_name

Name of the mode to be used by the LUs.

This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded on the right with EBCDIC spaces if the name is shorter than 8 bytes.

set_negotiable

Specifies whether the maximum negotiable session limit for this mode should be modified. Possible values are:

AP_YES: Use the value specified by plu_mode_session_limit as the maximum negotiable session limit for this LU-LU-mode combination.
AP_NO: Leave the maximum negotiable session limit as the value specified for the mode.

plu_mode_session_limit

Requested total session limit for this LU-LU-mode combination: the maximum number of parallel sessions permitted between these two LUs using this mode. Specify a value in the range 1-32,767. This value may be negotiated with the partner LU.

min_conwinners_source

Minimum number of sessions using this mode for which the local LU is the contention winner. Specify a value in the range 0-32,767. The sum of the min_conwinners_source and min_conwinners_target parameters must not exceed the plu_mode_session_limit parameter.

min_conwinners_target

Minimum number of sessions using this mode for which the partner LU is the contention winner. Specify a value in the range 0-32,767. The sum of the min_conwinners_source and min_conwinners_target parameters must not exceed the plu_mode_session_limit parameter.

auto_act

Number of sessions to automatically activate after the session limit is changed. Specify a value in the range 0-32,767. The actual number of automatically activated sessions is the minimum of this value and the negotiated minimum number of contention winner sessions for the local LU. When sessions are deactivated normally (specifying AP_DEACT_NORMAL) below this limit, new sessions are activated up to this limit.

responsible

Indicates whether the local or partner LU is responsible for deactivating sessions after the session limit is changed. Possible values are:

AP_SOURCE: The local LU is responsible.
AP_TARGET: The partner LU is responsible.

Returned Parameters: Successful Execution

If the verb executes successfully, SNAplus2 returns the following parameters:

primary_rc

AP_OK

secondary_rc

Possible values are:

AP_AS_NEGOTIATED: The session limits were changed, but one or more values were negotiated by the partner LU.
AP_AS_SPECIFIED: The session limits were changed as requested, without being negotiated by the partner LU.

Returned Parameters: Parameter Check

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

primary_rc

AP_PARAMETER_CHECK

secondary_rc

Possible values are:

AP_EXCEEDS_MAX_ALLOWED: The plu_mode_session_limit, min_conwinners_source, min_conwinners_target, or auto_act parameter was set to a value outside the valid range.
AP_CANT_CHANGE_TO_ZERO: The plu_mode_session_limit parameter cannot be set to zero using this verb; use RESET_SESSION_LIMIT instead.
AP_INVALID_LU_ALIAS: The lu_alias parameter did not match any defined local LU alias.
AP_INVALID_LU_NAME: The lu_name parameter did not match any defined local LU name.
AP_INVALID_MODE_NAME: The mode_name parameter did not match any defined mode name.
AP_INVALID_PLU_NAME: The fqplu_name parameter did not match any defined partner LU name.
AP_INVALID_RESPONSIBLE: The responsible parameter was not set to a valid value.
AP_INVALID_SET_NEGOTIABLE: The set_negotiable parameter was not set to a valid value.

Appendix A “Common Return Codes” lists further secondary return codes associated with AP_PARAMETER_CHECK, which are common to all NOF verbs.

Returned Parameters: State Check

If the verb does not execute because of a state error, SNAplus2 returns the following parameters.

primary_rc

AP_STATE_CHECK

secondary_rc

AP_MODE_RESET: No sessions are currently active for this LU-LU-mode combination. Use INITIALIZE_SESSION_LIMIT instead of CHANGE_SESSION_LIMIT to specify the limits.

Appendix A “Common Return Codes” lists further secondary return codes associated with AP_STATE_CHECK, which are common to all NOF verbs.

Returned Parameters: Session Allocation Error

If the verb does not execute because of a session allocation error, SNAplus2 returns the following parameters:

primary_rc

AP_ALLOCATION_ERROR

secondary_rc

AP_ALLOCATION_FAILURE_NO_RETRY: A session could not be allocated because of a condition that requires corrective action. Check the sense_data parameter and any logged messages to determine the reason for the failure, and take any action required. Do not attempt to retry the verb until the condition has been corrected.

sense_data

The SNA sense data associated with the allocation failure.

Returned Parameters: CNOS Processing Errors

If the verb does not execute because of an error, SNAplus2 returns the following parameters.

primary_rc

AP_CONV_FAILURE_NO_RETRY: The session limits could not be changed because of a condition that requires action (such as a configuration mismatch or a session protocol error). Check the SNAplus2 log file for information about the error condition, and correct it before retrying this verb.

primary_rc

AP_CNOS_PARTNER_LU_REJECT

secondary_rc

AP_CNOS_COMMAND_RACE_REJECT: The verb failed because the specified mode was being accessed by another administration program (or internally by the SNAplus2 software) for session activation or deactivation, or for session limit processing. The application should retry the verb, preferably after a timeout to allow the race condition to be cleared.

Returned Parameters: Other Conditions

Appendix A “Common Return Codes” lists further combinations of primary and secondary return codes that are common to all NOF verbs.

CHANGE_SESSION_LIMIT

Technical documentation

» Table of Contents

» Index

VCB Structure

Supplied Parameters

Returned Parameters: Successful Execution

Returned Parameters: Parameter Check

Returned Parameters: State Check

Returned Parameters: Session Allocation Error

Returned Parameters: CNOS Processing Errors

Returned Parameters: Other Conditions