The Oracle Tuxedo system uses TP-STATUS IN TPSTATUS-REC to supply information to a process when a routine fails. All ATMI calls set
TP-STATUS to a value that describes the nature of the error. When a call does not return to its caller, as in the case of
TPRETURN or
TPFORWAR, which are used to terminate a service routine, the only way the system can communicate success or failure is through
TP-STATUS in the requester.
APPL-RETURN-CODE is used to communicate user-defined conditions only. The system sets the value of
APPL-RETURN-CODE to the value of
APPL-CODE IN TPSVCRET-REC during
TPRETURN. The system sets
APPL-RETURN-CODE, regardless of the value of
APPL-RETURN-CODE IN TPSTATUS-REC during
TPRETURN, unless an error is encountered by
TPRETURN or a transaction timeout occurs.
Oracle Tuxedo system errors indicate problems at the system level, rather than at the application level. When Oracle Tuxedo system errors occur, the system writes messages explaining the exact nature of the errors to the central event log, and returns
TPESYSTEM in
TP-STATUS. For more information, refer to the
“Central Event Log” on page 11‑21. Because these errors occur in the system, rather than in the application, you may need to consult the system administrator to correct them.
When TPSEND and
TPRECV fail with a
TPEEVENT error after a conversational connection is established, an event has occurred. Data may or may not be sent by
TPSEND, depending on the event. The system returns
TPEEVENT in the
TPEVENT member of
TPSTATUS-REC and the course of action is dictated by the particular event.
The TPEMATCH error code is returned in
TP-STATUS when an attempt is made to perform an operation that results in a duplicate object. The following table lists the routines that may return the
TPEMATCH error code and the associated cause.
|
|
|
The svcname specified is already advertised for the server but with a function other than func. Although the function fails, svcname remains advertised with its current function (that is, func does not replace the current function name).
|
|
The tranid points to a transaction identifier that another process has already resumed. In this case, the caller’s state with respect to the transaction is not changed.
|
|
|
If TPRETURN encounters an error in processing or handling arguments, the system returns an error to the original requester and sets
TP-STATUS to
TPESVCERR. The receiver determines that an error has occurred by checking the value of
TP-STATUS. The system does not send the data from the
TPRETURN call, and if the failure occurred on
TPGETRPLY, it renders the call handle invalid.
If TPRETURN does not encounter the
TPESVCERR error, then the value returned in
TP-RETURN-VAL determines the success or failure of the call. If the application specifies
TPFAIL in the
TP-RETURN-VAL, the system returns
TPESVCFAIL in
TP-STATUS and sends the data message to the caller. If
TP-RETURN-VAL is set to
TPSUCCESS, the system returns successfully to the caller,
TP-STATUS is not set, and the caller receives the data.
The TPEBLOCK and
TPGOTSIG error codes may be returned at the request or the reply end of a message and, as a result, can be returned for all communication calls.
The system returns TPEBLOCK when a blocking condition exists and the process sending a request (synchronously or asynchronously) indicates, by setting
TPPNOBLOCK that it does not want to wait on a blocking condition. A blocking condition can exist when a request is being sent if, for example, all the system queues are full.
When TPCALL indicates a no blocking condition, only the sending part of the communication is affected. If a call successfully sends a request, the system does not return
TPEBLOCK, regardless of any blocking situation that may exist while the call waits for the reply.
The system returns TPEBLOCK for
TPGETRPLY when a call is made
TPNOBLOCK and a blocking condition is encountered while
TPGETRPLY is awaiting the reply. This may occur, for example, if a message is not currently available.
The TPGOTSIG error indicates an interruption of a system call by a signal; this situation is not actually an error condition. If
TPSIGRSTRT is set, the calls do not fail and the system does not return the
TPGOTSIG error code in
TP-STATUS.
|
|
|
|
|
The calling process references a service called 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, ensure that you have referenced the service correctly; otherwise, check with the system administrator.
|
|
|
|
|
|
The system cannot unadvertise SERVICE-NAME IN TPSVCDEF-REC because the name is not currently advertised by the calling process.
|
The TPENQUEUE(3cbl) or
TPDEQUEUE(3cbl) routine returns
TPEDIAGNOSTIC in
TP-STATUS if the enqueuing or dequeuing on a specified queue fails. The reason for failure can be determined by the diagnostic returned via the
ctl record. For a list of valid
ctl flags, refer to
TPENQUEUE(3cbl) or
TPDEQUEUE(3cbl) in the
Oracle Tuxedo ATMI COBOL Function Reference.
The Oracle Tuxedo system returns TPERELEASE in
TP-STATUS if a compatibility issue exists between multiple releases of an Oracle Tuxedo system participating in an application domain.
For example, the TPERELEASE error may be returned if the
TPACK flag is set when issuing the
TPNOTIFY(3cbl) routine (indicating that the caller blocks until an acknowledgment message is received from the target client), but the target client is using an earlier release of the Oracle Tuxedo system that does not support the
TPACK acknowledgement protocol.
Resource manager errors can occur with calls to TPOPEN(3cbl) and
TPCOSE(3cbl), in which case the system returns the value of
TPERMERR in
TP-STATUS. This error code is returned for
TPOPEN when the resource manager fails to open correctly. Similarly, this error code is returned for
TPCLOSE when the resource manager fails to close correctly. To maintain portability, the Oracle Tuxedo system does not return a more detailed explanation of this type of failure. To determine the exact nature of a resource manager error, you must interrogate the resource manager.
A blocking timeout specifies the maximum amount of time that an application waits for a reply to a service request. The application administrator defines the blocking timeout for the system in the configuration file.
A transaction timeout defines the duration of a transaction, which may involve several service requests. To define the transaction timeout for an application, pass the
T-OUT argument to
TPBEGIN.
TPETIME indicates a blocking timeout on a communication call if the call was not made in transaction mode or if
TPNOBLOCK was not set.
Note:
|
If you set TPNOBLOCK, a blocking timeout cannot occur because the call returns immediately if a blocking condition exists.
|
The TPCALL and
TPGETRPLY calls return
TPEOTYPE when a reply message is sent in a record that is not recognized or not allowed by the caller. In the latter case, the record type is included in the type switch, but the type returned does not match the record that was allocated to receive the reply and a change in record type is not allowed by the caller. The caller indicates this preference by setting
TPNOCHANGE. In this case, strong type checking is enforced; the system returns
TPEOTYPE when it is violated. By default, weak type checking is used. In this case, a record type other than the type originally allocated may be returned, as long as that type is recognized by the caller. The rules for sending replies are that the reply record must be recognized by the caller and, if strong type checking has been indicated, you must observe it.
. . .
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)
reference page. Other return codes are not possible,
so there is no need to test them.
. . .
continue
The values of TP-STATUS provide details about the nature of each problem and suggest the level at which it can be corrected. If your application defines a list of error conditions specific to your processing, the same can be said for the values of
APPL-RETURN-CODE IN TPSTATUS-REC.
•
|
Further calls to TPGETRPLY or TPRECV for any outstanding handles return a global state of transaction timeout; the system sets TP-STATUS to TPETIME.
|
•
|
Once a handle is used with TPGETRPLY to retrieve a reply, or with TPSEND or TPRECV to report an error condition, it becomes invalid and any further reference to it returns TPEBADDESC. This rule is always observed, regardless of whether the code is running in transaction mode.
|
•
|
TPRETURN encounters an error while processing its arguments; TP-STATUS is set to TPESVCERR.
|
•
|
The TP-RETURN-VAL to TPRETURN was set to TPFAIL; TP-STATUS is set to TPESVCFAIL.
|
•
|
TPCOMMIT is called by a participant rather than by the originator of a transaction; TP-STATUS is set to TPEPROTO.
|
If TPCOMMIT is called after an initiator/participant failure or transaction timeout, the result is an implicit abort error. Then, because the commit failed, the transaction should be aborted.
If the system returns TPESVCERR,
TPESVCFAIL,
TPEOTYPE, or
TPETIME for any communication call, the transaction should be aborted explicitly with a call to
TPABORT. You need not wait for outstanding communication handles before explicitly aborting the transaction. However, because these communication handles are considered stale after the call is aborted, any attempt to access them after the transaction is terminated returns
TPEBADDESC.
In the case of TPESVCERR,
TPESVCFAIL, and
TPEOTYPE, communication calls continue to be allowed as long as the transaction has not timed out. When these errors are returned, the transaction is marked abort-only. To preserve the results of any further work, you should call any communication functions with
TPNOTRAN. By setting this flag, you ensure that the work performed for the transaction marked “abort-only” will not be rolled back when the transaction is aborted.
The TPCOMMIT call may return
TPEHAZARD or
TPEHEURISTIC, depending on how
TP-COMMIT-CONTROL is set.
If you set TP-COMMIT-CONTROL to
TP-CMT-LOGGED, the application obtains control before the second phase of a two-phase commit is performed. In this case, the application may not be aware of a heuristic decision that occurs during the second phase.
TPEHAZARD or
TPEHEURISTIC can be returned in a one-phase commit, however, if a single resource manager is involved in the transaction and it returns a heuristic decision or a hazard indication during a one-phase commit.
If you set TP_COMMIT_CONTROL to
TP_CMT_COMPLETE, then the system returns
TPEHEURISTIC if any resource manager reports a heuristic decision, and
TPEHAZARD if any resource manager reports a hazard.
TPEHAZARD specifies that a participant failed during the second phase of commit (or during a one-phase commit) and that it is not known whether a transaction completed successfully.
When a process is in transaction mode and makes a communication call with TPNOTRAN, it prohibits the called service from becoming a participant in the current transaction. Whether the service request succeeds or fails has no impact on the outcome of the transaction. The transaction can still timeout while waiting for a reply that is due from a service, whether it is part of the transaction or not.
If you call a process while running in transaction mode, TPRETURN and
TPFORWAR place the service portion of the transaction in a state that allows it to be either committed or aborted when the transaction completes. You can call a service several times on behalf of the same transaction. The system does not fully commit or abort the transaction until the initiator of the transaction calls
TPCOMMIT or
TPABORT.
Neither TPRETURN nor
TPFORWAR should be called until all outstanding handles for the communication calls made within the service have been retrieved. If you call
TPRETURN with outstanding handles for which
TP-RETURN-VAL is set to
TPSUCCESS, the system encounters a protocol error and returns
TPESVCERR to the process waiting on
TPGETRPLY. If the process is in transaction mode, the system marks the caller as “abort-only.” Even if the initiator of the transaction calls
TPCOMMIT, the system implicitly aborts the transaction. If you call
TPRETURN with outstanding handles for which
TP-RETURN-VAL is set to
TPFAIL, the system returns
TPESVCFAIL to the process waiting on
TPGETRPLY. The effect on the transaction is the same.
When you call TPRETURN while running in transaction mode, this function can affect the result of the transaction by the processing errors that it encounters or that are retrieved from the value placed in
TP-RETURN-VAL by the application.
You can use TPFORWAR to indicate that success has been achieved up to a particular point in the processing of a request. If no application errors have been detected, the system invokes
TPFORWAR; otherwise, the system invokes
TPRETURN with
TPFAIL. If you call
TPFORWAR improperly, the system considers the call a processing error and returns a failed message to the requester.
Use the TPTERM call to remove a client context from an application.
•
|
TPRETURN and TPFORWAR, when called by the participating service, place that service’s portion of the transaction in a state from which it can be either aborted or committed by the initiator.
|
•
|
TPNOREPLY cannot be used when calling another service to participate in the current transaction.
|
If you issue a communication call with TPNOTRAN set and the called service is configured such that a transaction automatically starts when the service is called, the system places both the calling and called processes in transaction mode, but the two constitute different transactions. In this situation, the following facts apply:
•
|
TPRETURN plays the initiator’s transaction role: it terminates the transaction in the service in which the transaction was automatically started. Alternatively, if the transaction is automatically started in a service that terminates with TPFORWAR, the TPRETURN call issued in the last service in the forward chain plays the initiator’s transaction role: it terminates the transaction. (For an example, refer to the figure called “Transaction Roles of TPFORWAR and TPRETURN with AUTOTRAN” on page 11‑20.)
|
•
|
Because it is in transaction mode, TPRETURN is vulnerable to the failure of any participant in the transaction, as well as to transaction timeouts. In this scenario, the system is more likely to return a failed message.
|
If a communication call is made with TPNOTRAN, and the called service is not automatically placed in transaction mode by a configuration option, the service can define multiple transactions using explicit calls to
TPBEGIN,
TPCOMMIT, and
TPABORT. As a result, the transaction can be completed before a call is issued to
TPRETURN.
•
|
TPRETURN plays no transaction role; that is, the role of TPRETURN is always the same, regardless of whether transactions are explicitly defined in the service routine.
|
•
|
TPRETURN can return any value in TP-RETURN-VAL, regardless of the outcome of the transaction.
|
The Oracle Tuxedo system server calls TPSVRINIT during initialization. Specifically,
TPSVRINIT is called after the calling process becomes a server but before it starts handling service requests. If
TPSVRINIT performs any asynchronous communication, all replies must be retrieved before the function returns; otherwise, the system ignores all pending replies and the server exits. If
TPSVRINIT defines any transactions, they must be completed with all asynchronous replies retrieved before the function returns; otherwise, the system aborts the transaction and ignores all outstanding replies. In this case, the server exits gracefully.
The Oracle Tuxedo system server abstraction calls TPSVRDONE after it finishes processing service requests but before it exits. At this point, the server’s services are no longer advertised, but the server has not yet left the application. If
TPSVRDONE initiates communication, it must retrieve all outstanding replies before it returns; otherwise, pending replies are ignored by the system and the server exits. If a transaction is started within
TPSVRDONE, it must be completed with all replies retrieved; otherwise, the system aborts the transaction and ignores the replies. In this case, too, the server exits.
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.