Program Synchronization and Control

An important characteristic of the API design is that, at the option of the application program, no transport service request causes the issuing task to be suspended. As a result, the processing of service requests can be easily overlapped with other application program activities, and when executing on a multi-processor, can actually be executed in parallel. To support this requirement, the API provides a mechanism for initiating a service request and synchronizing with its subsequent completion under total control of the application program.

Processing that precedes acceptance of a service request, and all processing within the API address space, is identical for both modes of operation. When a service request is issued, the TPL is set active and its contents are checked for validity. If the request is valid and the state of the endpoint is acceptable, the request is scheduled for processing by the API address space. When the request completes, the TPL is posted complete. The TPL remains active during this entire period of time, and if a subsequent request attempts to use the TPL, it is completed immediately with an error.

When control is returned to the next sequential instruction in the application program task, the TPL has been set inactive, and may be reused for another request. Synchronous mode is appropriate for application programs that manage a single endpoint and do not need to overlap endpoint operations, such as send and receive operations, with other application program activities. This suggests that the communication of data via the endpoint is half-duplex in nature, and that some arrangement exists between the communicating entities to know when to send and receive data. Since only one operation may be pending at any point in time, synchronous operation is usually less complex than asynchronous operation.

While an asynchronous operation is pending, the associated TPL is active and cannot be used with another request until it has been posted complete. If the application program issues another TPL-based macro instruction, a different TPL must be used. Also, when an operation is pending for an endpoint, other operations which can be initiated at the same endpoint are limited.

It is also important to note that the TPL ECB may be posted or the TPL exit routine may be executed before the application receives control back from the API (for example, at the next sequential instruction following the TLI request macro). This is because this activity occurs upon a different unit of execution within the operating system.

When using an internal ECB, the application program does not wait or check the internal ECB, and lets the TCHECK function wait if necessary. The application program could have waited on the ECB explicitly knowing that it is located in the TPL location at TPLIECB (TPLECBXR). This diagram illustrates this processing flow:

Figure 3-3: Asynchronous Operation Using Internal ECB

When using an external ECB, the application program issues a WAIT for the external ECB, but could have allowed TCHECK to perform the wait implicitly. This diagram illustrates this processing flow:

Figure 3-4: Asynchronous Operation Using External ECB

When a TPL exit routine is specified, the TCHECK macro instruction is usually executed by the exit routine. However, the TCHECK macro instruction may be executed by the mainline program after the exit routine has run, but this may be difficult to coordinate. If the TCHECK macro instruction is executed before the operation completes (and EXIT is specified), an error is generated.

The important point to remember is that once a synchronous request is issued, the operation must be completed before another request can be issued from the same program thread. If the program thread is the mainline program, exit routines can still run and requests can be issued from those exit routines. However, if a synchronous request is issued by an exit routine, no other API-scheduled exit routines run until the synchronous operation is complete. This fact can be used to the advantage or detriment of the application program.

These two kinds of exit routines work somewhat differently and derive their names from how they are specified.

The TEXLST macro instruction is used to build an exit list, and the exit list is associated with the transport user by linking it to the APCB specified in the AOPEN macro instruction. For those exits that can be associated with a particular endpoint, the exit list must be specified in the TOPEN macro instruction. The TEXLST macro instruction keyword used to specify the exit routine's address is used in the remainder of this section when discussing particular types of exit routines.

The TEVNTLST macro instruction provides capabilities similar to TEXLST. TEVNTLST, however, can only be used with the TOPEN macro instruction. TEVNTLST may not be referenced by an APCB macro instruction. Internally, the TEVNTLST macro generates a parameter list that is identical to the parameter list generated by TEXLST. TEVNTLST provides the additional capability of specifying ECB addresses in lieu of exit routines. Both ECB addresses and exit routine addresses can be used in a TEVNTLST specification, but for a given event, only one ECB or exit address may be specified.

When a synchronous exit routine is entered, the general-purpose registers contain this information:

