LOGON exit routine

An application program can receive a request (through a CINIT request from the SSCP) to establish a session with another LU and act as the PLU of that session. The application program can handle each CINIT either by having VTAM® complete a previously issued OPNDST or schedule a LOGON exit routine. The LOGON exit routine technique enables the program to examine the CINIT or make other inquiries of VTAM using INQUIRE before establishing the session with OPNDST OPTCD=ACCEPT. OPNDST OPTCD=ACCEPT to accept the session or CLSDST to reject the session can be issued either in the LOGON exit routine or in another part of the program, after the LOGON exit routine returns to VTAM. If the session is rejected, sense data can be included on the negative response to the CINIT with CLSDST OPTCD=SENSE.

Note: When a CINIT is received, VTAM first checks for an outstanding OPNDST request that has not yet been completed. If there is no appropriate outstanding OPNDST request, VTAM then schedules a LOGON exit routine if one exists and the scheduling is allowed (see the following discussion of MACRF and SETLOGON). Therefore, a CINIT does not cause a LOGON exit routine to be scheduled if there is a pending OPNDST for the session. If no LOGON exit routine exists, and there is no outstanding OPNDST for the session, the CINIT is queued.

Regardless of the mechanism by which the LOGON exit routine is scheduled, the routine is asked to establish a session in which the application program acts as the PLU. The routine's principal task, therefore, is to determine whether it should honor the request and, when it determines that it should, issue OPNDST OPTCD=ACCEPT to establish the session. If the request is not honored, the routine issues CLSDST to reject the CINIT. If neither OPNDST nor CLSDST is issued, the CINIT remains queued, which can prevent the LU from establishing other sessions. If MACRF=LOGON is specified in the ACB and SETLOGON OPTCD=QUIESCE has not been issued, CINITs are queued for the application program regardless of whether a LOGON exit routine is available. A CINIT remains queued until the program issues OPNDST or CLSDST for the session unless a termination RU occurs. For example, a VARY TERM is issued or DACTLU/INOP flows. Queuing a CINIT does not necessarily mean that the CINIT is queued for eventual scheduling of the LOGON exit routine; it merely means that the CINIT is queued for an eventual OPNDST OPTCD=ACCEPT (or CLSDST). The LOGON exit routine is scheduled only if MACRF=LOGON is specified for the ACB and if the application program issued SETLOGON OPTCD=START. For further information about CINIT handling, see Table 1.

You can use SETLOGON OPTCD=HOLD and OPTCD=START to synchronize session setup requests. SETLOGON OPTCD=HOLD causes all subsequent CINIT requests to be queued and prevents the scheduling of the LOGON exit for session setup requests. When SETLOGON OPTCD=START is issued after SETLOGON OPTCD=HOLD, VTAM schedules the LOGON exit request. VTAM continues to drive the LOGON exit as usual until the application issues SETLOGON OPTCD=HOLD or SETLOGON OPTCD=QUIESCE. If a LOGON exit routine exists, SETLOGON OPTCD=START must be issued to cause session reallocation. If a LOGON exit routine exists and SETLOGON OPTCD=START is not issued, sessions are not reallocated as part of application activation.

A LOGON exit routine may be entered multiple times if the application supports this function. (Only an LU 6.2 application can support this function.) The application-capabilities vector specifies if the application program's LOGON exit routine can be entered multiple times during a session initiating processing for the same two session partners.

For a LOGON exit routine, information about the request that has been received is available in a read-only RPL provided by VTAM. This RPL resides in read-only VTAM storage and cannot be used by RPL-based macroinstructions. The following are also true for the RPL:

Read-only RPL (see Figure 2) can be examined by IFGRPL DSECT or by SHOWCB or TESTCB
RPL and the copy of the CINIT RU are freed when the exit routine returns to VTAM; any information needed from these areas must be copied before then.

Certain information can appear in control vectors appended to the CINIT RU.

Vector: Description
X'0D': Class-of-service and virtual route list
X'0E': Network-name control vector or network-qualified name of the PLU
X'0E': Network-name control vector or network-qualified name of the SLU
X'15': Network-qualified address pair control vector
X'2C': COS and TPF control vector
X'2D': Mode-name control vector
X'2F': Model-terminal-information control vector
X'59': Session authorization data control vector
X'5F': Extended fully qualified PCID control vector
X'60': Fully qualified PCID control vector
X'64': TCP information control vector
X'66': Data compression control vector

The read-only RPL's AREA field points to the beginning of a read-only copy of the CINIT RU. The RECLEN and AREALEN fields contain the length of the CINIT RU. The logon mode name and class-of-service name used to initiate the session are present in the CINIT. The following should be ignored:

The session key field containing network addresses
Any fields in the BIND image field in CINIT beyond the user data field.

Also, the lengths of the password and requester ID fields in CINIT are 0 because VTAM does not support these fields. The read-only RPL's AAREA field points to the beginning of the control vectors attached to the CINIT. Refer to SNA Formats for a list of control vectors on CINIT and their formats.

Table 1. LOGON exit routine: Registers upon entry
Reg	Contents
0, 2-13	Unpredictable
1	Address of a parameter list that includes the following: Word 1—address of ACB for application program Word 2—address of 8-byte symbolic name of SLU ¹ Name is placed in NAME field of NIB used for session Area is freed when exit routine returns to VTAM. Word 3—If LOGON exit routine is entered by SIMLOGON, this word contains USERFLD data from NIB used by SIMLOGON, otherwise this word is 0 Word 4—length of user data from the LU (this data can be accessed by INQUIRE OPTCD=LOGONMSG or examined in CINIT RU) Word 5—address of a VTAM-supplied, read-only RPL Word 6—CID of session to be established with LU ² Word 7—address of the network identifier parameter list ³
14	VTAM address that is branched to when LOGON exit routine completes processing
15	Address of LOGON exit routine
Note: This name is the LUALIAS name or the 8-byte name of the SLU taken from the CINIT. The application program should use the CID to identify the session for a particular logical unit. The network identifier parameter list is mapped by the ISTNRIPL DSECT. For more information, see Table 1.