The purpose of this chapter is to review the transaction and communication concepts discussed in the preceding chapters with the focus on how to manage and interpret error conditions correctly.

What are the means used by System/T to communicate to the application that a routine call has failed allowing the programmer to implement the appropriate logic? What are the various scenarios for determining whether to commit or abort a transaction? What errors are fatal to transactions? How does transaction mode affect the concept of time-out and what are the implications? How does transaction mode affect the roles of the routine calls and how they may be used? What operations are part of one transaction and what are the determining factors? Does the fate of one transaction ever determine the fate of another? What communication rules must be followed between processes within and not within the same transaction? How do global transaction calls affect the use of local transaction-defining routines (that is, routines used to explicitly mark the beginning and end of a local transaction) that may be part of the Data Manipulation Language (DML) that is native to the resource manager?

Many of these subjects have been touched upon already in earlier chapters. Now let's attempt to bring them together to explain the functionality of the ATMI, showing how the various pieces fit together following consistent rules that create an environment that combines message communication with transaction integrity.

Communicating Errors

The following discussion concerns how System/T communicates errors to the application developer. It is couched in terms of categories of errors and whether they are application or system-based. Hopefully, this discussion will give you more insight as to what errors to expect, what effect they have on transactions, and what kind of control you as a programmer have over them.

Throughout the guide, there has been a continual reference to the field TP-STATUS of TPSTATUS-REC. In an environment of concurrent processes, this is a key way to inform processes if their routine calls have succeeded or not. All the ATMI routines set TP-STATUS to a value that reveals the nature of the error. In cases where the routine does not return to its caller, as in the case of TPRETURN or TPFORWAR, since they are called to terminate a service routine, the only way to communicate success or failure is through APPL-RETURN-CODE IN TPSTATUS-REC in the requester.

APPL-RETURN-CODE IN TPSTATUS-REC can also be used to communicate user-defined conditions. The value in APPL-RETURN-CODE is set from the value placed in APPL-CODE IN TPSVCRET-REC during TPRETURN. This code is sent regardless of the setting of TP-RETURN-VAL IN TPSVCRET-REC unless an error is encountered by TPRETURN or a transaction time-out occurs.

Values of TP-STATUS

The setting returned by TP-STATUS IN TPSTATUS-REC represent categories of errors. All the ATMI routines whose failure is reported by the setting returned by TP-STATUS have the four basic categories of

• protocol errors (TPEPROTO)

• System/T errors (TPESYSTEM)

• operating system errors (TPEOS)

• errors from invalid members (TPEINVAL)

Protocol Errors

Protocol errors occur because an ATMI routine was called in an incorrect context. Refer to the INTRO manual page. This type of error usually happens for one of two reasons. Either the ATMI call is being made

• in the wrong order

• or by the wrong process.

A transaction participant rather than the initiator calling TPCOMMIT is a protocol error because the participant is the wrong process to be calling TPCOMMIT. This type of error is one that is totally correctable at the application level by enforcing the rules of order and propriety associated with the ATMI calls (that is, by making calls in the correct order by the appropriate processes). Since each ATMI call can return a protocol error, attempt to discover the exact error in the context of the semantics of the specific call and ask the two questions:

• Is this call being made in the correct order?

• Is this call being made by the correct process?

System/T Errors

When System/T errors occur, messages explaining their exact nature are written to the central event log. The last major section in this chapter explains this log in detail. Since these are system errors rather than application errors, the systems administrator may be needed to help correct them.

Operating System Errors

Operating system errors indicate that a system call has failed. A numeric value identifying the failed system call is returned in the global variable, Uunixerr. Operating system errors are seldom application errors; systems administration may need to be called on to correct them.

Errors from Invalid Arguments

All of the ATMI routines that take arguments can fail if invalid arguments are passed to them. In the case where the routine returns to the caller, the routine fails and sets TPEINVAL. In the case of TPRETURN or TPFORWAR if this type of error is discovered while processing the arguments, TPESVCERR is set for the routine waiting on the call; that is either TPCALL or TPGETRPLY. This is an application error and is correctable by the programmer.

Other Possible Error Categories

In addition to the four basic categories just discussed, others include