These procedures should be followed when coding a synchronous exit routine:

• The exit routine is not obligated to return to the API. However, if it does, register 14 should be saved and restored before returning.

• The exit routine is not required to save and restore general-purpose registers 2-12, and the API does not provide a save area for the exit routine. However, register 13 does contain the address of an 18-word save area supplied by the application program.

• If the exit routine issues any TPL-based macro instructions or calls any external routines, it must provide the address of its own 18-word save area in register 13. Register 13 should be restored before returning to the API.

• If the exit routine returns to the API, it should not execute any macro instruction or call any routine that would change the contents of the 18-word save area supplied by the application program. The API restores the application program's registers from the save area before returning to the next sequential instruction.

• Registers 0 and 15 are not restored by the API and the exit routine is not required to preserve them. Contents of these registers are passed to the application program if the exit routine returns to the API.

A synchronous exit routine is generally not required to be reentrant. However, if a synchronous exit routine executes other TPL-based macro instructions, the exit routine may be re-entered (recursion). Also, if TPL-based service requests are issued from the mainline program and asynchronous exit routines, or the synchronous exit routine is shared by two or more programs, it may be reentered. In this case, the application program should be prepared to handle reentrancy issues (for example, dynamic allocation of work areas).

**************************************************************************
*  SYNCHRONOUS ERROR RECOVERY ROUTINE
**************************************************************************
          USING SYNADX,12
SYNADX    LR    12,15               ESTABLISH BASE ADDRESS
          LR    2,0                 SAVE RECOVERY ACTION CODE
          LTR   3,1                 TEST TPL ADDRESS
          BNP   RECURSIV            IGNORE IF CALLED RECURSIVELY
          LR    5,14                OTHERWISE, SAVE RETURN ADDRESS
          O     3,=X'80000000'      SET RECURSION FLAG
          ST    13,SYNADSAV+4       BACK CHAIN SAVE AREAS
          LA    13,SYNADSAV         ESTABLISH NEW SAVE AREA
           .
          . [this exit routine is not intended to be reentrant]
           .
          TERROR VERBATIM,MF=(E,(3)) GENERATE DIAGNOSTIC MESSAGE
          LTR   15,15               MESSAGE RETURNED?
          BNZ   SKIPWTO             IF NOT, SKIP WTO
          LR    4,0                 SAVE WTO LIST ADDRESS
          XR    0,0
          USING TEM,4
          WTO   MF=(E,TEMWTO)       WRITE MESSAGE TO OPERATOR
          L     0,TEMSL             LOAD LENGTH AND SUBPOOL
          FREEMAIN R,LV=(0),A=(4) 							 RELEASE MESSAGE STORAGE AREA
          DROP  4
SKIPWTO   DS    0H
          . 
          . [perform recovery processing]
           .
RETURN    L     13,4(,13)           RESTORE PREVIOUS SAVE AREA ADDRESS
          LR    14,5                RESTORE RETURN ADDRESS
          XR    15,15               UPDATE GENERAL RETURN CODE
          XR    0,0                 CLEAR CONDITIONAL COMPLETION CODE
RECURSIV  DS    0H
          BR    14                  RETURN TO THE API
          LTORG
           .
           .
           .
SYNADSAV  DS     18F                 EXIT ROUTINE SAVE AREA
          TDSECT TEM                 GENERATE TEM DSECT

Asynchronous exit routines can interrupt the mainline program at any time, even if the mainline program is currently suspended (for example, because it issued a TCHECK or WAIT macro instruction). However, no API-invoked asynchronous exit routine can interrupt another asynchronous exit routine; thus each asynchronous exit routine must return to the API before the next asynchronous exit routine can be given control.

