SIMLOGON—Initiate a session, application program acts as the PLU

Purpose

The SIMLOGON macroinstruction is used to initiate sessions in which the application program issuing SIMLOGON acts as the PLU. SIMLOGON processing sends an Initiate request to the SSCP. If successful, this causes a CINIT request to be sent from the SSCP to the application program, which might result in the LOGON exit routine being scheduled. See LOGON exit routine for a description of how the application program receives the CINIT request.

Usage

The SIMLOGON macroinstruction uses the RPL to pass information to VTAM®. The RPL points to a list of NIBs which contain the names of the logical units with which sessions should be initiated. The RPL indicates whether sessions should be initiated for as many NIBs in the list as possible, or just for one of them. The RPL also indicates whether the session-initiation request can be queued.

For a detailed description of the operation of the SIMLOGON macroinstruction, refer to SIMLOGON macroinstruction.

Before issuing the SIMLOGON 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 SIMLOGON macroinstruction in the addressing mode of the application program that issued the macroinstruction and returns control to the application program in that same mode.

The SIMLOGON macroinstruction is used by the application program to initiate primary and backup XRF sessions from the PLU.

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


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

>--+----------------------------+------------------------------->
   |                        (1) |   
   '-,--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-----'   

>--+---------------------------------------------+-------------->
   |                  (2)                    (1) |   
   '-,--OPTCD--=--(------+-+-ASY-+------+--)-----'   
                         | '-SYN-'      |            
                         +-+-BACKUP--+--+            
                         | '-NBACKUP-'  |            
                         +-+-CONALL-+---+            
                         | '-CONANY-'   |            
                         +-+-Q--+-------+            
                         | '-NQ-'       |            
                         +-+-QALL-----+-+            
                         | +-QNOTENAB-+ |            
                         | '-QSESSLIM-' |            
                         '-+-RELRQ--+---'            
                           '-NRELRQ-'                

>--+------------------------------------+----------------------><
   |                                (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 SIMLOGON is to perform.

The following RPL operands apply to the SIMLOGON macroinstruction:

ACB=acb_address

Indicates the ACB that identifies the application program issuing SIMLOGON.

AREA=user_data_address

Indicates the location of the data that VTAM is to pass to the application program in the user data field of CINIT. The contents and format of the data are determined by the application program. They are equivalent to the user data field of an Initiate or a character-coded logon.

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) SIMLOGON 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) SIMLOGON 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. For details about these operands, refer to the RPL macroinstruction description in this chapter.

NIB=nib_address

Indicates the NIB whose NAME field identifies the SLU for the session being initiated and whose LOGMODE field specifies the logon mode name to be used, and if NQNAMES=YES, whose NIBNET field contains the network where the SLU resides. If the NIB field contains the address of a list of NIBs, that is LISTEND=NO (in the NIB pointed to), processing depends on the CONALL or CONANY option code. USERFLD can be used to specify a correlator to relate network services requests to this SIMLOGON.

OPTCD=BACKUP

OPTCD=NBACKUP

OPTCD=BACKUP is used to specify the initiation of a backup XRF session. Only one backup XRF session can be created per primary XRF session.

OPTCD=BACKUP is used only if either:

A primary XRF session exists for the same SLU.
This is the "normal" case, when the active XRF application creates the primary XRF session and then signals the alternate XRF application to start a backup XRF session.
A backup XRF session exists for the same SLU.
This is the exceptional case, when the NCP takes down the primary XRF session, but does not terminate its session with the SLU, keeping the backup session up pending a switch request state. In this case, if the primary XRF session desires to "recover" itself, it must first restart itself as a backup by issuing a SIMLOGON OPTCD=BACKUP, and then issuing a SESSIONC CONTROL to become the primary XRF session. In this case, the original backup session remains intact throughout the primary session recovery.

OPTCD=NBACKUP is the default and results in a session initiation request that does not specify a backup XRF session.

OPTCD=CONANY

OPTCD=CONALL

When CONANY is set, a session is initiated for the first available logical unit in the NIB list. Control is passed to the application program's LOGON exit routine, if one exists, when the resulting CINIT has been generated. When CONALL is set, a session is initiated for each available logical unit in the NIB list. If there is only one NIB, the setting of this option code does not matter.

OPTCD=Q

