CLSDST—Terminate sessions, application program is the PLU

Purpose

The CLSDST macroinstruction is used to terminate sessions in which the application program is acting as the PLU. CLSDST sends UNBIND requests from the PLU to the SLUs to terminate active sessions (sessions for which BIND has been sent). CLSDST sends TERMINATE for sessions which are queued. CLSDST also rejects CINIT requests received at the PLU for the specified SLU. The CLSDST macroinstruction can also be used to initiate the next session the SLU has. In addition, the CLSDST macroinstruction can be used to terminate a queued session when OPTCD=TERMQ is used.

Usage

Before issuing the CLSDST 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.

The CLSDST macroinstruction employs the RPL, and optionally the NIB, to identify the set of sessions to be terminated. A detailed description of the parameters and operation of the CLSDST macroinstruction is contained in Establishing and terminating sessions with logical units.

VTAM® receives control from the CLSDST macroinstruction in the addressing mode of the application program that issued the macroinstruction and returns control to the application program in that same mode.

Syntax


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

>--+-----------------------------------------------------+------>
   |                                                 (1) |   
   '-,--AAREA--=--target_plu's_symbolic_name_address-----'   

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

>--+-----------------------------------+------------------------>
   |                               (1) |   
   '-,--AREA--=--user_data_address-----'   

>--+---------------------------------------------+-------------->
   |                                         (1) |   
   '-,--ARECLEN--=--target_plu's_name_length-----'   

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

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

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

>--+---------------------------------------------+-------------->
   |          (1)         (2)                    |   
   '-,--OPTCD------=--(------+-+-ASY-+------+--)-'   
                             | '-SYN-'      |        
                             +-+-MTS--+-----+        
                             | '-NMTS-'     |        
                             +-+-PASS----+--+        
                             | +-RELEASE-+  |        
                             | '-TERMQ---'  |        
                             +-+-SENSE--+---+        
                             | '-NSENSE-'   |        
                             '-+-SONCODE--+-'        
                               '-NSONCODE-'          

>--+-----------------------------------------------------------+-->
   |                  (3)                                  (1) |   
   '-,--PARMS--=--(--------+-SONCODE--=--code---------+--)-----'   
                           '-THRDPTY--=--+-NONOTIFY-+-'            
                                         '-NOTIFY---'              

>--+------------------------------------+----------------------->
   |                                (1) |   
   '-,--RECLEN--=--user_data_length-----'   

>--+------------------------------+----------------------------->
   |                          (1) |   
   '-,--SSENSEO--=--+-0-----+-----'   
                    +-CPM---+         
                    +-FI----+         
                    +-RR----+         
                    '-STATE-'         

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

>--+-------------------------------------+---------------------><
   |                                 (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.
You can code more than one suboperand on OPTCD, but code no more than one from each group.
You can code more than one suboperand on PARMS, but code no more than one from each group.

Input parameters

RPL=rpl_address: Indicates the RPL that specifies which kind of processing CLSDST is to perform.

The following RPL operands apply to the CLSDST macroinstruction:

AAREA=target_plu's_symbolic_name_address

Indicates the name of the target PLU of a CLSDST OPTCD=PASS. If NQNAMES=NO, the name must be 8 bytes long, padded to the right with blanks. If NQNAMES=YES, the name can be 8 bytes long, padded to the right with blanks or it can be an 8-byte long network identifier padded to the right with blanks, followed by an 8-byte name padded with blanks to the right. The target PLU cannot be the application program that is issuing the CLSDST OPTCD=PASS.

ACB=acb_address

Indicates the ACB that identifies the application program issuing CLSDST.

AREA=user_data_address

Indicates the location of the user data to be sent to the target PLU of CLSDST OPTCD=PASS. The contents and format of the user data are determined by the logical units. The user data is equivalent to the user data field of an Initiate request or a character-coded logon. User data is sent only if OPTCD=PASS is set.

ARECLEN=target_plu's_name_length

Indicates the length (in bytes) of the data contained in the area indicated by the AAREA parameter.

ARG=(register)

Indicates the register containing the CID of the session to be terminated.

Note:

The NIB and the ARG operands occupy the same physical field (RPLARG) in the RPL. If the last macroinstruction operand used to set or modify this field was ARG=(register), or if the field has been left unchanged since VTAM inserted a CID into it, VTAM recognizes that this field contains a CID. If the last operand used to set or modify this field was NIB=address, VTAM recognizes that the field contains an NIB address.
If your application uses the RPL DSECT, IFGRPL, you must clear the RPLNIB bit if a CID is being inserted into the RPLARG field.

BRANCH

For application programs running in supervisor state under a TCB, BRANCH indicates whether authorized path processing is to be used. See Authorized path.

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.

ECB

Indicates that an ECB is posted when an asynchronous (OPTCD=ASY) CLSDST 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) CLSDST 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.