When an asynchronous event occurs, the associated exit routine (if defined by the application program) is scheduled by the API by being put on a transport user exit queue. If the mainline program is currently in control, execution of the mainline program is suspended and control is immediately given to the exit routine. If another asynchronous exit routine is in control, that exit routine must return to the API before the next exit routine on the user exit queue can be given control. If the asynchronous exit routine currently in control suspends execution (for example, by issuing TCHECK or WAIT), it prevents other asynchronous exit routines from gaining control. When the final asynchronous exit routine returns to the API (the transport user exit queue is now empty), the mainline program resumes control at the point where it was interrupted.

The API schedules exits only for the API events, and is unaware of asynchronous exits scheduled by other program products or the operating system. Therefore, the serialization of asynchronous exits described here only applies to the API exits, and only applies to exits for one transport user (in other words, task).

These procedures should be followed when coding an asynchronous exit routine:

• Asynchronous exit routines must return control with a BR 14 after register 14 has been restored with the address it contained when the exit routine was entered.

• Except for general-register 14, the exit routine is not required to save the API registers; register 13 does not contain the address of an API or application program save area.

• If the exit routine issues any TPL-based macro instructions or calls any external routines, it must provide the address of its own 18-word save area in register 13.

• The AOPEN or ACLOSE macro instruction cannot be executed in an asynchronous exit routine (the API or otherwise). The AOPEN or ACLOSE macro instruction must always be executed from the mainline program.

• Care must be taken not to reuse save areas still in use by other parts of the application program. For example, the save area used by the mainline program when a TPL-based macro instruction is issued is in use until the API returns to the mainline program; it should not be used by an asynchronous exit routine in the meantime.

• If the exit routine issues a TPL-based macro instruction and completion is awaited in the same routine (for example, by the use of TCHECK or WAIT) the mainline program, as well as the exit routine, is suspended until the requested operation is completed. To avoid such delays, consider using a TPL exit routine for notification of completion.

Since asynchronous exit routines are serialized by the API, they are not normally re-entered. However, if the same asynchronous exit routine is shared by two or more tasks, it must be coded to be reentrant. In this case, save areas and work areas should be allocated dynamically.

Here is an example of an asynchronous exit routine. In this example, the exit routine is entered when data is available to be received. The exit routine issues a TRECV macro instruction in asynchronous mode and returns to the API. The TPL completion exit is also shown:

**************************************************************************
*  ASYNCHRONOUS EXIT ROUTINE TO HANDLE DATA INDICATIONS
**************************************************************************
          USING DORECV,12
DORECV    LR    12,15               ESTABLISH BASE ADDRESS
          LR    2,1                 MOVE TXP ADDRESS
          LR    3,14                SAVE RETURN ADDRESS
          LA    13,SAVEAREA         ESTABLISH SAVE AREA
          USING TXP,2
          L     4,TXPEPID           LOAD ENDPOINT ID
          LA    5,RECVTPL           LOAD RECEIVE TPL ADDRESS
          USING TPL,5
          TRECV EP=(4),MF=(E,(5))   INITIATE RECEIVE REQUEST
          LTR   15,15               REQUEST ACCEPTED?
          BZ    RECVEXIT            IF SO, RETURN TO API
RECVERR   DS    OH
           .
          . [perform error recovery processing]
           .
          DROP  2 
          USING RECVDONE,15
**************************************************************************
* TPL EXIT ROUTINE FOR TRECV SERVICE REQUEST
**************************************************************************
RECVDONE L      12,=A(DORECV)       ESTABLISH COMMON BASE ADDRESS
          DROP  15
          LR    5,1                 MOVE TPL ADDRESS
          LR    3,14                SAVE RETURN ADDRESS
          LA    13,SAVEAREA         ESTABLISH SAVE AREA
          TCHECKMF=(E,(1))          CHECK TPL AND SET INACTIVE
          LTR   15,15               RECEIVE SUCCESSFUL?
          BNZ   RECVERR             IF NOT, GO HANDLE ERROR
           .
          . [received data is now available for processing]
           .
RECVEXIT LR     14,3                RESTORE RETURN ADDRESS
          BR    14                  RETURN TO API
          DROP  5,12
          LTORG
           .
           .
           .