• errors from lack of entries in system tables or the data structure used to identify record types (TPENOENT)

• errors from incorrect permission to enter the application (TPEPERM)

• resource manager errors (TPERMERR)

• transaction related errors (TPETRAN)

• errors from mismatching of typed records (TPEITYPE and TPEOTYPE)

• errors that apply only to asynchronous communication calls or conversational calls because they involve communications handles (TPELIMIT and TPEBADDESC)

• errors that can occur as a result of the communication calls in general (TPESVCFAIL, TPESVCERR, TPEBLOCK, and TPEGOTSIG)

• transaction and blocking time-out errors (TPETIME)

• errors from calling TPCOMMIT when the transaction should have been explicitly aborted (TPEABORT)

• errors that signal that a heuristic decision was (or may have been) taken (TPEHAZARD, TPEHEURISTIC)

No Entry Errors

The no entry type error, TPENOENT, has more than one meaning and depends on which routine call is returning it. The routine that allows you to join the application, TPINITIALIZE, the routine that unlists an advertised service, TPUNADVERTISE, and the communication routines, TPCALL, TPACALL, TPCONNECT and TPGPRIO are the routines that return this error. The following table lists the routines and specifies the reason for the failure in each case.

Function	Explanation
TPINITIALIZE	The calling process cannot join the application because there is no space left in the bulletin board to make an entry for it. See your systems administrator.
TPCALL	The calling process is referencing a service, SERVICE-NAME IN TPSVCDEF-REC that is not known to the system since there is no entry for it in the bulletin board. On an application level, make sure you have referenced the service correctly, otherwise see your systems administrator.
TPACALL	Same as TPCALL.
TPCONNECT	Cannot connect to SERVICE-NAME IN TPSVCDEF-REC because it does not exist or is not a conversational service
TPGPRIO	The calling process is asking for a request priority when no request has been made. The system has no current entry for a request. This is an application error.
TPUNADVERTISE	Cannot unadvertise the service name because it is not currently advertised by the calling process

Permission Errors

The only ATMI routine that returns this error is TPINITIALIZE. If the calling process does not have the correct permissions to enter the application, this call fails returning TPEPERM. Permissions are set in the configuration file and as such the correction of this error is outside of your application. See the System/T administrator if it is encountered.

Resource Manager Errors

These errors can occur with calls to TPOPEN and TPCLOSE and they return a setting of TPERMERR. The meaning of the System/T error code is intentionally vague in this case so as not to hinder portability. The exact nature of the error must be determined by interrogating the resource manager in its own specific manner. Obviously when this error code is returned for TPOPEN, it indicates that the problem has to do with a failure on the part of the resource manager to open correctly and for TPCLOSE, to close correctly.

Transaction-Related Errors

When this type of error occurs, TPETRAN is returned in TP-STATUS. TPBEGIN, TPCANCEL and the TPCALL/TPACALL routines can return this error code. For TPBEGIN, it usually means some transient system error occurred when attempting to start the transaction that may clear up with a repeated call.

TPCANCEL returns this error code when called from within a transaction.

In the case of the communication routines, it means a call was made in transaction mode to a service that does not support transactions. What does this mean? Some services belong to server groups that access a DBMS that can support transactions whereas other services may be responsible for printing out a form and access a printer which knows nothing about transactions. The configuration of services into servers and server groups is an administrative task. In order to determine which services support transactions ask your systems administrator. This is an application error. For the communication call to such a service to succeed, the TPNOTRAN setting for TPSVCDEF-REC must be set. In other words, you may not ask a service that does not support transactions to be a participant in the transaction. If you desire the service, it can be asked for only if the TPNOTRAN setting is explicitly set or if you access the service outside of your transaction.

Typed Record Errors

Typed record errors are returned as a result of sending processes requests or replies in typed records that are unfamiliar to them. TPEITYPE is returned by TPCALL and TPACALL when the request data record is sent to a service that does not know about this type. What does this mean? The record types that processes know about are determined both by the configuration file and by the System/T libraries that have been linked into the process. These libraries define and initialize a data structure to the typed records that the process is to know about. The library can be tailored to each process. Also, an application can supply its own copy of a file that defines record types. An application can set up the record type data structure (referred to as a record type switch) on a per process basis. Refer to the tuxtypes(5) and typesw(5) manual pages. This is an administrative decision and is mentioned here to clarify what is meant by a process knowing about a typed record. The rule for sending requests is that you must always send a request in a typed record that a service knows about; this information can be obtained from your systems administrator.

