Notes on SAMP3

SAMP3 physically consists of one application program, but logically consists of two programs. The first logical program is labeled “AUTHPATH,” and the second logical program is labeled “AUTHEXIT.”

AUTHPATH begins by opening an ACB and establishing a session with an LU. In order to use the authorized forms of SEND, RECEIVE, RESETSR, or SESSIONC, the application program must have authorization to change from problem program state to supervisor state. See Assigning operating system authorization for a description of how to become an authorized program.

SAMP3 changes into supervisor state by issuing the operating system macroinstruction MODESET. MODESET obtains the zero protection key needed to use authorized path. To schedule an SRB, an application program must be in supervisor state with a key of zero.

At this point, SAMP3 departs from normal VTAM® application programming. It is now operating as a system program, using a system key. The application program issues the RECEIVE macroinstruction in its asynchronous form with an exit routine specified. The operand BRANCH=YES causes authorized path to be used. The exit routine runs under control of an SRB.

The exit routine, AUTHEXIT, issues the CHECK macroinstruction, which delimits processing of the RECEIVE macroinstruction issued in the mainline program. Then the input is tested for three possibilities:

Echo
No echo
An error condition.

If an echo is desired, the SEND macroinstruction is used to return the data just received. This SEND uses authorized path because it is issued under control of the SRB under which the exit routine was scheduled. The mainline program is then posted to continue issuing the RECEIVE.

If no echo is desired, and an error has not been encountered, the RESETSR macroinstruction is issued to change the logical unit (LU) back to continue-any mode to allow it to be addressed by the next issuance of the RECEIVE macroinstruction. RESETSR uses authorized path because it is issued under control of the SRB under which the exit routine was scheduled.

If an error condition was encountered, the mainline program is posted to issue CLSDST and CLOSE ACB after offering the user the option of an ABEND dump.

Otherwise, the mainline program is posted to continue issuing the RECEIVE OPTCD=ANY to accept data from the LU. Because the exit routine runs under an SRB, the branch entry to POST, rather than the POST SVC, must be used, which in turn requires obtaining and releasing the local lock with the SETLOCK macroinstruction.

The mainline program checks the input for the string “LOGOFF” and, if it finds this input, issues CLSDST and CLOSE ACB to shut down the application program. (Notice that the CLSDST macroinstruction uses the BRANCH=NO operand to turn off the RPLBRANC flag turned on by the RECEIVE which used the BRANCH=YES operand.) If the “LOGOFF” string is not found, the mainline program continues issuing the RECEIVE and the exit again gains control.