RECVTPL  TRECV  DABUF=DATAAREA,DALEN=L'DATAAREA,                         +
                OPTCD=ASYNC,EXIT=RECVDONE,MF=L
*                                   TPL FOR RECEIVING DATA
DATAAREA  DS    XL1024              RECEIVE DATA BUFFER
SAVEAREA  DS    18F                 EXIT ROUTINE SAVE AREA
          TDSECT TXP,TPL            GENERATE DSECTS

This diagram illustrates the transport endpoint exit parameters (TXP):

This table describes the contents of the TXP:

The TXP is dynamically formatted in key-0 storage and cannot be modified by an exit routine executing with its normal private-area key.

If the application program identified a SYNAD or LERAD exit routine in the exit list provided to AOPEN, the appropriate exit routine is entered if the TPL service request was completed with an error. Otherwise, the TPL exit routine should check register 15 returned by the TCHECK macro instruction, or check the return code fields of the TPL to determine if the request was completed successfully.

The exit routine may initiate additional API service requests using the same TPL, or may supply a different TPL. If additional TPL-based requests are executed, it is best that the exit routine not wait for completion, otherwise entry into other asynchronous exit routines may be delayed. Newly initiated requests should specify posting of an ECB or a TPL exit routine which, in the latter case, may be the same exit routine. When processing is complete, control must be returned to the API by branching to the address contained in register 14 when the exit routine was entered.

All protocol event exits are entered with register 1 containing the address of a TXP. The TXP identifies the exit type (TXPTYPE) as a protocol event (TXPTPROT), TXPEPID contains the endpoint ID for the endpoint associated with the protocol event, and TXPPARM contains a fullword value identifying the particular event. The event code is in multiples of four and can be used as a branch or table index to locate the appropriate processing routine.

These protocol event codes are defined:

The event code is used by the API to determine which exit routine address to load from the exit list. Therefore, the application program can supply a different exit routine for each protocol event, or supply a common exit routine that handles all events, or a particular subset of events. If no exit routine is specified in the TOPEN or AOPEN exit list, the application program cannot receive asynchronous notification of the corresponding protocol event.

A protocol event exit routine generally issues an appropriate TPL-based macro instruction to clear the pending indication. Since the indication serves to notify the application program that some awaited event has occurred, it is generally safe to issue the responding macro instruction in synchronous mode without fear of suspending the exit routine for an indefinite period of time. However, the exit routine must be suspended long enough for the API address space to complete the service request. Therefore, for optimum performance, it may be better to execute the request in asynchronous mode and supply a TPL exit routine to handle the subsequent completion.

The exit routine is not obliged to clear the pending indication in the exit routine. Instead, an ECB could be posted on which the mainline program is waiting. When the exit routine completes its processing, control must be returned to the API by branching to the address contained in register 14 when the exit routine was entered.

The CONNECT exit routine is scheduled or the ECB is posted when a connect indication is generated and no TLISTEN service request is outstanding (in other words, the TLISTEN request has been issued and is awaiting completion). A connect indication is generated by the API on receiving a T-CONNECT.indication primitive issued by the transport provider. Connect indications can only be generated on endpoints in the enabled (TSENABLD) or connect-indication-pending (TSINCONN) state.

Once the CONNECT exit routine has been scheduled, it is not rescheduled until all available connect indications have been received by a TLISTEN macro instruction. If another T-CONNECT.indication is issued by the transport provider, it is queued without rescheduling the CONNECT exit routine. Therefore, once the CONNECT exit routine has been entered, sufficient TLISTEN service requests should be issued to receive all of the indications that have been queued. The COUNT field (TPLCOUNT) returned in the TPL by TLISTEN indicates the number of additional connect indications to be received. Also, a bit (TOMORE) is set in the option code field (TPLOPCD2) to indicate more connect indications are available. The application program should receive and accept or reject connect indications quickly since a limited number may be queued (see the QLSTN parameter on the TBIND macro instruction in the Cisco IOS for S/390 Assembler API Macro Reference).

