SESSIONC—Send a session-control request or response

Purpose

SESSIONC sends a Start Data Traffic (SDT), Clear, or Set and Test Sequence Numbers (STSN) request on a session from an application program acting as a PLU. SESSIONC is also used to send a Request Recovery (RQR) request as well as responses to rejected BIND requests, SDT requests, and STSN requests on a session from an application program acting as an SLU.

Usage

For XRF, the SESSIONC macroinstruction initiates the switch from backup session status to primary session status. SESSIONC uses a CONTROL operand to specify this "switch."

Material from Send a Start Data-Traffic request to the SLU through Send a Switch request initiating the switch from backup to primary session status shows the SESSIONC options. The transmission services profile that is in use determines the use of these requests. See Specifying a session parameter, for a description of the profiles and the requests that can be used. Examples of the use of session-control requests and responses sent by SESSIONC are given in Request and response exchanges for typical communication operations, and in Controlling flow.

Before issuing the SESSIONC macroinstruction, the application program must set register 13 to the address of an 18-word save area. Refer to Summary of register usage, for information pertaining to the register contents upon return of control.

SESSIONC -RSP(BIND): If PARMS=(NQNAMES=YES) on the ACB macroinstruction, and if the NIB is specified with a network identifier in the NIBNET field, the network identifier is used along with the LU name in NIBSYM to determine the target of the UNBIND or BIND response.

Syntax


>>-+------+--SESSIONC--RPL--=--rpl_address---------------------->
   '-name-'                                  

>--+----------------------------------------------+------------->
   |                                          (1) |   
   '-,--AAREA--=--alternate_data_area_address-----'   

>--+-----------------------------------------------+------------>
   |                                           (1) |   
   '-,--AAREALN--=--alternate_data_area_length-----'   

>--+----------------------------+------------------------------->
   |                        (1) |   
   '-,--ACB--=--acb_address-----'   

>--+-------------------------------+---------------------------->
   |                           (1) |   
   +-,--ARG--=--(--register--)-----+   
   |                        (1)    |   
   '-,--NIB--=--nib_address--------'   

>--+---------------------------+-------------------------------->
   |                       (1) |   
   '-,--BRANCH--=--+-NO--+-----'   
                   '-YES-'         

>--+-------------------------------+---------------------------->
   |                           (1) |   
   '-,--CONTROL--=--+-BIND---+-----'   
                    +-CLEAR--+         
                    +-RQR----+         
                    +-SDT----+         
                    +-STSN---+         
                    '-SWITCH-'         

>--+--------------------------------------+--------------------->
   |                     (1)              |   
   +-,--ECB--=--INTERNAL------------------+   
   +-,--ECB--=--ecb_address---------------+   
   |                                  (1) |   
   '-,--EXIT--=--exit_routine_address-----'   

>--+---------------------------+-------------------------------->
   '-,--IBSQAC--=--+-IGNORE--+-'   
                   +-INVALID-+     
                   +-RESET---+     
                   +-SET-----+     
                   +-TESTNEG-+     
                   +-TESTPOS-+     
                   '-TESTSET-'     

>--+--------------------------------------------+--------------->
   |                                        (1) |   
   '-,--IBSQVAL--=--inbound_sequence_number-----'   

>--+---------------------------+-------------------------------->
   '-,--OBSQAC--=--+-IGNORE--+-'   
                   +-INVALID-+     
                   +-RESET---+     
                   +-SET-----+     
                   +-TESTNEG-+     
                   +-TESTPOS-+     
                   '-TESTSET-'     

>--+---------------------------------------------+-------------->
   |                                         (1) |   
   '-,--OBSQVAL--=--outbound_sequence_number-----'   

>--+--------------------------------+--------------------------->
   |                            (1) |   
   '-,--OPTCD--=--(--+-ASY-+--)-----'   
                     '-SYN-'            

>--+------------------------------------------+----------------->
   |                                      (1) |   
   '-,--RESPOND--=--+-(--FME--)---------+-----'   
                    +-(--EX--,--FME--)--+         
                    '-(--NEX--,--FME--)-'         

>--+----------------------------------+------------------------->
   |                              (1) |   
   '-,--SEQNO--=--sequence_number-----'   

   .-,--SSENSEO--=--0---------.   
>--+--------------------------+--------------------------------->
   '-,--SSENSEO--=--+-0-----+-'   
                    +-CPM---+     
                    +-FI----+     
                    +-RR----+     
                    '-STATE-'     

