Organization and flow of Sample Program 2

Figure 1 shows the principal routines in sample program 2; the notes following the figure indicate how sample program 2 works. More detailed logic is shown and discussed in subsequent figures and notes.

Figure 1 shows the mainline program and the exit routines as separate groups of routines. This is a logical rather than a physical separation; exit routines are distinctive because they are entered only when an event occurs that requires handling by an exit routine. When an asynchronous exit routine is scheduled, VTAM® suspends execution of the mainline program until the exit routine completes its processing and returns to VTAM. In general, only one asynchronous exit routine can be executed at a time; if an exit routine event occurs while an exit routine is being executed, the second exit routine is scheduled for entry only after the first exit routine is completed. The LERAD and SYNAD exit routines are exceptions to this general rule; they can be entered as the result of an RPL-based operation, such as OPNDST, RECEIVE, or CHECK in another exit routine (in which case, they can be viewed as extensions of the exit routine that caused them to be entered). For details, see Normal operating system environment for a VTAM application program.

Except for the LERAD and SYNAD exit routines, each exit routine must establish its own addressability, be executed, and then return to VTAM; VTAM's registers need not be saved or restored. A temporary branch to part of the mainline routine can be made from an exit routine and common code can be shared, but the exit routine would be considered to be in progress until control is returned to VTAM. The LERAD and SYNAD exit routines are furnished addressability as the result of loading registers (a user save area address is passed in register 13).

Figure 1. Organization and flow of Sample Program 2

The diagram shows the principal routines in sample program 2 with numbers referring to additional notes to indicate how sample program 2 works. In the diagram, the mainline program and the exit routines are shown as separate groups of routines.

Except for an RPL exit routine, whose address is specified in the RPL or RPL-based macroinstruction, the addresses of exit routines to be associated with the program are defined in an EXLST macroinstruction. In addition, for DFASY, RESP, and SCIP exit routines, different exit lists can be defined for different sessions or sets of sessions. In sample program 2, one exit list is assumed; the address of this exit list is provided to VTAM in the EXLST operand of the ACB when the ACB is opened.

The following notes are keyed to the numbers in Figure 1.

1

The ACB is opened and a SETLOGON OPTCD=START is issued. A RECEIVE to read input from any session is issued; the operation is to be completed asynchronously, and an RPL exit routine (RPL1) is designated for scheduling by VTAM when the operation is completed. The session whose input is read into sample program 2 is to be put into continue-specific mode. Thus, subsequent RECEIVEs to read input from any session, issued in the RPL exit routine, excludes the session whose input was just read and with whom the program is now in specific communication. The RECEIVE can be coded:

RECEIVE  RPL=RPL1ANY,AREA=AREAANY,AREALEN=100,                         C
               RTYPE=DFSYN,OPTCD=(ASY,ANY,CS),EXIT=RPL1

Issuing more than one RECEIVE OPTCD=ANY at this point can improve efficiency. If three RECEIVEs are issued using three different RPLs and data areas, when one RECEIVE is completed (thus causing the RPL1 exit routine to be scheduled and entered), the two outstanding RECEIVEs can allow scheduling of RPL1. The RECEIVE that is completed first can be reissued in the RPL1 exit routine.

The RPLs and input areas can be assembled in the program as fixed areas and reused each time the program issues a RECEIVE OPTCD=ANY.

A branch is made to the wait routine, which waits for the first input to arrive from a session. The initial routine is executed only once.

2

Both 3600 and 3270 LUs can cause the LOGON exit routine to be invoked. INQUIRE is used to determine which type of LU is having a session established. The particular type of SNA terminal product (3600, 3790, and 3270, for example) need not be identified by the VTAM application program. Instead, the VTAM application program distinguishes between types of LUs on the basis of the session parameter set associated with the LU. In this example, 3600 LUs have a different set of session parameters than 3270 LUs; the program can relate to an LU that is establishing a session with one of these sets, and use the appropriate routine to communicate with the LU. Storage that is to be associated with this session can be obtained from a pool or can be obtained dynamically from the system. (The storage can include an ECB, an RPL, and an area for additional session-related information.) The address of this storage or any other session-related information can be put in the USERFLD field of the NIB, using the MODCB macroinstruction; when the session is established, VTAM saves this address and returns it to the program following completion of each subsequent RPL-based macroinstruction on the session.