When associations are being used with an endpoint operating in connectionless mode (CLTS), datagrams arriving from a new source address causes a connect indication to be simulated. The datagram is queued until the connect indication is received and accepted. Thus, the CONNECT exit routine can be used to form CLTS associations in the same manner it is used to establish COTS connections.

The CONFIRM exit routine is scheduled when a confirm indication is generated and no TCONFIRM service request is outstanding. A confirm indication is generated by the API on receiving a T-CONNECT.confirm primitive issued by the transport provider. Confirm indications can only be generated on endpoints in the connect-in-progress (TSOUCONN) state (in other words, a TCONNECT macro instruction has been successfully executed at the endpoint and the application program is awaiting connect confirmation).

If the TCONFIRM macro instruction completes successfully, the connection has been established and the state of the endpoint becomes connected (TSCONNCT).

If the application program no longer desires to establish the connection, a TDISCONN macro instruction should be executed instead.

The exit routine is not obliged to receive (or clear) the confirm indication and may defer this responsibility to the mainline program by posting an ECB on which it is waiting.

A confirm indication can only occur as the result of a successful TCONNECT service request. Therefore, only one confirm indication can be received on a given endpoint until the connection is released, and another TCONNECT request is issued. If the endpoint is operating in connectionless mode with associations, a confirm indication is simulated when the TCONNECT request is issued. Thus, the CONFIRM exit routine can be used to form CLTS associations in a manner similar to COTS connections.

The DATA exit routine is scheduled when a normal data indication is generated and no TRECV service request is outstanding. A normal data indication is generated by the API on receiving a T-DATA.indication primitive from the transport provider. Normal data indications can only be generated on endpoints in the connected (TSCONNCT) or release-in-progress (TSOURLSE) state.

The DATA exit routine should execute a TRECV macro instruction to receive the data buffered for the endpoint. Alternatively, the DATA exit routine may defer this responsibility to the mainline program by posting an ECB on which it is waiting. However, optimum performance is achieved by receiving the data as soon as possible.

Once the DATA exit routine has been scheduled, it is not rescheduled until all available data has been received by the application program. If another T-DATA.indication primitive is issued by the transport provider and some previous data has not yet been received, new data is buffered at the endpoint without rescheduling the DATA exit routine. Therefore, once the DATA exit routine has been entered, sufficient TRECV service requests should be issued to receive all of the available data. A bit (TOMORE) is set in the option code field (TPLOPCD2) of the TPL to indicate more data is available to be received (see the description of the TRECV macro instruction in the Cisco IOS for S/390 Assembler API Macro Reference).

The DGERR exit routine is scheduled whenever the transport provider indicates to the API that it could not deliver a datagram previously transferred with a TSENDTO service request. The transport provider detected the error after the TSENDTO request was completed successfully. Datagram error indications can only occur on CLTS endpoints that are in the disabled (TSDSABLD) state.

The DGERR exit routine should execute a TRECVERR macro instruction to receive the protocol address and protocol options associated with the datagram in error. A protocol-dependent datagram error code is also returned (read Cisco IOS for S/390 Assembler API Macro Reference for more information).

The disconnect indication serves to notify the application program that an established connection has been released or a connection attempt has been abandoned. The exit routine should execute a TCLEAR macro instruction that returns the endpoint to the enabled or disabled state. Alternatively, the exit routine may post an ECB waited on by the mainline program, and the mainline program can issue the TCLEAR macro instruction. The TCLEAR macro instruction receives information associated with the disconnect indication, including disconnect user data and a protocol-dependent disconnect reason code.

Only one disconnect indication can be generated per established connection or connection attempt. A disconnect indication is never generated for a CLTS endpoint.