TPEOTYPE is returned by TPCALL and TPGETRPLY when the reply message is sent in a record that is not known or not allowed by the caller. What does this mean? Not known has the same semantics as previously explained for the request record. Not allowed means that although the process knows of the existence of this record type, the type returned to it does not match the type of the record it allocated to receive the reply and the caller is not allowing for there to be a change in record type. The caller indicates this preference by setting TPNOCHANGE. In this case, strong type checking is enforced returning TPEOTYPE when violated. The default is to have weak type checking allowing a different record type to be returned as long as it is known to the caller. Again, the rule for sending replies is that the reply record must be known to the caller and you must observe strong type checking if it has been indicated.

Communication Handle Errors

The errors discussed in this section can occur only when making asynchronous calls or conversational calls because they involve the misuse of the communication handle, COMM-HANDLE IN TPSVCDEF-REC. Asynchronous calls depend on communication handles to identify replies with their corresponding requests. Conversational sends and receives depend on communication handles to identify the connection; the call that initiates the connection depends on the availability of a communications handle. There are two things that System/T doesn't like you to do with communication handles.

• exceed your limit (TPELIMIT)

• reference one that has become invalid (TPEBADDESC)

The limit for outstanding communication handles (replies) has been defined for the system as fifty and is a non-tunable parameter. The only way to change it is to recompile the system. The maximum number of handles allowed should be ample for your application, but this limit is system-defined and cannot be redefined by your application.

The limit for communications handles for simultaneous conversational connections is defined in the configuration file and is more flexible than the limit for replies. The MAXCONV parameter in the &UR; section of the configuration file can be changed when the application is not running; it can be dynamically changed in the &UM; section when the application is running (See tmconfig(1)).

There are two general ways that a communications handle can become invalid. If a communications handle has been used to retrieve a message (including a failed message) and an attempt is made to reuse it, the system complains that you cannot reuse the handle and returns TPEBADDESC.

Sometimes a condition occurs where you can no longer reference a communications handle although it has never been used to retrieve a message. In this case we refer to the handle as having become stale and any attempt to reference it causes TPEBADDESC to be returned. One of the conditions that causes this to happen is calling TPABORT or TPCOMMIT when there are still replies to be retrieved. The outstanding handles for these replies are considered stale. Another condition that causes this to happen is transaction time-out. When it is reported on the call to TPGETRPLY, no message is retrieved with that handle, and any further reference to it is invalid because it is considered stale. This error can be corrected at the application level.

General Communication Call Errors

These errors can occur only when making communication calls but have nothing to do with the nature of the call being synchronous or asynchronous.

The communication errors, TPESVCERR and TPESVCFAIL are the result of the reply part of communication. They can be returned as a result of a call to TPCALL or TPGETRPLY and they are determined by the arguments passed to and the processing done by TPRETURN. If TPRETURN encounters an error in processing or handling arguments, it will cause a failed message to be sent to the caller. This failed message is detected by the receiver with TP-STATUS being set to TPESVCERR. The caller's data is not sent, and if the failure was on TPGETRPLY, the communications handle becomes invalid. If an error of this nature is not encountered by TPRETURN, then the setting for TP-RETURN-VAL determines the success or failure of the call. If the application logic set TPFAIL, TPESVCFAIL is returned and the data message is sent to the caller.

The error codes TPEBLOCK and TPEGOTSIG can happen on the request or the reply end of message communication. As a result, it can be returned for all three of the request/response communication calls. TPEBLOCK is returned when a blocking condition exists and the process sending a request either synchronously or asynchronously has indicated that it does not want to wait on a blocking condition by setting TPNOBLOCK. A blocking condition can exist when sending a request if, for example, all the queues of the desired service are full. When TPCALL indicates a no blocking condition, it affects only the sending part of the communication. If the call successfully sends the request, TPEBLOCK will not be returned regardless of any blocking situation that may exist while the call waits for the reply. TPEBLOCK is returned for TPGETRPLY when the call is made set to TPNOBLOCK and a blocking condition is encountered while awaiting the reply; for example, if a message is not currently available.

