INTRO-introduction to the COBOL application-transaction monitor interface
The application-transaction monitor interface provides the interface between the COBOL application and the transaction processing system. This interface is known as ATMI and these pages specify its COBOL language binding. It provides routines to open and close resources, manage transactions, manage record types, and invoke request/response and conversational service calls.
The routines described in the ATMI reference pages imply a particular model of communication. This model is expressed in terms of how client and server programs can communicate using request and reply messages.
There are two basic communication paradigms: request/response and conversational. Request/response services are invoked by service requests along with their associated data. Request/response services can receive exactly one request (upon entering the service routine) and send at most one reply (upon returning from the service routine). Conversational services, on the other hand, are invoked by connection requests along with a means of referring to the open connection (that is, a handle used in calling subsequent connection routines). Once the connection has been established and the service routine invoked, either the connecting program or the conversational service can send and receive data as defined by the application until the connection is torn down.
Note that a program can initiate both request/response and conversational communication, but cannot accept both request/response and conversational service requests. The following sections describe the two communication paradigms in greater detail.
With regard to request/response communication, a client is defined as a program that can send requests and receive replies. By definition, clients cannot receive requests nor send replies. A client can send any number of requests, and can wait for the replies synchronously or receive (some limited number of) the replies at its convenience. In certain cases, a client can send a request that has no reply. TPINITIALIZE() and TPTERM() allow a client to join and leave a BEA TUXEDO system application.
A request/response server is a program that can receive one (and only one) service request at a time and send at most one reply to that request. While a server is working on a particular request, it can act like a client by initiating request/response or conversational requests and receiving their replies. In such a capacity, a server is called a requester. Note that both client and server programs can be requesters (in fact, a client can be nothing but a requester).
A request/response server can forward a request to another request/response server. Here, the server passes along the request it received to another server and does not expect a reply. It is the responsibility of the last server in the chain to send the reply to the original requester. Use of the forwarding routine ensures that the original requester ultimately receives its reply.
Servers and service routines offer a structured approach to writing BEA TUXEDO system applications. In a server, the application writer can concentrate on the work performed by the service rather than communications details such as receiving requests and sending replies. Because many of the communication details are handled by the BEA TUXEDO system, the application must adhere to certain conventions when writing a service routine. At the time a server finishes its service routine, it can send a reply using TPRETURN() or forward the request using TPFORWAR(). A service is not allowed to perform any other work nor is it allowed to communicate with any other program after this point. Thus, a service performed by a server is started when a request is received and ended either when a reply is sent or the request is forwarded.
Concerning request and reply messages, there is an inherent difference between the two: a request has no associated context before it is sent, but a reply does. For example, when sending a request, the caller must supply addressing information, whereas a reply is always returned to the program that originated the request, that is, addressing context is maintained for a reply and the sender of the reply can exert no control over its destination. The differences between the two message types manifest themselves in the parameters and descriptions of the routines described in TPCALL().
When a request message is sent, it is sent at a particular priority. The priority affects how a request is dequeued: when a server dequeues requests, it dequeues the one with the highest priority. To prevent starvation, the oldest request is dequeued every so often regardless of priority. By default, a request's priority is associated with the service name to which the request is being sent. Service names can be given priorities at configuration time (see ubbconfig(5)). A default priority is used if none is defined. In addition, the priority can be set at runtime using a routine (TPSPRIO()) described in TPCALL(). By doing so, the caller can override the configuration or default priority when the message is sent.
With regard to conversational communication, a client is defined as a program that can initiate a conversation but cannot accept a connection request.
A conversational server is a program that can receive connection requests. Once the connection has been established and the service routine invoked, either the connecting program or the conversational service can send and receive data as defined by the application until the connection is torn down. The conversation is half-duplex in nature such that one side of the connection has control and can send data until it gives up control to the other side. While the connection is established, the server is \Q\Qreserved'' such that no other program can establish a connection with the server. As with a request/response server, the conversational server can act as a requester by initiating other requests or connections with other servers. Unlike a request/response server, a conversational server can not forward a request to another server. Thus, a conversational service performed by a server is started when a request is received and ended when the final reply is sent via TPRETURN().
Once the connection is established, the communications handle implies any context needed regarding addressing information for the participants. Messages can be sent and received as needed by the application. There is no inherent difference between the request and reply messages and no notion of priority of messages.
The BEA TUXEDO system queued message model allows for enqueueing a request message to stable storage for subsequent processing without waiting for its completion, and optionally getting a reply via a queued response message. The ATMI verbs that queue messages and dequeue responses are TPENQUEUE() and TPDEQUEUE(). They can be called from any type of BEA TUXEDO system application processes: client, server, or conversational.
The queued message facility is an XA-compliant resource manager. Messages are enqueued and dequeued within transactions to ensure reliable one-time-only processing.
The BEA TUXEDO system supports two sets of mutually exclusive verbs for defining and managing transactions: BEA TUXEDO system's ATMI transaction demarcation verbs (which are prefaced with TP) and X/Open's TX Interface (whose verbs are prefaced with TX). Because X/Open used ATMI's transaction demarcation verbs as the base for the TX Interface, the syntax and semantics of the TX Interface are quite similar to ATMI. This section is an overview of ATMI's transaction concepts. The following section introduces additional concepts of the TX Interface.
A transaction in the BEA TUXEDO system is used to define a single logical unit of work that either wholly succeeds or has no effect whatsoever. A transaction allows work performed in many programs, at possibly different sites, to be treated as an atomic unit of work. The initiator of a transaction normally uses TPBEGIN() and either TPCOMMIT() or TPABORT() to delineate the operations within a transaction.
The initiator may also suspend its work on the current transaction by issuing TPSUSPEND. Another process may take over the role of the initiator of a suspended transaction by issuing TPRESUME. As a transaction initiator, a program must call one of TPSUSPEND, TPCOMMIT, or TPABORT. Thus, one program can start a transaction that another may finish.
If a program calling a service is in transaction mode, then the called service routine is also placed in transaction mode on behalf of the same transaction. Otherwise, whether the service is invoked in transaction mode or not depends on options specified for the service in the configuration file. A service that is not invoked in transaction mode can define multiple transactions between the time it is invoked and the time it ends. On the other hand, a service routine invoked in transaction mode can participate in only one transaction, and work on that transaction is completed upon termination of the service routine. Note that a connection cannot be upgraded to transaction mode: if TPBEGIN() is called while a conversation exists, the conversation remains outside of the transaction (that is, as if TPCONNECT() had been called with the TPNOTRAN setting).
A service routine joining a transaction that was started by another program is called a participant. A transaction can have several participants. A service can be invoked to do work on the same transaction more than once. Only the initiator of a transaction (that is, a program either calling TPBEGIN or TPRESUME) can call TPCOMMIT() or \% TPABORT(). Participants influence the outcome of a transaction by using TPRETURN() or TPFORWAR(). These two calls signify the end of a service routine and indicate that the routine has finished its part of the transaction.
Transactions defined by the TX Interface are practically identical with those defined by the ATMI verbs. An application writer may use either set of verbs when writing clients and service routines. In fact, the BEA TUXEDO system does not require all client and server programs within a single application to use one set of verbs or the other. However, the two verb sets may not be used together within a single program (that is, a program cannot call TPBEGIN() and later call TXCOMMIT()).
The TX Interface has two calls for opening and closing resource managers in a portable manner, TXOPEN() and TXCLOSE(), respectively. Transactions are started with TXBEGIN() and completed with either TXCOMMIT() or TXROLLBACK(). TXINFORM() is used to retrieve transaction information, and there are three calls to set options for transactions: TXSETCOMMITRET(), TXSETTRANCTL(), and TXSETTIMEOUT(). The TX Interface has no equivalents to ATMI's TPSUSPEND(3) and TPRESUME().
In addition to the semantics and rules defined for ATMI transactions, the TX Interface has some additional semantics that are worth introducing here. First, service routine writers wanting to use the TX Interface must supply their own TPSVRINIT() routine that calls TXOPEN(). The default BEA TUXEDO system-supplied TPSVRINIT() calls TPOPEN(). The same rule applies for TPSVRDONE(): if the TX Interface is being used, then service routine writers must supply their own TPSVRDONE() that calls TXCLOSE().
Second, the TX Interface has two additional semantics not found in ATMI. These are chained and unchained transactions, and transaction characteristics.
The TX Interface supports chained and unchained modes of transaction execution. By default, clients and service routines execute in the unchained mode; when an active transaction is completed, a new transaction does not begin until TXBEGIN() is called.
In the chained mode, a new transaction starts implicitly when the current transaction completes. That is, when TXCOMMIT() or TXROLLBACK() is called, the BEA TUXEDO system coordinates the completion of the current transaction and initiates a new transaction before returning control to the caller. (Certain failure conditions may prevent a new transaction from starting.)
Clients and service routines enable or disable the chained mode by calling TXSETTRANCTL(). Transitions between the chained and unchained mode affect the behavior of the next TXCOMMIT() or TXROLLBACK() call. The call to TXSETTRANCTL() does not put the caller into or take it out of transaction mode.
Since TXCLOSE() cannot be called when the caller is in transaction mode, a caller executing in chained mode must switch to unchained mode and complete the current transaction before calling TXCLOSE().
A client or a service routine may call TXINFORM() to obtain the current values of their transaction characteristics and to determine whether they are executing in transaction mode.
The state of an application program includes several transaction characteristics. The caller specifies these by calling TXSET* functions. When a client or a service routine sets the value of a characteristic, it remains in effect until the caller specifies a different value. When the caller obtains the value of a characteristic via TXINFORM(), it does not change the value.
There are three types of timeouts in the BEA TUXEDO system: one is associated with the duration of a transaction from start to finish. A second is associated with the maximum length of time a blocking call will remain blocked before the caller regains control. The third is a service timeout and occurs when a call exceeds the number of seconds specified in the SVCTIMEOUT parameter in the SERVICES section of ubbconfig(5). The first kind of timeout is specified when a transaction is started with TPBEGIN() (see TPBEGIN() for details). The second kind of timeout can occur when using the BEA TUXEDO system communication routines defined in TPCALL(). Callers of these routines typically block when awaiting a reply that has yet to arrive, although they can also block trying to send data (for example, if request queues are full). The maximum amount of time a caller remains blocked is determined by a BEA TUXEDO system configuration file parameter (see the BLOCKTIME parameter in ubbconfig(5) for details).
Blocking timeouts are performed by default when the caller is not in transaction mode. When a client or server is in transaction mode, it is subject to the timeout value with which the transaction was started and is not subject to the blocking timeout value specified in the UBBCONFIG file.
When a transaction timeout occurs, replies to asynchronous requests made in transaction mode become \Q\Qstale.'' That is, if a program is waiting for a particular asynchronous reply for a request sent in transaction mode and a transaction timeout occurs, the handle for that reply becomes stale (invalid). Similarly, if a transaction timeout occurs, an event is generated on the connection handle associated with the transaction and that handle becomes invalid. On the other hand, if a blocking timeout occurs, the handle is still valid and the waiting program can re-issue the call to await the reply.
The service timeout mechanism provides a way for the system to kill processes that may be frozen by some unknown or unexpected system error. When a service timeout occurs in a request/response service, the BEA TUXEDO system kills the server process that is executing the frozen service and returns error code TPESVCERR. If a service timeout occurs in a conversational service, the TPEV_SVCERR event is returned.
Beginning in Release 6.4, some additional detail is provided beyond the TPESVCERR error code. If a service failed due to exceeding the timeout threshold, an event,.SysServiceTimeout, is posted and a call to tperrordetail(3) will return the TPED_SVCTIMEOUT error code.
By default, a server's services are advertised when it is booted and unadvertised when it is shut down. If a server needs to control at run time the set of services that it offers, it can do so by calling TPADVERTISE() and TPUNADVERTISE(). These routines affect only the services offered by the calling server unless that server belongs to a multiple server, single queue (MSSQ) set. Because all servers in an MSSQ set must offer the same set of services, these routines also affect the advertisements of all servers sharing the caller's MSSQ set.
In order to send data to another application program, the sending application program first places the data in a record. The ATMI interface supports the notion of a typed record. A typed record is really a pair of COBOL records. The data record is defined in static storage and contains application data to be passed to another application program. An auxiliary type record accompanies the data record and it identifies to the BEA TUXEDO system the interpretation and translation rules of the data record as it passes across heterogeneous machine boundaries. The auxiliary type record contains the data record's type, its optional subtype, and its optional length. Some record types require further specification via a subtype (for example, a particular record layout) and those of variable length require a length to be specified.
The application programmer may choose one of the six supported typed records. Note, the BEA TUXEDO system provides a method for adding user specific typed records. Refer to the C language binding intro(3) section for details. REC-TYPE in TPTYPE-REC selects which record type the application wishes to send or receive. SUB-TYPE in TPTYPE-REC must also be given when further classification is required (for example, a view record). When sending, LEN in TPTYPE-REC indicates the number of bytes to be sent and when receiving the number of bytes to move into the user's record. The following are the supported REC-TYPEs.
CARRAY
CARRAY record type allows an arbitrary number of characters which may contain LOW-VALUE characters anywhere in the record. When sending data, LEN must contain the number of bytes to be transferred.
STRING
STRING record type allows an arbitrary number of characters which may not contain LOW-VALUE characters within the record but may be at the end of the record. When sending data, LEN must contain the number of bytes to be transferred.
VIEW
VIEW, SUB-TYPE must contain the name of the view. When sending a VIEW type, LEN must contain the number of bytes to be transferred or set NO-LENGTH which will send the length of the view.
Two of the above record types have synonyms: X_OCTET is a synonym for CARRAY, and X_COMMON is a synonym for VIEW. X_COMMON supports a subset of the data types supported by VIEW: longs (PICS9(9) COMP-5), shorts (PICS9(4) COMP-5), and characters (PICX(n)). X_COMMON should be used when both C and COBOL programs are communicating.
In all three cases, after a successful transfer, LEN contains the number of bytes transferred. When receiving data, LEN must contain the maximum number of bytes the data area contains. After a successful call, LEN contains the number of bytes moved into the data area. If the size of the incoming message is larger than the size specified in LEN, only LEN amount of data is moved into the data area; the remaining data is discarded.
The BEA TUXEDO system provides a method for adding user specific record types. Refer to the C language binding intro(3) section for details.
There are two methods for sending messages to application clients outside the boundaries of the client/server interaction defined above. The first is the broadcast mechanism supported by TPBROADCAST(). This function allows application clients, servers, and administrators to broadcast typed record messages to a set of clients selected on the basis of the names assigned to them. The names assigned to clients are determined in part by the application by the information passed in the TPINFDEF-REC data structure at TPINITIALIZE() time and in part by the system based on the processor at which the client accesses the application.
The second is the notification of a particular client as identified from an earlier or current service request. Each service request contains a unique client identifier that identifies the originating client for the service request. TPCALL()'s and TPFORWAR()'s from within a service routine do not change the originating client for that chain of service requests. Client identifiers can be saved and passed between application servers. The routine TPNOTIFY() is used to notify clients identified in this manner.
The following return code and setting definitions are used by the ATMI routines.
*
* TPSTATUS.cbl
*
05 TP-STATUS PICS9(9) COMP-5.
88 TPOK VALUE 0.
88 TPEABORT VALUE 1.
88 TPEBADDESC VALUE 2.
88 TPEBLOCK VALUE 3.
88 TPEINVAL VALUE 4.
88 TPELIMIT VALUE 5.
88 TPENOENT VALUE 6.
88 TPEOS VALUE 7.
88 TPEPERM VALUE 8.
88 TPEPROTO VALUE 9.
88 TPESVCERR VALUE 10.
88 TPESVCFAIL VALUE 11.
88 TPESYSTEM VALUE 12.
88 TPETIME VALUE 13.
88 TPETRAN VALUE 14.
88 TPEGOTSIG VALUE 15.
88 TPERMERR VALUE 16.
88 TPEITYPE VALUE 17.
88 TPEOTYPE VALUE 18.
88 TPERELEASE VALUE 19.
88 TPEHAZARD VALUE 20.
88 TPEHEURISTIC VALUE 21.
88 TPEEVENT VALUE 22.
88 TPEMATCH VALUE 23.
88 TPEMAXVAL VALUE 24.
05 TPEVENT PICS9(9) COMP-5.
88 TPEV-NOEVENT VALUE 0.
88 TPEV-DISCONIMM VALUE 1.
88 TPEV-SENDONLY VALUE 2.
88 TPEV-SVCERR VALUE 3.
88 TPEV-SVCFAIL VALUE 4.
88 TPEV-SVCSUCC VALUE 5.
05 TPSVCTIMOUT PICS9(9) COMP-5.
88 TPED-NOEVENT VALUE 0.
88 TPEV-SVCTIMEOUT VALUE 1.
88 TPEV-TERM VALUE 2.
05 APPL-RETURN-CODE PICS9(9) COMP-5.
The TPTYPE COBOL structure is used whenever sending or receiving application data. REC-TYPE indicates the type of data record that is to be sent. SUB-TYPE indicates the name of the view if a VIEW REC-TYPE is specified. LEN indicates the amount of data to send and amount received.
*
* TPTYPE.cbl
*
05 REC-TYPE PICX(8).
88 X-OCTET VALUE "X_OCTET".
88 X-COMMON VALUE "X_COMMON".
05 SUB-TYPE PICX(16).
05 LEN PICS9(9) COMP-5.
88 NO-LENGTH VALUE 0.
05 TPTYPE-STATUSPICS9(9) COMP-5.
88 TPTYPEOK VALUE 0.
88 TPTRUNCATE VALUE 1.
The TPSVCDEF data structure is used by functions to pass settings to and from the BEA TUXEDO system.
*
* TPSVCDEF.cbl
*
05 COMM-HANDLE PIC S9(9) COMP-5.
05 TPBLOCK-FLAG PIC S9(9) COMP-5.
88 TPBLOCK VALUE 0.
88 TPNOBLOCK VALUE 1.
05 TPTRAN-FLAG PIC S9(9) COMP-5.
88 TPTRAN VALUE 0.
88 TPNOTRAN VALUE 1.
05 TPREPLY-FLAG PIC S9(9) COMP-5.
88 TPREPLY VALUE 0.
88 TPNOREPLY VALUE 1.
05 TPACK-FLAG PIC S9(9) COMP-5 REDEFINES TPREPLY-FLAG.
88 TPNOACK VALUE 0.
88 TPACK VALUE 1.
05 TPTIME-FLAG PIC S9(9) COMP-5.
88 TPTIME VALUE 0.
88 TPNOTIME VALUE 1.
05 TPSIGRSTRT-FLAG PIC S9(9) COMP-5.
88 TPNOSIGRSTRT VALUE 0.
88 TPSIGRSTRT VALUE 1.
05 TPGETANY-FLAG PIC S9(9) COMP-5.
88 TPGETHANDLE VALUE 0.
88 TPGETANY VALUE 1.
05 TPSENDRECV-FLAG PIC S9(9) COMP-5.
88 TPSENDONLY VALUE 0.
88 TPRECVONLY VALUE 1.
05 TPNOCHANGE-FLAG PIC S9(9) COMP-5.
88 TPCHANGE VALUE 0.
88 TPNOCHANGE VALUE 1.
05 TPSERVICETYPE-FLAG PIC S9(9) COMP-5.
88 TPREQRSP VALUE IS 0.
88 TPCONV VALUE IS 1.
*
05 APPKEY PIC S9(9) COMP-5.
05 CLIENTID OCCURS 4 TIMES PIC S9(9) COMP-5.
05 SERVICE-NAME PIC X(15).
The TPINFDEF data structure is used by TPINITIALIZE() to join the application.
*
* TPINFDEF.cbl
*
05 USRNAME PICX(30).
05 CLTNAME PICX(30).
05 PASSWD PICX(30).
05 GRPNAME PICX(30).
05 NOTIFICATION-FLAG PICS9(9) COMP-5.
88 TPU-SIG VALUE 1.
88 TPU-DIP VALUE 2.
88 TPU-IGN VALUE 3.
05 ACCESS-FLAG PICS9(9) COMP-5.
88 TPSA-FASTPATH VALUE 1.
88 TPSA-PROTECTED VALUE 2.
05 DATALEN PICS9(9) COMP-5.
The TPQUEDEF data structure is used to pass and retrieve information associated with enqueuing the message.
*
* TPQUEDEF.cbl
*
05 TPBLOCK-FLAG PICS9(9) COMP-5.
88 TPNOBLOCK VALUE 0.
88 TPBLOCK VALUE 1.
05 TPTRAN-FLAG PICS9(9) COMP-5.
88 TPNOTRAN VALUE 0.
88 TPTRAN VALUE 1.
05 TPTIME-FLAG PICS9(9) COMP-5.
88 TPNOTIME VALUE 0.
88 TPTIME VALUE 1.
05 TPSIGRSTRT-FLAG PICS9(9) COMP-5.
88 TPNOSIGRSTRT VALUE 0.
88 TPSIGRSTRT VALUE 1.
05 TPNOCHANGE-FLAG PICS9(9) COMP-5.
88 TPNOCHANGE VALUE 0.
88 TPCHANGE VALUE 1.
05 TPQUE-ORDER-FLAG PICS9(9) COMP-5.
88 TPQDEFAULT VALUE 0.
88 TPQTOP VALUE 1.
88 TPQBEFOREMSGID VALUE 2.
05 TPQUE-TIME-FLAG PICS9(9) COMP-5.
88 TPQNOTIME VALUE 0.
88 TPQTIME-ABS VALUE 1.
88 TPQTIME-REL VALUE 2.
05 TPQUE-PRIORITY-FLAG PICS9(9) COMP-5.
88 TPQNOPRIORITY VALUE 0.
88 TPQPRIORITY VALUE 1.
05 TPQUE-CORRID-FLAG PICS9(9) COMP-5.
88 TPQNOCORRID VALUE 0.
88 TPQCORRID VALUE 1.
05 TPQUE-REPLYQ-FLAG PICS9(9) COMP-5.
88 TPQNOREPLYQ VALUE 0.
88 TPQREPLYQ VALUE 1.
05 TPQUE-FAILQ-FLAG PICS9(9) COMP-5.
88 TPQNOFAILUREQ VALUE 0.
88 TPQFAILUREQ VALUE 1.
05 TPQUE-MSGID-FLAG PICS9(9) COMP-5.
88 TPQNOMSGID VALUE 0.
88 TPQMSGID VALUE 1.
05 TPQUE-GETBY-FLAG PICS9(9) COMP-5.
88 TPQGETNEXT VALUE 0.
88 TPQGETBYMSGID VALUE 1.
88 TPQGETBYCORRID VALUE 2.
05 TPQUE-WAIT-FLAG PICS9(9) COMP-5.
88 TPQNOWAIT VALUE 0.
88 TPQWAIT VALUE 1.
05 DIAGNOSTIC PICS9(9) COMP-5.
88 QMEINVAL VALUE -1.
88 QMEBADRMID VALUE -2.
88 QMENOTOPEN VALUE -3.
88 QMETRAN VALUE -4.
88 QMEBADMSGID VALUE -5.
88 QMESYSTEM VALUE -6.
88 QMEOS VALUE -7.
88 QMENOTA VALUE -8.
88 QMEPROTO VALUE -9.
88 QMEBADQUEUE VALUE -10.
88 QMENOMSG VALUE -11.
88 QMEINUSE VALUE -12.
88 QMENOSPACE VALUE -13.
05 DEQ-TIME PICS9(9) COMP-5.
05 PRIORITY PICS9(9) COMP-5.
05 MSGID PICX(32).
05 CORRID PICX(32).
05 QNAME PICX(15).
05 QSPACE-NAME PICX(15).
05 REPLYQUEUE PICX(15).
05 FAILUREQUEUE PICX(15).
05 CLIENTID OCCURS4 TIMESPICS9(9) COMP-5.
05 APPL-RETURN-CODE PICS9(9) COMP-5.
05 APPKEY PICS9(9) COMP-5.
The TPSVCRET data structure is used by TPRETURN() to indicate the status of the transaction.
*
* TPSVCRET.cbl
*
05 TP-RETURN-VAL PICS9(9) COMP-5.
88 TPSUCCESS VALUE 0.
88 TPFAIL VALUE 1.
88 TPEXIT VALUE 2.
05 APPL-CODE PICS9(9) COMP-5.
The TPTRXDEF data structure is used by TPBEGIN() to set transaction timeouts, and by TPSUSPEND() and TPRESUME() to get and set, respectively, transaction identifiers.
*
* TPTRXDEF.cbl
*
05 T-OUT PICS9(9) COMP-5 VALUE IS0.
05 TRANID OCCURS6 TIMESPICS9(9) COMP-5.
The TPCMTDEF data structure is used by TPSCMT() to set the commit level characteristics.
*
* TPCMTDEF.cbl
*
05 CMT-FLAG PICS9(9) COMP-5.
88 TP-CMT-LOGGED VALUE 1.
88 TP-CMT-COMPLETE VALUE 2.
05 PREV-CMT-FLAG PICS9(9) COMP-5.
88 PREV-TP-CMT-LOGGED VALUE 1.
88 PREV-TP-CMT-COMPLETE VALUE 2.
The TPAUTDEF data structure is used by TPCHKAUTH() to check if authentication is required.
* TPAUTDEF.cbl
*
05 AUTH-FLAG PICS9(9) COMP-5.
88 TPNOAUTH VALUE 0.
88 TPSYSAUTH VALUE 1.
88 TPAPPAUTH VALUE 2.
The TPPRIDEF data structure is used by TPSPRIO() and TPGPRIO() to manipulate message priorities.
*
* TPPRIDEF.cbl
*
05 PRIORITY PICS9(9) COMP-5.
05 PRIO-FLAG PICS9(9) COMP-5.
88 TPABSOLUTE VALUE 0.
88 TPRELATIVE VALUE 1.
The TPTRXLEV data structure is used by TPGETLEV() to receive transaction level setting.
*
* TPTRXLEV.cbl
*
05 TPTRXLEV-FLAG PICS9(9) COMP-5.
88 TP-NOT-IN-TRAN VALUE 0.
88 TP-IN-TRAN VALUE 1.
The TPBCTDEF data structure is used by TPNOTIFY() and TPBROADCAST() to send notifications.
*
* TPBCTDEF.cbl
*
05 TPBLOCK-FLAG PICS9(9) COMP-5.
88 TPBLOCK VALUE 0.
88 TPNOBLOCK VALUE 1.
05 TPTIME-FLAG PICS9(9) COMP-5.
88 TPTIME VALUE 0.
88 TPNOTIME VALUE 1.
05 TPSIGRSTRT-FLAG PICS9(9) COMP-5.
88 TPNOSIGRSTRT VALUE 0.
88 TPSIGRSTRT VALUE 1.
05 LMID PICX(30).
05 USERNAME PICX(30).
05 CLTNAME PICX(30).
The FML-INFO data structure is used by FINIT(), FVSTOF(), and FVFTOS() to deal with FML buffers.
*
* FMLINFO.cbl
*
05 FML-STATUS PIC S9(9) COMP-5.
88 FOK VALUE 0.
88 FALIGNERR VALUE 1.
88 FNOTFLD VALUE 2.
88 FNOSPACE VALUE 3.
88 FNOTPRES VALUE 4.
88 FBADFLD VALUE 5.
88 FTYPERR VALUE 6.
88 FEUNIX VALUE 7.
88 FBADNAME VALUE 8.
88 FMALLOC VALUE 9.
88 FSYNTAX VALUE 10.
88 FFTOPEN VALUE 11.
88 FFTSYNTAX VALUE 12.
88 FEINVAL VALUE 13.
88 FBADTBL VALUE 14.
88 FBADVIEW VALUE 15.
88 FVFSYNTAX VALUE 16.
88 FVFOPEN VALUE 17.
88 FBADACM VALUE 18.
88 FNOCNAME VALUE 19.
*
05 FML-LENGTH PIC S9(9) COMP-5.
*
05 FML-MODE PIC S9(9) COMP-5.
88 FUPDATE VALUE 1.
88 FCONCAT VALUE 2.
88 FJOIN VALUE 3.
88 FOJOIN VALUE 4.
*
05 VIEWNAME PIC X(33).
The TPEVTDEF data structure is used by TPPOST(), TPSUBSCRIBE(), and TPUNSUBSCRIBE() to handle event postings and subscriptions.
*
* TPEVTDEF.cbl
*
05 TPBLOCK-FLAG PIC S9(9) COMP-5.
88 TPBLOCK VALUE 0.
88 TPNOBLOCK VALUE 1.
05 TPTRAN-FLAG PIC S9(9) COMP-5.
88 TPTRAN VALUE 0.
88 TPNOTRAN VALUE 1.
05 TPREPLY-FLAG PIC S9(9) COMP-5.
88 TPREPLY VALUE 0.
88 TPNOREPLY VALUE 1.
05 TPTIME-FLAG PIC S9(9) COMP-5.
88 TPTIME VALUE 0.
88 TPNOTIME VALUE 1.
05 TPSIGRSTRT-FLAG PIC S9(9) COMP-5.
88 TPNOSIGRSTRT VALUE 0.
88 TPSIGRSTRT VALUE 1.
05 TPEV-METHOD-FLAG PIC S9(9) COMP-5.
88 TPEVNOTIFY VALUE 0.
88 TPEVSERVICE VALUE 1.
88 TPEVQUEUE VALUE 2.
05 TPEV-PERSIST-FLAG PIC S9(9) COMP-5.
88 TPEVNOPERSIST VALUE 0.
88 TPEVPERSIST VALUE 1.
05 TPEV-TRAN-FLAG PIC S9(9) COMP-5.
88 TPEVNOTRAN VALUE 0.
88 TPEVTRAN VALUE 1.
*
05 EVENT-COUNT PIC S9(9) COMP-5.
05 SUBSCRIPTION-HANDLE PIC S9(9) COMP-5.
05 NAME-1 PIC X(31).
05 NAME-2 PIC X(31).
05 EVENT-NAME PIC X(31).
05 EVENT-EXPR PIC X(255).
05 EVENT-FILTER PIC X(255).
The following return code and setting definitions are used by the TX routines.
*
* TXSTATUS.cbl
*
05 TX-STATUS PICS9(9) COMP-5.
88 TX-NOT-SUPPORTED VALUE 1.
* Normal execution
88 TX-OK VALUE 0.
* Normal execution
88 TX-OUTSIDE VALUE -1.
* Application is in an RM local transaction
88 TX-ROLLBACK VALUE -2.
* Transaction was rolled back
88 TX-MIXED VALUE -3.
* Transaction was partially committed and partially
* rolled back
88 TX-HAZARD VALUE -4.
* Transaction may have been partially committed and
* partially rolled back
88 TX-PROTOCOL-ERROR VALUE -5.
* Routine invoked in an improper context
88 TX-ERROR VALUE -6.
* Transient error
88 TX-FAIL VALUE -7.
* Fatal error
88 TX-EINVAL VALUE -8.
* Invalid arguments were given
88 TX-COMMITTED VALUE -9.
* The transaction was heuristically committed
88 TX-NO-BEGIN VALUE -100.
* Transaction committed plus new transaction could not
* be started
88 TX-ROLLBACK-NO-BEGIN VALUE -102.
* Transaction rollback plus new transaction could not
* be started
88 TX-MIXED-NO-BEGIN VALUE -103.
* Mixed plus new transaction could not be started
88 TX-HAZARD-NO-BEGIN VALUE -104.
* Hazard plus new transaction could not be started
88 TX-COMMITTED-NO-BEGIN VALUE -109.
* Heuristically committed plus transaction could not
* be started
The TXINFDEF record defines a data structure where the result of the TXINFORM() call will be stored.
*
* TXINFDEF.cbl
*
05 XID-REC.
* XID record
10 FORMAT-ID PICS9(9) COMP-5.
* A value of -1 in FORMAT-ID means that the XID is null
10 GTRID-LENGTH PICS9(9) COMP-5.
10 BRANCH-LENGTH PICS9(9) COMP-5.
10 XID-DATA PICX(128).
05 TRANSACTION-MODE PICS9(9) COMP-5.
* Transaction mode settings
88 TX-NOT-IN-TRAN VALUE 0.
88 TX-IN-TRAN VALUE 1.
05 COMMIT-RETURN PICS9(9) COMP-5.
* Commit_return settings
88 TX-COMMIT-COMPLETED VALUE 0.
88 TX-COMMIT-DECISION-LOGGED VALUE 1.
05 TRANSACTION-CONTROL PICS9(9) COMP-5.
* Transaction_control settings
88 TX-UNCHAINED VALUE 0.
88 TX-CHAINED VALUE 1.
05 TRANSACTION-TIMEOUT PICS9(9) COMP-5.
* Transaction_timeout value
88 NO-TIMEOUT VALUE 0.
05 TRANSACTION-STATE PICS9(9) COMP-5.
* Transaction_state information
88 TX-ACTIVE VALUE 0.
88 TX-TIMEOUT-ROLLBACK-ONLY VALUE 1.
88 TX-ROLLBACK-ONLY VALUE 2.
BEA TUXEDO keeps track of the state for each program and verifies that legal state transitions occur for the various function calls and options. The state information includes the program type (request/response server, conversational server, or client), the initialization state (uninitialized or initialized), the resource management state (closed or open), the transaction state of the program, and the state of all asynchronous request/response and connection handles. When an illegal state transition is attempted, the called function fails, setting TPSTATUS-REC to TPEPROTO. The legal states and transitions for this information are described in the following tables. The table below indicates which functions request/response servers, conversational servers, and clients are allowed to call.
Note that TPSVRINIT and TPSVRDONE are not in this table since these functions are not called by applications (that is, they are application-supplied functions that are invoked by BEA TUXEDO).
| Function | Process Type | ||
|---|---|---|---|
| Request/response | Conversational | Client | |
| Server | Server | ||
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
N |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
N |
N |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
N |
N |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
N |
N |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
N |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
N |
N |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
|
N |
N |
Y |
|
|
Y |
Y |
N |
|
|
Y |
Y |
Y |
The remaining state tables are for both clients and servers, unless otherwise noted. Keep in mind that because some functions can not be called by both clients and servers (for example, The following state table indicates whether or not a client program has been initialized and registered with the transaction manager. Note that this table assumes the use of A server is placed in the initialized state by BEA TUXEDO's dispatcher before its TPINITIALIZE), certain state transitions shown below may not be possible for both program types. The above table should be consulted to determine whether the program in question is allowed to call a particular function.
TPINITIALIZE, which is optional. That is, a client may implicitly join an application by issuing one of many ATMI verbs (for example, TPACALL or TPCALL). A client must use TPINITIALIZE when either application authentication is required (see TPINITIALIZE and the description of the SECURITY keyword in ubbconfig(5)) or the client wishes to directly access an XA-compliant resource manager (see TPINITIALIZE).
TPSVRINIT function is invoked, and it is placed in the uninitialized state by BEA TUXEDO's dispatcher after its TPSVRDONE function has returned. Note that in all of the state tables shown below, an error return from a function causes the program to remain in the same state, unless otherwise noted.
| Function | States | |
|---|---|---|
| Uninitialized | Initialized | |
| I0 | I1 | |
|
|
I0 |
I1 |
|
|
I1 |
I1 |
|
|
I0 |
I1 |
|
|
I0 |
I0 |
|
|
I0 |
I1 |
|
all others |
|
I1 |
Note:
"all others" refers to the remaining ATMI calls
The remaining state tables assume a precondition of state I (regardless of whether a process arrived in this state via The following table indicates the state of a client or server with respect to whether or not a resource manager associated with the process has been initialized.
tpinit or the BEA TUXEDO main).
| Function | States | |
|---|---|---|
| Closed | Open | |
| R0 | R1 | |
|
|
R1 |
R1 |
|
|
R0 |
R0 |
|
|
|
R1 |
|
|
|
R1 |
|
|
|
R1 |
|
|
|
R1 |
|
|
|
R1 |
|
|
|
R1 |
|
all others |
R0 |
R1 |
The following state table indicates the state of a process with respect to whether or not the process is associated with a transaction. For servers, transitions to states T1 and T2 assume a precondition of state R1 (for example, TPOPEN has been called with no subsequent call to TPCLOSE or TPTERM).
The following state table indicates the state of a single request handle returned by tpacall.
Note:
* This state change occurs only if the descriptor is not associated with the caller's transaction.
The following state table indicates the state of a connection descriptor returned by The states are as follows:
tpsuspend returns a protocol error.tpconnect or provided by a service invocation in the TPSVCINFO structure. For primitives that do not take a connection descriptor, the state changes apply to all connection descriptors, unless otherwise noted.
C1 - TPCONNECT handle send-only
C2 - TPCONNECT handle receive-only
C3 - TPSVCDEF handle send-only
C4 - TPSVCDEF handle receive-only
Note:
* If the program is in transaction mode and
BEA TUXEDO ensures that a process calls the TX verbs in a legal sequence. When an illegal state transition is attempted (that is, a call from a state with a blank transition entry), the called function returns The states are defined below:
TPNOTRAN is not specified, the connection is in transaction mode.
TPTRAN flag is set, the connection is in transaction mode. tpsuspend returns a protocol error. TX State Transitions
TX_PROTOCOL_ERROR. The legal states and transitions for the TX primitives are shown in the table below. Calls that return failure do not make state transitions, except where described by specific state table entries. Any BEA TUXEDO client or server is allowed to use the TX verbs.
TXOPEN.
transaction_control characteristic is TX-UNCHAINED.
transaction_control characteristic is TX-CHAINED.
transaction_control characteristic is TX-UNCHAINED.
transaction_control characteristic is TX-CHAINED.
TX_SET1 denotes any of TX_OK, TX_ROLLBACK, TX_MIXED, TX_HAZARD, or
TX_COMMITTED (TX_ROLLBACK is not returned by tx_rollback and
TX_COMMITTED is not returned by tx_commit).
buffer(3c), PADVERTISE(3cbl), TPBEGIN(3cbl), TPCALL(3cbl), TPCONNECT(3cbl), TPINITIALIZE(3cbl), TPOPEN(3cbl), TPSVCSTART(3cbl), tuxtypes(5), typesw(5)