The RELEASE exit routine is scheduled when a release indication is generated and no TRELACK service request is outstanding. A release indication is generated by the API on receiving a T-RELEASE.indication primitive from a transport provider that supports orderly release of a connection. Release indications can only be generated on endpoints in the connected (TSCONNCT) or release-in-progress (TSOURLSE) state.

The RELEASE exit routine should execute a TRELACK macro instruction to acknowledge the release indication. Alternatively, the exit routine may post an ECB on which the mainline program is waiting, and the mainline program can acknowledge the release indication.

Only one release indication is generated per established connection, and can only be generated on endpoints for which the orderly release option was selected. If the endpoint is operating in connectionless mode using associations, the optional orderly release service is automatically selected. In this case, a release indication is simulated when the application program executes a TRELEASE macro instruction.

Once the XDATA exit routine has been scheduled, it is not rescheduled until all available data has been received by the application program. If another T-EXPEDITED-DATA.indication primitive is issued by the transport provider and some previous data has not yet been received, new data is buffered at the endpoint without rescheduling the XDATA exit routine. Therefore, once the XDATA exit routine has been entered, sufficient TRECV service requests should be issued to receive all of the available data. A bit (TOMORE) is set in the option code field (TPLOPCD2) to indicate more data is available to be received (read Cisco IOS for S/390 Assembler API Macro Reference for more information).

For the purpose of scheduling exit routines, expedited data is treated as normal data if no XDATA exit routine has been specified. If the DATA and XDATA exit routines have both been specified, an expedited data indication is generated if no expedited data is available to be received and new expedited data arrives. However, if expedited data is pending, newly arriving normal data does not generate a normal data indication, and the DATA exit routine is not scheduled.

This table summarizes when the DATA and XDATA exit routines are scheduled:

Used to handle physical errors and exceptional conditions

Used to handle program logic errors

If the appropriate error recovery exit routine is not provided by the application program, the detection and recovery from such errors must be handled inline with the macro instruction. The SYNAD and LERAD exit routines are specified in the AOPEN exit list and apply to all endpoints opened by a given transport user (in other words, the application program task).

The SYNAD or LERAD exit routine can be entered at two different points during the execution of any TPL-based service request:

• If the initial request for the operation fails (in other words, after it is rejected)

• If the request is accepted, after the operation fails (in other words, after it is completed abnormally)

If the TPL-based macro instruction is executed in asynchronous mode, then the first point occurs just prior to returning control to the next sequential instruction following the TPL-based macro instruction, and the second point occurs just prior to returning control to the next sequential instruction following the corresponding TCHECK macro instruction.

If the TPL-based macro instruction is executed in synchronous mode, then the TCHECK function is embedded, and the application program cannot distinguish at which point entry was made.

In either case, entry into a SYNAD or LERAD exit routine is made no more than once for any given instance of a TPL-based macro instruction.

The SYNAD or LERAD exit routine is entered with the TPL address in register 1, and a recovery action code in register 0. The recovery action code can be used to determine error recovery procedures. This is the same recovery action code that is returned to the application program if a SYNAD or LERAD exit routine is not specified. The value of the recovery action code also determines which exit routine is entered. Therefore, the SYNAD and LERAD exit list addresses can specify a common exit routine, or separate exit routines tailored for their individual use.

Register 14 contains an address in the API that the exit routine should branch to if it desires to return control to the next sequential instruction in the application program. If control is returned, the contents of registers 0 and 15 is passed through to the application program, and the contents of registers 2-12 is restored from the save area whose address is in register 13. The exit routine should take care not to modify the contents of the save area or the save area address. If the exit routine requires its own save area, one should be allocated, and the contents of register 13 should be restored before returning to the API.

On entry to the SYNAD or LERAD exit routine, registers 2-12 contain the application program's general-purpose registers at the time the initial request was issued or when the TCHECK macro instruction was executed, depending at which point the exit routine was called. The exit routine can take advantage of this fact if it knows how those registers are used by the application program. The exit routine is free to use the registers for any purpose without restoring them before returning to the API.

