REQSESS—Initiate a session, application program acts as the SLU

Purpose

The REQSESS macroinstruction is used to initiate a session in which the application program acts as the SLU.

Usage

REQSESS sends an Initiate request to the SSCP which in turn sends a CINIT request to the desired PLU. If the PLU accepts the session and sends a BIND, the application program's SCIP exit routine is scheduled with the BIND. The application program can then choose to establish the session or not. Before an application program can issue the REQSESS macroinstruction, it must have issued a SETLOGON OPTCD=START, or the REQSESS fails. Also, the ACB of the application program must specify MACRF=LOGON.

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

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

If PARMS=(NQNAMES=YES) on the ACB macroinstruction, and 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 build a session initiation request.

Syntax


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

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

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

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

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

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

>--+-----------------------------------------+------------------>
   |          (1)         (2)                |   
   '-,--OPTCD------=--(------+-+-ASY-+--+--)-'   
                             | '-SYN-'  |        
                             +-+-MTS--+-+        
                             | '-NMTS-' |        
                             '-NQ-------'        

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

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.

Input parameters

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

The following RPL operands apply to the REQSESS macroinstruction:

AAREA=0

The AAREA field must be set to 0 whenever the REQSESS macroinstruction is issued. If a value other than 0 is present in this field, the REQSESS macroinstruction fails, (RTNCD,FDB2)=(X'14',X'50').

ACB=acb_address

Indicates the ACB that identifies the application program issuing REQSESS.

AREA=user_data_address

Indicates the location of the user data that is to be sent to the PLU in the user data field of the CINIT. If this field is used, the RECLEN field must also be specified.

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) REQSESS 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) REQSESS 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 contains the symbolic name of the PLU with which the application program wants to be in session and if NQNAMES=YES, whose NIBNET field contains the network identifier in which the PLU resides. The LOGMODE field specifies the logon mode name to be used in the session being initiated. The USERFLD field can be used to specify a correlator to relate network services requests to the REQSESS. LISTEND must be set to YES. For further details, refer to REQSESS macroinstruction.

OPTCD=MTS

OPTCD=NMTS

If you set the MTS option code, VTAM expects to find valid MTS override data in an area pointed to by NIBMTSAR and formatted to match the ISTMTS DSECT. If you set the NMTS option code, VTAM does not expect any MTS override data.

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

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

OPTCD=NQ

OPTCD=NQ is an optional parameter. If OPTCD=Q is specified (or is present in the RPL from a previous operation), an error results, (RTNCD,FDB2)=(X'14',X'50').

If the PLU with which the REQSESS requests a session is not available (for example, (1) a VTAM PLU application program has not opened its ACB, (2) has opened an ACB that specified MACRF=NLOGON, (3) is in the process of closing its ACB, (4) has issued SETLOGON OPTCD=QUIESCE, or (5) is unavailable because of an error condition), the REQSESS macroinstruction is rejected with, for example, (RTNCD,FDB2)=(X'10',X'02'). If the PLU application program has opened an ACB that specifies MACRF=LOGON but has not issued a SETLOGON OPTCD=START, the session-initiation request is accepted and the REQSESS macroinstruction is completed successfully. The resulting CINIT is queued at the PLU application program until it does a SETLOGON OPTCD=START, OPNDST OPTCD=ACCEPT, or CLSDST OPTCD=RELEASE.

OPTCD=SYN

OPTCD=ASY

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

RECLEN=user_data_length

Indicates the number of bytes of user data (located at the AREA address) to be sent to the receiving PLU. The value in RECLEN must be 255 (decimal) or less. If the RECLEN field is set to 0, the AREA field is ignored.

Examples

CALLPRI  REQSESS RPL=RPLA1,NIB=NIBPA1,OPTCD=(ASY,NQ),                  C
               EXIT=RQEXRTN,AREA=LOGMSG,                               C
               RECLEN=L'LOGMSG,AAREA=0
         .
         .
         .
RPLA1    RPL   ACB=ACB1,AM=VTAM
NIBPA1   NIB   NAME=GRACIE,LISTEND=YES,                                C
               LOGMODE=MODE1
LOGMSG   DC    C'LOGON REQUEST FROM USER 09'

CALLPRI requests a session between the application program associated with ACB1, which acts as the secondary end of the session, and application program GRACIE, which acts as the primary end of the session. When the REQSESS macroinstruction is completed, RQEXRTN is scheduled.

Completion information

A REQSESS operation is successfully completed when the SSCP responds to the Initiate request. This can be before or after BIND has been received for the requested session.

After the REQSESS macroinstruction is completed, the following RPL fields are set:

The value 41 (decimal) is set in the REQ field, indicating a REQSESS request.
The RTNCD and FDB2 fields are set as indicated in Return codes and sense fields for RPL-based macroinstructions.
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. More information about these fields is 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.