|
|
This topic includes the following sections:
The BEA 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.
The codes returned in TP-STATUS represent categories of errors, which are listed in the following table.
Protocol1
|
|
TPETRAN2
|
|
1Applicable to all ATMI calls for which failure is reported by the value returned in 2Refer to Fatal Transaction Errors for more information on this error category. |
As footnote 1 shows, four categories of errors are reported by TP-STATUS and are applicable to all ATMI calls. The remaining categories are used only for specific ATMI calls.The following sections describe some error categories in detail.
For information on the errors that lead to abort, refer to Fatal Transaction Errors.
BEA Tuxedo system errors indicate problems at the system level, rather than at the application level. When BEA 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. Because these errors occur in the system, rather than in the application, you may need to consult the system administrator to correct them.
Communication handle errors occur as a result of exceeding the maximum limit of communication handles or referencing an invalid value. Asynchronous and conversational calls return TPELIMIT when the maximum number of outstanding communication handles has been exceeded. TPEBADDESC is returned when an invalid communication handle value is specified for an operation.
Communication handle errors occur only during asynchronous calls or conversational calls. (Call descriptors are not used for synchronous calls.) Asynchronous calls depend on communication handles to associate replies with the corresponding requests. Conversational send and receive routines depend on communication handles to identify the connection; the call that initiates the connection depends on the availability of a communication handle.
Communication handle errors can be done by checking for specific errors at the application level.
The system allows up to 50 outstanding communication handles (replies) per context (or BEA Tuxedo application association). This limit is enforced by the system; it cannot be redefined by your application.
The limit for communication handles for simultaneous conversational connections is more flexible than the limit for replies. The application administrator defines the limit in the configuration file. When the application is not running, the administrator can modify the MAXCONV parameter in the RESOURCES section of the configuration file. When the application is running, the administrator can modify the MACHINES section dynamically. Refer to tmconfig, wtmconfig(1) in the BEA Tuxedo Command Reference for more information.
A communication handle can become invalid and, if referenced, cause an error to be returned to TP-STATUS in either of two situations:
A communication handle might become stale, for example, in the following circumstances:
When an unknown handle is specified for conversational services, the TPSEND, TPRECV, and TPDISCON routines return TPEBADDESC.
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.
For a complete description of conversational events, refer to Understanding Conversational Communication Events in Programming BEA Tuxedo ATMI Applications Using C.
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.
For more information on these routines, refer to the BEA Tuxedo ATMI COBOL Function Reference.
General communication call errors can occur during any communication calls, regardless of whether those calls are synchronous or asynchronous. Any of the following errors may be returned in TP-STATUS: TPESVCFAIL, TPESVCERR, TPEBLOCK, or TPGOTSIG.
If the reply portion of a communication fails as a result of a call to TPCALL or TPGETRPLY, the system returns TPESVCERR or TPSEVCFAIL to TP-STATUS. The system determines the error by the arguments that are passed to TPRETURN and the processing that is performed by this call.
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.
Invalid argument errors indicate that an invalid argument was passed to a routine. Any ATMI call that takes arguments can fail if you pass it arguments that are invalid. In the case of a call that returns to the caller, the call fails and causes TP-STATUS to be set to TPEINVAL. In the case of TPRETURN or TPFORWAR, the system sets TP-STATUS to TPESVCERR for either the TPCALL or TPGETRPLY call that initiated the request and is waiting for results to be returned.
You can correct an invalid argument error at the application level by ensuring that you pass only valid arguments to routines.
No entry errors result from a lack of entries in the system tables or the data structure used to identify record types. The meaning of the no entry type error, TPENOENT, depends on the call that is returning it. The following table lists the calls that return this error and describes various causes of error.
Operating system errors indicate that an operating system call has failed. The system returns TPEOS in TP-STATUS. On UNIX systems, the system returns a numeric value identifying the failed system call in the global variable Uunixerr. To resolve operating system errors, you may need to consult your system administrator.
If a calling process does not have the correct permissions to join the application, the TPINITIALIZE call fails, returning TPEPERM in TP-STATUS. Permissions are set in the configuration file, outside of the application. If you encounter this error, check with the application administrator to make sure the necessary permissions are set in the configuration file.
Protocol errors occur when an ATMI call is invoked, either in the wrong order or using an incorrect process. For example, a client may try to begin communicating with a server before joining the application. Or TPCOMMIT may be called by a transaction participant instead of the initiator.
You can correct a protocol error at the application level by enforcing the rules of order and proper usage of ATMI calls.
To determine the cause of a protocol error, answer the following questions:
Protocol errors return the TPEPROTO value in TP-STATUS.
Refer to "Introduction to the COBOL Application-Transaction Monitor Interface" in the BEA Tuxedo ATMI COBOL Function Reference for more information.
The TPENQUE
UE(3cbl) or TPDEQUEU
E(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 TPENQUEU
E(3cbl) or TPDEQU
EUE(3cbl) in the BEA Tuxedo ATMI COBOL Function Reference.
The BEA Tuxedo system returns TPERELEASE in TP-STATUS if a compatibility issue exists between multiple releases of a BEA Tuxedo system participating in an application domain.
For example, the TPERELEASE error may be returned if the TPACK flag is set when issuing the TPNOT
IFY(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 BEA Tuxedo system that does not support the TPACK acknowledgement protocol.
Resource manager errors can occur with calls to TPOPE
N(3cbl) and TPC
OSE(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 BEA 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.
The BEA Tuxedo system supports timeout errors to establish a limit on the amount of time that the application waits for a service request or transaction. The BEA Tuxedo system supports two types of configurable timeout mechanisms: blocking and transaction.
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.
The system may return timeout errors on communication calls for either blocking or transaction timeouts, and on TPCOMMIT for transaction timeouts only. In each case, if a process is in transaction mode and the system returns TPETIME on a failed call, a transaction timeout has occurred.
By default, if a process is not in transaction mode, the system performs blocking timeouts.
If a process is not in transaction mode and a blocking timeout occurs on an asynchronous call, the communication call that blocked fails, but the call descriptor is still valid and may be used on a reissued call. Other communication is not affected.
When a transaction timeout occurs, the communication handle to an asynchronous transaction reply (specified without TPNOTRAN) becomes stale and may no longer be referenced.
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. |
For additional information on handling timeout errors, refer to Transaction Considerations.
For information on transactions and the non-fatal and fatal errors that can occur, refer to Transaction Considerations.
Typed record errors are returned when requests or replies to processes are sent in records of an unknown type. The TPCALL and TPACALL calls return TPEITYPE when a request data record is sent to a service that does not recognize the type of the record.
Processes recognize record types that are identified in both the configuration file and the BEA Tuxedo system libraries that are linked into the process. These libraries define and initialize a data structure that identifies the typed records that the process recognizes. You can tailor the library to each process, or an application can supply its own copy of a file that defines the record types. An application can set up the record type data structure (referred to as a record type switch) on a process-specific basis. For more information, see tuxtypes(5)and typesw(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference.
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.
Within an application, you can pass information about user-defined errors to calling programs using the rcode argument of TPRETURN. Also, the system sets the value of APPL-RETURN-CODE to the value of APPL-CODE IN TPSVCRET-REC during TPRETURN. For more information about TPRETURN(
3cbl), refer to the BEA Tuxedo ATMI COBOL Function Reference.
Your application logic should test for error conditions for the calls that have return values, and take appropriate action when an error occurs.
The following example shows a typical method of handling errors. The term ATMICALL(3) is used in this example to represent a generic ATMI call.
. . .
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.
The following sections describe how various programming features work when used in transaction mode. The first section provides rules of basic communication etiquette that should be observed in code written for transaction mode.
When writing code to be run in transaction mode, you must observe the following rules of basic communication etiquette:
TPACALL to TPNOTRAN or TPNOREPLY.TPRETURN or TPFORWAR. This rule must be observed regardless of whether the code is running in transaction mode.TPNOTRAN) before calling TPCOMMIT.TPACALL in which the transaction, but not the reply, is suppressed.TPNOTRAN set so that the results of the communication are preserved after the transaction is rolled back.TPEBADDESC.TPGETRPLY or TPRECV for any outstanding handles return a global state of transaction timeout; the system sets TP-STATUS to TPETIME.TPACALL set to TPNOREPLY, TPNOBLOCK, or TPNOTRAN.TPGETRPLY returns whatever value represents the local state of the call; that is, it returns either success or an error code that reflects the local condition.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.TPNOTRAN) become stale, and any further references to them return TPEBADDESC.
The following sections describe transaction-related errors.
When transaction errors occur, the system returns TPETRAN in TP-STATUS. The precise meaning of such an error, however, depends on the call that is returning it. The following table lists the calls that return transaction errors and describes possible causes of them.
When a fatal transaction error occurs, the application should explicitly abort the transaction by having the initiator call TPABORT. Therefore, it is important to understand the errors that are fatal to transactions. Three conditions cause a transaction to fail:
TPRETURN encounters an error while processing its arguments; TP-STATUS is set to TPESVCERR.TP-RETURN-VAL to TPRETURN was set to TPFAIL; TP-STATUS is set to TPESVCFAIL.TP-STATUS is set to TPEOTYPE.TP-STATUS is set to TPETIME.TPCOMMIT is called by a participant rather than by the originator of a transaction; TP-STATUS is set to TPEPROTO.
The only protocol error that is fatal to transactions is calling TPCOMMIT from the wrong participant in a transaction. This error can be corrected in the application during the development phase.
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.
When a transaction timeout occurs, communication can continue, but communication requests cannot:
Therefore, to make asynchronous calls, you must set TPNOREPLY, TPNOBLOCK, or TPNOTRAN.
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.
As described in Transaction Errors, two types of timeouts can occur in a BEA Tuxedo application: blocking and transaction. The following sections describe how various programming features are affected by transaction timeouts. Refer to Transaction Errors for more information on timeouts.
What is the state of a transaction if a timeout occurs after a call to TPCOMMIT? If the transaction timed out and the system knows that it was aborted, the system reports these events by setting TP-STATUS to TPEABORT. If the status of the transaction is unknown, the system sets the error code to TPETIME.
When the state of a transaction is in doubt, you must query the resource manager. First, verify whether or not any of the changes that were part of the transaction were applied. Then you can determine whether the transaction was committed or aborted.
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.
For additional information on using TPNOTRAN, refer to TPRETURN and TPFORWAR Calls.
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.
If the client context is in transaction mode, the call fails with TPEPROTO returned in TP-STATUS, and the client context remains part of the application and in transaction mode.
When the call is successful, the client context is allowed no further communication or participation in transactions because the current thread of execution is no longer part of the application.
When you use an ATMI call to define transactions, the BEA Tuxedo system executes an internal call to pass any global transaction information to each resource manager participating in the transaction. When you call TPCOMMIT or TPABORT, for example, the system makes internal calls to direct each resource manager to commit or abort the work it did on behalf of the caller's global transaction.
When a global transaction has been initiated, either explicitly or implicitly, you should not make explicit calls to the resource manager's transaction calls in your application code. Failure to follow this transaction rule causes indeterminate results. You can use the TPGETLEV call to determine whether a process is already in a global transaction before calling the resource manager's transaction call.
Some resource managers allow programmers to configure certain parameters (such as the transaction consistency level) by specifying options available in the interface to the resource managers themselves. Such options are made available in two forms:
Consult the documentation for your resource managers for additional information.
The method of setting options varies for each resource manager. In the BEA Tuxedo System SQL resource manager, for example, the set transaction statement is used to negotiate specific options (consistency level and access mode) for a transaction that has already been started by the BEA Tuxedo system.
The following sections provide some considerations for the following transaction scenarios:
When a caller in transaction mode calls another service to participate in the current transaction, the following facts apply:
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.)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.
In this situation, the following facts apply:
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.TPESVCFAIL, TPEITYPE/TPEOTYPE, and TPESVCERR.
The BEA Tuxedo system-supplied subroutines, TPSVRINIT and TPSVRDONE, must follow certain rules when used in transactions.
The BEA 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 BEA 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.
The central event log is a record of significant events in your BEA Tuxedo application. Messages about these events are sent to the log by your application clients and services via the USERLO G(3cbl) routine.
Any analysis of the central event log must be provided by the application. You should establish strict guidelines for the events that are to be recorded in the USERL OG(3cbl). Application debugging can be simplified by eliminating trivial messages.
For information on configuring the central event log on the Windows 2003 platform, refer to Using BEA Tuxedo ATMI on Windows.
The application administrator defines (in the configuration file) the absolute pathname that is used as the prefix of the name of the error message file on each machine. The USER
LOG(3cbl) routine creates a date—in the form mmddyy, representing the month, day, and year—and adds this date to the pathname prefix, forming the full filename of the central event log. A new file is created daily. Thus, if a process sends messages to the central event log on succeeding days, the messages are written into different files.
Entries in the log consist of the following components:
For example, suppose that a security program executes the following call at 4:22:14pm on a UNIX machine called mach1 (as returned by the uname command):
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.
The resulting log entry appears as follows:
162214.mach1!security.23451: UNKNOWN USER
In this example, the process ID for security is 23451.
If the preceding message was generated by the BEA Tuxedo system (rather than by the application), it might appear as follows:
162214.mach1!security.23451: COBAPI_CAT: 999: UNKNOWN USER
In this case, the message catalog name is COBAPI_CAT and the message number is 999.
If the message is sent to the central event log while the process is in transaction mode, other components are added to the tag in the user log entry. These components consist of the literal string gtrid followed by three long hexadecimal integers. The integers uniquely identify the global transaction and make up what is referred to as the global transaction identifier, that is, the gtrid. This identifier is used mainly for administrative purposes, but it also appears in the tag that prefixes the messages in the central event log. If the system writes the message to the central event log in transaction mode, the resulting log entry appears as follows:
162214.mach1!security.23451: gtrid x2 x24e1b803 x239:
UNKNOWN USER
To write a message to the event log, you must perform the following steps:
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.
. . .
In this example, the message is sent to the central event log if TPO
PEN(3cbl) returns -1.
|