NIB=nib_address

Indicates the NIB whose NAME field identifies the sessions to be terminated. (See Scope of CLSDST for details.) If the NIB operand is not specified, the RPLARG field must contain the CID of the session.

If OPTCD=PASS is specified, the NIB optionally has a LOGMODE field which specifies the name of the session parameter set to be used in establishing a new session.

If OPTCD=TERMQ is specified, a NIB must be supplied, which identifies the NAME of the session partner, which identifies the session to be terminated.

If the application program issues CLSDST OPTCD=PASS with PARMS=(THRDPTY=NOTIFY), the USERFLD contents are passed as a correlator to the application program's NSEXIT exit routine, if it is scheduled.

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.

OPTCD=MTS

OPTCD=NMTS

If you code OPTCD=MTS, VTAM expects to find valid model terminal support (MTS) override data in an area pointed to by NIBMTSAR and formatted to match the ISTMTS DSECT. OPTCD=MTS is valid only in combination with OPTCD=PASS and requires the specification of the NIB operand. If you code OPTCD=NMTS, VTAM does not expect any MTS override data, and the NIB operand remains optional.

If you do not code either OPTCD=MTS or OPTCD=NMTS on this macroinstruction, VTAM uses the value left over from the previous use of the RPL.

Note: NIBMTSAR is an alternate name for the NIBNDAR field used by the OPNDST and OPNSEC macroinstruction to point to BIND image data. Therefore, do not code both MTSAREA and BNDAREA on the same macroinstruction.

OPTCD=NSENSE

OPTCD=SENSE

When a CLSDST macroinstruction is issued with OPTCD=RELEASE to reject a CINIT request, OPTCD=NSENSE or OPTCD=SENSE indicates whether values were specified with the SSENSEO, SSENSMO, and USENSEO operands. If OPTCD=NSENSE is coded, VTAM rejects the CINIT with a sense value of X'08010000'. If OPTCD=SENSE is specified, VTAM rejects the CINIT with the application-specified sense values in the SSENSEO, SSENSMO, and USENSEO fields of the RPL.

Note: Only a nonzero sense is allowed for OPTCD=SENSE. If you specify OPTCD=SENSE, and a sense code of X'00000000', CLSDST is rejected with RTNCD/FDB2=X'14',X'50' (RPL field not valid).

OPTCD=NSONCODE

OPTCD=SONCODE

If OPTCD=NSONCODE, VTAM uses an UNBIND SON code of X'01'. If OPTCD=SONCODE, VTAM uses the SON code specified in the RPL with the PARMS=(SONCODE=code) operand.

OPTCD=PASS

OPTCD=RELEASE

OPTCD=TERMQ

For CLSDST (PASS), two names can be network-qualified: the name of the LU whose session is to be terminated, and the name of the primary LU that the session is being passed to.

If PARMS=(NQNAMES=NO) on the ACB macroinstruction and ARECLEN is greater than or equal to 8, the 8-byte name in AAREA is used as the target of the primary LU that the session is being passed to.
If PARMS=(NQNAMES=YES) on the ACB macroinstuction and ARECLEN is greater than or equal to 16, the network-qualified name in AAREA is used as the target of the primary LU that the session is being passed to.
If PARMS=(NQNAMES=YES) on the ACB macroinstuction and ARECLEN is greater than or equal to 8 but less than 16, the 8-byte name in AAREA is used as the target of the primary LU that the session is being passed to.