TPEGOTSIG really does not flag an error condition but indicates when a signal interrupts a System/T call. If the communication routines set TPSIGRSTRT, the calls will not fail and this code will not be returned.

Conversational Errors

Once a conversational connection has been established, TPSEND and TPRECV can fail with a TPEEVENT error. No data is sent by TPSEND. The event type is returned in the TPEVENT member of TPSTATUS-REC. A course of action is dictated by the particular event.

In conversational services TPSEND, TPRECV and TPDISCON return TPEBADDESC when an unknown handle is specified.

Time-out Errors

Time-out errors can occur for one of two reasons:

• the maximum length of time a blocking call may remain blocked until the caller regains control has exceeded the amount of time it was allotted, that is, a blocking time-out occurred

• the duration of a transaction from start to finish has exceeded the amount of time it was allotted, that is, a transaction time-out occurred

As a result, this error can be returned on communication calls for either blocking or transaction time-out and on TPCOMMIT for transaction time-out only. In every case, if a process is in transaction mode and TPETIME is returned on a failed call, it means a transaction time-out has occurred.

TPETIME indicates a blocking time-out on a communication call if

• the call was not made in transaction mode and

• the call was not made with TPNOBLOCK set

You may recall that if TPNOBLOCK is set, a blocking time-out cannot occur because the call returns immediately if a blocking condition exists.

Blocking time-out is a value set by the administrator of the system and is defined in the configuration file. Transaction time-out is defined by the application by the first argument passed to TPBEGIN.

Further implications concerning the concept of time-out will be discussed in the section Time-out later in this chapter.

Errors Leading to Abort

Errors by a participant in a transaction can cause TPCOMMIT to fail returning the error code of TPEABORT. The transaction is implicitly aborted because of the failure and should be explicitly aborted. There are two ways that this error code can be returned.

• If a transaction has been marked abort-only by the initiator or one of the participants or

• the transaction timed out and its status is known to be aborted.

Heuristic Decision Errors

Based on the how TP-COMMIT-CONTROL is set, TPCOMMIT may return TPEHAZARD or TPEHEURISTIC. If TP-COMMIT-CONTROL is set to TP-CMT-LOGGED, the application gets control before the second phase of the two-phase commit is done, so it may not hear about a heuristic that occurs during the second phase. If TP-COMMIT-CONTROL is set to TP-CMT-COMPLETE, the application finds out about heuristics, but may still get back TPEHAZARD. Since TPEHAZARD simply means that a participant failed during the second phase and we con't know if it completed the transaction successfully or unsuccessfully.

How to Deal with Errors

Figure 1 illustrates a general way of dealing with errors. The term ATMICALL(3) is used in this example to generically represent an ATMI routine call.

Fig. 1: How to Deal with Errors

	. . .
	CALL "TPINITIALIZE" USING TPINFDEF-REC
			USR-DATA-REC
			TPSTATUS-REC.
	IF NOT TPOK
		error message, EXIT PROGRAM
        CALL "TPBEGIN" USING TPTRXDEF-REC
			TPSTATUS-REC.
	IF NOT TPOK
		error message, EXIT PROGRAM
	Make atmi calls
	Check return values
	IF  TPEINVAL
		DISPLAY "Invalid arguments were given."
	IF  TPEPROTO
		DISPLAY "A call was made in an improper context."
	. . .
	Include all error cases described in the ATMICALL(3) manual page
	Other return codes are not possible, so there should be no need
	to test them.
	. . .
	continue

The specific settings of TPSTATUS-REC give you more insight into the nature of the problem and on what level it can be corrected.

Fatal Transaction Errors

In managing transactions, it is important to understand which errors prove fatal to transactions. When these errors are encountered, transactions should be explicitly aborted on the application level by having the initiator of the transaction call TPABORT. Basically, there are three conditions that cause a transaction to fail. They are:

• the initiator or a participant of the transaction caused it to be marked abort-only either because

  • TPRETURN encountered an error while processing its members (TPESVCERR)

  • the TP-RETURN-VAL argument of TPRETURN was set to TPFAIL (TPESVCFAIL)

  • the type or subtype of the reply record is not known or allowed by the caller and as a result success or failure cannot be determined (TPEOTYPE)