A session with an LU can be established as the result of a logical-unit-initiated logon, installation-initiated (automatic) logon, VTAM operator-initiated logon, or application-program-initiated logon. A 3600 logical-unit-initiated logon either could be the result of some logical-unit-operator action or could be initiated solely by the 3601 application program without involving an LU operator (in either case, the actual request would be transmitted by the 3601 application program). Figure 1 shows part of the general sequence of events that occur prior to and during a logon. Here is a sequence of events that can occur prior to and during a 3600 logical-unit-initiated logon:

The 3601 and its LUs, defined to VTAM during VTAM definition, are made an active part of the VTAM network (perhaps by a VTAM operator VARY command).
As a result of receiving an activation request for the 3601 controller, VTAM sends an Activate Physical Unit request to the 3601 controller. The 3601 acknowledges the request and responds that it is ready for operation. (This request is followed by an Activate Logical Unit request to one or more of the LUs [logical work stations] associated with that particular 3601.)
After the Activate Logical Unit request is received, the 3601 application program either can wait for a terminal operator at a 3601 work station to indicate that the LU (work station) is to be logged on to a host application program, or can issue a logon on its own initiative. This is done by sending an Initiate request to VTAM specifying the name of the VTAM application program with which the LU is to be in session. The Initiate request can also specify a logon mode name (indirectly specifying a session parameter set) and a user-defined logon message.
VTAM, receiving the Initiate request, schedules sample program 2's LOGON exit routine.
In the LOGON exit routine, after confirming the validity of the logon, the session is established, using an OPNDST OPTCD=ACCEPT macroinstruction. OPNDST causes VTAM to send a BIND request (containing the session parameter) and to issue a Start Data Traffic (SDT) request to the LU (assuming SDT=SYSTEM was specified in the NIB used for session establishment). On receipt of a response to the SDT, the LU is in session with the VTAM application program and the OPNDST is posted complete. (If SDT=APPL is specified in the NIB used for session establishment, the VTAM application program must itself send the initial SDT, using the SESSIONC CONTROL=SDT macroinstruction.)

OPNDST can be specified as a synchronous operation or an asynchronous operation. If the latter, OPNDST can identify either an ECB to be posted or an RPL exit routine to be scheduled as soon as the session is established.

Note: For better system performance, specify OPNDST asynchronously from EXLST exit routines.

For a synchronous operation, the same RPL and NIB can be used for each session being established through the LOGON exit routine.

So that the session parameter suggested to be associated with the session can be obtained (which in this program determines whether the 3600 or the 3270 I/O routines are used with the session), an INQUIRE OPTCD=SESSPARM macroinstruction can be issued. This allows the session parameter and user data (logon message) from the original Initiate to be inspected and perhaps saved in the storage that is to be associated with the session.

Optionally, the read-only RPL provided as input to the LOGON exit routine can be used to locate and inspect the CINIT RU. The CINIT contains the session parameter, user data, and other information.

It might be desirable to use the SEND macroinstruction to write an initial request on the session; this could be done from the LOGON exit routine or in an RPL exit routine following an asynchronously posted OPNDST operation.

3

As soon as the first input is received from a session, the operation started by the RECEIVE OPTCD=ANY issued in the initial routine is completed. The RPL1 exit routine is then scheduled and entered.

RPL1 can use the USER field or the ARG field of the RPL of the request just completed to locate the application program session-related control block. On entry to RPL1, the address of the RPL is in register 1.

