|
|
 |
| e-docs > Tuxedo > ATMI COBOL Function Reference > Section 3(cbl) - COBOL Functions |
|
ATMI COBOL Function Reference
|
Section 3(cbl) - COBOL Functions
Introduction to the COBOL Application-Transaction Monitor Interface
Description
The Application-Transaction Monitor Interface (ATMI) 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.
Communication Paradigms
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.
Note: In various parts of the BEA Tuxedo ATMI documentation we refer to threads. Because the BEA Tuxedo system does not support multithreading in COBOL, COBOL programmers may assume that the term thread refers to an entire process or context, depending on the circumstances. For example:
BEA Tuxedo Request/
Response Paradigm for Client/Server
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 ATMI 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 ATMI 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 when either 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 run time using a routine (TPSPRIO()) described in TPCALL(). By doing so, the caller can override the configuration or default priority when the message is sent.
BEA Tuxedo System Conversational Paradigm for Client/Server
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 "reserved" 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.
BEA Tuxedo System Queued Message Model
The BEA Tuxedo ATMI queued message model allows for enqueuing 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 functions that queue messages and dequeue responses are TPENQUEUE() and TPDEQUEUE(). They can be called from any type of BEA Tuxedo ATMI application processes: client, server, or conversational.
The queued message facility is an XA-compliant resource manager. Persistent messages are enqueued and dequeued within transactions to ensure reliable one-time-only processing.
ATMI Transactions
The BEA Tuxedo system supports two sets of mutually exclusive functions for defining and managing transactions: the BEA Tuxedo system's ATMI transaction demarcation functions (the names of which include the prefix TP) and X/Open's TX Interface functions (the names of which include the prefix TX_). Because X/Open used ATMI's transaction demarcation functions as the base for the TX Interface, the syntax and semantics of the TX Interface are quite similar to those of the ATMI. This section is an overview of ATMI transaction concepts. The next section introduces additional concepts about the TX Interface.
In the BEA Tuxedo system, a transaction 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 processes, possibly at 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 the following: 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 (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 calling either 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.
TX Transactions
Transactions defined by the TX Interface are practically identical with those defined by the ATMI functions. An application writer may use either set of functions 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 functions or the other. However, the two function 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() 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.
Chained and Unchained Transactions
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().
Transaction Characteristics
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.
Timeouts
There are three types of timeouts in the BEA Tuxedo ATMI 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 the configuration file.
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 ATMI 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 ATMI 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 invalid. 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 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 reissue 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.
If a transaction has timed out, the only valid communications before the transaction is aborted are calls to TPACALL() with TPNOREPLY, TPNOTRAN, and TPNOBLOCK set.
Dynamic Service Advertisements
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 the set of services that it offers at run time, 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.
Typed Records
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. For details, refer to the "Introduction to the C Language Application-Transaction Monitor Interface" in the BEA Tuxedo ATMI C Function Reference. 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.
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 (PIC S9(9) COMP-5), shorts (PIC S9(4) COMP-5), and characters (PIC X(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.
Buffer Type Switch
The BEA Tuxedo system provides a method for adding user specific record types. For details, see the "Buffer Type Switch" section in Introduction to the C Language Application-to-Transaction Monitor Interface.
Single or Multiple Application Context per Process
The BEA Tuxedo system allows client programs to create an association with one or more applications per process. If TPINITIALIZE() is called with the TP-MULTI-CONTEXTS setting of CONTEXTS-FLAG in TPINFDEF-REC, then multiple client contexts are allowed. If TPINITIALIZE() is called implicitly or the CONTEXTS-FLAG is not set to TP-MULTI-CONTEXTS, then only a single application association is allowed.
In single-context mode, if TPINITIALIZE() is called more than once (that is, if it is called after the client has already joined the application), no action is taken and success is returned.
In multi-context mode, each call to TPINITIALIZE() creates a new application association. The program can obtain a handle representing this application association by calling TPGETCTXT() and it can call TPSETCTXT() to set its context.
Once an application has chosen single-context mode, all calls to TPINITIALIZE() must specify single-context mode until all application associations are terminated. Similarly, once an application has chosen multi-context mode, all calls to TPINITIALIZE() must specify multi-context mode until all application associations are terminated.
Server programs can be associated with only a single application and cannot act as clients.
Note: In addition to allowing multiple application contexts per process, the BEA Tuxedo system allows multiple application threads per process. Multithreading is supported, however, only in the C language interface.
The following state table shows the transitions that may occur, within a client process, among the following states: the uninitialized state, the initialized in single-context mode state, and the initialized in multi-context mode state.
Unsolicited Notification 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 (specifically, by the information passed in the TPINFDEF-REC data structure at TPINITIALIZE time) and in part by the system (based on the processor through 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. Calls to the TPCALL() and TPFORWAR() functions 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 TPNOTIFY() function is used to notify clients identified in this manner. COBOL Language ATMI Return Codes and Other Definitions The following return code and setting definitions are used by the ATMI routines: 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 the amount received. The TPSVCDEF data structure is used by functions to pass settings to and from the BEA Tuxedo system: The TPINFDEF data structure is used by TPINITIALIZE() to join the application: The TPCONTEXTDEF data structure is used by TPGETCTXT() and TPSETCTXT() to manipulate program contexts: The TPQUEDEF data structure is used to pass and retrieve information associated with enqueuing the message: The TPSVCRET data structure is used by TPRETURN() to indicate the status of the transaction: The TPTRXDEF data structure is used by TPBEGIN() to set transaction timeouts, and by TPSUSPEND() and TPRESUME() to get and set, respectively, transaction identifiers: The TPCMTDEF data structure is used by TPSCMT() to set the commit level characteristics: The TPAUTDEF data structure is used by TPCHKAUTH() to check if authentication is required: The TPPRIDEF data structure is used by TPSPRIO() and TPGPRIO() to manipulate message priorities: The TPTRXLEV data structure is used by TPGETLEV() to receive transaction level setting: The TPBCTDEF data structure is used by TPNOTIFY() and TPBROADCAST() to send notifications: The FML-INFO data structure is used by FINIT(), FVSTOF(), and FVFTOS() to deal with FML buffers: The TPEVTDEF data structure is used by TPPOST(), TPSUBSCRIBE(), and TPUNSUBSCRIBE() to handle event postings and subscriptions: The TPKEYDEF data structure is used by TPKEYCLOSE(), TPKEYGETINFO(), TPKEYOPEN(), and TPKEYSETINFO()to manage public-private keys for performing message-based digital signature and encryption operations: COBOL Language TX Return Codes and Other Definitions The following return code and setting definitions are used by the TX routines: The TXINFDEF record defines a data structure where the result of the TXINFORM() call will be stored: ATMI State Transitions The BEA Tuxedo system 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 may be called by request/response servers, conversational servers, and clients. Note that TPSVRINIT() and TPSVRDONE() are not included in this table because they are not called by applications (that is, they are application-supplied functions that are invoked by the BEA Tuxedo system).
*
* TPSTATUS.cbl
*
05 TP-STATUS PIC S9(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 TPEDIAGNOSTIC VALUE 24.
88 TPEMIB VALUE 25.
88 TPEMAXVAL VALUE 26.
05 TPEVENT PIC S9(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 PIC S9(9) COMP-5.
88 TPED-NOEVENT VALUE 0.
88 TPEV-SVCTIMEOUT VALUE 1.
88 TPEV-TERM VALUE 2.
05 APPL-RETURN-CODE PIC S9(9) COMP-5.*
* TPTYPE.cbl
*
05 REC-TYPE PIC X(8).
88 X-OCTET VALUE "X_OCTET".
88 X-COMMON VALUE "X_COMMON".
05 SUB-TYPE PIC X(16).
05 LEN PIC S9(9) COMP-5.
88 NO-LENGTH VALUE 0.
05 TPTYPE-STATUS PIC S9(9) COMP-5.
88 TPTYPEOK VALUE 0.
88 TPTRUNCATE VALUE 1.*
* 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).*
* TPINFDEF.cbl
*
05 USRNAME PIC X(30).
05 CLTNAME PIC X(30).
05 PASSWD PIC X(30).
05 GRPNAME PIC X(30).
05 NOTIFICATION-FLAG PIC S9(9) COMP-5.
88 TPU-SIG VALUE 1.
88 TPU-DIP VALUE 2.
88 TPU-IGN VALUE 3.
05 ACCESS-FLAG PIC S9(9) COMP-5.
88 TPSA-FASTPATH VALUE 1.
88 TPSA-PROTECTED VALUE 2.
05 CONTEXTS-FLAG PIC S9(9) COMP-5.
88 TP-SINGLE-CONTEXT VALUE 0.
88 TP-MULTI-CONTEXTS VALUE 1.
05 DATALEN PIC S9(9) COMP-5. *
* TPCONTEXTDEF.cbl
*
05 CONTEXT PIC S9(9) COMP-5.
*
* TPQUEDEF.cbl
*
05 TPBLOCK-FLAG PIC S9(9) COMP-5.
88 TPNOBLOCK VALUE 0.
88 TPBLOCK VALUE 1.
05 TPTRAN-FLAG PIC S9(9) COMP-5.
88 TPNOTRAN VALUE 0.
88 TPTRAN VALUE 1.
05 TPTIME-FLAG PIC S9(9) COMP-5.
88 TPNOTIME VALUE 0.
88 TPTIME VALUE 1.
05 TPSIGRSTRT-FLAG PIC S9(9) COMP-5.
88 TPNOSIGRSTRT VALUE 0.
88 TPSIGRSTRT VALUE 1.
05 TPNOCHANGE-FLAG PIC S9(9) COMP-5.
88 TPNOCHANGE VALUE 0.
88 TPCHANGE VALUE 1.
05 TPQUE-ORDER-FLAG PIC S9(9) COMP-5.
88 TPQDEFAULT VALUE 0.
88 TPQTOP VALUE 1.
88 TPQBEFOREMSGID VALUE 2.
05 TPQUE-TIME-FLAG PIC S9(9) COMP-5.
88 TPQNOTIME VALUE 0.
88 TPQTIME-ABS VALUE 1.
88 TPQTIME-REL VALUE 2.
05 TPQUE-PRIORITY-FLAG PIC S9(9) COMP-5.
88 TPQNOPRIORITY VALUE 0.
88 TPQPRIORITY VALUE 1.
05 TPQUE-CORRID-FLAG PIC S9(9) COMP-5.
88 TPQNOCORRID VALUE 0.
88 TPQCORRID VALUE 1.
05 TPQUE-REPLYQ-FLAG PIC S9(9) COMP-5.
88 TPQNOREPLYQ VALUE 0.
88 TPQREPLYQ VALUE 1.
05 TPQUE-FAILQ-FLAG PIC S9(9) COMP-5.
88 TPQNOFAILUREQ VALUE 0.
88 TPQFAILUREQ VALUE 1.
05 TPQUE-MSGID-FLAG PIC S9(9) COMP-5.
88 TPQNOMSGID VALUE 0.
88 TPQMSGID VALUE 1.
05 TPQUE-GETBY-FLAG PIC S9(9) COMP-5.
88 TPQGETNEXT VALUE 0.
88 TPQGETBYMSGIDOLD VALUE 1.
88 TPQGETBYCORRIDOLD VALUE 2.
88 TPQGETBYMSGID VALUE 3.
88 TPQGETBYCORRID VALUE 4.
05 TPQUE-WAIT-FLAG PIC S9(9) COMP-5.
88 TPQNOWAIT VALUE 0.
88 TPQWAIT VALUE 1.
05 TPQUE-DELIVERY-FLAG PIC S9(9) COMP-5.
88 TPQNODELIVERYQOS VALUE 0.
88 TPQDELIVERYQOS VALUE 1.
05 TPQUEQOS-DELIVERY-FLAG PIC S9(9) COMP-5.
88 TPQQOSDELIVERYDEFAULTPERSIST VALUE 0.
88 TPQQOSDELIVERYPERSISTENT VALUE 1.
88 TPQQOSDELIVERYNONPERSISTENT VALUE 2.
05 TPQUE-REPLY-FLAG PIC S9(9) COMP-5.
88 TPQNOREPLYQOS VALUE 0.
88 TPQREPLYQOS VALUE 1.
05 TPQUEQOS-REPLY-FLAG PIC S9(9) COMP-5.
88 TPQQOSREPLYDEFAULTPERSIST VALUE 0.
88 TPQQOSREPLYPERSISTENT VALUE 1.
88 TPQQOSREPLYNONPERSISTENT VALUE 2.
05 TPQUE-EXPTIME-FLAG PIC S9(9) COMP-5.
88 TPQNOEXPTIME VALUE 0.
88 TPQEXPTIME-ABS VALUE 1.
88 TPQEXPTIME-REL VALUE 2.
88 TPQEXPTIME-NONE VALUE 3.
05 TPQUE-PEEK-FLAG PIC S9(9) COMP-5.
88 TPQNOPEEK VALUE 0.
88 TPQPEEK VALUE 1.
05 DIAGNOSTIC PIC S9(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 QMEABORTED VALUE -8.
88 QMEPROTO VALUE -9.
88 QMEBADQUEUE VALUE -10.
88 QMENOMSG VALUE -11.
88 QMEINUSE VALUE -12.
88 QMENOSPACE VALUE -13.
88 QMERELEASE VALUE -14.
88 QMEINVHANDLE VALUE -15.
88 QMESHARE VALUE -16.
05 DEQ-TIME PIC S9(9) COMP-5.
05 EXP-TIME PIC S9(9) COMP-5.
05 PRIORITY PIC S9(9) COMP-5.
05 MSGID PIC X(32).
05 CORRID PIC X(32).
05 QNAME PIC X(15).
05 QSPACE-NAME PIC X(15).
05 REPLYQUEUE PIC X(15).
05 FAILUREQUEUE PIC X(15).
05 CLIENTID OCCURS4 TIMES PIC S9(9) COMP-5.
05 APPL-RETURN-CODE PIC S9(9) COMP-5.
05 APPKEY PIC S9(9) COMP-5.*
* TPSVCRET.cbl
*
05 TP-RETURN-VAL PIC S9(9) COMP-5.
88 TPSUCCESS VALUE 0.
88 TPFAIL VALUE 1.
88 TPEXIT VALUE 2.
05 APPL-CODE PIC S9(9) COMP-5.*
* TPTRXDEF.cbl
*
05 T-OUT PIC S9(9) COMP-5 VALUE IS 0.
05 TRANID OCCURS 6 TIMES PIC S9(9) COMP-5.*
* TPCMTDEF.cbl
*
05 CMT-FLAG PIC S9(9) COMP-5.
88 TP-CMT-LOGGED VALUE 1.
88 TP-CMT-COMPLETE VALUE 2.
05 PREV-CMT-FLAG PIC S9(9) COMP-5.
88 PREV-TP-CMT-LOGGED VALUE 1.
88 PREV-TP-CMT-COMPLETE VALUE 2.* TPAUTDEF.cbl
*
05 AUTH-FLAG PIC S9(9) COMP-5.
88 TPNOAUTH VALUE 0.
88 TPSYSAUTH VALUE 1.
88 TPAPPAUTH VALUE 2.*
* TPPRIDEF.cbl
*
05 PRIORITY PIC S9(9) COMP-5.
05 PRIO-FLAG PIC S9(9) COMP-5.
88 TPABSOLUTE VALUE 0.
88 TPRELATIVE VALUE 1.*
* TPTRXLEV.cbl
*
05 TPTRXLEV-FLAG PIC S9(9) COMP-5.
88 TP-NOT-IN-TRAN VALUE 0.
88 TP-IN-TRAN VALUE 1.*
* TPBCTDEF.cbl
*
05 TPBLOCK-FLAG PIC S9(9) COMP-5.
88 TPBLOCK VALUE 0.
88 TPNOBLOCK 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 LMID PIC X(30).
05 USERNAME PIC X(30).
05 CLTNAME PIC X(30).*
* 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.
88 FEBADOP VALUE 20.
*
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).*
* 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).*
* TPKEYDEF.cbl
*
05 KEY-HANDLE PIC S9(9) COMP-5.
05 PRINCIPAL-NAME PIC X(512).
05 LOCATION PIC X(1024).
05 IDENTITY-PROOF PIC X(2048).
05 PROOF-LEN PIC S9(9) COMP-5.
05 CRYPTO-PROVIDER PIC X(128).
05 SIGNATURE-FLAG PIC S9(9) COMP-5.
88 TPKEY-NOSIGNATURE VALUE 0.
88 TPKEY-SIGNATURE VALUE 1.
05 DECRYPT-FLAG PIC S9(9) COMP-5.
88 TPKEY-NODECRYPT VALUE 0.
88 TPKEY-DECRYPT VALUE 1.
05 ENCRYPT-FLAG PIC S9(9) COMP-5.
88 TPKEY-NOENCRYPT VALUE 0.
88 TPKEY-ENCRYPT VALUE 1.
05 AUTOSIGN-FLAG PIC S9(9) COMP-5.
88 TPKEY-NOAUTOSIGN VALUE 0.
88 TPKEY-AUTOSIGN VALUE 1.
05 AUTOENCRYPT-FLAG PIC S9(9) COMP-5.
88 TPKEY-NOAUTOENCRYPT VALUE 0.
88 TPKEY-AUTOENCRYPT VALUE 1.
05 ATTRIBUTE-NAME PIC X(64).
05 ATTRIBUTE-VALUE-LEN PIC S9(9) COMP-5.*
* TXSTATUS.cbl
*
05 TX-STATUS PIC S9(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*
* TXINFDEF.cbl
*
05 XID-REC.
* XID record
10 FORMAT-ID PIC S9(9) COMP-5.
* A value of -1 in FORMAT-ID means that the XID is NULL
10 GTRID-LENGTH PIC S9(9) COMP-5.
10 BRANCH-LENGTH PIC S9(9) COMP-5.
10 XID-DATA PIC X(128).
05 TRANSACTION-MODE PIC S9(9) COMP-5.
* Transaction mode settings
88 TX-NOT-IN-TRAN VALUE 0.
88 TX-IN-TRAN VALUE 1.
05 COMMIT-RETURN PIC S9(9) COMP-5.
* Commit_return settings
88 TX-COMMIT-COMPLETED VALUE 0.
88 TX-COMMIT-DECISION-LOGGED VALUE 1.
05 TRANSACTION-CONTROL PIC S9(9) COMP-5.
* Transaction_control settings
88 TX-UNCHAINED VALUE 0.
88 TX-CHAINED VALUE 1.
05 TRANSACTION-TIMEOUT PIC S9(9) COMP-5.
* Transaction_timeout value
88 NO-TIMEOUT VALUE 0.
05 TRANSACTION-STATE PIC S9(9) COMP-5.
* Transaction_state information
88 TX-ACTIVE VALUE 0.
88 TX-TIMEOUT-ROLLBACK-ONLY VALUE 1.
88 TX-ROLLBACK-ONLY VALUE 2.
Function Process Type Request/Response Conversational Client TPABORT() Y Y Y TPACALL() Y Y Y TPADVERTISE() Y Y N TPBEGIN() Y Y Y TPBROADCAST() Y Y Y TPCALL() Y Y Y TPCANCEL() Y Y Y TPCHKAUTH() Y Y Y TPCHKUNSOL() N N Y TPCLOSE() Y Y Y TPCOMMIT() Y Y Y TPCONNECT() Y Y Y TPDEQUE() Y Y Y TPDISCON() Y Y Y TPENQUEUE() Y Y Y TPFORWAR() Y N N TPGETCTXT() Y Y Y TPGETLEV() Y Y Y TPGETRPLY() Y Y Y TPGPRIO() Y Y Y TPINITIALIZE() N N Y TPNOTIFY() Y Y Y TPOPEN() Y Y Y TPPOST() Y Y Y TPRECV() Y Y Y TPRESUME() Y Y Y TPRETURN() Y Y N TPSCMT() Y Y Y TPSEND() Y Y Y TPSETCTXT() N N Y TPSETUNSOL() N N Y TPSPRIO() Y Y Y TPSUBSCRIBE() Y Y Y TPSUSPEND() Y Y Y TPTERM() N N Y TPUNADVERTISE() Y Y N TPUNSUBSCRIBE() Y Y Y The remaining state tables are for both clients and servers, unless otherwise noted. Keep in mind that because some functions cannot be called by both clients and servers (for example, 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. 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 TPINITIALIZE(), which is optional in single-context mode. That is, a single-context client may implicitly join an application by issuing one of many ATMI functions (for example, TPACALL() or TPCALL()). A client must use TPINITIALIZE() when one of the following is true:
Server
Server
A server is placed in the initialized state by the BEA Tuxedo dispatcher before its TPSVRINIT() function is invoked, and it is placed in the uninitialized state by the BEA Tuxedo 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.
The remaining state tables assume a precondition of state I (regardless of whether a process arrived in this state via TPINITIALIZE(), TPSETCTXT(), or the BEA Tuxedo service dispatcher). 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:
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: a This state change occurs only if the descriptor is not associated with the caller's transaction.
b This state change occurs only if the descriptor is associated with the caller's transaction.
c If the descriptor is associated with the caller's transaction, then TPSUSPEND() returns a protocol error.
The following state table indicates the state of a connection descriptor returned by 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.
The states are as follows:
C0 - No handle
C1 - TPCONNECT handle send-only
C2 - TPCONNECT handle receive-only
C3 - TPSVCDEF handle send-only
C4 - TPSVCDEF handle receive-only
Note: a If the program is in transaction mode and TPNOTRAN is not specified, the connection is in transaction mode.
b If the TPTRAN flag is set, the connection is in transaction mode.
c If the connection is not in transaction mode, no state change.
d If the connection is in transaction mode, then TPSUSPEND() returns a protocol error.
TX State Transitions
BEA Tuxedo ensures that a process calls the TX functions 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 TX_PROTOCOL_ERROR. The legal states and transitions for the TX functions 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 functions.
The states are defined below:
See Also
buffer(3c), TPINITIALIZE(3cbl), TPADVERTISE(3cbl), TPBEGIN(3cbl), TPCALL(3cbl), TPCONNECT(3cbl), TPGETCTXT(3cbl), TPKEYCLOSE(3cbl), TPKEYGETINFO(3cbl), TPKEYOPEN(3cbl), TPKEYSETINFO(3cbl), TPOPEN(3cbl), TPSETCTXT(3cbl), TPSVCSTART(3cbl), tuxtypes(5), typesw(5)
|
|
|
|
||
 |
|
|
 |
 |
 |
|
||