• the transaction timed out (TPETIME)

• TPCOMMIT was called by a participant rather than by the originator of a transaction (TPEPROTO)

If TPESVCERR, TPESVCFAIL, TPEOTYPE, or TPETIME is returned for any of the communication calls, the transaction should be explicitly aborted with a call to TPABORT. If there are still outstanding descriptors, there is no need to wait for them before explicitly aborting the transaction. However, any attempt to access these descriptors after the transaction has been terminated will return TPEBADDESC since they are considered stale after the call.

Note that in the case of TPESVCERR, TPESVCFAIL, and TPEOTYPE, communication calls are still allowed as long as the transaction has not timed out. With the return of these errors, the transaction has been marked abort-only. In order for any further work to have any lasting effect, the communication calls should be made with TPNOTRAN. set. In this way the work performed for the transaction that has been marked abort-only will not be rolled back when the transaction is aborted.

When a transaction time-out occurs, communication can continue, but it must be conducted with the following conditions enforced. The communication requests

• cannot require replies

• cannot block

• and cannot be performed on behalf of the caller's transaction

This means asynchronous calls can be made with setting of TPNOREPLY, TPNOBLOCK or TPNOTRAN.

Calling TPCOMMIT from the wrong participant in a transaction represents the only protocol error that is fatal to transactions. This error can be corrected on the application level during the development phase.

Calling TPCOMMIT when there is initiator/participant failure or transaction time-out represents the implicit abort error discussed earlier in the section Errors Leading to Abort. Because the commit failed, the transaction should be aborted.

Time-out

As already indicated there are two possible types of time-out that can occur in System/T. The effect of time-out on communication calls is different depending on the type that occurred. Also, issues concerning

• what happens if a transaction times out while committing and

• do calls to services that are not part of your transaction use time on your transaction clock?

are addressed in the following sections.

Blocking vs. Transaction Time-out

We have defined blocking time-out as exceeding the amount of time a call can wait for a blocking condition to clear up. Transaction time-out occurs when a transaction takes longer than the amount of time defined for it by the T-OUT IN TPTRXDEF-REC argument to TPBEGIN. By default, if a process is not in transaction mode, blocking time-outs are performed. When the communication call is set to TPNOTIME, it applies to blocking time-outs only. If a process is in transaction mode, blocking time-out and the TPNOTIME setting are not relevant. The process is sensitive to transaction time-out only as it has been defined for it when the transaction was started. What are the implications of the two different types of time-out with concern to communication calls?

If a process is not in transaction mode and a blocking time-out occurs on an asynchronous call, the communication call that blocked will fail, but the communications handle is still valid and may be used on a re-issued call. Further communication in general is unaffected.

In the case of transaction time-out, the communications handle to an asynchronous reply becomes stale and may no longer be referenced. The only further communication allowed is the one case described earlier of no reply, no blocking, and no transaction.

Effect on TPCOMMIT

What is the state of a transaction if time-out occurs after the call to TPCOMMIT? It is unknown; the transaction can have either succeeded or failed. If the transaction timed out and the system knows that it was aborted, this is communicated to you by the error code TPEABORT returned in TP-STATUS. If the status of the transaction is unknown, TPETIME is the error code. When the state of the transaction is in doubt, you must query the resource to see if any of the changes that were part of that transaction have been applied to it in order to discover whether the transaction committed or aborted.

Effect of the TPNOTRAN Flag

When a process is in transaction mode and makes a communication call with a setting of TPNOTRAN, it prohibits the called service from becoming a participant of that transaction and as such the service's success or failure cannot influence the outcome of that transaction. This will be discussed in greater detail in the next section, Roles of TPRETURN and TPFORWAR. However, if the caller is expecting a reply, its transaction clock is still ticking away while the services that generate the reply are being performed. As a result, the transaction can time out while waiting for a reply that is due from a service that is not part of that transaction.

Roles of TPRETURN and TPFORWAR