A CHECK macroinstruction is required to free the RPL for reuse; it also causes LERAD or SYNAD exit routines to be entered if any error occurred.

RPL1 posts an ECB so that, subsequently, the wait routine in the mainline program determines that the input has been received and passes it to the processing routine analyzer. The RPL1 exit routine then reissues a RECEIVE OPTCD=ANY. Because a session-related RPL obtained in the LOGON exit routine is used for subsequent operations with the session, the RPL causing entry to RPL1 can be continuously reused by the RECEIVE in RPL1. This RECEIVE OPTCD=ANY operation is to be asynchronous with respect to the rest of the program and RPL1 is reentered each time the request is completed. The session whose input caused entry to RPL1 is now in continue-specific (CS) mode. The RECEIVE can be coded identically to the RECEIVE in the initial routine.

Although not shown in Figure 1, the RPL exit routine sends a positive response to the request that caused it to be entered if a positive response is requested by the LU. If a response is to be sent for an exception condition, sending the negative response is probably performed in a SYNAD exit routine after a CHECK is issued.

An alternative to having an RPL exit routine for the RECEIVE OPTCD=ANY and related logic is to have this logic located in the mainline program and have an ECB posted. In sample program 2, one advantage to using an RPL exit routine is that input resulting from a RECEIVE OPTCD=ANY is handled sooner in an RPL exit routine than if an ECB were to be posted (which would require waiting until the next entry to the mainline program's wait routine). This gives some preference to handling the first input of a new transaction over transactions in progress.

4

The wait routine waits on a list of ECBs, with each ECB associated with a separate RPL. When an ECB is posted, the wait routine is activated, and the routine searches the ECB list to find the posted ECB and zeros it out. The routine then issues a CHECK macroinstruction. (The CHECK is bypassed here for the RECEIVE OPTCD=ANY that caused entry to the RPL1 exit routine, because CHECK has already been issued for that RPL). CHECK clears the RPL for reuse in the next request involving the session, and if an error occurred, the macroinstruction causes the LERAD or SYNAD routine to be entered. On return from CHECK, the feedback fields of the RPL contain information provided by VTAM; in addition, the LERAD or SYNAD routine can indicate action to be taken.

If the operation was successful, the wait routine branches to the address associated with the ECB. (In the case of the first input of a transaction, that address is the one for the processing routine analyzer.) When control is returned to the wait routine, the routine again searches the ECB list to see if another ECB has been posted. If a posted ECB is found, processing continues as described above. If not, RECEIVE OPTCD=ANY is issued again, and the program enters the wait state.

5

The processing routine analyzer, which can consist of separate routines for different types of LUs, analyzes the input and branches to or calls the appropriate processor. This processor can be coded in a higher-level language, such as COBOL or PL/I.

6

The processing routine processes the input and prepares the output. This might require one or more disk I/O operations, which can be performed by calling a common disk I/O routine. When output is ready, or during a communication when the next input is required, the processing routine requests VTAM I/O, causing control to pass to an appropriate VTAM I/O routine.

7

The disk I/O routine requests a disk I/O operation asynchronously and uses the wait routine to wait for completion. This allows processing for other sessions to continue while a disk I/O operation for one session is under way.

8

Although not shown, a processing routine can return control to the next sequential instruction in the mainline program from which it was called; a branch can then be made to a common I/O routine, which in turn branches to a 3600 or a 3270 input or output routine. A special routine might be required to edit 3270 input and format 3270 output.

If the LU has the 3600 session parameter, an input or an output operation is requested as appropriate. The operation is specified as asynchronous; completion is determined when the ECB related to the session is posted. Before issuing the request, the address to which the wait routine should branch (the return address is the processing routine) is placed in the ECB-related session control block.

If additional input is requested, the input, when it arrives, is not used to satisfy the outstanding RECEIVE OPTCD=ANY request in RPL1 because the session is now in CS mode.

If output is requested, the data can be sent in a chain of requests; this is useful with output that is passed from the 3601 application program to a 3610 printer. The 3601 application program can store all requests of the chain in a buffer until the entire chain is received (or print each request as it arrives). The VTAM application program would ensure arrival of the entire chain by receiving a single positive response sent by the 3601 application program when the last request of the chain is received. This notifies the VTAM application program that the data transfer was successful.

If the output completes a transaction, the session is reset to continue-any (CA) mode so that input that begins the next transaction satisfies the RECEIVE OPTCD=ANY request that is issued in RPL1.

Details about the 3600 I/O routine are provided in Figure 1 and in accompanying notes.

9

If the LU has the 3270 session parameter, different I/O routines are required. The size of I/O areas required can be different and the range of input that arrive can be wider. An additional requirement is the use of brackets for controlling the overlap of input and output with 3270. Details about the 3270 I/O routines are provided in Figure 1 and in accompanying notes.

10

The RESP exit routine is scheduled and entered when a response arrives from an LU. A response is received by VTAM because the VTAM application program requested it in the RESPOND operand of the SEND macroinstruction. When the response is received, the operation, scheduled only in the 3270 or 3600 output routine, is now completed and the RESP exit routine can now post the ECB. If the operation was successful, the response is positive; if an error occurred, a negative response is indicated in the RPL. The RESP exit routine can set up parameters and branch to the SYNAD exit routine which analyzes the error and takes corrective action. The ECB is posted and control is returned to VTAM.

Details of the RESP exit routine are in Figure 1 and accompanying notes.

11

In sample program 2, two kinds of expedited-flow data-flow-control requests can be received from a 3601 LU: a request to stop sending to the LU at the end of the chain that is currently being sent (a Quiesce at End of Chain [QEC] request) and a request to reinitiate sending after previously being requested to stop (a Release Quiesce [RELQ] request). The use of these requests might be desirable if a work station operator wants to interrupt a long series of printing so that the keyboard input can be entered. After handling the operator's request, the VTAM application program can resume printing. When either of these requests is received, VTAM schedules sample program 2's DFASY exit routine.

This exit routine does not apply to 3270 operation. Details of this routine are shown in Figure 1 and accompanying notes.

12

The TPEND exit routine is scheduled and entered when the VTAM operator enters a HALT command or when VTAM terminates itself or is abnormally terminated. In addition to other possible processing, the TPEND exit routine posts a special close ECB so that, subsequently, the mainline program's wait routine branches to a CLOSE macroinstruction in the mainline program.

13

The LERAD, SYNAD, and LOSTERM exit routines handle different categories of errors or unusual situations. The LERAD or SYNAD exit routine can be entered as the result of any RPL-based request. The LOSTERM exit routine is scheduled asynchronously when certain situations occur, such as the deactivation of an LU by the terminal operator. Like other parts of the program, the LOSTERM exit routine can branch to the LERAD or SYNAD exit routine for problem analysis. The LERAD exit routine primarily handles logic errors; it is most likely for these to occur during the debugging stages of the program. This exit routine can gather information, format it, and save it for programmer analysis after the program ends. The SYNAD exit routine primarily handles physical errors; it determines what general action should be taken (for example, retry, end the session with the LU, terminate the program, or send a request to the VTAM operator) and either takes the action or passes an action code to the mainline program where the action is taken. The SYNAD exit routine can also record information related to situations that it handles for later problem analysis.

A number of error situations must be perceived and analyzed as the result of receiving a response from an LU; the response is analyzed following a SEND POST=RESP, following a RECEIVE RTYPE=RESP, or after a RESP exit routine is entered. Errors or special situations that result in negative responses cause the SYNAD exit routine to be entered when a synchronous macroinstruction or a CHECK macroinstruction is issued; the SYNAD exit routine can determine the cause of the negative response by analyzing sense information in the RPL and then take appropriate action. The program, after determining that a negative response has been received, can also branch directly to the SYNAD exit routine.