The format of the network-qualified name in AAREA is the 8-byte network identifier (padded with blanks, if necessary) followed by the 8-byte resource name (padded with blanks, if necessary).

If AAREA contains a network-qualified name, VTAM initiates a session between the PLU, specified as a network-qualified name in RPLAAREA, and the SLU this application program is currently in session with. The name of the SLU is specified as described under Network-qualified names with CLSDST.

When the session setup is completed, regardless of whether the setup is successful, the NSEXIT is scheduled, and the NOTIFY request or the NSPE request is presented to the exit. The control vectors X'0E' are removed from the NOTIFY request that is presented to the initiating application program; therefore, the NOTIFY request appears no different from the NOTIFY request in previous releases of VTAM. However, the network-qualified names are available and are pointed to by Word 7 on the parameter list passed to the NSEXIT.

The control vector X'59' for session authorization data, if present in the original CINIT, may not be passed to the initiating LU. This action is determined by settings for the SMEAUTH start option and the structure of the control vector as it is built by the session management exit. The SMEAUTH start option can override the session management exit's setting. For more information, refer to z/OS Communications Server: SNA Resource Definition Reference and z/OS Communications Server: SNA Customization.

If AAREA contains a non-network-qualified name, VTAM initiates a session between the PLU, specified as a non-network-qualified name in RPLAAREA, and the SLU this application program is currently in session with. The name of the SLU is specified as described under Network-qualified names with CLSDST. The name translations that occur for other non-network-qualified names (for example, for names in SIMLOGON) also occur for the name in RPLARREA.

If (PARMS=(THRDPTY=NOTIFY)) is specified, when the session setup is completed, regardless of whether the setup is successful, the NSEXIT is scheduled, and the NOTIFY request or the NSPE request is presented to the exit.

When RELEASE is set, VTAM determines the identity of the logical unit's next session partner (if any). When PASS is set, the application program determines the identity of the logical unit's next session partner; an Initiate request is sent to the SSCP to request a session between the SLU and the target PLU whose symbolic name is indicated in the AAREA field of the RPL used by CLSDST. If the AREA and RECLEN fields are also set, user data is sent to the target PLU in the CINIT request.

If OPTCD=TERMQ is coded, VTAM only terminates queued sessions (active sessions are not terminated). When TERMQ is specified, the session partner name must be used via the NIB. CID cannot be used for this option. VTAM sends a TERMINATE for this option.

OPTCD=SYN

OPTCD=ASY

If SYN option code is set, control is returned to the application program when the CLSDST operation has completed. If ASY option code is set, control is returned as soon as VTAM has accepted the request. Once the CLSDST 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 CLSDST operation, you should not use the SYN option if you are suspending the CLSDST-issuing task or if SRB for this time is undesirable. Use the ASY option code, instead.

PARMS=(SONCODE=code)

The application program sets the UNBIND SON code by specifying PARMS=(SONCODE=code) and OPTCD=SONCODE, where code is the 1-byte UNBIND type code used by VTAM on an UNBIND RU. See SNA Formats , which contains a description of the UNBIND RU, for definitions of the UNBIND type codes (SON codes). VTAM does not validate the code specified in this parameter.

If PARMS=(SONCODE=X'FE') is specified, system-sense and user-sense are set with the existing SSENSEO, SSENSMO, and USENSEO RPL fields.

PARMS=(THRDPTY=NOTIFY)

PARMS=(THRDPTY=NONOTIFY)

Indicates for CLSDST OPTCD=PASS whether the application program receives notification when the new session is established between the target PLU and the SLU (that is, when a positive response is received to the BIND for that session). If THRDPTY=NOTIFY is specified, and the session is established, the application program receives a Notify request in its NSEXIT exit routine. If the session setup fails, the application program receives an NSPE or Notify in its NSEXIT exit routine, regardless of the setting of this parameter.

RECLEN=user_data_length