OPTCD=NQ

If OPTCD=NQ is specified, then the Initiate requests sent to the SSCP indicate sessions might not be queued, and the Initiate succeeds only if the logical unit is immediately available. If OPTCD=Q is specified, then the Initiate requests sent to the SSCP indicate sessions can be queued if the logical unit is not enabled or is at its session limit. (OPTCD=QALL or OPTCD=QSESSLIM or OPTCD=QNOTENAB determines whether both or just one of these conditions causes the request to be queued.) In that case, the Initiate succeeds if the logical unit is active, connected, and not inhibited for sessions in which it acts as the SLU. (See Defining LUs for the definitions of these states.) Once the logical unit becomes available, a pending-active session is created immediately.

OPTCD=QALL

OPTCD=QSESSLIM

OPTCD=QNOTENAB

This option is meaningful only if the Q option is set. IF QALL is set, the session can be queued if the logical unit is not enabled or is at its session limit. If QSESSLIM is set, the session can be queued only if the logical unit is at its session limit. If QNOTENAB is set, the session can be queued only if the logical unit is not enabled for a session in which it is the SLU.

OPTCD=RELRQ

OPTCD=NRELRQ

This option is meaningful only if the Q option code is set. If RELRQ is set and if the device-type logical unit with which the session is being requested is in session with another application program, VTAM invokes that application program's RELREQ exit routine. If NRELRQ is set, the other application program is not notified of your request for the logical unit. For further details, see SIMLOGON macroinstruction.

OPTCD=SYN

OPTCD=ASY

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

Note: When using SIMLOGON OPTCD=ASY, an application program task could be suspended if an RPL exit routine is not provided. See Initializing a session for details.

RECLEN=user_data_length: Indicates how many bytes of user data are to be sent. The value in RECLEN must be decimal 255 or less. If no user data is to be sent, RECLEN should be set to 0 and the AREA field is ignored.

Examples

SIM1     SIMLOGON RPL=RPL1,ACB=ACB1,NIB=NIBLIST1,                      C
               AREA=LGNMSG,RECLEN=60,EXIT=CHECKPGM,                    C
               OPTCD=(ASY,CONALL,NRELRQ,Q)
         .
         .
         .
LGNMSG   DC    CL60'LOGON FROM NIBLIST1 STATION'
ACB1     ACB   MACRF=LOGON
NIBLIST1 NIB   NAME=STATIONA,LISTEND=NO,                               C
               LOGMODE=BATCH
         NIB   NAME=STATIONB,LISTEND=NO
         NIB   NAME=STATIONC,LISTEND=YES

SIM1 initiates sessions between ACB1 and all of the logical units represented in NIBLIST1. Each Initiate contains a 60-byte user data field taken from LGNMSG. The logon mode name for STATIONA is BATCH; STATIONB and STATIONC use a default logon mode name. The CONALL option code indicates that Initiate requests are to be generated for all the available logical units represented in the list. NRELRQ indicates that if any of the logical units of NIBLIST1 is in session with an ACB other than ACB1, that ACB's RELREQ exit routine is not to be scheduled. After the SIM1 operation is completed, control is transferred to CHECKPGM.

Completion information

The SIMLOGON operation is successfully completed when the response is received for the Initiate request sent to the SSCP. This response is sent when a queued or pending active session is created, or when it is recognized that a session cannot be initiated. The sending of the CINIT request (and, therefore, the scheduling of the LOGON exit routine) might not occur immediately after the SIMLOGON macroinstruction is posted. Also, if ECB posting is used, the LOGON exit routine or NSEXIT exit routine can be scheduled for the requested session before the application program recognizes that the SIMLOGON has completed successfully.

When the SIMLOGON operation is completed, the following RPL fields are set:

The value 22 (decimal) is placed in the REQ field, indicating a SIMLOGON 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. See Return codes and sense fields for RPL-based macroinstructions for more information about these fields.
If the RTNCD and FDB2 fields are zeroes, check NIBSLWRK in each NIB to determine which is successful.

OPTCD=Q is not allowed when OPTCD=BACKUP is specified, because session queueing is not supported for backup XRF sessions. An error is posted with return code (RTNCD,FDB2)= (14,7D) if OPTCD=(BACKUP,Q) is specified.

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