>--+------------------------------------------------+----------->
   |                                            (1) |   
   '-,--SSENSMO--=--system–sense_modifier_value-----'   

>--+---------------------------+-------------------------------->
   |                       (1) |   
   '-,--STYPE--=--+-REQ--+-----'   
                  '-RESP-'         

>--+-------------------------------------+---------------------><
   |                                 (1) |   
   '-,--USENSEO--=--user–sense_value-----'

Notes:

Operand value can be placed in its RPL field either by specification on an RPL macroinstruction operand or by explicitly setting the field using the IFGRPL DSECT.

Input parameters

RPL=rpl_address: Indicates the RPL that specifies which kind of processing SESSIONC performs.

The following RPL operands apply to the SESSIONC macroinstruction:

AAREA=alternate_data_area_address

For XRF, the AAREA field in the RPL is initialized by the application program to provide the address of the input area where the SWITCH response information should be placed.

AAREALN=alternate_data_area_length

For XRF, the AAREALN field in the RPL is initialized by the application program to contain the length of the input area pointed to by AAREA. The AAREA field is ignored if AAREALN=0 (no switch response information is returned).

ACB=acb_address

Indicates the ACB that identifies the application program issuing SESSIONC. If not specified, the ACB address already in RPLDACB is used.

ARG=(register)

The SESSIONC macroinstruction is always directed to one specific session. The ARG operand specifies the register containing the CID of the session. If the ARG operand is not specified, the CID already in the RPLARG field is used. The RPL form of SESSIONC can be used for rejecting a BIND by specifying RPLARG equal to the CID, as provided in the SCIP exit when the BIND request was received.

Note: If your application uses the RPL DSECT, IFGRPL, you must clear the RPLNIB bit if a CID is being inserted into the RPLARG field. For application programs running in supervisor state under a TCB, BRANCH indicates whether authorized path processing is to be used. See Authorized path.

BRANCH

If the macroinstruction is issued in an application program that is running in supervisor state under a TCB, set BRANCH to YES to specify that you should use authorized path processing.

BRANCH=YES: When the macroinstruction is issued, VTAM® processes the macroinstruction using authorized path. For programs running under an SRB rather than under a TCB, the macroinstruction is processed in this manner automatically, regardless of the actual setting of the BRANCH field.
BRANCH=NO: When the macroinstruction is issued, VTAM does not process the macroinstruction using authorized path.

CONTROL

CONTROL=BIND

Sends a BIND request-rejected response to a primary logical unit to indicate a rejection of the BIND request.

CONTROL=CLEAR

Sends a Clear request on the session. All SEND, RECEIVE, RESETSR, and SESSIONC requests in progress for the session are completed normally or with (RTNCD,FDB2)=(0C,0C). If the transmission services profile supports SDT, all subsequent SEND, RECEIVE, and RESETSR requests are rejected with (RTNCD,FDB2)=(14,41) until SDT is sent and a positive SDT response is received. Before SESSIONC is completed, VTAM sets the inbound and outbound sequence numbers to 0.

CONTROL=RQR

Sends a Request Recovery request to the primary logical unit. This operand asks the primary logical unit to take recovery action for this session (for example, issue Clear, STSN, and SDT).

CONTROL=SDT

Sends a Start Data Traffic request or a response to an SDT on the session. When SDT=SYSTEM is coded as part of the NIB used to establish the session, VTAM automatically sends a Start Data Traffic request or an SDT response as part of the session-establishment process. If SDT=APPL is coded instead, it is the application program's responsibility to send the request or response when data traffic is to begin.

CONTROL=STSN

Sends a Set and Test Sequence Numbers request (if STYPE=REQ) to the logical unit acting as the secondary end of the session or returns information (if STYPE=RESP) to the primary logical unit in response to an STSN request.

CONTROL=SWITCH

Causes the backup XRF session to become the primary XRF session.

The former primary XRF session, if still "active," is terminated with an UNBIND (CLEANUP). This command can be issued only on a backup XRF session. If issued on a primary XRF session, it is rejected.

After the positive response to the SWITCH is received by VTAM and the operation is posted complete, the session recovery can proceed.

The SWITCH response contains the status of the session at the time the SWITCH is completed. The application program uses this information (found in control vector hex 29) to recover the session. See Table 1 for more information.