If the TCHECK or TPL-based macro instruction that caused entry into the SYNAD or LERAD exit routine used one of the general registers between 2 and 12 inclusive to contain the TPL address, bit 0 of that register is copied into bit 0 of register 1. If the mainline program assures that bit 0 is always reset when issuing a TPL-based request, and the exit routine assures bit 0 is set when issuing such a request, recursion can be detected by testing register 1. Any SYNAD or LERAD exit routine that issues TPL-based requests should test for recursion or risk entering an endless loop.

There are some circumstances when the SYNAD or LERAD exit routine cannot be entered. This happens when a fatal error occurs before the proper environment can be established to call the exit routine. In this case, control is always returned to the next sequential instruction in the application program. The general return code in register 15 is greater than 4, indicating that a fatal error occurred. This usually occurs before a TPL-based request is accepted, but can also occur on a TCHECK macro instruction if the TPL or some internal control block has become corrupted.

These are examples of fatal errors that prevent scheduling of the SYNAD or LERAD exit routine:

• An invalid function code was detected

• The TPL does not contain a valid control block identifier, or resides in store-protected memory

• The TPL does not contain a valid endpoint ID

• The APCB or internal API control blocks have become corrupted

• The APCB is closed

If control is returned to the API, register 15 should contain a general return code which the application program can test for success or failure. If the exit routine was able to recover from the error, a 0 should be returned to indicate success. This appears to the application program as if no error occurred. Otherwise, a non-zero value should be returned. We recommend that the exit routine use values consistent with the design of the API.

If the exit routine chooses not to return, control continues as if there were a branch to the exit routine immediately following the TCHECK or TPL-based macro instruction. However, this is permitted only if the TCHECK or TPL-based macro instruction was executed by the mainline program, or an extension thereof. If the SYNAD or LERAD exit routine was entered from a macro instruction executed by an asynchronous exit routine, be careful to always return to the API so the asynchronous exit routine can also return control.

The LERAD exit routine is entered when a program logic error occurs. Errors of this type are generally detected early before a TPL-based request is accepted by the API. The recovery action code in register 0 is set to one of these values:

TAFORMAT and TAPROCED errors enter the LERAD exit routine with the TPL set inactive and the TPLRTNCD field containing valid return-code information. The specific error code (TPLERRCD) and diagnostic code (TPLDGNCD) contain additional information regarding the error.

If the recovery action code is set to TATPLERR, the TPL is still active and return-code information could not be stored. This recovery action code can occur as the result of one of these different circumstances:

• A TPL-based request was issued and the associated TPL was active

• A TCHECK macro instruction was executed before the TPL was marked complete.

The second circumstance can only occur for asynchronous requests for which a TPL exit routine has been specified (in other words, the TCHECK macro instruction was executed before the exit routine was entered). For this recovery action code there is no way for the exit routine to differentiate the cause of the error.

Program logic errors typically occur while an application program is being developed and debugged. Hopefully, once debugging is complete, errors of this type do not occur. Therefore, it is unusual for a LERAD exit routine to attempt to recover from such errors. The best course of action is to dump the address space and terminate the application program.

The SYNAD exit routine is entered when a physical error or exceptional condition occurs. Unlike program logic errors, which tend not to occur after a program has been debugged, these errors can happen at any time and often occur after a TPL-based request has been accepted by the API.

The recovery action code in register 0 is set to one of these values:

The SYNAD exit routine is always entered with the TPL set inactive and the TPLRTNCD field containing valid return-code information stored by the API. A copy of the recovery action code is stored in the TPL (TPLACTCD) along with a specific error code (TPLERRCD) and a diagnostic code (TPLDGNCD). This information can be used to determine more precisely the particular cause of the error.

Similarly, TXPUCNTX is related to the endpoint and is specified when the endpoint is opened by coding the UCNTX parameter on the TOPEN macro instruction. The API merely copies this information into the TXP before the exit routine is entered.

