|
|
 |
| e-docs > Tuxedo > ATMI C Function Reference > Section 3c - C Functions |
|
ATMI C Function Reference
|
Section 3c - C Functions
Introduction to the C Language Application-to-Transaction Monitor Interface
Description
The Application-to-Transaction Monitor Interface (ATMI) provides the interface between the application and the transaction processing system. This interface is known as the ATMI interface. It provides function calls to open and close resources, manage transactions, manage typed buffers, and invoke request/response and conversational service calls.
Communication Paradigms
The function calls described in the ATMI reference pages imply a particular model of communication. This model is expressed in terms of how client and server processes 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 descriptor 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 process 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 documentation we refer to threads. When this term is used in a discussion of multithreaded applications, it is self-explanatory. In some instances, however, the term is used in a discussion of a topic that is relevant for both single-threaded and multithreaded applications. In such cases, readers who are running single-threaded applications may assume that the term thread refers to an entire process.
BEA Tuxedo ATMI System Request/
Response Paradigm for Client/Server
With regard to request/response communication, a client is defined as a process 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. tpinit() and tpterm() allow a client to join and leave a BEA Tuxedo ATMI system application.
A request/response server is a process that can receive one (and only one) service request at a time and send at most one reply to that request. (If the server is multithreaded, however, it can receive multiple requests at one time and issue multiple replies at one time.) 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 processes 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 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 BEA Tuxedo ATMI system's main, 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 tpforward(). A service is not allowed to perform any other work nor is it allowed to communicate with any other process 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 process 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(). By doing so, the caller can override the configuration or default priority when the message is sent.
BEA Tuxedo ATMI System Conversational Paradigm for Client/Server
With regard to conversational communication, a client is defined as a process that can initiate a conversation but cannot accept a connection request.
A conversational server is a process 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. In a single-threaded server, while the connection is established, the server is "reserved" such that no other process can establish a connection with it. When a connection is established to a multithreaded server, however, that server is not reserved for exclusive use by one process. Instead, it can accept requests from multiple client threads.
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 cannot 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 connection descriptor 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.
Message Delivery
Sending and receiving messages, whether in conversation mode or request/response mode, implies communication between two units of an application. The great majority of messages lead to a reply or at least an acknowledgment, so that is an assurance that the message was received. There are, however, certain messages (some originated by the system, others originated by an application) where a reply or acknowledgment is not expected. For example, the system can send an unsolicited message using tpnotify() without the TPACK() flag, or an application can send a message using tpacall() with the TPNOREPLY() flag. If the message queue of the receiving program is full, the message is dropped.
If the sending and receiving side are on different machines, the communication takes place between bridge processes that send and receive messages across a network. This raises the additional possibility of non-delivery due to a circuit failure. Even when either of these conditions leads to the positing of an event or to a ULOG message, it is not easy to associate the event or ULOG message with the non-arrival of a particular message.
Because the BEA Tuxedo ATMI system is designed to handle large volumes of messages across broad networks, it is not programmed to detect and correct the small percentage of failures-to-deliver described in the preceding paragraphs. For that reason, there can be no guarantee that every message will be delivered.
Message Sequencing
In the conversational model, for messages being exchanged using tpsend() and tprecv(), a sequence number is added to the message header and messages are received in the order in which they are sent. If a server or client gets a message out of order, the conversation is stopped, any transaction in progress is rolled back, and message 1572 in LIBTUX, "Bad Conversational Sequence Number," is logged.
In the Request/Response model, messages are not sequenced by the system. If the application logic implies a sequence, it is the responsibility of the application to monitor and control it. The parallel message transmission made possible by the support of multiple network addresses for bridge processes increases the possibility that messages will not be received in the order sent. An application that is concerned about this may choose to specify a single network address for each bridge process, add sequence numbers to their messages or require periodic acknowledgments.
Queued Message Model
The BEA Tuxedo ATMI system 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 system application processes: client, server, or conversational. The functions tpenqueue() and tpdequeue() can also be used for peer-to-peer communication where neither the enqueuing application nor the dequeuing application are designated as server or client.
The queued message facility is an XA-compliant resource manager. Persistent messages are enqueued and dequeued within transactions to ensure one-time-only processing.
ATMI Transactions
The BEA Tuxedo ATMI 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 ATMI 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 process must call one of the following: tpsuspend(), tpcommit(), or tpabort(). Thus, one process can start a transaction that another may finish.
If a process 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() flag).
A service routine joining a transaction that was started by another process 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 process calling either tpbegin() or tpresume()) can call tpcommit() or tpabort(). Participants influence the outcome of a transaction by using tpreturn() or tpforward(). 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 developer may use either set of functions when writing clients and service routines, but should not intermingle one set of functions with the other within a single process (that is, a process cannot call tpbegin() and later call tx_commit()).
The TX Interface has two calls for opening and closing resource managers in a portable manner, tx_open() and tx_close(), respectively. Transactions are started with tx_begin() and completed with either tx_commit() or tx_rollback(). tx_info() is used to retrieve transaction information, and there are three calls to set options for transactions: tx_set_commit_return(), tx_set_transaction_control(), and tx_set_transaction_timeout(). 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 tx_open(). The default BEA Tuxedo ATMI 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 tx_close().
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 tx_begin() is called.
In the chained mode, a new transaction starts implicitly when the current transaction completes. That is, when tx_commit() or tx_rollback() is called, the BEA Tuxedo ATMI 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 tx_set_transaction_control(). Transitions between the chained and unchained mode affect the behavior of the next tx_commit() or tx_rollback() call. The call to tx_set_transaction_control() does not put the caller into or take it out of transaction mode.
Since tx_close() 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 tx_close().
Transaction Characteristics
A client or a service routine may call tx_info() to obtain the current values of their transaction characteristics and to determine whether they are executing in transaction mode.
The state of an application process includes several transaction characteristics. The caller specifies these by calling tx_set_*() 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 tx_info(), it does not change the value.
Error Handling
Most of the ATMI functions have one or more error returns. An error condition is indicated by an otherwise impossible returned value. This is usually -1 or error, or 0 for a bad field identifier (BADFLDID) or address. The error type is also made available in the external integer tperrno. tperrno is not cleared on successful calls, so it should be tested only after an error has been indicated.
The tpstrerror() function is provided to produce a message on the standard error output. It takes one argument, an integer (found in tperrno) and returns a pointer to the text of an error message in LIBTUX_CAT. The pointer can be used as an argument to userlog().
tperrordetail() can be used as the first step of a three step procedure to get additional detail about an error in the most recent BEA Tuxedo ATMI system call on the current thread. tperrordetail() returns an integer which is then used as an argument to tpstrerrordetail() to retrieve a pointer to a string that contains the error message. The pointer can then be used as an argument to userlog or to fprintf().
The error codes that can be produced by an ATMI function are described on each ATMI reference page. The F_error() and F_error32() functions are provided to produce a message on the standard error output for FML errors. They take one parameter, a string; print the argument string appended with a colon and a blank; and then print an error message followed by a newline character. The error message displayed is the one defined for the error number currently in Ferror() or Ferror32(), which is set when errors occur.
Fstrerror(), and its counterpart, Fstrerror32(), can be used to retrieve the text of an FML error message from a message catalog; it returns a pointer that can be used as an argument to userlog.
The error codes that can be produced by an FML function are described on each FML reference page.
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(3c) for details.) The second kind of timeout can occur when using the BEA Tuxedo ATMI system communication routines defined in tpcall(3c). 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 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 invalid. That is, if a process is waiting for a particular asynchronous reply for a request sent in transaction mode and a transaction timeout occurs, the descriptor for that reply becomes invalid. Similarly, if a transaction timeout occurs, an event is generated on the connection descriptor associated with the transaction and that descriptor becomes invalid. On the other hand, if a blocking timeout occurs, the descriptor is still valid and the waiting process 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 ATMI 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 TP_EVSVCERR 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.
Since release 6.4, some additional detail has been provided beyond the TPESVCERR error code. If a service fails due to exceeding the timeout threshold, an event, .SysServiceTimeout, is posted.
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.
Buffer Management
Initially, a process has no buffers. Before sending a message, a buffer must be allocated using tpalloc(). The sender's data can then be placed in the buffer and sent. This buffer has a specific structure. The particular structure is denoted by the type argument to the tpalloc() function. Since some structures can need further classification, a subtype can also be given (for example, a particular type of C structure).
When receiving a message, a buffer is required into which application data can be received. This buffer must be one originally gotten from tpalloc(). Note that a BEA Tuxedo ATMI system server, in its main, allocates a buffer whose address is passed to a request/response or conversational service upon invoking the service. (See tpservice(3c) for details on how this buffer is treated.)
Buffers used for receiving messages are treated slightly differently than those used for sending: the size and address usually change upon receipt of a message, since the system internally swaps the buffer passed into the receive call with internal buffers it used to process the buffer. A buffer may grow or shrink when it receives data. Whether it grows or shrinks depends on the amount of data sent by the sender, and the internal data flow needed to get the data from sender to receiver. Many factors can affect the buffer size, including compression, receiving a message from a different type of machine, and the action of the postrecv() function for the type of buffer being used (see buffer(3c)). The buffer sizes in Workstation clients are usually different from those in native clients.
It is best to think of the receive buffer as a placeholder, rather than the actual container that will receive the message. The system sometimes uses the size of the buffer you pass as a hint, so it does help if it is big enough to hold the expected reply.
On the sending side, buffer types that might be filled to less than their allocated capacity (for example, FML or STRING buffers) send only the amount used. A 100K FML32 buffer with one integer field in it is sent as a much smaller buffer, containing only that integer.
This means that the receiver will receive a buffer smaller than what was originally allocated by the sender, yet larger than the data that was sent. For example, if a STRING buffer of 10K bytes is allocated, and the string "HELLO" is copied into it, only the six bytes are sent, and the receiver will probably end up with a buffer that is around 1K or 4K bytes. (It may be larger or smaller, depending on other factors.) The BEA Tuxedo ATMI system guarantees only that a received message will contain all of the data that was sent; it does not guarantee that the message will contain all the free space it originally contained.
The process receiving the reply is responsible for noting size changes in the buffer (using tptypes()) and reallocating the buffer if necessary. All BEA Tuxedo ATMI functions change a receiver's buffer return information about the amount of data in the buffer, so it should become standard practice to check the buffer size every time a reply is received.
One can send and receive messages using the same data buffer. Alternatively, a different data buffer can be allocated for each message. It is usually the responsibility of the calling process to free its buffers by invoking tpfree(). However, in limited cases, the BEA Tuxedo ATMI system frees the caller's buffer. For more information about buffer usage, see the descriptions of communication functions such as tpfree().
Buffer Type Switch
The tmtype_sw_t structure provides the description required when adding new buffer types to tm_typesw(), the buffer type switch for a process. The switch elements are defined in typesw(5). The function names used in this entry are templates for the actual function names defined by the BEA Tuxedo ATMI system or by applications in which custom buffer types are created. These function names can be mapped easily to switch elements: to create a template name simply add the prefix _tm to the element name of a function pointer. For example, the template name for the element initbuf is _tminitbuf.
The type element must be non-NULL and at most 8 characters in length. If this element is not unique in the switch, then subtype() must be non-NULL.
The subtype() element can be NULL, a string of at most 16 characters, or * (the wildcard character). The combination of type() and subtype() must uniquely identify an element in the switch.
A given type can have multiple subtypes. If all subtypes are to be treated the same for a given type, then the wildcard character, "*", can be used. Note that the tptypes() function can be used to determine a buffer's type and subtype if subtypes need to be distinguished. If some subset of the subtypes within a particular type are to be treated individually, and the rest are to be treated identically, then those that are to be singled out with specific subtype values should appear in the switch before the subtype designated with the wildcard. Thus, searching for types and subtypes in the switch is done from top to bottom, and the wildcard subtype entry accepts any "leftover" type matches.
The dfltsize() element is used when allocating or reallocating a buffer. The semantics of tpalloc() and tprealloc() are such that the larger of the following two values is used to create or reallocate a buffer: the value of dfltsize() or the value of the size parameter for the tpalloc() and tprealloc() functions. For some types of structures, such as a fixed-sized C structure, the buffer size should equal the size of the structure. If dfltsize() is set to this value, then the caller may not need to specify the buffer's length to routines in which a buffer is passed. dfltsize() can be 0 or less. However, if tpalloc() or tprealloc() is called and the size parameter for the function being called is also less than or equal to 0, then the routine will fail. We recommend setting dfltsize() to a value greater than 0.
The BEA Tuxedo ATMI system provides five basic buffer types:
Two of these buffer types have synonyms: X_OCTET is a synonym for CARRAY, and both X_C_TYPE and X_COMMON are synonyms for VIEW. X_C_TYPE supports all the same elements as VIEW, whereas X_COMMON supports only longs, shorts, and characters. X_COMMON should be used when both C and COBOL programs are communicating.
An application wishing to supply its own buffer type can do so by adding an instance to the tm_typesw() array. Whenever adding or deleting a buffer type, be careful to leave a NULL entry at the end of the array. Note that a buffer type with a NULL name is not permitted. An application client or server is linked with the new buffer type switch by explicitly specifying the name of the source or object file on the buildserver() or buildclient() command line using the -f option.
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 buffer 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 TPINIT typed buffer at tpinit() time) and in part by the system (based on the processor through which the client accesses the application).
The second method 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 tpforward() 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.
Single or Multiple Application Contexts per Process
The BEA Tuxedo ATMI system allows client programs to create an association with one or more applications per process. If tpinit() is called with the TPMULTICONTEXTS parameter included in the flags field of the TPINIT structure, then multiple client contexts are allowed. If tpinit() is called implicitly, is called with a NULL parameter, or the flags field does not include TPMULTICONTEXTS, then only a single application association is allowed.
In single-context mode, if tpinit() 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 multicontext mode, each call to tpinit() creates a new application association. The application can obtain a handle representing this application association by calling tpgetctxt(). Any thread in the same process can call tpsetctxt() to set that thread's context.
Once an application has chosen single-context mode, all calls to tpinit() must specify single-context mode until all application associations are terminated. Similarly, once an application has chosen multicontext mode, all calls to tpinit() must specify multicontext mode until all application associations are terminated.
Server programs can be associated with only a single application and cannot act as clients. However, within each server program, there may be multiple server dispatch contexts. Each server dispatch context works in its own thread.
Table 2 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 multicontext mode state.
Context State Changes for a Client Thread In a multicontext application, calls to various functions result in context state changes for the calling thread and any other threads that are active in the same context as the calling process. The following diagram illustrates the context state changes that result from calls to the tpinit(), tpsetctxt(), and tpterm() functions. (The tpgetctxt() function does not produce any context state changes.) Multicontext State Transitions
Note: When tpterm() is called by a thread running in the multicontext state (TPMULTICONTEXTS), the calling thread is placed in the NULL context state (TPNULLCONTEXT). All other threads associated with the terminated context are switched to the invalid context state (TPINVALIDCONTEXT). Table 3 lists all possible context state changes produced by calling tpinit(), tpsetctxt(), and tpterm(). These states are thread-specific; different threads can be in different states when they are part of a multicontexted application. By contrast, each context state listed in the preceding table (Per-Process Context Modes) applies to an entire process.
Support for Threads Programming The BEA Tuxedo ATMI system supports multithreaded programming in several ways. If the process is using single-context mode, then as the application creates new threads, those threads share the BEA Tuxedo ATMI context for the process. In a client, after a thread issues a tpinit() call in single-context mode, other threads may then proceed to issue ATMI calls. For example, one thread may issue a tpacall() and a different thread in the same process may issue a tpgetrply(). When in multicontext mode, threads initially are not associated with a BEA Tuxedo ATMI application. A thread can either join an existing application association by calling tpsetctxt() or create a new association by calling tpinit() with the TPMULTICONTEXTS flag set. Whether running in single-context mode or multicontext mode, the application is responsible for coordinating its threads so that ATMI operations are performed at the appropriate time. An application may create additional threads within a server by using OS thread functions. These threads may operate independently of the BEA Tuxedo ATMI system, or they may operate in the same context as one of the server dispatch threads. Initially, application-created server threads are not associated with any server dispatch context. An application-created server thread may call tpsetctxt() to associate itself with a server dispatch thread. The application-created server thread must complete all of its ATMI calls before the dispatched thread calls tpreturn() or tpforward(). A server thread dispatched by the BEA Tuxedo ATMI system may not call tpsetctxt(). In addition, application-created threads may not make ATMI calls that would cause an implicit tpinit() when not associated with a context. On the other hand, this failure to make ATMI calls does not occur with dispatcher-created threads because those threads are always associated with a context. All server threads are prohibited from calling tpinit(). In a multithreaded application, a thread that is operating in the TPINVALIDCONTEXT state is prohibited from calling many ATMI functions. The following lists specify which functions may and may not be called under these circumstances. The BEA Tuxedo ATMI system allows a thread operating in the TPINVALIDCONTEXT state to call the following functions:
The BEA Tuxedo ATMI system does not allow a thread operating in the TPINVALIDCONTEXT state to call the following functions:
C Language ATMI Return Codes and Other Definitions
The following return code and flag definitions are used by the ATMI routines. For an application to work with different transaction monitors without change or recompilation, each system must define its flags and return codes as follows:
/*
* The following definitions must be included in atmi.h
*/
/* Flags to service routines */
#define TPNOBLOCK 0x00000001 /* non-blocking send/rcv */
#define TPSIGRSTRT 0x00000002 /* restart rcv on interrupt */
#define TPNOREPLY 0x00000004 /* no reply expected */
#define TPNOTRAN 0x00000008 /* not sent in transaction mode */
#define TPTRAN 0x00000010 /* sent in transaction mode */
#define TPNOTIME 0x00000020 /* no timeout */
#define TPABSOLUTE 0x00000040 /* absolute value on tmsetprio */
#define TPGETANY 0x00000080 /* get any valid reply */
#define TPNOCHANGE 0x00000100 /* force incoming buffer to match */
#define RESERVED_BIT1 0x00000200 /* reserved for future use */
#define TPCONV 0x00000400 /* conversational service */
#define TPSENDONLY 0x00000800 /* send-only mode */
#define TPRECVONLY 0x00001000 /* recv-only mode */
#define TPACK 0x00002000 /* */
/* Flags to tpreturn - also defined in xa.h */
#define TPFAIL 0x20000000 /* service FAILURE for tpreturn */
#define TPEXIT 0x08000000 /* service FAILURE with server exit */
#define TPSUCCESS 0x04000000 /* service SUCCESS for tpreturn */
/* Flags to tpscmt - Valid TP_COMMIT_CONTROL
* characteristic values
*/
#define TP_CMT_LOGGED 0x01 /* return after commit
* decision is logged */
#define TP_CMT_COMPLETE 0x02 /* return after commit has
* completed */
/* client identifier structure */
struct clientid_t {
long clientdata[4]; /* reserved for internal use */
}
typedef struct clientid_t CLIENTID;
/* context identifier structure */
typedef long TPCONTEXT_T;
/* interface to service routines */
struct tpsvcinfo {
name[32];
long flags; /* describes service attributes */
char *data; /* pointer to data */
long len; /* request data length */
int cd; /* connection descriptor
* if (flags TPCONV) true */
long appkey; /* application authentication client
* key */
CLIENTID cltid; /* client identifier for originating
* client */
};
typedef struct tpsvcinfo TPSVCINFO;
/* tpinit(3c) interface structure */
#define MAXTIDENT 30
struct tpinfo_t {
char usrname[MAXTIDENT+2]; /* client user name */
char cltname[MAXTIDENT+2]; /* app client name */
char passwd[MAXTIDENT+2]; /* application password */
long flags; /* initialization flags */
long datalen; /* length of app specific data */
long data; /* placeholder for app data */
};
typedef struct tpinfo_t TPINIT;
/* The transactionID structure passed to tpsuspend(3c) and tpresume(3c) */
struct tp_tranid_t {
long info[6]; /* Internally defined */
};
typedef struct tp_tranid_t TPTRANID;
/* Flags for TPINIT */
#define TPU_MASK 0x00000007 /* unsolicited notification
* mask */
#define TPU_SIG 0x00000001 /* signal based
* notification */
#define TPU_DIP 0x00000002 /* dip-in based
* notification */
#define TPU_IGN 0x00000004 /* ignore unsolicited
* messages */
#define TPU_THREAD 0x00000040 /* THREAD notification */
#define TPSA_FASTPATH 0x00000008 /* System access ==
* fastpath */
#define TPSA_PROTECTED 0x00000010 /* System access ==
* protected */
#define TPMULTICONTEXTS 0x00000020 /* multiple context associa-
* tions per process */
/* /Q tpqctl_t data structure */
#define TMQNAMELEN 15
#define TMMSGIDLEN 32
#define TMCORRIDLEN 32
struct tpqctl_t { /* control parameters to queue primitives */
long flags; /* indicates which values are set */
long deq_time; /* absolute/relative time for dequeuing */
long priority; /* enqueue priority */
long diagnostic; /* indicates reason for failure */
char msgid[TMMSGIDLEN]; /* ID of message before which to queue */
char corrid[TMCORRIDLEN]; /* correlation ID used to identify message */
char replyqueue[TMQNAMELEN+1]; /* queue name for reply message */
char failurequeue[TMQNAMELEN+1]; /* queue name for failure message */
CLIENTID cltid; /* client identifier for */
/* originating client */
long urcode; /* application user-return code */
long appkey; /* application authentication client key */
long delivery_qos; /* delivery quality of service */
long reply_qos; /* reply message quality of service */
long exp_time /* expiration time */
};
typedef struct tpqctl_t TPQCTL;
/* /Q structure elements that are valid - set in flags */
#ifndef TPNOFLAGS
#define TPNOFLAGS 0x00000 /* no flags set -- no get */
#endif
#define TPQCORRID 0x00001 /* set/get correlation ID */
#define TPQFAILUREQ 0x00002 /* set/get failure queue */
#define TPQBEFOREMSGID 0x00004 /* enqueue before message ID */
#define TPQGETBYMSGIDOLD 0x00008 /* deprecated */
#define TPQMSGID 0x00010 /* get msgid of enq/deq message */
#define TPQPRIORITY 0x00020 /* set/get message priority */
#define TPQTOP 0x00040 /* enqueue at queue top */
#define TPQWAIT 0x00080 /* wait for dequeuing */
#define TPQREPLYQ 0x00100 /* set/get reply queue */
#define TPQTIME_ABS 0x00200 /* set absolute time */
#define TPQTIME_REL 0x00400 /* set relative time */
#define TPQGETBYCORRIDOLD 0x00800 /* deprecated */
#define TPQPEEK 0x01000 /* non-destructive dequeue */
#define TPQDELIVERYQOS 0x02000 /* delivery quality of service */
#define TPQREPLYQOS 0x04000 /* reply msg quality of service*/
#define TPQEXPTIME_ABS 0x08000 /* absolute expiration time */
#define TPQEXPTIME_REL 0x10000 /* relative expiration time */
#define TPQEXPTIME_NONE 0x20000 /* never expire */
#define TPQGETBYMSGID 0x40008 /* dequeue by msgid */
#define TPQGETBYCORRID 0x80800 /* dequeue by corrid */
/* Valid flags for the quality of service fields in the TPQCTL structure */
#define TPQQOSDEFAULTPERSIST 0x00001 /* queue's default persistence */
/* policy */
#define TPQQOSPERSISTENT 0x00002 /* disk message */
#define TPQQOSNONPERSISTENT 0x00004 /* memory message */
/* error return codes */
extern int tperrno;
extern long tpurcode;
/* tperrno values - error codes */
* The reference pages explain the context in which the following
* error codes can return.
*/
#define TPMINVAL 0 /* minimum error message */
#define TPEABORT 1
#define TPEBADDESC 2
#define TPEBLOCK 3
#define TPEINVAL 4
#define TPELIMIT 5
#define TPENOENT 6
#define TPEOS 7
#define TPEPERM 8
#define TPEPROTO 9
#define TPESVCERR 10
#define TPESVCFAIL 11
#define TPESYSTEM 12
#define TPETIME 13
#define TPETRAN 14
#define TPGOTSIG 15
#define TPERMERR 16
#define TPEITYPE 17
#define TPEOTYPE 18
#define TPERELEASE 19
#define TPEHAZARD 20
#define TPEHEURISTIC 21
#define TPEEVENT 22
#define TPEMATCH 23
#define TPEDIAGNOSTIC 24
#define TPEMIB 25
#define TPMAXVAL 26 /* maximum error message */
/* conversations - events */
#define TPEV_DISCONIMM 0x0001
#define TPEV_SVCERR 0x0002
#define TPEV_SVCFAIL 0x0004
#define TPEV_SVCSUCC 0x0008
#define TPEV_SENDONLY 0x0020
/* /Q diagnostic codes */
#define QMEINVAL -1
#define QMEBADRMID -2
#define QMENOTOPEN -3
#define QMETRAN -4
#define QMEBADMSGID -5
#define QMESYSTEM -6
#define QMEOS -7
#define QMEABORTED -8
#define QMENOTA QMEABORTED
#define QMEPROTO -9
#define QMEBADQUEUE -10
#define QMENOMSG -11
#define QMEINUSE -12
#define QMENOSPACE -13
#define QMERELEASE -14
#define QMEINVHANDLE -15
#define QMESHARE -16
/* EventBroker Messages */
#define TPEVSERVICE 0x00000001
#define TPEVQUEUE 0x00000002
#define TPEVTRAN 0x00000004
#define TPEVPERSIST 0x00000008
/* Subscription Control Structure */
struct tpevctl_t {
long flags;
char name1[XATMI_SERVICE_NAME_LENGTH];
char name2[XATMI_SERVICE_NAME_LENGTH];
TPQCTL qctl;
};
typedef struct tpevctl_t TPEVCTL;
C Language TX Return Codes and Other Definitions
The following return code and flag definitions are used by the TX routines. For an application to work with different transaction monitors without change or recompilation, each system must define its flags and return codes as follows:
#define TX_H_VERSION 0 /* current version of this
* header file */
/*
* Transaction identifier
*/
#define XIDDATASIZE 128 /* size in bytes */
struct xid_t {
long formatID; /* format identifier */
long gtrid_length; /* value not to exceed 64 */
long bqual_length; /* value not to exceed 64 */
char data[XIDDATASIZE];
};
typedef struct xid_t XID;
/*
* A value of -1 in formatID means that the XID is null.
*/
/*
* Definitions for tx_ routines
*/
/* commit return values */
typedef long COMMIT_RETURN;
#define TX_COMMIT_COMPLETED 0
#define TX_COMMIT_DECISION_LOGGED 1
/* transaction control values */
typedef long TRANSACTION_CONTROL;
#define TX_UNCHAINED 0
#define TX_CHAINED 1
/* type of transaction timeouts */
typedef long TRANSACTION_TIMEOUT;
/* transaction state values */
typedef long TRANSACTION_STATE;
#define TX_ACTIVE 0
#define TX_TIMEOUT_ROLLBACK_ONLY 1
#define TX_ROLLBACK_ONLY 2
/* structure populated by tx_info */
struct tx_info_t {
XID xid;
COMMIT_RETURN when_return;
TRANSACTION_CONTROL transaction_control;
TRANSACTION_TIMEOUT transaction_timeout;
TRANSACTION_STATE transaction_state;
};
typedef struct tx_info_t TXINFO;
/*
* tx_ return codes
* (transaction manager reports to application)
*/
#define TX_NOT_SUPPORTED 1 /* option not supported */
#define TX_OK 0 /* normal execution */
#define TX_OUTSIDE -1 /* application is in an RM
* local transaction */
#define TX_ROLLBACK -2 /* transaction was rolled
* back */
#define TX_MIXED -3 /* transaction was
* partially committed and
* partially rolled back */
#define TX_HAZARD -4 /* transaction may have been
* partially committed and
* partially rolled back */
#define TX_PROTOCOL_ERROR -5 /* routine invoked in an
* improper context */
#define TX_ERROR -6 /* transient error */
#define TX_FAIL -7 /* fatal error */
#define TX_EINVAL -8 /* invalid arguments were given */
#define TX_COMMITTED -9 /* transaction has
* heuristically committed */
#define TX_NO_BEGIN -100 /* transaction committed plus
* new transaction could not
* be started */
#define TX_ROLLBACK_NO_BEGIN (TX_ROLLBACK+TX_NO_BEGIN)
/* transaction rollback plus
* new transaction could not
* be started */
#define TX_MIXED_NO_BEGIN (TX_MIXED+TX_NO_BEGIN)
/* mixed plus new transaction
* could not be started */
#define TX_HAZARD_NO_BEGIN (TX_HAZARD+TX_NO_BEGIN)
/* hazard plus new transaction
* could not be started */
#define TX_COMMITTED_NO_BEGIN (TX_COMMITTED+TX_NO_BEGIN)
/* heuristically committed plus
* new transaction could not
* be started */
ATMI State Transitions
The BEA Tuxedo ATMI system keeps track of the state for each process and verifies that legal state transitions occur for the various function calls and options. The state information includes the process 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 process, and the state of all asynchronous request and connection descriptors. When an illegal state transition is attempted, the called function fails, setting tperrno to TPEPROTO. The legal states and transitions for this information are described in the following tables.
Table 4 indicates which functions may be called by request/response servers, conversational servers, and clients. Note that tpsvrinit(), tpsvrdone(), tpsvrthrinit(), and tpsvrthrdone() 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 ATMI system).
Function Process Type Request/Response Server Conversational Server Client tpabort Y Y Y tpacall Y Y Y tpadvertise Y Y N tpalloc Y Y Y 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 tpdequeue Y Y Y tpdiscon Y Y Y tpenqueue Y Y Y tpforward Y N N tpfree Y Y Y tpgetctxt Y Y Y tpgetlev Y Y Y tpgetrply Y Y Y tpgprio Y Y Y tpinit N N Y tpnotify Y Y Y tpopen Y Y Y tppost Y Y Y tprealloc Y Y Y tprecv Y Y Y tpresume Y Y Y tpreturn Y Y N tpscmt Y Y Y tpsend Y Y Y tpservice Y Y N tpsetctxt Y (in application- Y (in application- Y tpsetunsol N N Y tpsprio Y Y Y tpsubscribe Y Y Y tpsuspend Y Y Y tpterm N N Y tptypes Y Y 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, tpinit()), certain state transitions shown below may not be possible for both process types. The above table should be consulted to determine whether the process in question is allowed to call a particular function. The following state table indicates whether or not a thread in a client process has been initialized and registered with the transaction manager. Note that this table assumes the use of tpinit(), 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, tpconnect() or tpcall()). A client must use tpinit() when one of the following is true:
created threads)
created threads)
A server is placed in the initialized state by the BEA Tuxedo ATMI system's main() before its tpsvrinit() function is invoked, and it is placed in the uninitialized state by the BEA Tuxedo ATMI system's main() after its tpsvrdone() function has returned. Note that in all of the state tables shown below, an error return from a function causes the thread to remain in the same state, unless otherwise noted.
The remaining state tables assume a precondition of state I1 (regardless of whether a process arrived in this state via tpinit(), tpsetctxt(), or the BEA Tuxedo ATMI system's main()). Table 6 indicates the state of a client or server with respect to whether or not a resource manager associated with the process has been initialized.
Table 7 indicates the state of a process with respect to whether or not the process is associated with a transaction. For servers, transitions to states T1and T2 assume a precondition of state R1 (for example, tpopen() has been called with no subsequent call to tpclose() or tpterm()).
Table 8 indicates the state of a single request descriptor 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.
Table 9 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:
Note: a If process 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
The BEA Tuxedo ATMI system 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 Table 10. Calls that return failure do not make state transitions, unless they are described by specific state table entries. Any BEA Tuxedo ATMI system client or server is allowed to use the TX functions.
The states are defined below:
See Also
buffer(3c), tpadvertise(3c), tpalloc(3c), tpbegin(3c), tpcall(3c), tpconnect(3c), tpgetctxt(3c), tpinit(3c), tpopen(3c), tpservice(3c), tpsetctxt(3c), tuxtypes(5), typesw(5)
|
|
|
|
||
 |
|
|
 |
 |
 |
|
||