ECB

Indicates that an ECB is posted when an asynchronous (OPTCD=ASY) SESSIONC operation is posted as being complete. You cannot specify both ECB and EXIT on a single macroinstruction.

ECB=event_control_block_address: Specifies that VTAM is to post an event control block (ECB). Event_control_block_address is the location of the ECB to be posted. The ECB can be any fullword of storage aligned on a fullword boundary.
ECB=INTERNAL: Specifies that VTAM is to post an internal ECB.

EXIT=exit_routine_address

Indicates the address of an RPL exit routine that is scheduled when an asynchronous (OPTCD=ASY) SESSIONC operation is posted as being complete. You cannot specify both ECB and EXIT on a single macroinstruction. For details about the EXIT operand, refer to the RPL macroinstruction description in this chapter.

IBSQAC and OBSQAC

The IBSQAC (inbound sequence number action code) and the OBSQAC (outbound sequence number action code) fields designate the type of STSN request to be sent on the session. The application program can set either or both of these fields. The effect of setting one is identical to the effect of setting the other, except that one applies to incoming requests and the other to outgoing requests. Table 1 summarizes the STSN request types (SET, TESTSET, INVALID and IGNORE) and the responses they can elicit from the logical unit at the other end of the session.

IBSQAC

OBSQAC

The IBSQAC (inbound sequence number result code) and the OBSQAC (outbound sequence number result code) fields designate the type of STSN response to be sent on the session. The result codes are set in response to the action codes set in a previously received STSN request as shown in Table 1. The STSN request types are: TESTPOS, TESTNEG, INVALID, and RESET.

IBSQVAL=inbound_sequence_number

Indicates a value that is one less than the new value that VTAM is to begin assigning to inbound requests. This value must be a decimal integer 0—65535 inclusive. This field can be sent on either an STSN request or a STSN response, as shown in Table 1.

Note: Inbound refers to requests that are transmitted from the terminal to the application.

NIB=nib address

When an application program wants to return a request-rejected response to a BIND request, the NIB address indicates the NIB whose NAME field identifies a pending active session to be terminated, and if using network-qualified names, whose NIBNET field contains the network identifier of the logical unit. Alternatively, the ARG operand can be used to identify the session.

For a detailed description of the use of the SESSIONC macroinstruction to send a BIND request rejected response, refer to SESSIONC macroinstruction with CONTROL=BIND.

Note: If your application uses the RPL DSECT, IFGRPL, you must set the RPLNIB bit if an NIB address is being inserted into the RPLARG field.

OBSQVAL=outbound_sequence_number

Indicates a value that is one less than the new value that VTAM is to begin assigning to outbound (from the application program) requests. This value must be between a decimal integer 0–65535 inclusive. This field can be sent on either a STSN request or a STSN response as shown in Table 1.

Note: Outbound refers to requests that are transmitted from the application program to a device.

OPTCD=SYN

OPTCD=ASY

If the SYN option code is set, control is returned to the application program when the SESSIONC operation has completed. If the ASY option code is set, control is returned as soon as VTAM has accepted the request. After the SESSIONC operation has completed, the ECB is posted or the RPL exit routine is scheduled, depending on the setting of the ECB-EXIT field.

Refer to the RPL macroinstruction description in this chapter for details about OPTCD=SYN or OPTCD=ASY.

Because it might take VTAM a relatively long time to complete the SESSIONC operation, you should not use the SYN option if suspending the SESSIONC issuing task or SRB for this time is undesirable. Use the ASY option code, instead.

For XRF, ASY is recommended for CONTROL=SWITCH.

RESPOND

Indicates whether a negative or positive response is to be sent for a session-control request. See How requests and responses are exchanged for possible responses that can be sent.

SEQNO=sequence_number

Indicates the sequence number of a response. The application program using SESSIONC to respond to any session-control request must set this field with the sequence number of that request. The sequence number was made available in the SCIP exit routine when the session-control request was received.

SSENSEO

This field is set by VTAM for a Logical Unit Status (LUSTAT) request and informs the logical unit of the type of error that caused the exception condition. These error types are described in Return codes and sense fields for RPL-based macroinstructions. SSENSEO=0 is the default.

This field can also provide application-specified sense values for negative responses to CINIT or for UNBIND. Refer to the sections on the CLSDST or TERMSESS macroinstructions in this chapter for additional information.

SSENSMO=system-sense_modifier_value