If a process is called in transaction mode, TPRETURN and TPFORWAR place the service's portion of the transaction in a state where it can be either committed or aborted when the transaction is completed by its initiator. A service may be called several times on behalf of the same transaction. It is not fully committed or aborted until the initiator of the transaction calls TPCOMMIT or TPABORT.

Neither TPRETURN nor TPFORWAR should be called until all outstanding descriptors for the communication calls made within the service have been retrieved. If TPRETURN is called with outstanding descriptors with TP-RETURN-VAL set to TPSUCCESS, this constitutes a protocol error and is returned as TPESVCERR to the process waiting on TPGETRPLY. If the process is in transaction mode, it will cause the caller's current transaction to be marked internally as abort-only. Even if the initiator of the transaction should call TPCOMMIT, the transaction is aborted implicitly. If TPRETURN is called with outstanding descriptors with TP-RETURN-VAL set to TPFAIL, TPESVCFAIL is returned to the process waiting on TPGETRPLY. The effect on the transaction is the same.

It is always the case that when TPRETURN is called in transaction mode, it can determine the fate of that transaction either from the processing errors it encounters or from the value the application places in TP-RETURN-VAL. Calling TPFORWAR can be used to indicate success up to that point in processing the request. If no application errors have been detected TPFORWAR is invoked, otherwise TPRETURN with TPFAIL. If TPFORWAR is called improperly, it is considered a processing error and a failed message is returned to the requester.

Many of the ideas presented here have already been discussed in earlier sections, but they bear repeating. The following sections highlight various possible scenarios involving the transaction role of TPRETURN as well as the communication rules.

Service in Same Transaction as Caller

This is the straightforward case of the caller in transaction mode that calls another service to participate in the current transaction. What are the implications?

• TPRETURN and TPFORWAR, when called by the participating service, place that service's portion of the transaction in a state where it can be either aborted or committed by the initiator

• the success or failure of the called process affects the current transaction. If any of the errors that prove fatal to transactions are encountered by the participant, the current transaction is marked abort-only

• the lasting effect of the work done by a successful participant is dependent on the fate of the transaction, that is if the transaction is aborted, the work of all participants is undone

• the TPNOREPLY flag cannot be used when calling another service to participate in the current transaction

Service in Different Transaction with AUTOTRAN Set

If a communication call is made with the TPNOTRAN flag set and the called service is configured so that a transaction will automatically get started when it is called, these processes will both be in transaction mode but they will be in different transactions. What are the implications?

• TPRETURN plays the initiator's transaction role to terminate the transaction in the service where the transaction was automatically started alternatively, if the transaction is automatically started in a service that terminates with TPFORWAR, the TPRETURN in the last service in the forward chain plays the initiator's transaction role to terminate the transaction. Refer to Figure 7.

• because it is in transaction mode, TPRETURN is also vulnerable to failure and is subject to the failure of any participant in the transaction as well as transaction time-out and as a result is more likely to send a failed message to the caller

• any failed messages or application failures returned to the caller do not affect the state of the caller's transaction

• the caller is vulnerable to its own transaction timing out as it waits for its reply

• if no reply is expected, the caller's transaction cannot be affected in any way by the communication call

Transaction Roles of TPFORWAR and TPRETURN with AUTOTRAN

01 LOG-REC PIC X(15) VALUE "UNKNOWN USER ".
01 LOGREC-LEN PIC S9(9) VALUES IS 13.
CALL "USERLOG" USING LOG-REC LOGREC-LEN TPSTATUS-REC.

162214.mach1!security.23451: UNKNOWN USER

162214.mach1!security.23451: COBAPI_CAT: 999: UNKNOWN USER

162214.mach1!security.23451: gtrid x2 x24e1b803 x239:
	UNKNOWN USER

	01 TPSTATUS-REC.
	   COPY TPSTATUS.
	01 LOGMSG 	PIC X(50).
	01 LOGMSG-LEN 	PIC S9(9) COMP-5.
	. . .
	CALL "TPOPEN" USING TPSTSTUS-REC.
	IF NOT TPOK
		MOVE "TPSVRINIT: Cannot Open Data Base" TO LOGMSG
		MOVE 43 LOGMSG-LEN
		CALL "USERLOG" USING LOGMSG
			LOGMSG-LEN
			TPSTATUS-REC.
	. . .