For those exit routines that are not provided a TXP, a different technique may be used. In this case, the exit routine is always provided the address of a TPL. Since the application program provides the TPL, it can arrange to have the TPL located relative to other information.

• Synchronous

For synchronous TPL-based requests, a single macro instruction is issued. On return to the application program, error or exceptional-condition information about the requested operation is available.

• Asynchronous

For asynchronous requests, two TPL-based macro instructions are required:

• A request macro instruction

• A TCHECK macro instruction

Error and exceptional-condition information can thus be returned at two different stages, as a result of the request for the operation being accepted and, if the request is accepted, as a result of the operation completing successfully or unsuccessfully.

The general return code also indicates what other information is available in register 0 and the return code field of the TPL.

• They are used by the API to determine whether the SYNAD or LERAD exit routine should be entered following the unsuccessful completion of a request

• They provide the exit routine a way distinguish a class of errors and to dispatch the appropriate processing routine. These recovery actions codes are used by the API:

Specific error codes have been carefully selected to have generic applicability across a variety of transport providers.

Diagnostic codes are provider-dependent, and an application program that is intended to be portable between transport providers should not analyze this code. However, it is a good idea to include the diagnostic code with any information recorded for diagnostic purposes.

The diagnostic code is four bytes in length. The first 2 bytes are the module ID, followed by a 2-byte serial number that identifies a particular error within the module:

Figure 3-7: Diagnostic Code

The four byte diagnostic code appears in API traces and is recorded in the extended diagnostic area if TPL extensions are used.

When returned to the standard TPL, the diagnostic code is uniquely mapped to a 2 byte code.

The first byte identifies the module that encountered the error. The second byte identifies a specific error instance identifier within the module.

Diagnostic codes that can accompany specific error codes are listed in the Cisco IOS for S/390 Unprefixed Messages and Codes Reference.

• The task that issues the ACLOSE macro instruction must be the task that opened the APCB.

• All asynchronous exit routines are entered from an IRB on the TCB of the task that opened the APCB to which the exit list is linked.

• All asynchronous exit routines are entered from an IRB on the TCB of the task that opened the endpoint to which the exit list is linked.

• All asynchronous exit routines associated with a given task are executed at the same priority (in other words, asynchronous exit routines are serialized at the task level).

• If desired, other tasks may issue TPL-based requests (other than TOPEN and TCLOSE) for any given endpoint. However, exits continue to execute on the owning task, as mentioned in the previous two rules.

• Exits associated with an endpoint that is passed with a TCLOSE OPTCD=PASS macro will be driven in the task that issues the corresponding TOPEN OPTCD=OLD when the TOPEN completes.

• A task that relinquishes control of an endpoint by issuing a TCLOSE macro instruction (with OPTCD=PASS) is treated as if it had never opened the endpoint at all.

• The task that receives control of an endpoint by issuing a TOPEN macro instruction (with OPTCD=OLD) becomes the owning task, and is treated as if it originally opened the endpoint.

An additional facility is provided to pass sessions from one address space to another. Using this facility involves establishing a session up to some state (with no active data transfer in progress) and issuing a TCLOSE macro with OPTCD=PASS. Optionally, the user may specify which address space, by ASCB address, can receive the session. The receiving program issues a TOPEN macro specifying the original endpoint ID, the OPTCD=OLD, the ASCB address of the address space that is passing the endpoint, and optionally the TCB address of the task that is passing the endpoint. The endpoint does not need to be in common storage.

Do not assume that the endpoint ID remains the same after the TOPEN OPTCD=OLD is issued; as in any TOPEN invocation, the endpoint ID token should be copied on completion of the TOPEN and used in all subsequent requests that refer to the endpoint.

The application may also specify ASCB=ANY on the TCLOSE OPTCD=PASS macro to indicate that the endpoint is eligible for passing to any address space that issues a matching TOPEN OPTCD=OLD request.

Initialization of the second address space, passing the required information, and synchronization of the two address spaces is up to the user.