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 the BEA TUXEDO system 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.
The following discussion concerns how the BEA TUXEDO system 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 The setting returned by Introduction
Communicating Errors
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
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
TPEPROTO)
TPESYSTEM)
Protocol errors occur because an ATMI routine was called in an incorrect context. Refer to the Protocol Errors
INTRO(3cbl) reference page. This type of error usually happens for one of the following reasons:
When BEA TUXEDO system 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 indicate that a system call has failed. A numeric value identifying the failed system call is returned in the global variable, 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 In addition to the four basic categories just discussed, others include
BEA TUXEDO System Errors
Operating System Errors
Uunixerr. Operating system errors are seldom application errors; systems administrators may need to be called on to correct them.
Errors from Invalid Arguments
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
TPENOENT)
TPEPERM)
TPERMERR)
TPETRAN)
TPEITYPE and TPEOTYPE)
TPETIME)
TPCOMMIT when the transaction should have been explicitly aborted (TPEABORT)
TPEHAZARD, TPEHEURISTIC)
The no entry type error, No Entry Errors
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.
The only ATMI routine that returns this error is These errors can occur with calls to When this type of error occurs, 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 accessing a printer that 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 Typed record errors are returned as a result of sending processes requests or replies in typed records that are unfamiliar to them. 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, Permission Errors
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 BEA TUXEDO administrator if it is encountered.
Resource Manager Errors
TPOPEN and TPCLOSE and they return a setting of TPERMERR. The meaning of the BEA TUXEDO system 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
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.
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
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 BEA TUXEDO 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 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
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 the BEA TUXEDO system does not like you to do with communication handles.
TPELIMIT)
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 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 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 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, The error codes Once a conversational connection has been established, In conversational services Time-out errors can occur for one of two reasons:
MAXCONV parameter in the RESOURCES section of the configuration file can be changed when the application is not running; it can be dynamically changed in the MACHINES section when the application is running (see tmconfig(1)).
TPEBADDESC.
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
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.
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 BEA TUXEDO call. If the communication routines set TPSIGRSTRT, the calls will not fail and this code will not be returned.
Conversational Errors
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.
TPSEND, TPRECV and TPDISCON return TPEBADDESC when an unknown handle is specified.
Time-out Errors
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
You may recall that if 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 Further implications concerning the concept of time-out will be discussed in the section "Time-out" later in this chapter.
Errors by a participant in a transaction can cause TPNOBLOCK is set, a blocking time-out cannot occur because the call returns immediately if a blocking condition exists.
TPBEGIN.
Errors Leading to Abort
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:
Based on how Listing 15-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.
Heuristic Decision Errors
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, we cannot know if it completed the transaction successfully or unsuccessfully.
How to Deal with Errors
Listing 15-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 INTRO(3cbl)
reference 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 the level on which it can be corrected.
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:
TPRETURN encountered an error while processing its members (TPESVCERR).
TP-RETURN-VAL argument of TPRETURN was set to TPFAIL (TPESVCFAIL).
TPETIME).
TPCOMMIT was called by a participant rather than by the originator of a transaction (TPEPROTO).
If Note that in the case of When a transaction time-out occurs, communication can continue, but it must be conducted with the following conditions enforced. The communication requests
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.
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.
This means asynchronous calls can be made with setting of Calling Calling As already indicated there are two possible types of time-out that can occur in the BEA TUXEDO system. The effect of time-out on communication calls is different depending on the type that occurred. In addition, the following sections address the following issues:
TPNOREPLY, TPNOBLOCK or TPNOTRAN.
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.
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
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 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.
What is the state of a transaction if time-out occurs after the call to When a process is in transaction mode and makes a communication call with a setting of If a process is called in transaction mode, Neither It is always the case that when 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 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?
Blocking vs. Transaction Time-out
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?
Effect on TPCOMMIT
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
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
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.
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.
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.
TPRETURN as well as the communication rules.
Service in Same Transaction as Caller
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
If a communication call is made with the Service in Different Transaction with AUTOTRAN Set
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 15-1.
Figure 15-1 Transaction Roles of TPFORWAR and TPRETURN with AUTOTRAN
If a communication call is made with Service Starts New Explicit Transaction
TPNOTRAN, and the called service is not automatically placed in transaction mode by a configuration option, the service can define as many transactions as it wants with explicit calls to TPBEGIN, TPCOMMIT, and TPABORT. As a result, the transaction is already completed before the call to TPRETURN. What are the implications?
TPRETURN plays no transaction role; that is, the role of TPRETURN would be exactly the same whether transactions were explicitly defined within the service routine or not.
TPRETURN can send any value back in TP-RETURN-VAL regardless of the outcome of the transaction.
Certain rules are in effect when processes perform in transaction mode. Many of them have been touched upon already, but now, by way of summary, let's bring them together and discuss them in one place.
The basic communication etiquette that must be observed while in transaction mode is as follows:
Transaction Rules
Communication Etiquette
TPACALL is set to TPNOTRAN or TPNOREPLY
TPCOMMIT
TPEBADDESC
TPACALL set to TPNOREPLY or TPNOBLOCK or TPNOTRAN
TPGETRPLY will return whatever represents the local state of the call, that is, it can either return success or an error code that represents the local condition
In both the standard subroutines, namely The BEA TUXEDO system server abstraction calls The BEA TUXEDO system server abstraction calls An interesting point arises when using the ATMI transaction calls to define transactions. The BEA TUXEDO system makes an internal call to pass the global transaction information to each resource manager participating in the transaction. When This represents a good occasion to use the transaction call, Some resource managers offer specific options in their interface. (For example, a resource manager might offer various transaction consistency levels or flags.) Some resource manager providers offer programmers of distributed applications the opportunity to negotiate these options using resource manager-specific calls; in other resource managers these options are hard-coded in the version of the transaction interface supplied by the resource manager provider. Documentation for the resource managers you are using should be consulted for further information on this subject.
In the BEA TUXEDO System/SQL Resource Manager, the The central event log is a UNIX System file to which you can send messages from BEA TUXEDO clients and services. Writing to the central event log is accomplished through the One of the system parameters set up by the administrator determines the absolute pathname prefix of the userlog error message file on each machine. The Each log entry consists of a tag and message text.
BEA TUXEDO System-Supplied Subroutines
TPSVRINIT and TPSVRDONE, transactions may be defined and communication may be performed. What rules must they follow?
TPSVRINIT
TPSVRINIT during initialization. This routine is called after the process has become a server but before it handles service requests. If TPSVRINIT performs any asynchronous communication, all replies must be retrieved before returning, or the BEA TUXEDO system will ignore all pending replies and the server exits. If TPSVRINIT defines any transactions, they must be completed with all asynchronous replies retrieved before returning, or the BEA TUXEDO system will abort the transaction and ignore the outstanding replies. The server exits gracefully.
TPSVRDONE
TPSVRDONE after it has finished processing service requests but before it exits. Its services are no longer advertised, but it has not yet left the application. If TPSVRDONE initiates communication, it must retrieve all outstanding replies before it returns, or the pending replies will be ignored by the BEA TUXEDO system and the server exits. If a transaction has been started within this subroutine, it must be completed with all replies retrieved, or the BEA TUXEDO system will abort the transaction and ignore the replies. The server exits.
Leaving the Application
TPTERM is used to remove a client from an application. What transaction rules must it obey? If the client is in transaction mode, the call fails with TPEPROTO returned in TP-STATUS, and the client is still part of the application and in transaction mode. When the call is successful, no further communication or participation in transactions is allowed because the process is no longer part of the application.
Global Transactions and Resource Managers
TPCOMMIT or TPABORT is called, the BEA TUXEDO system makes internal calls to direct each resource manager to commit or abort the work they did on behalf of the caller's global transaction. When you write service routines in a DTP environment you need not and should not make resource manager-specific calls to start, commit, or abort transactions. 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 will give indeterminate results.
TPGETLEV, to determine if a process is already in a global transaction before calling the resource manager's transaction call.
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 method of setting such options will vary for other resource managers.
The Central Event Log
USERLOG routine. The central event log simply provides a record of events considered worth recording. Any organized analysis of the central event log must be provided by the application.
How the Log Is Named
USERLOG routine concatenates the month, day and year in the form mmddyy to the prefix to form the full file name of the central event log. That means that if a process sends a message to the central event log on succeeding days, the message is written into different files.
What Log Entries Look Like
hhmmss)
For example, if the call
is made at 4:22:14pm by the assuming If the above message was generated by the BEA TUXEDO system (as opposed to the application), it might look like this:
where If the message was sent to the central event log while the process is in transaction mode, the user log entry will have additional components in the tag. These components consist of the literal You can either have the error message you wish to write to the log in a record and use the record name as the argument to the call, or include the message as a literal within quotation marks as the argument to the call, as is shown in the example below.
In this example, the message is sent to the central event log if 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.security program, on a machine where uname -n returns the value mach1, the resulting log entry will look like this:
162214.mach1!security.23451: UNKNOWN USER
23451 is the process ID for security.
162214.mach1!security.23451: COBAPI_CAT: 999: UNKNOWN USER
COBAPI_CAT: 999: represents a message catalog name and message number.
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. This identifier is used mainly for administrative purposes, but it does make an appearance in the tag that prefixes the messages in the central event log. If the foregoing message is written to the central event log in transaction mode, the resulting log entry will look like this:
162214.mach1!security.23451: gtrid x2 x24e1b803 x239:
UNKNOWN USER How to Write to the Event Log
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.
. . .TPOPEN is not successful.