SIMLOGON macroinstruction

The application program that is functioning as a PLU uses the SIMLOGON macroinstruction to initiate sessions. SIMLOGON is also used to supply dial parameters when an application functioning as a PLU initiates a session with an LU associated with a PU that is coded in a switched major node.

SIMLOGON processing sends an Initiate request to the SSCP. After successfully receiving the Initiate request, the SSCP sends a CINIT request to the application program. VTAM® can then schedule the LOGON exit routine. See LOGON exit routine for a description of how the application program receives the CINIT request.

An application program must be authorized to issue the SIMLOGON macroinstruction (AUTH=ACQ on the APPL definition statement).

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 LUs 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 one of them. The RPL also indicates whether the session-initiation request can be queued.

The RPLAREA field can point to a user area containing up to 255 bytes of user data to be sent with the session-initiation request. The AREALEN field in the RPL must contain the length of the data. This user data is passed to the PLU in the CINIT request.

The NIBs, pointed to in the RPL, must be in contiguous storage with LISTEND=NO specified in all the NIBs except the last one, which must specify LISTEND=YES. The NAME field of each NIB contains the name of the LU with which to initiate a session.

In addition, if network-qualified names are being used, the NETID field of each NIB can contain the name of the network where the LU is located. The LOGMODE field of each NIB contains the logon mode name of a session parameter set and class of service suggested for use in establishing the session. If the application program is supplying the dial parameters, the NIB contains the address of the application program's dial parameter list. See Establishing parameters for sessions for more information about session communication.

If the USERFLD in the NIB is not 0, it is a correlator for the Initiate procedure, and is passed to the LOGON exit routine with a CINIT request if the procedure is successful. If the procedure fails, the USERFLD in the NIB is passed to the NSEXIT exit routine with a Notify request. If the USERFLD is 0, a Network Services Procedure Error (NSPE) request is passed to the NSEXIT routine if the procedure fails. The correlator permits the application program to determine if a CINIT or Notify is caused by SIMLOGON and, if so, which one. If the application program and the SLU support parallel sessions, multiple concurrent SIMLOGONs can be outstanding for the same SLU. In that case, a unique correlator for each SIMLOGON would be needed, if the application program wanted to match the CINIT request or Notify request with the SIMLOGON that caused it. That is because the PLU and the SLU names passed to the LOGON exit routine do not uniquely identify the session-initiation request if the same PLU and SLU are involved in multiple CINIT requests.

Note: When using OPTCD=ASY during session initiation, an application program task can be suspended unless provided with an RPL exit routine. See Initializing a session for information about using SIMLOGON OPTCD=ASY during session initiation.