Additional coding considerations for authorized path

When an application program executes two or more asynchronous authorized path macroinstructions for the same session, the requests might not be satisfied by VTAM® in the order that the macroinstructions are issued. To ensure that VTAM processes requests in order, wait until one macroinstruction is posted complete before executing the next.

Here are some examples of how requests can be processed out of order:
  • If two SEND POST=RESP,OPTCD=ASY macroinstructions are executed on a given session without an intervening CHECK macroinstruction, the second request could arrive at the logical unit before the first request. This can happen if both authorized path macroinstructions are issued under two different SRBs.
  • Similarly, if multiple RECEIVE macroinstructions are outstanding for a session, SRB scheduling can make it appear that input arrived on the session out of order. For example, the RECEIVE EXIT SRB for the input data request with a sequence number of 8 can execute prior to the RECEIVE EXIT SRB scheduled for input data request number 7. This can be avoided by having no more than one RECEIVE outstanding at a time for a session and issuing another RECEIVE only when the first completes.
RPL exit routines for authorized path macroinstructions are always scheduled under SRBs (in supervisor state and key 0), even if the authorized path macroinstruction was invoked under a TCB. On entry to such an RPL exit routine:
  • Register 1 contains the address of the RPL.
  • Register 13 does not contain a save area address because no save area is provided. (This is also true for an RPL exit routine running under a TCB.)
  • Register 14 contains the return address of the dispatcher.
  • Register 15 contains the entry-point address of the exit routine.

The SRB under which an RPL exit routine is run or under which control is returned to an application program is not necessarily the same SRB under which the original RPL-based macroinstruction was issued. For synchronous SRB-mode macroinstruction requests, the application optionally can request that VTAM retain the SRB of the issuer's processing thread throughout the processing of the request. This is accomplished by specifying OPTCD=(SYN,KEEPSRB) on the RPL-based macroinstruction request. This permits the processing environment established by the application, including FRRs, BAKR stacks, and other SRB-related resources, to be kept intact.

CAUTION:
To provide this function, VTAM utilizes SUSPEND and RESUME. Suspending the SRB (as opposed to exiting and returning under a different SRB) allows the environment to be preserved. However, SUSPEND and RESUME may impact performance. Take this into account when making use of this parameter for performance sensitive API invocations (such as SEND or RECEIVE).

When part of an application program is executed under the control of an SRB, that part of the application program cannot issue a WAIT macroinstruction or any other SVC except ABEND, SVC 13. VTAM does any suspension and resumption of processing for that part of the application program without using WAIT or POST macroinstructions (for example, when OPTCD=SYN is issued).

A CHECK macroinstruction can be issued if asynchronous ECB posting is used, but it can usually be issued only under the control of a TCB. A CHECK macroinstruction cannot be issued under an SRB unless it is certain that the associated RPL has been posted complete; for example, CHECK for an RPL can be issued in the RPL-exit routine scheduled for that RPL because the RPL is posted complete before the exit routine is scheduled. If CHECK is issued under an SRB before the RPL has been posted complete, the CHECK issues a WAIT, but the WAIT SVC is not allowed under an SRB.

When an RPL exit routine is executing under the control of an SRB, the exit routine should establish a functional recovery routine (FRR) by using the supervisor macroinstruction SETFRR. For additional information about the use of functional recovery routines, see  Functional recovery routines.

To ensure that VTAM serializes its references to VTAM control blocks, VTAM authorized users should not execute the SEND, RECEIVE, SESSIONC, or RESETSR macroinstructions while a CLSDST or TERMSESS macroinstruction for the same session is in progress.

An authorized program that holds system locks should release those locks before invoking VTAM to avoid conflicts with VTAM's use of the locks. Otherwise, if a conflict occurs, z/OS® abnormally terminates the VTAM function being processed for that program.

SYNAD and LERAD exit routines are scheduled in the same mode (TCB or SRB) as the program that issued the macroinstruction giving control to the exit routine. For asynchronous requests, the SYNAD or LERAD exit routine can be entered either when the authorized path macroinstruction is issued or when a CHECK macroinstruction is issued.

Rules relating to the reentrance of certain VTAM exit routines are described in Using exit routines. When the RPL, SYNAD, and LERAD exit routines are scheduled as a result of authorized path and corresponding CHECK macroinstructions being issued, the following two additional rules apply:
  • RPL exit routines must be reentrant, because VTAM schedules RPL exit routines in parallel under different SRBs. If the RPL exit routine invokes any authorized path or CHECK macroinstructions, the SYNAD and LERAD exit routines must also be reentrant.
  • If the application program itself schedules parallel processing under different SRBs, and if these SRBs invoke any authorized path or CHECK macroinstructions, the SYNAD and LERAD exit routines must be reentrant.