The value set in this field is used in conjunction with the SSENSEO setting to describe the specific type of error that caused the exception condition. The meanings assigned to the SSENSMO values are described in detail in SNA Formats If this operand is omitted, the SSENSMO field is set to 0.

This field can also be used to provide application-specified sense values for negative responses to CINIT or for UNBIND. Refer to the TERMSESS macroinstructions in this chapter.

Specify any decimal integer 0–255 inclusive, or specify a 1-byte hexadecimal constant.

STYPE

This field designates the type of output to be sent on the session.

STYPE=REQ: The application program uses this to send a request.
STYPE=RESP: Is used when a response is to be sent.

For XRF, only REQ applies to CONTROL=SWITCH.

USENSEO=user-sense_value

Indicates sense information related to a negative response to an SDT, STSN request, or a BIND request rejected response. Refer to the RPL macroinstruction description of these operands for format information. Additionally, register notation can be used for SSENSMO and USENSEO; the low-order 1 or 2 bytes, respectively, are used from the register.

Examples

SESSC1   SESSIONC RPL=RPL1,
CONTROL=STSN,OBSQAC=TESTSET,                C
               OBSQVAL=(3),IBSQAC=IGNORE

SESSC1 sends an STSN request to a logical unit on a session and sets the VTAM-supplied outbound (from the application program) sequence number to the value contained in the low-order 2 bytes of register 3. The logical unit, noting that the type of STSN request is TESTSET, can indicate TESTPOS, TESTNEG, INVALID, or RESET with its response. The response information is available in RPL1 when SESSC1 is completed. If OBSQAC is found by the application program to be set to TESTPOS or TESTNEG, the OBSQVAL field contains the logical unit's version of the outbound sequence number. No action is taken by either end on the inbound (to the PLU) sequence number.

Completion information

If STYPE=REQ, the SESSIONC operation is successfully completed when the request has been sent and a response has been returned and posted in the RPL (similar to SEND POST=RESP). If STYPE=RESP, the SESSIONC operation is successfully completed when the response is moved to VTAM buffers and the RPL is available for reuse (similar to SEND POST=SCHED).

After the SESSIONC operation is completed, the following RPL fields are set:

The value 37 (decimal) is set in the REQ field, indicating a SESSIONC operation.
The value originally set in the USERFLD field of the NIB used to establish the session is set in the USER field of the RPL. The USER field is not set when SESSIONC is used to send a request rejected response to BIND.
The RTNCD and FDB2 fields are set as indicated in Return codes and sense fields for RPL-based macroinstructions.

Registers 0 and 15 are also set as indicated in Handling errors and special conditions.

If a CONTROL value of other than BIND, RQR, SDT, CLEAR, STSN, or SWITCH is used, then return code (RTNCD,FDB2) "CONTROL not valid" is issued.

If the SESSIONC is issued for a session that has been terminated, a return code (RTNCD,FDB2)=(0C,0B) can be posted.

For unauthorized application programs for which CONTROL=SWITCH is specified, if AAREALN is not zero and the area pointed to by AAREA and delimited by AAREALN is not entirely within user storage, then return code (RTNCD,FDB2)= (14,1E) is posted.

If CONTROL=SWITCH is specified and AAREALN specifies a length greater than zero but less than the length of control vector hex 29, then the returned data is truncated and return code (RTNCD,FDB2)=(00,05) is posted.

If SESSIONC is used to send a session-control request, when the macroinstruction is posted complete, the following RPL fields are set:

The SEQNO field is set to the sequence number assigned to the session-control request.
The CONTROL field is set to the value received in the response; however, this should be the same request code value as was in the original SESSIONC.
Additionally, if SESSIONC was originally used to send a STSN request, either the IBSQAC or OBSQAC fields (or both) are usually set to TESTPOS, TESTNEG, INVALID, or RESET depending on the action codes initially set in these fields when SESSIONC was issued. Table 1 lists the result codes that can be returned for each action code initially set. Either the IBSQVAL or OBSQVAL fields (or both) contain a sequence number when the corresponding IBSQAC or OBSQAC result code is set to TESTPOS or TESTNEG.
If the macroinstruction returns an error code, the SSENSEI, SSENSMI, and USENSEI field can be set indicating system-sense information, system-sense modifier, and user-sense information. See Return codes and sense fields for RPL-based macroinstructions for more information about these fields.