Simple example of authorized path usage

See Sample code of a simple application program, for a coded example of an application program that uses authorized path macroinstructions.

The flow chart shows an example of authorized path usage. The text below explains the flow chart in detail. — Figure 1. Example of the use of authorized path

Figure 1 illustrates the basic logic for using authorized path when running under a TCB and under an SRB. The program in Figure 1 is highly simplified. The program establishes and handles input from only one session; an actual program would establish and handle input from many sessions. In addition, the logic associated with input/output requests would be more complex in an actual program. The following notes are related to the numbers in Figure 1.

1

The application program begins processing as a task running under the control of a TCB. As part of normal VTAM® processing, it issues an OPEN macroinstruction to open an ACB. The OPEN might look like this:

OPEN  AUTHACB

In this example, AUTHACB contains:

AUTHACB  ACB   AM=VTAM,APPLID=APPL5ID,PASSWD=APPL5ID

2

The application program issues an OPNDST macroinstruction to establish a session with a logical unit. The OPNDST might be coded:

OPNDST RPL=AUTHRPL,OPTCD=SYN

The RPL, named AUTHRPL, contains the rest of the information needed for OPNDST.

3

The application program uses the MODESET macroinstruction to change into supervisor state. This is coded:

MODESET MODE=SUP

4

The RECEIVE macroinstruction conforms to the coding rules for authorized path running under the control of a TCB. The BRANCH=YES operand is specified. The RECEIVE macroinstruction might be coded:

RECEIVE RPL=AUTHRPL,RTYPE=DFSYN,AREA=INPUT00,              C
        AREALEN=100,OPTCD=(ASY,ANY,CS),EXIT=AUTHEXIT,      C
        BRANCH=YES

It is known that a request received on the session never exceeds 100 bytes.

5

Because the RECEIVE was specified as an asynchronous operation (OPTCD=ASY), the mainline program, AUTHPATH, can continue execution until an input request on the session completes the receive-any operation. In a more elaborate program, meaningful processing could be done here. But in AUTHPATH, the program immediately enters a wait state, waiting on its own ECB.

6

When a request is received on the session, control goes to the RPL exit routine named AUTHEXIT. This exit routine runs under the control of an SRB. VTAM processing is completed with the scheduling of the exit routine; VTAM itself is not suspended. For example, VTAM could immediately schedule another RPL exit under an SRB.

The CHECK macroinstruction frees the RPL for reuse and causes entry to a LERAD or SYNAD exit routine if necessary. The CHECK macroinstruction is coded:

CHECK RPL=AUTHRPL

7

The exit routine then tests the input request to see if it is a logoff request (a request in a special format that indicates the logical unit wants to end the session with the program AUTHPATH).

8

If the request is a logoff request, the exit routine turns on a logoff indicator, posts the ECB (as in step 11), and exits, thus returning control to the mainline program, AUTHPATH.

9

If the request is not a logoff request, the exit routine analyzes the request and builds a reply.

10

The exit routine is running under the control of an SRB because it is an RPL exit routine entered from a macroinstruction using authorized path. The SEND macroinstruction, therefore, automatically uses authorized path. The SEND looks like this:

SEND  RPL=AUTHRPL,OPTCD=(SYN,CA),CONTROL=DATA,             C
      STYPE=REQ,RTYPE=DFSYN,RECLEN=95,AREA=OUTPUT00,       C
      POST=SCHED,RESPOND=(NEX,NFME,NRRN)

The macroinstruction specifies that the SEND operation is to be performed synchronously (SYN in OPTCD), meaning that the exit routine surrenders control until the SEND operation is scheduled. The macroinstruction also specifies that no response is returned, which assumes that failure of the request to arrive is detected by analyzing the next request entered by the terminal operator.

11

After the SEND operation has been scheduled, the exit routine posts the ECB on which the mainline program (AUTHPATH) has been waiting. This must be done by a branch entry to the supervisor POST routine, because SVCs cannot be issued in SRB mode. The exit routine then exits and thus returns control to AUTHPATH.

12

Because the ECB has been posted, the wait at 5 is satisfied and AUTHPATH continues execution. It tests to determine whether the logoff indicator has been set. If the indicator has not been set, it returns to 4 to reissue the RECEIVE macroinstruction. Thus, execution continues using steps 4 through 12 for as long as input requests other than logoff are received on the session.

When the logoff indicator has been set (indicating that the request received from the logical unit was a logoff request), execution continues at 13.

13

The program terminates the session by using the CLSDST macroinstruction. The CLSDST might be coded:

CLSDST RPL=AUTHRPL,BRANCH=NO,OPTCD=SYN

14

The CLOSE macroinstruction closes the ACB.

If desired, both the OPNDST and CLSDST macroinstructions could have been coded to use authorized path. This could have been done by interchanging steps 2 and 3, and by coding BRANCH=YES on the RPL macroinstruction.