SETLOGON—Modify an application program's capability to establish sessions
Purpose
- Whether VTAM® is to schedule an application program's LOGON exit routine when a CINIT request is received
- Whether an application program is enabled to act as an SLU
- The application's use of persistent sessions or generic resources.
For further information on some of the terms used in the following paragraphs, refer to Defining LUs and to Table 1. See also the OPTCD=APPSTAT section of the INQUIRE macroinstruction description in this topic.
Usage
The nine types of SETLOGON requests are START, STOP, QUIESCE, HOLD, NPERSIST, PERSIST, GNAMEADD, GNAMEDEL, and GNAMESUB. The option code in SETLOGON's RPL determines which type is used.
Although SETLOGON START, STOP, QUIESCE, HOLD, GNAMEADD, GNAMEDEL, and GNAMESUB cannot be used if the ACB was opened with MACRF=NLOGON, SETLOGON PERSIST and NPERSIST can be used.
The START version of SETLOGON causes any application program issuing INQUIRE OPTCD=APPSTAT to be told that your application program is active.
The first SETLOGON OPTCD=START issued after OPEN has been executed causes VTAM to schedule the LOGON exit routine for each CINIT request that has been received. It also allows subsequent CINIT requests to schedule the LOGON exit routine. The LOGON exit routine cannot be scheduled before the first SETLOGON OPTCD=START; therefore, any CINITs received prior to SETLOGON OPTCD=START are queued.
Additionally, the first SETLOGON OPTCD=START causes VTAM to mark the application program enabled for sessions in which it acts as the secondary logical unit. Before the first SETLOGON OPTCD=START occurs, the application program is disabled for sessions in which it is to act as the secondary logical unit. If queuing is specified by the session initiator, an attempt to initiate such a session is queued; otherwise, it is rejected. The first SETLOGON OPTCD=START causes any such queued session to become pending active, which should eventually result in a BIND request received in the SCIP exit routine. Note that the SCIP exit routine cannot be scheduled with a BIND request before the first SETLOGON OPTCD=START occurs.
Subsequent SETLOGON START requests can be used in conjunction with SETLOGON HOLD to pace session setup requests. (You might want to use pacing in the event that storage shortages occur.) When SETLOGON START is issued after SETLOGON HOLD, VTAM schedules the LOGON exit for each queued CINIT request, and schedules the SCIP exit for each queued BIND request. VTAM continues to drive the LOGON and SCIP exits as usual until the application issues SETLOGON HOLD or SETLOGON QUIESCE.
The STOP version of SETLOGON does not stop the scheduling of the LOGON or SCIP exit routines. However, any application program issuing INQUIRE OPTCD=APPSTAT for your ACB is told that new sessions should not be initiated with your application program. Thus, the STOP version can be used only for private application program protocols and is not enforced by VTAM.
The QUIESCE version of SETLOGON causes VTAM to indicate that the application program is inhibited for any new sessions. The only way to initiate new sessions is to close and reopen the ACB. However, any CINIT or BIND requests already queued at the application program logical unit are unaffected by SETLOGON OPTCD=QUIESCE. Thus, for these pending active sessions, OPNDST OPTCD=ACCEPT and OPNSEC can complete normally. An application program might want to use this type of SETLOGON at the end of a day's work, prior to closing the ACB; this would give the application program a chance to handle its current load of active and pending active sessions without any new ones being initiated. Any application program issuing INQUIRE OPTCD=APPSTAT for your ACB is told that your application program is shutting down and cannot accept new sessions. Any attempts to initiate sessions with your application program are rejected.
You can use the SETLOGON macroinstruction with the option codes, OPTCD=HOLD and OPTCD=START, to pace session setup requests. SETLOGON HOLD causes all subsequent CINIT and BIND requests to be queued and prevents the scheduling of the LOGON and the SCIP exits for session setup requests. When SETLOGON START is issued after SETLOGON HOLD, VTAM schedules the LOGON exit for each queued CINIT request and the SCIP exit for each queued BIND request. VTAM continues to drive the LOGON and SCIP exits as usual until the application issues SETLOGON HOLD or SETLOGON QUIESCE.
For this application program, GNAMEADD indicates that VTAM recognizes an association between the network name in the ACB macroinstruction and the generic name coded on the GNAME parameter of the NIB macroinstruction; GNAMEDEL causes VTAM to terminate that association. The SETLOGON OPTCD=GNAMEADD must be issued before SETLOGON OPTCD=START is issued. The application can specify whether it wants to own the affinities for all the sessions that are established with it. The application does this by using the AFFIN keyword of the NIB macroinstruction. For more details, see NIB—Create a node initialization block.
An application can be a subordinate of another application that is using a generic name. In this case, the subordinate application uses OPTCD=GNAMESUB to have its sessions included in the other application's session count for workload balancing purposes. When GNAMESUB is used, the NIB must indicate the application network name (NAME parameter) of the generic resource application to which this application is subordinate and the generic resource name (GNAME parameter).
An application that is capable of persistence uses SETLOGON OPTCD=PERSIST to enable persistent LU-LU session support. The application can also indicate support of receipt of various forced takeover requests by coding the FORCETKO operand to indicate the required support level on the SETLOGON OPTCD=PERSIST statement. This same application uses SETLOGON OPTCD=NPERSIST to disable persistence, but this SETLOGON OPTCD does not affect the setting of whether the application supports receipt of a forced takeover.
Before issuing the SETLOGON 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 SETLOGON 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
>>-+------+--SETLOGON--RPL--=--rpl_address----------------------> '-name-' >--+----------------------------+-------------------------------> | (1) | '-,--ACB--=--acb_address-----' >--+---------------------------+--------------------------------> | (1) | '-,--BRANCH--=--+-NO--+-----' '-YES-' >--+--------------------------------------+---------------------> | (1) | +-,--ECB--=--INTERNAL------------------+ +-,--ECB--=--ecb_address---------------+ | (1) | '-,--EXIT--=--exit_routine_address-----' >--+-----------------------------------------------+------------> | (2) (1) | '-,--OPTCD--=--(--------+-+-ASY-+------+--)-----' | '-SYN-' | '-+-GNAMEADD-+-' +-GNAMEDEL-+ +-GNAMESUB-+ +-HOLD-----+ +-NPERSIST-+ +-PERSIST--+ +-QUIESCE--+ +-START----+ '-STOP-----' >--+----------------------------+-------------------------------> | (3) | '-,--NIB--=--nib_address-----' >--+----------------------------------------------------------+->< | (4) (1) | '-,--PARMS--=--(--+-MAXSESS--=--value-------------+--)-----' | (5) | +-PSTIMER--=--value-------------+ | (6) | '-------FORCETKO--=--+-NONE---+-' +-SINGLE-+ +-MULTI--+ '-ALL----'
- 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.
- NIB is valid only when OPTCD=GNAMEADD, OPTCD=GNAMEDEL, or OPTCD=GNAMESUB is coded.
- PARMS=(MAXSESS=value) is valid only when OPTCD=GNAMEADD is coded.
- PARMS=(PSTIMER=value) is valid only when OPTCD=PERSIST is coded. PSTIMER may be specified with FORCETKO on the same SETLOGON OPTCD=PERSIST invocation.
- PARMS=(FORCETKO=NONE|MULTI|SINGLE|ALL) is valid only when OPTCD=PERSIST is coded. FORCETKO can be specified with PSTIMER on the same SETLOGON OPTCD=PERSIST invocation.
Input parameters
- RPL=rpl_address
- Indicates the RPL that specifies which kind of processing SETLOGON is to perform.
- ACB=acb_address
- Indicates the ACB that identifies the application program issuing SETLOGON.
- 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)
SETLOGON 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) SETLOGON 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 topic.
- NIB=nib_address
- Indicates the NIB that specifies the generic name for the application. For OPTCD=GNAMESUB, the NIB also contains the application program network name of the particular generic resource instance. NIB= is valid only with the use of OPTCD=GNAMEADD, OPTCD=GNAMEDEL, or OPTCD=GNAMESUB.
- OPTCD=GNAMEADD
- OPTCD=GNAMEDEL
- OPTCD=GNAMESUB
- OPTCD=HOLD
- OPTCD=QUIESCE
- OPTCD=START
- OPTCD=STOP
- OPTCD=NPERSIST
- OPTCD=PERSIST
- Indicates information about the application program's session-establishment capability. Refer to the introductory description of the SETLOGON macroinstruction for details.
- OPTCD=SYN
- OPTCD=ASY
- If the SYN option code is set, control is returned to the application
program when the SETLOGON operation has completed. If ASY option code
is set, control is returned as soon as VTAM has
accepted the request. After the SETLOGON operation has been 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 topic for
details about OPTCD=SYN or OPTCD=ASY.
Because it might take VTAM a relatively long time to complete the SETLOGON operation, you should not use the SYN option if suspending the SETLOGON-issuing task or SRB for this time is undesirable. Use the ASY option code, instead.
- PARMS=(MAXSESS=value)
- This code, used only with OPTCD=GNAMEADD, indicates the maximum number of sessions allowed for the application. The total number of sessions includes sessions from subordinate generic resources. See description of generic resources for information about subordinate generic resources.
- PARMS=(PSTIMER=value)
- This code, used only with OPTCD=PERSIST, indicates how long an application program can remain pending recovery. The recovering application must successfully issue an OPEN ACB before the timer expires or the sessions will be terminated. The initial value is 0, which means the safety timer is not used. The maximum timeout interval is 86400 seconds (24 hours). A default value does not exist. If PSTIMER is not specified, the current value is not changed. If a value is specified, PSTIMER must be coded on the same macroinstruction as OPTCD=PERSIST.
- PARMS=(FORCETKO)
- Indicates whether the application accepts some form of persistent sessions takeover requests when this application image is not pending some form of recovery currently. This parameter is valid only if OPTCD=PERSIST is also coded. There is no default for the FORCETKO operand, although an application will, unless otherwise indicated, support receipt of SNPS takeover requests only. If FORCETKO is not specified on the SETLOGON OPTCD=PERSIST, then the current setting for the application is unchanged.
- PARMS=(FORCETKO=ALL)
- The application accepts either SNPS or MNPS forced takeover requests when the application does not require some form of recovery processing.
- PARMS=(FORCETKO=MULTI)
- The application accepts only MNPS forced takeover requests when the application does not require recovery processing. SNPS forced takeover requests will be rejected.
- PARMS=(FORCETKO=NONE)
- The application does not accept SNPS or MNPS forced takeover requests.
- PARMS=(FORCETKO=SINGLE)
- The application accepts only SNPS forced takeover requests when the application does not require some form of SNPS recovery processing. MNPS forced takeover requests are rejected. An application, unless it specifies otherwise using SETLOGON OPTCD=PERSIST, is assumed to support this level of function.
Examples
OPEN ACB1
ADD SETLOGON OPTCD=GNAMEADD,NIB=NIBGRSC,ACB=ACB1
⋮
BEGIN SETLOGON RPL=RPL1,ACB=ACB1,OPTCD=START
⋮
HOLDEXITS SETLOGON RPL=RPL1,ACB=ACB1,OPTCD=HOLD
⋮
RESUME1 SETLOGON RPL=RPL1,ACB=ACB1,OPTCD=START
⋮
DELETE SETLOGON OPTCD=GNAMEDEL,NIB=NIBGRSC,ACB=ACB1
⋮
TOOMANY SETLOGON RPL=RPL1,ACB=ACB1,OPTCD=STOP
⋮
ADD2 SETLOGON OPTCD=GNAMEADD,NIB=NIBGRSC,ACB=ACB1
⋮
RESUME2 SETLOGON RPL=RPL1,ACB=ACB1,OPTCD=START
⋮
NOMORE SETLOGON RPL=RPL1,ACB=ACB1,OPTCD=QUIESCE
⋮
ACB1 ACB APPLID=APPLNAME,MACRF=LOGON
APPLNAME DC 05
DC CL5'STOCK'
⋮
NIBGRSC NIB GNAME=JOHNDOEADD identifies the application program with the application network name STOCK as a generic resource member using the generic resource name JOHNDOE. A generic resource member must issue OPTCD=GNAMEADD prior to establishing any LU-LU sessions.
Before BEGIN is executed, the application program's LOGON exit routine cannot be scheduled. Once BEGIN has completed, however, STOCK's LOGON exit routine is scheduled as each CINIT is received. STOCK might then also enter into a session as the secondary logical unit by issuing a REQSESS macroinstruction.
HOLDEXITS causes all CINIT and BIND requests to be queued and prevents the scheduling of the LOGON and SCIP exits for session setup requests.
RESUME1 causes VTAM to schedule the LOGON exit for each queued CINIT request, and schedules the SCIP exit for each queued BIND request.
DELETE removes STOCK as a generic resource member. After DELETE is completed, VTAM stops using STOCK to resolve session initiations from LUs that specify the generic resource name JOHNDOE. LUs can continue establishing sessions using the name STOCK. Additionally, any LU currently in session with STOCK can continue establishing parallel sessions using the generic resource name JOHNDOE.
TOOMANY causes VTAM to flag the application program as temporarily unwilling to accept CINITs. It does not prevent CINITs from being sent to STOCK and causing STOCK's LOGON exit routine to be scheduled. If an application program that wants to initiate a session with the STOCK application program first issues INQUIRE OPTCD=APPSTAT, it receives feedback information indicating that session-initiation requests should not be issued for STOCK.
ADD2 specifies that VTAM use STOCK as a generic resource member of the generic resource name JOHNDOE. LUs can continue establishing sessions using the name STOCK. After ADD2 is completed, VTAM can use STOCK to resolve session initiations from LUs that specify the generic resource name, JOHNDOE.
RESUME2 reverses the effect of TOOMANY; application programs issuing INQUIRE OPTCD=APPSTAT receive feedback information indicating that session-initiation requests are being accepted (the same feedback information that results if INQUIRE is issued after BEGIN but before TOOMANY).
NOMORE prevents further sessions from being successfully initiated with STOCK. An INQUIRE issued by another application program would indicate this, and any attempt to initiate a session with STOCK would fail. If any CINITs are queued at STOCK when QUIESCE is issued, they remain queued and can be processed normally.
Completion information
A SETLOGON operation is successfully completed when the SSCP has recorded the application program's altered session-establishment capability. If ECB posting is used, the SCIP and LOGON exit routines can be scheduled before the application program recognizes that the processing of the SETLOGON has been completed successfully.
- The value 21 (decimal) is set in the REQ field, indicating a SETLOGON request.
- If OPTCD=QUIESCE, the number of CINIT requests queued for the application program is set in the RECLEN field.
- If this is the first SETLOGON OPTCD=START request issued after opening the ACB, and a temporary storage shortage occurs during an attempt to schedule the LOGON exit routine, the SETLOGON fails (RTNCD,FDB2)=(X'08,'X'00'). The LOGON exit routine is successfully scheduled for all CINITs prior to the storage shortage. Any remaining automatic logons are not processed by additional SETLOGON requests. The application program can request that the VTAM operator issue a VARY command for each of the logons.
- 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.
Registers 0 and 15 are also set as indicated in Handling errors and special conditions.