Indicates how many bytes of user data are to be sent to the target PLU of a CLSDST OPTCD=PASS. The value in RECLEN can be no larger than 255. If RECLEN is set to 0, the AREA field is ignored and no user data is sent.

SSENSEO=0

SSENSEO=CPM

SSENSEO=FI

SSENSEO=RR

SSENSEO=STATE

This field can be used to provide application-specified sense values for negative responses to CINIT or for UNBIND. See the section on the TERMSESS macroinstruction for more information.

SSENSMO=system-sense_modifier_value

This field can be used to provide application-specified sense values for negative responses to CINIT or for UNBIND. See the TERMSESS macroinstruction for more information.

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

USENSEO=user-sense_value

This field can be used to provide application specified sense values for negative responses to CINIT or for UNBIND. See the TERMSESS macroinstruction for more information.

Specify any decimal integer 0–65535 inclusive, or specify a 2-byte hexadecimal or character constant.

Examples

CL1      CLSDST RPL=RPL1,                                              C
               ACB=ACB1,                                               C
               NIB=NIB3,                                               C
               AAREA=APPLNAME,                                         C
               AREA=LGNMSG,RECLEN=60,                                  C
               ECB=POSTIT1,OPTCD=(ASY,PASS),                           C
               PARMS=(THRDPTY=NOTIFY)
         .
         .
         .
         .
         .
         .
POSTIT1  DS    F
NIB3     NIB   NAME=LU1,LOGMODE=BATCH
APPLNAME DC    CL8'PLOTTER'
LGNMSG   DC    CL60'LOGON FROM LU1'

CL1 terminates the session with the logical unit represented in NIB3 (LU1) after initiating a session between LU1 and the application program named PLOTTER. This macroinstruction also specifies a logon mode name (BATCH) and 60 bytes of information containing a user data field (LGNMSG). The user data field and the session parameters that VTAM derives from the logon mode name can be accessed (using INQUIRE) by the application program receiving the CINIT resulting from the Initiate before it issues OPNDST. The logon mode name (BATCH in this example) and class-of-service name are contained in the CINIT request and can be accessed by the target PLUs LOGON exit routine. The application program's NSEXIT routine is driven with a Notify request when the session between LU1 and PLOTTER has been established.

CL2      CLSDST RPL=RPL2,                                              C
               ARG=(3),                (SESSION TO BE TERMINATED)      C
               ECB=POSTIT2,                                            C
               OPTCD=(ASY,RELEASE,SENSE),                              C
               SSENSEO=5,SSENSMO=6                                     C

CL2 terminates the session whose CID has been placed in register 3. Unlike the first example, CL2 does not initiate a session with a specified PLU.

CL3      CLSDST RPL=RPL3,                                              C
               ACB=ACB1,                                               C
               NIB=NIB6,               (SESSION TO BE TERMINATED)      C
               AAREA=APPLNAME,         (APPLICATION TO RECEIVE CINIT   C
                                        REQUEST)                       C
               RECLEN=0,               (NO USER DATA)                  C
               ECB=POSTIT3,OPTCD=(ASY,PASS)
         .
         .
         .
         .
         .
         .
APPLNAME DC    CL8'PLOTTER'
POSTIT3  DC    F'0'
NIB6     NIB   NAME=LU3

CL3 terminates the session with the logical unit represented by NIB6 (LU3), and initiates a session between LU3 and the application program named PLOTTER. Because the RECLEN field is being set to 0, no user data field is sent to PLOTTER. The default logon mode name of 8 blanks is assumed.

Completion information

The CLSDST operation is successfully completed when either:

The SSCP responds to the Terminate request generated by CLSDST for CLSDST OPTCD=TERMQ.
The current session terminates for CLSDST OPTCD=RELEASE or PASS. For CLSDST OPTCD=PASS, completion does not depend on the action (accepting or rejecting the session) of the target PLU.

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

The value 31 (decimal) is set in the REQ field, indicating a CLSDST request.
The RTNCD and FDB2 fields are set as indicated in Return codes and sense fields for RPL-based macroinstructions.

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

If the macroinstruction returns an error code, the SSENSEI, SSENSMI, and USENSEI fields 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.

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