Table of Contents Previous Next PDF


Section 3c - C Functions

Section 3c - C Functions
 
Converts a tm structure to a calendar time
Routine for retrieving service and parameter information from a Tuxedo repository file.
Routine for setting when tpcommit() should return
Gets the value for environment variable TPMBACONV in the process environment
Sets the value for environment variable TPMBACONV in the process environment
Sets commit_return characteristic
Sets transaction_control characteristic
Sets transaction_timeout characteristic
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 Oracle 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.
Oracle 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 an Oracle 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 Oracle 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 Oracle 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.
Oracle 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 Oracle 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 Oracle 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 Oracle 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 Oracle Tuxedo ATMI system supports two sets of mutually exclusive functions for defining and managing transactions: the Oracle 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 Oracle 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 Oracle 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 Oracle 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 Oracle 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 Oracle 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 Oracle 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 an Oracle 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 Oracle 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 an Oracle 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 Oracle 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 Oracle 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 Oracle 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 Oracle 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 Oracle Tuxedo ATMI system provides five basic buffer types:
CARRAY—a character array, possibly containing NULL characters, which is neither encoded nor decoded during transmission
STRING—a NULL-terminated character array
FML—fielded buffers (FML or FML32)
XML—XML document or datagram buffer
VIEW—simple C structures (VIEW or VIEW32); all views are handled by the same set of routines. The name of a particular view is its subtype name.
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 Oracle 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.
 
S0
S1
S2
tpinit without TPMULTICONTEXTS
S1
S1
S2(error)
tpinit with TPMULTICONTEXTS
S2
S1 (error)
S2
Implicit tpinit
S1
S1
S2 (error)
tpterm—not last association
S2
tpterm—last association
S0
S0
tpterm—no association
S0
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.
 
tpinit without TPMULTICONTEXTS
tpinit with TPMULTICONTEXTS
tpsetctxt to TPNULLCONTEXT
tpsetctxt to context 0
tpsetctxt to context > 0
Implicit tpinit
tpterm in this thread
tpterm in a different thread of this context
Support for Threads Programming
The Oracle 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 Oracle 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 an Oracle 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 Oracle 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 Oracle 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 Oracle Tuxedo ATMI system allows a thread operating in the TPINVALIDCONTEXT state to call the following functions:
The Oracle 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[128];
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 127
#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 Oracle 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 Oracle Tuxedo ATMI system).
 
Y (in application-
created threads
)
Y (in application-
created threads
)
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:
Application authentication is required. (See tpinit(3c) and the description of the SECURITY keyword in UBBCONFIG(5) for details.)
A server is placed in the initialized state by the Oracle Tuxedo ATMI system’s main() before its tpsvrinit() function is invoked, and it is placed in the uninitialized state by the Oracle 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.
 
I0
I1
I0
I1
I0
I1
I0
I1
I1
I1
I0
I1
tpsetctxt
(set to a non-NULL context)
I1
I1
tpsetctxt
(with the TPNULLCONTEXT context set)
I0
I0
I0
I1
tpterm
(in this thread)
I0
I0
tpterm
(in a different thread of this context)
I0
I0
I0
I1
I1
I1
The remaining state tables assume a precondition of state I1 (regardless of whether a process arrived in this state via tpinit(), tpsetctxt(), or the Oracle 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.
 
R1
R1
R0
R0
R1
R1
R1
R1
R1
tpservice with flag TPTRAN
R1
R0
R1
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()).
 
T0
T0
T0
T1
T0
tpservice with flag TPTRAN
T2
tpservice (not in transaction mode)
T0
T0
T0
T0
T0
R0
I0
T0
T0
T1
T2
Table 8 indicates the state of a single request descriptor returned by tpacall().
 
A1
A0
A0 a
A0
A0 b
A0
A0 b
A0
A1 c
A0
A0
A0
A0
I0
I0
A0
A1
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:
C0—No descriptor
C1tpconnect() descriptor send-only
C2tpconnect() descriptor receive-only
C3TPSVCINFO descriptor send-only
C4TPSVCINFO descriptor receive-only
 
C0
C1
C2
C3
C4
tpconnect with TPSENDONLY
C1 a
tpconnect with TPRECVONLY
C2 a
tpservice with flag TPSENDONLY
C3 b
tpservice with flag TPRECVONLY
C4 b
tprecv/no event
C2
C4
tprecv/TPEV_SENDONLY
C1
C3
tprecv/TPEV_DISCONIMM
C0
C0
tprecv/TPEV_SVCERR
C0
tprecv/TPEV_SVCFAIL
C0
tprecv/TPEV_SVCSUCC
C0
tpsend/no event
C1
C3
tpsend with flag TPRECVONLY
C2
C4
tpsend/TPEV_DISCONIMM
C0
C0
tpsend/TPEV_SVCERR
C0
tpsend/TPEV_SVCFAIL
C0
tpterm (client only)
C0
C0
tpcommit (originator only)
C0
C0 c
C0c
tpsuspend (originator only)
C0
C1 d
C2 d
tpabort (originator only)
C0
C0 c
C0 c
C0
C0
tpreturn (CONV server)
C0
C0
C0
C0
tpforward (CONV server)
C0
C0
C0
C0
C0
C1
C2
C3
C4
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 Oracle 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 Oracle Tuxedo ATMI system client or server is allowed to use the TX functions.
The states are defined below:
S0: No RMs have been opened or initialized. An application association cannot start a global transaction until it has successfully called tx_open.
S1: An application association has opened its RM but is not in a transaction. Its transaction_control characteristic is TX_UNCHAINED.
S2: An application association has opened its RM but is not in a transaction. Its transaction_control characteristic is TX_CHAINED.
S3: An application association has opened its RM and is in a transaction. Its transaction_control characteristic is TX_UNCHAINED.
S4: An application association has opened its RM and is in a transaction. Its transaction_control characteristic is TX_CHAINED.
 
S0
S1
S2
S3
S4
S3
S4
S0
S0
S0
tx_commit −> TX_SET1
S1
S4
tx_commit −> TX_SET2
S2
S1
S2
S3
S4
S1
S1
S2
S3
S4
tx_rollback −> TX_SET1
S1
S4
tx_rollback −> TX_SET2
S2
S1
S2
S3
S4
S2
S2
S4
S4
S1
S1
S3
S3
S1
S2
S3
S4
TX_SET1 denotes any of the following: TX_OK, TX_ROLLBACK, TX_MIXED, TX_HAZARD, or TX_COMMITTED. TX_ROLLBACK is not returned by tx_rollback() and TX_COMMITTED is not returned by tx_commit().
TX_SET2 denotes any of the following: TX_NO_BEGIN, TX_ROLLBACK_NO_BEGIN, TX_MIXED_NO_BEGIN, TX_HAZARD_NO_BEGIN, or TX_COMMITTED_NO_BEGIN. TX_ROLLBACK_NO_BEGIN is not returned by tx_rollback() and TX_COMMITTED_NO_BEGIN is not returned by tx_commit().
If TX_FAIL is returned on any call, the application process is in an undefined state with respect to the above table.
When tx_info() returns either TX_ROLLBACK_ONLY or TX_TIMEOUT_ROLLBACK_ONLY in the transaction state information, the transaction is marked rollback-only and will be rolled back whether the application program calls tx_commit() or tx_rollback().
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)
AEMsetblockinghook(3c)
Name
AEMsetblockinghook()—Establishes an application-specific blocking hook function.
Synopsis
#include <atmi.h>
int AEMsetblockinghook(_TM_FARPROC)
Description
AEMsetblockinghook() is an “ATMI Extension for Mac” that allows a Mac task to install a new function which the ATMI networking software uses to implement blocking ATMI calls. It takes a pointer to the procedure instance address of the blocking function to be installed.
A default function, by which blocking ATMI calls are handled, is included. The function AEMsetblockinghook() gives the application the ability to execute its own function at “blocking” time in place of the default function. If called with a NULL pointer, the blocking hook function is reset to the default function.
When an application invokes a blocking ATMI operation, the operation is initiated and then a loop is entered which is equivalent to the following pseudocode:
for(;;) {
execute operation in non-blocking mode
if error
break;
if operation complete
break;
while(BlockingHook())
;
}
Return Values
AEMsetblockinghook() returns a pointer to the procedure-instance of the previously installed blocking function. The application or library that calls the AEMsetblockinghook() function should save this return value so that it can be restored if necessary. (If “nesting” is not important, the application may simply discard the value returned by AEMsetblockinghook() and eventually use AEMsetblockinghook(NULL) to restore the default mechanism.) AEMsetblockinghook() returns NULL on error and sets tperrno to indicate the error condition.
Errors
Under failure, AEMsetblockinghook() sets tperrno to the following value:
[TPEPROTO]
AEMsetblockinghook() was called while a blocking operation was in progress.
Portability
This interface is supported only in Mac clients.
Notices
The blocking function is reset after tpterm(3c) is called by the application.
AEOaddtypesw(3c)
Name
AEOaddtypesw()—Installs or replaces a user-defined buffer type at execution time.
Synopsis
#include <atmi.h>
#include <tmtypes.h>

int FAR PASCAL AEOaddtypesw(TMTYPESW *newtype)
Description
AEOaddtypesw() is an “ATMI Extension for OS/2” that allows an OS/2 client to install a new, or replace an existing, user-defined buffer type at execution time. The argument to this function is a pointer to a TMTYPESW structure that contains the information for the buffer type to be installed.
If the type() and the subtype() match an existing buffer type already installed, then all the information is replaced with the new buffer type. If the information does not match the type() and the subtype() fields, then the new buffer type is added to the existing types registered with the Oracle Tuxedo ATMI system. For new buffer types, make sure that the WSH and other Oracle Tuxedo ATMI system processes involved in the call processing have been built with the new buffer type.
The function pointers in the TMTYPESW array should appear in the Module Definition file of the application in the EXPORTS section.
The application can also use the Oracle Tuxedo ATMI system’s defined buffer type routines. The application and the Oracle Tuxedo ATMI system’s buffer routines can be intermixed in one user defined buffer type.
Return Values
Upon success, AEOaddtypesw() returns the number of user buffer types in the system Upon failure, AEOaddtypesw() returns -1 and sets tperrno to indicate the error condition.
Errors
Upon failure, AEOaddtypesw() sets tperrno to one of the following values:
[TPEINVAL]
AEOaddtypesw() was called and the type parameter was NULL.
[TPESYSTEM]
An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
Portability
This interface is supported only in Windows clients. The preferred way to install a type switch is to add it to the Oracle Tuxedo ATMI system type switch DLL. Please refer to Setting Up an Oracle Tuxedo Application for more information.
Notices
FAR PASCAL is used only for the 16-bit OS/2 environment.
Examples
#include <os2.h>
#include <atmi.h>
#include <tmtypes.h>

int FAR PASCAL Nfinit(char FAR *, long);
int (FAR PASCAL * lpFinit)(char FAR *, long);
int FAR PASCAL Nfreinit(char FAR *, long);
int (FAR PASCAL * lpFreinit)(char FAR *, long);
int FAR PASCAL Nfuninit(char FAR *, long);
int (FAR PASCAL * lpFuninit)(char FAR *, long);

TMTYPESW newtype =
{
“MYFML”, ““, 1024, NULL, NULL,
NULL, _fpresend, _fpostsend, _fpostrecv, _fencdec,
_froute
};

newtype.initbuf = Nfinit;
newtype.reinitbuf = Nfreinit;
newtype.uninitbuf = Nfuninit;

if(AEOaddtypesw(newtype) == -1) {
userlog(“AEOaddtypesw failed %s”, tpstrerror(tperrno));
}
int
FAR PASCAL
Nfinit(char FAR *ptr, long len)
{
......
return(1);
}

int
FAR PASCAL
Nfreinit(char FAR *ptr, long len)
{
......
return(1);
}

int
FAR PASCAL
Nfuninit(char FAR *ptr, long mdlen)
{
......
return(1);
}
The application Module Definition File:
; EXAMPLE.DEF file

NAME EXAMPLE

DESCRIPTION 'EXAMPLE for OS/2'

EXETYPE OS/2


EXPORTS
Nfinit
Nfreinit
Nfuninit
....
See Also
buildwsh(1), buffer(3c), typesw(5)
AEPisblocked(3c)
Name
AEPisblocked()—Determines if a blocking call is in progress.
Synopsis
#include <atmi.h>
int far pascal AEPisblocked(void)
Description
AEPisblocked() is an “ATMI Extension for OS/2 Presentation Manager” that allows a OS/2 PM task to determine if it is executing while waiting for a previous blocking call to complete.
Return Values
If there is an outstanding blocking function awaiting completion, AEPisblocked() returns 1. Otherwise, it returns 0.
Errors
No errors are returned.
Portability
This interface is supported only in OS/2 PM clients.
Comments
Although a blocking ATMI call appears to an application as though it “blocks,” the OS/2 PM ATMI DLL has to relinquish the processor to allow other applications to run. This means that it is possible for the application which issued the blocking call to be reentered, depending on the message(s) it receives. In this instance, the AEPisblocked() function can be used to ascertain whether the task has been reentered while waiting for an outstanding blocking call to complete. Note that ATMI prohibits more than one outstanding call per thread.
See Also
AEMsetblockinghook(3c)
AEWsetunsol(3c)
Name
AEWsetunsol()—Posts a Windows message for Oracle Tuxedo ATMI unsolicited event.
Synopsis
#include <windows.h>
#include <atmi.h>
int far pascal AEWsetunsol(HWND hWnd, WORD wMsg)
Description
In certain Microsoft Windows programming environments, it is natural and convenient for the Oracle Tuxedo ATMI system’s unsolicited messages to be posted to the Windows event message queue.
AEWsetunsol() controls which window to notify, hWnd, and which Windows message type to post, wMsg. When an Oracle Tuxedo ATMI unsolicited message arrives, a Windows message is posted. lParam() is set to the Oracle Tuxedo ATMI system buffer pointer, or zero if none. If lParam() is non-zero, the application must call tpfree() to release the buffer.
If wMsg is zero, any future unsolicited messages will be logged and ignored.
In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to AEWsetunsol().
Return Values
Upon failure, AEWsetunsol() returns -1 and sets tperrno to indicate the error condition.
Errors
Upon failure, AEWsetunsol() sets tperrno to one of the following values:
[TPESYSTEM]
An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
[TPEOS]
An operating system error has occurred.
Portability
This interface is supported only in Microsoft Windows clients.
Notices
AEWsetunsol() posting of Windows messages may not be activated simultaneously with a tpsetunsol() callback routine. The most recent tpsetunsol() or AEWsetunsol() request controls how unsolicited messages will be handled.
See Also
tpsetunsol(3c)
buffer(3c)
Name
buffer()—Semantics of elements in tmtype_sw_t.
Synopsis
int /* Initialize a new data buffer */
_tminitbuf(char *ptr, long len)
int /* Reinitialize a reallocated data buffer */
_tmreinitbuf(char *ptr, long len)
int /* Uninitialize a data buffer to be freed */
_tmuninitbuf(char *ptr, long len)
long /* Process buffer before sending */
_tmpresend(char *ptr, long dlen, long mdlen)
void /* Process buffer after sending */
_tmpostsend(char *ptr, long dlen, long mdlen)
long /* Process buffer after receiving */
_tmpostrecv(char *ptr, long dlen, long mdlen)
long /* Encode/decode a buffer to/from a transmission format */
_tmencdec(int op, char *encobj, long elen, char *obj, long olen)
int /* Determine server group for routing based on data */
_tmroute(char *routing_name, char *service, char *data, long \ len, char *group)
int /* Evaluate boolean expression on buffer’s data */
_tmfilter(char *ptr, long dlen, char *expr, long exprlen)
int /* Extract buffer’s data based on format string */
_tmformat(char *ptr, long dlen, char *fmt, char *result, long \ maxresult)
long /* Process buffer before sending, possibly generating copy */
_tmpresend2(char *iptr, long ilen, long mdlen, char *optr, long olen, long *flags )
long /* Multibyte code-set encoding conversion */
_tmconvmb(char *ibufp, long ilen, char *enc_name, char *obufp, long olen, long
    *flags)
Description
This page describes the semantics of the elements and routines defined in the tmtype_sw_t structure. These descriptions are necessary for adding new buffer types to a process buffer type switch, tm_typesw. 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 Oracle Tuxedo ATMI system as well as by applications adding their own buffer types. The names map to the switch elements very simply: the template names are made by taking each function pointer’s element name and prepending _tm (for example, the element initbuf has the function name _tminitbuf()).
The element type must be non-NULL and up to 8 characters in length. The element subtype can be NULL, a string of up to 16 characters, or the wildcard character, “*”. If type is not unique in the switch, then subtype must be used; 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 function tptypes() 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 which 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.
dfltsize() is used when allocating or reallocating a buffer. The larger of dfltsize() and the routines’ size parameter is used to create or reallocate a buffer. For some types of structures, like 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 its size parameter is also less than or equal to 0, then the routine will fail. It is not recommended to set dfltsize() to a value less than 0.
Routine Specifics
The names of the functions specified below are template names used within the Oracle Tuxedo ATMI system. Any application adding new routines to the buffer type switch must use names that correspond to real functions, either provided by the application or library routines. If a NULL function pointer is stored in a buffer type switch entry, the Oracle Tuxedo ATMI system calls a default function that takes the correct number and type of arguments, and returns a default value.
_tminitbuf
_tminitbuf() is called from within tpalloc() after a buffer has been allocated. It is passed a pointer to the new buffer, ptr, along with its size so that the buffer can be initialized appropriately. len is the larger of the length passed into tpalloc() and the default specified in dfltsize() in that type’s switch entry. Note that ptr will never be NULL due to the semantics of tpalloc() and tprealloc(). Upon successful return, ptr is returned to the caller of tpalloc().
If a single switch entry is used to manipulate many subtypes, then the writer of _tminitbuf() can use tptypes() to determine the subtype.
If no buffer initialization needs to be performed, specify a NULL function pointer.
Upon success, _tminitbuf() returns 1. If the function fails, it returns -1 causing tpalloc() to also return failure setting tperrno to TPESYSTEM.
_tmreinitbuf
_tmreinitbuf() behaves the same as _tminitbuf() except it is used to reinitialize a reallocated buffer. It is called from within tprealloc() after the buffer has been reallocated.
If no buffer reinitialization needs to be performed, specify a NULL function pointer.
Upon success, _tmreinitbuf() returns 1. If the function fails, it returns -1 causing tprealloc() to also return failure setting tperrno to TPESYSTEM.
_tmuninitbuf
_tmuninitbuf() is called by tpfree() before the data buffer is freed. _tmuninitbuf() is passed a pointer to the application portion of a data buffer, along with its size, and can be used to clean up any structures or state information associated with that buffer. ptr will never be NULL due to tpfree()’s semantics. Note that _tmuninitbuf() should not free the buffer itself. The tpfree() function is called automatically for any FLD_PTR fields in the data buffer.
If no processing needs to be performed before freeing a buffer, specify a NULL function pointer.
Upon success, _tmuninitbuf() returns 1. If the function fails, it returns -1 causing tpfree() to print a log message.
_tmpresend
_tmpresend() is called before a buffer is sent in tpcall(), tpacall(), tpconnect(), tpsend(), tpbroadcast(), tpnotify(), tpreturn(), or tpforward(). It is also called after _tmroute() but before _tmencdec(). If ptr() is non-NULL, preprocessing is performed on a buffer before it is sent. _tmpresend()’s first argument, ptr, is the application data buffer passed into the send call. Its second argument, dlen, is the data’s length as passed into the send call. Its third argument, mdlen, is the actual size of the buffer in which the data resides.
One important requirement on this function is that it ensures that when the function returns, the data pointed to by ptr can be sent “as is.” That is, since _tmencdec() is called only if the buffer is being sent to a dissimilar machine, _tmpresend() must ensure upon return that no element in ptr’s buffer is a pointer to data that is not contiguous to the buffer.
If no preprocessing needs to be performed on the data and the amount of data the caller specified is the same as the amount that should be sent, specify a NULL function pointer. The default routine returns dlen and does nothing to the buffer.
If _tmpresend2() is not NULL, _tmpresend() is not called and _tmpresend2() is called in its place.
Upon success, _tmpresend() returns the amount of data to be sent. If the function fails, it returns -1 causing _tmpresend()’s caller to also return failure setting tperrno to TPESYSTEM.
_tmpostsend
_tmpostsend() is called after a buffer is sent in tpcall(), tpbroadcast(), tpnotify(), tpacall(), tpconnect(), or tpsend(). This routine allows any post-processing to be performed on a buffer after it is sent and before the function returns. Because the buffer passed into the send call should not be different upon return, _tmpostsend() is called to repair a buffer changed by _tmpresend(). This function’s first argument, ptr, points to the data sent as a result of _tmpresend(). The data’s length, as returned from _tmpresend(), is passed in as this function’s second argument, dlen. The third argument, mdlen, is the actual size of the buffer in which the data resides. This routine is called only when ptr is non-NULL.
If no post-processing needs to be performed, specify a NULL function pointer.
_tmpostrecv
_tmpostrecv() is called after a buffer is received, and possibly decoded, in tpgetrply(), tpcall(), tprecv(), or in the Oracle Tuxedo ATMI system’s server abstraction, and before it is returned to the application. If ptr is non-NULL, _tmpostrecv() allows post-processing to be performed on a buffer after it is received and before it is given to the application. Its first argument, ptr, points to the data portion of the buffer received. Its second argument, dlen, specifies the data’s size coming in to _tmpostrecv(). The third argument, mdlen, specifies the actual size of the buffer in which the data resides.
If _tmpostrecv() changes the data length in post-processing, it must return the data’s new length. The length returned is passed up to the application in a manner dependent on the call used (for example, tpcall() sets the data length in one of its arguments for the caller to check upon return).
The buffer’s size might not be large enough for post-processing to succeed. If more space is required, _tmpostrecv() returns the negative absolute value of the desired buffer size. The calling routine then resizes the buffer, and calls _tmpostrecv() a second time.
If no post-processing needs to be performed on the data and the amount of data received is the same as the amount that should be returned to the application, specify a NULL function pointer. The default routine returns dlen and does nothing to the buffer.
On success, _tmpostrecv() returns the size of the data the application should be made aware of when the buffer is passed up from the corresponding receive call. If the function fails, it returns -1 causing _tmpostrecv()’s caller to return failure, setting tperrno to TPESYSTEM.
_tmencdec
_tmencdec() is used to encode/decode a buffer sent/received over a network to/from a machine having different data representations. The Oracle Tuxedo ATMI system recommends the use of XDR; however, any encoding/decoding scheme can be used that obeys the semantics of this routine.
This function is called by tpcall(), tpacall(), tpbroadcast(), tpnotify(), tpconnect(), tpsend(), tpreturn(), or tpforward() to encode the caller’s buffer only when it is being sent to an “unlike” machine. In these calls, _tmencdec() is called after both _tmroute() and _tmpresend(), respectively. Recall from the description of _tmpresend() that the buffer passed into _tmencdec() contains no pointers to data that is not contiguous to the buffer.
On the receiving end, tprecv(), tpgetrply(), the receive half of tpcall() and the server abstraction all call _tmencdec() to decode a buffer after they have received it from an “unlike” machine but before calling _tmpostrecv().
_tmencdec()’s first argument, op, specifies whether the function is encoding or decoding data. op can be one of TMENCODE or TMDECODE.
When op is TMENCODE, encobj points to a buffer allocated by the Oracle Tuxedo ATMI system where the encoded version of the data will be copied. The unencoded data resides in obj. That is, when op is TMENCODE, _tmencdec() transforms obj to its encoded format and places the result in encobj. The size of the buffer pointed to by encobj is specified by elen and is at least four times the size of the buffer pointed to by obj whose length is olen. olen is the length returned by _tmpresend. _tmencdec() returns the size of the encoded data in encobj (that is, the amount of data to actually send). _tmencdec() should not free either of the buffers passed into the function.
When op is TMDECODE, encobj points to a buffer allocated by the Oracle Tuxedo ATMI system where the encoded version of the data resides as read off a communication endpoint. The length of the buffer is elen. obj points to a buffer that is at least the same size as the buffer pointed to by encobj into which the decoded data is copied. The length of obj is olen. As obj is the buffer ultimately returned to the application, this buffer may be grown by the Oracle Tuxedo ATMI system before calling _tmencdec() to ensure that it is large enough to hold the decoded data. _tmencdec() returns the size of the decoded data in obj. After _tmencdec() returns, _tmpostrecv() is called with obj passed as its first argument, _tmencdec()’s return value as its second, and olen as its third. _tmencdec() should not free either of the buffers passed into the function.
_tmencdec() is called only when non-NULL data needs to be encoded or decoded.
If no encoding or decoding needs to be performed on the data even when dissimilar machines exist in the network, specify a NULL function pointer. The default routine returns either olen (op equals TMENCODE) or elen (op equals TMDECODE).
On success, _tmencdec() returns a non-negative length as described above. If the function fails, it returns -1 causing _tmencdec()’s caller to return failure, setting tperrno to TPESYSTEM.
_tmroute
The default for message routing is to route a message to any available server group that offers the desired service. Each service entry in the UBBCONFIG file can specify the logical name of some routing criteria for the service using the ROUTING parameter. Multiple services can share the same routing criteria. In the case that a service has a routing criteria name specified, _tmroute() is used to determine the server group to which a message is sent based on data in the message. This mapping of data to server group is called “data-dependent routing.” _tmroute() is called before a buffer is sent (and before _tmpresend() and _tmencdec() are called) in tpcall(), tpacall(), tpconnect(), and tpforward().
routing_name is the logical name of the routing criteria (as specified in the UBBCONFIG file) and is associated with every service that needs data dependent routing. service is the name of the service for which the request is being made. The parameter data points to the data that is being transmitted in the request and len is its length. Unlike the other routines described in these pages, _tmroute() is called even when ptr is NULL. The group parameter is used to return the name of the group to which the request should be routed. This group name must match one of the group names listed in the UBBCONFIG file (and one that is active at the time the group is chosen). If the request can go to any available server providing the specified service, group should be set to the NULL string and the function should return 1.
If data dependent routing is not needed for the buffer type, specify a NULL function pointer. The default routine sets group to the NULL string and returns 1.
Upon success, _tmroute() returns 1. If the function fails, it returns -1 causing _tmroute()’s caller to also return failure; as a result, tperrno is set to TPESYSTEM. If _tmroute() fails because a requested server or service is not available, tperrno is set to TPENOENT.
If group is set to the name of an invalid server group, the function calling _tmroute() will return an error and set tperrno to TPESYSTEM.
_tmfilter
_tmfilter() is called by the EventBroker server to analyze the contents of a buffer posted by tppost(). An expression provided by the subscriber (tpsubscribe()) is evaluated with respect to the buffer’s contents. If the expression is true, _tmfilter() returns 1 and the EventBroker performs the subscription’s notification action. Otherwise, if _tmfilter() returns 0, the EventBroker does not consider this posting a “match” for the subscription.
If exprlen is -1, expr is interpreted as a NULL-terminated character string. Otherwise expr is interpreted as exprlen bytes of binary data. An exprlen of 0 indicates no expression.
If filtering does not apply to this buffer type, specify a NULL function pointer. The default routine returns 1 if there is no expression or if expr is an empty NULL-terminated string. Otherwise the default routine returns 0.
_tmformat
_tmformat() is called by the EventBroker server to convert a buffer’s data into a printable string, based on a format specification named fmt. The EventBroker converts posted buffers to strings as input for userlog or system notification actions.
The output is stored as a character string in the memory location pointed to by result. Up to maxresult bytes are written in result, including a terminating NULL character. If result is not large enough, _tmformat() truncates its output. The output string is always NULL terminated.
On success, _tmformat() returns a non-negative integer. 1 means success, 2 means the output string is truncated. If the function fails, it returns -1 and stores an empty string in result.
If formatting does not apply to this buffer type, specify a NULL function pointer. The default routine succeeds and returns an empty string in result.
_tmpresend2
_tmpresend2() is called before a buffer is sent in tpcall(), tpacall(), tpconnect(), tpsend(), tpbroadcast(), tpnotify(), tpreturn(), and tpforward(). It is also called after _tmroute() but before _tmencdec(). If iptr is not NULL, preprocessing is performed on a buffer before the buffer is sent.
The first argument to _tmpresend2(), iptr, is the application data buffer passed into the send call. The second argument, ilen, is the length of the data as passed into the send call. The third argument, mdlen, is the actual size of the buffer in which the data resides.
Unlike _tmpresend(), _tmpresend2() receives a pointer, optr, which is used to pass a pointer to a buffer into which the data in iptr can be placed, after any required processing is done. Use this pointer if you want to use a new buffer for the data modified by _tmpresend2() instead of modifying the input buffer. The fifth argument, olen, is the size of the optr buffer. The sixth argument, flags, tells _tmpresend2() whether the buffer being processed is the parent buffer (the one being sent). The flags argument is returned by _tmpresend2() to indicate the results of processing.
The size of the optr buffer may not be large enough for successful postprocessing. If more space is required, _tmpresend2() returns the negative absolute value of the desired buffer size. All olen bytes of the optr buffer are preserved. The calling routine then resizes the buffer and calls _tmpresend2() a second time.
If no postprocessing needs to be performed on the data, and the amount of data received is the same as the amount that should be returned to the application, specify a NULL function pointer. The default routine returns ilen and does not modify the buffer.
The following is a valid flag on input to _tmpresend2():
[TMPARENT]
This is the parent buffer (the one being sent).
The flags returned in flags specify the results of _tmpresend2(). Possible values are:
[TMUSEIPTR]
_tmpresend2() was successful: the processed data is in the buffer referenced by iptr, and the return value contains the length of the data to be sent.
[TMUSEOPTR]
_tmpresend2() was successful: the processed data is in the buffer referenced by optr, and the return value contains the length of the data to be sent.
If TMUSEOPTR is returned, the processing done after messages are transmitted is different from the processing done by _tmpresend(): the iptr buffer remains unchanged and _tmpostsend() is not called. If TMUSEIPTR is returned, _tmpostsend() is called, as it is called for _tmpresend(). It is the responsibility of the caller to allocate and to free or cache the optr buffer.
There are several reasons why you may want to use this approach for a typed buffer:
The _tmpresend2() function ensures that when a function returns, the data in the buffer to be sent can be sent without further processing. Because _tmencdec() is called only if the buffer is being sent to a dissimilar machine, _tmpresend2() ensures, upon return, that all data is stored contiguously in the buffer to be sent.
If no preprocessing needs to be performed on the data, and the amount of data specified by the caller is the same as the amount that should be sent, specify a NULL function pointer for _tmpresend2() in the buffer type switch. If _tmpresend2() is NULL, _tmpresend() is called by default.
Upon success, _tmpresend2() returns the amount of data to be sent or, if a larger buffer is needed, the negative absolute value of the desired buffer size. If the function fails, it returns -1, causing the caller of _tmpresend2() to also return failure, setting tperrno to TPESYSTEM.
_tmconvmb
_tmconvmb() is called after tmpostrecv() to convert multibyte data from a source encoding to a target encoding. The first argument to _tmconvmb(), ibufp, is a pointer to a stream of bytes—the multibyte data—to be converted. The second argument, ilen, is the number of bytes in ibufp. The third argument, enc_name, is one of the encoding names used in the processing. For an MBSTRING buffer, the third argument is the target encoding name; for an FML32 buffer, the third argument is the source encoding name.
_tmconvmb() receives a pointer, obufp, which is used to pass a pointer to a buffer into which the data in ibufp can be placed, after any required code-set encoding conversion is done. Use this pointer if you want to use a new buffer for the data converted by _tmconvmb() instead of modifying the input pointer. The fifth argument, olen, is the size of the obufp buffer. The flags argument is returned by _tmconvmb() to indicate the results of processing.
The size of the obufp buffer may not be large enough for successful post processing. If more space is required, _tmconvmb() returns the negative absolute value of the desired buffer size. All ilen bytes of the ibufp buffer are preserved. The calling routine then resizes the buffer and calls _tmconvmb() a second time.
If no code-set encoding conversion needs to be performed on the data, and the encoding name of the sending process is the same as the encoding name of the receiving process, specify a NULL function pointer. The default routine returns ilen and does not convert the buffer. If this function does not know how to convert the code-set encoding, it returns -1.
The value returned in flags specifies the result of _tmconvmb(). Possible values are:
[TMUSEIPTR]
_tmconvmb() was successful: the processed data is in the buffer referenced by ibufp, and the return value contains the length of the converted data to be passed to the service.
[TMUSEOPTR]
_tmconvmb() was successful: the processed data is in the buffer referenced by obufp, and the return value contains the length of the data to be converted. It is the responsibility of the caller to allocate and to free or cache the obufp buffer.
Upon success, _tmconvmb() returns the amount of data buffer that had code-set encoding conversion or, if a larger buffer is needed, the negative absolute value of the desired buffer size. If the function fails, it returns -1, causing the caller of _tmconvmb() to also return failure, setting tperrno to TPESYSTEM.
See Also
tpacall(3c), tpalloc(3c), tpcall(3c), tpconnect(3c), tpdiscon(3c), tpfree(3c), tpgetrply(3c), tpgprio(3c), tprealloc(3c), tprecv(3c), tpsend(3c), tpsprio(3c), tptypes(3c), tuxtypes(5)
catgets(3c)
Name
catgets()—Reads a program message.
Synopsis
#include <nl_types.h>
char *catgets (nl_catd catd, int set_num, int msg_num, char *s)
Description
catgets() attempts to read message msg_num, in set set_num, from the message catalogue identified by catd. catd is a catalogue descriptor returned from an earlier call to catopen(). s points to a default message string which will be returned by catgets() if the identified message catalogue is not currently available.
A thread in a multithreaded application may issue a call to catgets() while running in any context state, including TPINVALIDCONTEXT.
Diagnostics
If the identified message is retrieved successfully, catgets() returns a pointer to an internal buffer area containing the NULL terminated message string. If the call is unsuccessful because the message catalogue identified by catd is not currently available, a pointer to s is returned.
See Also
catopen, catclose(3c)
catopen, catclose(3c)
Name
catopen(), catclose()—Opens/closes a message catalogue.
Synopsis
#include <nl_types.h>
nl_catd catopen (char *name, int oflag)
int catclose (nl_catd catd)
Description
catopen() opens a message catalogue and returns a catalogue descriptor. name specifies the name of the message catalogue to be opened. If name contains a “/” then name specifies a pathname for the message catalogue. Otherwise, the environment variable NLSPATH is used. If NLSPATH does not exist in the environment, or if a message catalogue cannot be opened in any of the paths specified by NLSPATH, then the default path is used (see nl_types(5)).
The names of message catalogues, and their location in the filestore, can vary from one system to another. Individual applications can choose to name or locate message catalogues according to their own special needs. A mechanism is therefore required to specify where the catalogue resides.
The NLSPATH variable provides both the location of message catalogues, in the form of a search path, and the naming conventions associated with message catalogue files. For example:
NLSPATH=/nlslib/%L/%N.cat:/nlslib/%N/%L
The metacharacter % introduces a substitution field, where %L substitutes the current setting of the LANG environment variable (see following section), and %N substitutes the value of the name parameter passed to catopen(). Thus, in the above example, catopen() will search in /nlslib/$LANG/name.cat, then in /nlslib/name/$LANG, for the required message catalogue.
NLSPATH will normally be set up on a system wide basis (for example, in /etc/profile) and thus makes the location and naming conventions associated with message catalogues transparent to both programs and users.
The following table lists the full set of metacharacters.
 
The LANG environment variable provides the ability to specify the user’s requirements for native languages, local customs and character set, as an ASCII string in the form LANG=language[_territory[.codeset]]
A user who speaks German as it is spoken in Austria and has a terminal that operates in ISO 8859/1 codeset, would want the setting of the LANG variable to be as follows:
LANG=De_A.88591
With this setting it should be possible for the user to find relevant catalogues if they exist.
If the LANG variable is not set then the value of LC_MESSAGES as returned by setlocale(3c) is used. If this is NULL then the default path as defined in nl_types(5) is used.
oflag() is reserved for future use and should be set to 0. The results of setting this field to any other value are undefined.
catclose() closes the message catalogue identified by catd.
A thread in a multithreaded application may issue a call to catopen() or catclose() while running in any context state, including TPINVALIDCONTEXT.
Diagnostics
If successful, catopen() returns a message catalogue descriptor for use on subsequent calls to catgets() and catclose(). Otherwise catopen() returns (nl_catd) -1. catclose() returns 0 if successful, otherwise -1.
See Also
catgets(3c), setlocale(3c), nl_types(5)
decimal(3c)
Name
decimal()—Decimal conversion and arithmetic routines.
Synopsis
#include “decimal.h”
int
lddecimal(cp, len, np) /* load a decimal */
char*cp; /* input: location of compacted format */
int
len; /* input: length of compacted format */
dec_t*np; /* output: location of dec_t format */
void
stdecimal(np, cp, len) /* store a decimal */
dec_t*np; /* input: location of dec_t format */
char*cp; /* output: location of compacted format */
int len; /* input: length of compacted format */
int
deccmp(n1, n2) /* compare two decimal numbers */
dec_t*n1; /* input: number to be compared */
dec_t*n2; /* input: number to be compared */
int
dectoasc(np, cp, len, right) /* convert dec_t to ascii */
dec_t*np; /* input: number to be converted */
char*cp; /* output: number after conversion */
int len; /* input: length of output string */
int right; /* input: number of places to right of decimal point */
int
deccvasc(cp, len, np) /* convert ascii to dec_t */
char*cp; /* input: number to be converted */
int len; /* input: maximum length of number to be converted */
dec_t*np; /* output: number after conversion */
int
dectoint(np, ip) /* convert int to dec_t */
dec_t*np; /* input: number to be converted */
int *ip; /* output: number after conversion */
int
deccvint(in, np) /* convert dec_t to int */
int in; /* input: number to be converted */
dec_t*np; /* output: number after conversion */
int
dectolong(np, lngp) /* convert dec_t to long */
dec_t*np; /* input: number to be converted */
long*lngp; /* output: number after conversion */
int
deccvlong(lng, np) /* convert long to dec_t */
longlng; /* input: number to be converted */
dec_t*np; /* output: number after conversion */
int
dectodbl(np, dblp) /* convert dec_t to double */
dec_t*np; /* input: number to be converted */
double *dblp; /* output: number after conversion */
int
deccvdbl(dbl, np) /* convert double to dec_t */
double *dbl; /* input: number to be converted */
dec_t*np; /* output: number after conversion */
int
dectoflt(np, fltp) /* convert dec_t to float */
dec_t*np; /* input: number to be converted */
float*fltp; /* output: number after conversion */
int
deccvflt(flt, np) /* convert float to dec_t */
double *flt; /* input: number to be converted */
dec_t*np; /* output: number after conversion */
int
decadd(*n1, *n2, *n3) /* add two decimal numbers */
dec_t*n1; /* input: addend */
dec_t*n2; /* input: addend */
dec_t*n3; /* output: sum */
int
decsub(*n1, *n2, *n3) /* subtract two decimal numbers */
dec_t*n1; /* input: minuend */
dec_t*n2; /* input: subtrahend */
dec_t*n3; /* output: difference */
int
decmul(*n1, *n2, *n3) /* multiply two decimal numbers */
dec_t*n1; /* input: multiplicand */
dec_t*n2; /* input: multiplicand */
dec_t*n3; /* output: product */
int
decdiv(*n1, *n2, *n3) /* divide two decimal numbers */
dec_t*n1; /* input: dividend */
dec_t*n2; /* input: divisor */
dec_t*n3; /* output: quotient */
Description
These functions allow storage, conversion, and manipulation of packed decimal data on the Oracle Tuxedo ATMI system. Note that the format in which the decimal data type is represented on the Oracle Tuxedo ATMI system is different from its representation under CICS.
A thread in a multithreaded application may issue a call to any of the decimal conversion functions while running in any context state, including TPINVALIDCONTEXT.
Native Decimal Representation
Decimals are represented on native Oracle Tuxedo ATMI system nodes using the dec_t structure. This definition of this structure is as follows:
#define DECSIZE 16
struct decimal {
short dec_exp; /* exponent base 100 */
short dec_pos; /* sign: 1=pos, 0=neg, -1=null */
short dec_ndgts; /* number of significant digits */
char dec_dgts[DECSIZE]; /* actual digits base 100 */
};
typedef struct decimal dec_t;
It should never be necessary for programmers to directly access the dec_t structure, but it is presented here nevertheless to give an understanding of the underlying data structure. If large amounts of decimal data need to be stored, the stdecimal() and lddecimal() functions may be used to obtain a more compact format. dectoasc(), dectoint(), dectolong(), dectodbl(), and dectoflt() allow the conversion of decimals to other data types. deccvasc(), deccvint(), deccvlong(), deccvdbl(), and deccvflt() allow the conversion of other data types to the decimal data type. deccmp() is the function which compares two decimals. It returns -1 if the first decimal is less than the second, 0 if the two decimals are equal, and 1 if the first decimal is greater than the second. A negative value other than -1 is returned if either of the arguments is invalid. decadd(), decsub(), decmul(), and decdiv() perform arithmetic operations on decimal numbers.
Return Value
Unless otherwise stated, these functions return 0 on success and a negative value on error.
getURLEntityCacheDir(3c)
Name
getURLEntityCacheDir() - Specifies a Xerces class method for getting the absolute path to the location where the DTD, schema and Entity files are cached.
Synopsis
char * getURLEntityCacheDir()
Description
getURLEntityCacheDir() is a method that is called to find out the location where the DTD, schema and Entity files are cached. It returns the absolute path to the cached file location. This method is exclusively used in conjunction with the following two Xerces objects:
getURLEntityCaching(3c)
Name
GetURLEntityCaching() - Specifies a Xerces class method for getting the caching mechanism for DTD, schema and Entity files.
Synopsis
bool getURLEntityCaching()
Description
GetURLEntityCaching() is a method that is called to find out if caching of the DTD, schema and Entity files are turned on or off. It returns true if caching is turned on and false if caching is turned off. This method is exclusively used in conjunction with the following two Xerces objects:
gp_mktime(3c)
Name
gp_mktime()—Converts a tm structure to a calendar time.
Synopsis
#include <time.h>
time_t gp_mktime (struct tm *timeptr);
Description
gp_mktime() converts the time represented by the tm structure pointed to by timeptr into a calendar time (the number of seconds since 00:00:00 Universal Coordinated Time—UTC, January 1, 1970).
The tm structure has the following format:
struct tm {
int tm_sec; /* seconds after the minute [0, 61] */
int tm_min; /* minutes after the hour [0, 59] */
int tm_hour; /* hour since midnight [0, 23] */
int tm_mday; /* day of the month [1, 31] */
int tm_mon; /* months since January [0, 11] */
int tm_year; /* years since 1900 */
int tm_wday; /* days since Sunday [0, 6] */
int tm_yday; /* days since January 1 [0, 365] */
int tm_isdst; /* flag for daylight savings time */
};
In addition to computing the calendar time, gp_mktime() normalizes the supplied tm structure. The original values of the tm_wday and tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated in the definition of the structure. On successful completion, the values of the tm_wday and tm_yday components are set appropriately, and the other components are set to represent the specified calendar time, but with their values forced to be within the appropriate ranges. The final value of tm_mday is not set until tm_mon and tm_year are determined.
The original values of the components may be either greater than or less than the specified range. For example, a tm_hour of -1 means 1 hour before midnight, tm_mday of 0 means the day preceding the current month, and tm_mon of -2 means 2 months before January of tm_year.
If tm_isdst is positive, the original values are assumed to be in the alternate time zone. If it turns out that the alternate time zone is not valid for the computed calendar time, then the components are adjusted to the main time zone. Likewise, if tm_isdst is zero, the original values are assumed to be in the main time zone and are converted to the alternate time zone if the main time zone is not valid. If tm_isdst is negative, the correct time zone is determined and the components are not adjusted.
Local time zone information is used as if gp_mktime() had called tzset().
gp_mktime() returns the specified calendar time. If the calendar time cannot be represented, the function returns the value (time_t)-1.
A thread in a multithreaded application may issue a call to gp_mktime() while running in any context state, including TPINVALIDCONTEXT.
Example
What day of the week is July 4, 2001?
#include <stdio.h>
#include <time.h>

static char *const wday[] = {
"Sunday", "Monday", "Tuesday", "Wednesday",
"Thursday", "Friday", "Saturday", "-unknown-"
};

struct tm time_str;
/*...*/
time_str.tm_year = 2001 - 1900;
time_str.tm_mon = 7 - 1;
time_str.tm_mday = 4;
time_str.tm_hour = 0;
time_str.tm_min = 0;
time_str.tm_sec = 1;
time_str.tm_isdst = -1;
if (gp_mktime(time_str) == -1)
time_str.tm_wday=7;
printf("%s\en", wday[time_str.tm_wday]);
Notices
tm_year of the tm structure must be for year 1970 or later. Calendar times before 00:00:00 UTC, January 1, 1970 or after 03:14:07 UTC, January 19, 2038 cannot be represented.
Portability
On systems where the C compilation system already provides the ANSI C mktime() function, gp_mktime() simply calls mktime() to do the conversion. Otherwise, the conversion is provided directly in gp_mktime().
In the latter case, the TZ environment variable must be set. Note that in many installations, TZ is set to the correct value by default when the user logs on. The default value for TZ is GMT0. The format for TZ is the following:
stdoffset[dst[offset],[start[time],end[time]]]
std and dst
Three or more bytes that designate the standard time zone (std) and daylight savings time time zone (dst). Only std is required. If dst is missing, then daylight savings time does not apply in this locale. Uppercase and lowercase letters are allowed. Any characters except a leading colon (:), digits, a comma (,), a minus (-) or a plus (+) are allowed.
offset
Indicates the value one must add to the local time to arrive at Coordinated Universal Time. The offset has the following form: hh[:mm[:ss]]. The minutes (mm) and seconds (ss) are optional. The hour (hh) is required and may be a single digit. The offset following std is required. If no offset follows dst, daylight savings time is assumed to be one hour ahead of standard time. One or more digits may be used; the value is always interpreted as a decimal number. The hour must be between 0 and 24, and the minutes (and seconds) if present, between 0 and 59. Out of range values may cause unpredictable behavior. If preceded by a “-”, the time zone is east of the Prime Meridian; otherwise it is west (which may be indicated by an optional preceding “+” sign).
start/time,end/time
Indicates when to change to and back from daylight savings time, where start/time describes when the change from standard time to daylight savings time occurs, and end/time describes when the change back happens. Each time field describes when, in current local time, the change is made.
The formats of start and end are one of the following:
Jn
The Julian day n (1 n 365). Leap days are not counted. That is, in all years, February 28 is day 59 and March 1 is day 60. It is impossible to refer to the occasional February 29.
n
The zero-based Julian day (0 n 365). Leap days are counted, and it is possible to refer to February 29.
Mm.n.d
Day d (0 d 6) of week n of month m in the year (1 n 5, 1 m 12), where week 5 means “the last d-day in month m,” which may occur in either the fourth or the fifth week). Week 1 is the first week in which day d occurs. Day 0 (zero) is Sunday.
Implementation specific defaults are used for start and end if these optional fields are not given.
The time has the same format as offset except that no leading sign (“-” or “+”) is allowed. The default, if time is not specified, is 02:00:00.
See Also
ctime(3c), getenv(3c), timezone(4) in a UNIX system reference manual
nl_langinfo(3c)
Name
nl_langinfo()—Language information.
Synopsis
#include <nl_types.h>
#include <langinfo.h>

char *nl_langinfo (nl_item item);
Description
nl_langinfo() returns a pointer to a NULL-terminated string containing information relevant to a particular language or cultural area defined in the programs locale. The manifest constant names and values of item are defined by langinfo.h.
For example:
nl_langinfo (ABDAY_1);
returns a pointer to the string “Dim” if the identified language is French and a French locale is correctly installed; or “Sun” if the identified language is English.
A thread in a multithreaded application may issue a call to nl_langinfo() while running in any context state, including TPINVALIDCONTEXT.
Diagnostics
If setlocale() has not been called successfully, or if langinf0() data for a supported language is either not available or item is not defined therein, then nl_langinfo() returns a pointer to the corresponding string in the C locale. In all locales, nl_langinfo() returns a pointer to an empty string if item contains an invalid setting.
Notices
The array pointed to by the return value should not be modified by the program. Subsequent calls to nl_langinfo() may overwrite the array.
See Also
setlocale(3c), strftime(3c), langinfo(5), nl_types(5)
rpc_sm_allocate, rpc_ss_allocate(3c)
Name
rpc_sm_allocate(), rpc_ss_allocate()—Allocates memory within the RPC stub memory management scheme.
Synopsis
#include <rpc/rpc.h>
idl_void_p_t rpc_sm_allocate(unsigned32 size, unsigned32 *status)
idl_void_p_t rpc_ss_allocate(unsigned32 size)
Description
Applications call rpc_sm_allocat3() to allocate memory within the RPC stub memory management scheme. The input parameter, size, specifies in bytes, the size of memory to be allocated. Before a call to this routine, the stub memory management environment must have been established. For service code that is called from the server stub, the stub itself normally establishes the necessary environment. When rpc_sm_allocate() is used by code that is not called from the stub, the application must establish the required memory management environment by calling rpc_sm_enable_allocate().
Specifically, if the parameters of a server stub include any pointers other than those used for passing parameters by reference or the [enable_allocate] attribute is specified for the operation in the ACS file, then the environment is automatically set up. Otherwise, the environment must be set up by the application by calling rpc_sm_enable_allocate().
When the stub establishes the memory management environment, the stub itself frees any memory allocated by rpc_sm_allocate(). The application can free such memory before returning to the calling stub by calling rpc_sm_free().
When the application establishes the memory management environment, it must free any memory allocated, either by calling rpc_sm_free() or by calling rpc_sm_disable_allocate().
The output parameter, status, returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include:
rpc_s_ok
Always returned. The return value is used to determine failure.
rpc_ss_allocate() is the exception-returning version of this function and has no status output parameter. No exceptions are raised.
A thread in a multithreaded application may issue a call to rpc_sm_allocate() or rpc_ss_allocate() while running in any context state, including TPINVALIDCONTEXT.
Return Values
Upon success, the routines return a pointer to the allocated memory. Note that in the ISO standard C environments, idl_void_p_t is defined as void * and in other environments it is defined as char *.
If there is insufficient memory, the routines return a NULL pointer.
See Also
rpc_sm_disable_allocate, rpc_ss_disable_allocate(3c), rpc_sm_enable_allocate, rpc_ss_enable_allocate(3c), rpc_sm_free, rpc_ss_free(3c)
Programming Oracle Tuxedo ATMI Applications Using TxRPC
rpc_sm_client_free, rpc_ss_client_free(3c)
Name
rpc_sm_client_free(), rpc_ss_client_free()—Frees memory returned from a client stub.
Synopsis
#include <rpc/rpc.h>
void rpc_sm_client_free (idl_void_p_t node_to_free, unsigned32 *status)
void rpc_ss_client_free (idl_void_p_t node_to_free)
Description
The rpc_sm_client_free() routine releases memory allocated and returned from a client stub. The input parameter, node_to_free, specifies a pointer to memory returned from a client stub. Note that in the ISO standard C environments, idl_void_p_t is defined as void * and in other environments is defined as char *.
This routine enables a routine to deallocate dynamically allocated memory returned by an RPC call without knowledge of the memory management environment from which it was called.
Note that this routine is always called from client code, even if the code can is executing as part of a server.
The output parameter, status, returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include:
rpc_s_ok
Success.
rpc_ss_client_free() is the exception-returning version of this function and has no status output parameter. No exceptions are raised.
A thread in a multithreaded application may issue a call to rpc_sm_client_free() or rpc_ss_client_free() while running in any context state, including TPINVALIDCONTEXT.
Return Values
None.
See Also
rpc_sm_free, rpc_ss_free(3c), rpc_sm_set_client_alloc_free, rpc_ss_set_client_alloc_free(3c), rpc_sm_swap_client_alloc_free, rpc_ss_swap_client_alloc_free(3c)
Programming Oracle Tuxedo ATMI Applications Using TxRPC
rpc_sm_disable_allocate, rpc_ss_disable_allocate(3c)
Name
rpc_sm_disable_allocate(), rpc_ss_disable_allocate()—Releases resources and allocated memory within the stub memory management scheme.
Synopsis
#include <rpc/rpc.h>
void rpc_sm_disable_allocate(unsigned32 *status);
void rpc_ss_disable_allocate(void);
Description
The rpc_sm_disable_allocate() routine releases all resources acquired by a call to rpc_sm_enable_allocate(), and any memory allocated by calls to rpc_sm_allocate() after the call to rpc_sm_enable_allocate() was made.
The rpc_sm_enable_allocate() and rpc_sm_disable_allocate() routines must be used in matching pairs. Calling this routine without a previous matching call to rpc_sm_enable_allocate() results in unpredictable behavior.
The output parameter, status, returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include:
rpc_s_ok
Success.
rpc_ss_disable_allocate() is the exception-returning version of this function and has no status output parameter. No exceptions are raised.
A thread in a multithreaded application may issue a call to rpc_sm_disable_allocate() or rpc_ss_disable_allocate() while running in any context state, including TPINVALIDCONTEXT.
Return Values
None.
See Also
rpc_sm_allocate, rpc_ss_allocate(3c), rpc_sm_enable_allocate, rpc_ss_enable_allocate(3c)
Programming Oracle Tuxedo ATMI Applications Using TxRPC
rpc_sm_enable_allocate, rpc_ss_enable_allocate(3c)
Name
rpc_sm_enable_allocate(), rpc_ss_enable_allocate()—Enables the stub memory management environment.
Synopsis
#include <rpc/rpc.h>
void rpc_sm_enable_allocate(unsigned32 *status)
void rpc_ss_enable_allocate(void)
Description
Applications can call rpc_sm_enable_allocate() to establish a stub memory management environment in cases where one is not established by the stub itself. A stub memory management environment must be established before any calls are made to rpc_sm_allocate(). For service code called from the server stub, the stub memory management environment is normally established by the stub itself. Code that is called from other contexts needs to call rpc_sm_enable_allocate() before calling rpc_sm_allocate() (for example, if the service code is called directly instead of from the stub).
The output parameter, status, returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include:
rpc_s_ok
Success.
rpc_s_no_memory
Insufficient memory available to set up necessary data structures.
rpc_ss_enable_allocate() is the exception-returning version of this function and has no status output parameter. The following exceptions are raised by this routine:
rpc_x_no_memory
Insufficient memory available to set up necessary data structures.
A thread in a multithreaded application may issue a call to rpc_sm_enable_allocate() or rpc_ss_enable_allocate() while running in any context state, including TPINVALIDCONTEXT.
Return Values
None.
See Also
rpc_sm_allocate, rpc_ss_allocate(3c), rpc_sm_disable_allocate, rpc_ss_disable_allocate(3c)
Programming Oracle Tuxedo ATMI Applications Using TxRPC
rpc_sm_free, rpc_ss_free(3c)
Name
rpc_sm_free, rpc_ss_free()—Frees memory allocated by the rpc_sm_allocate() routine.
Synopsis
#include <rpc/rpc.h>
void rpc_sm_free(idl_void_p_t node_to_free, unsigned32 *status)
void rpc_ss_free(idl_void_p_t node_to_free)
Description
Applications call rpc_sm_free() to release memory allocated by rpc_sm_allocate(). The input parameter, node_to_free, specifies a pointer to memory allocated by rpc_sm_allocate(). Note that in ISO standard C environments, idl_void_p_t is defined as void * and in other environments is defined as char *.
When the stub allocates memory within the stub memory management environment, service code called from the stub can also use rpc_sm_free() to release memory allocated by the stub.
Unpredictable behavior results if rpc_ss_free() is called with a pointer to memory not allocated by rpc_sm_allocate() or memory allocated by rpc_sm_allocate(), but not the first address of such an allocation.
The output parameter, status, returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include:
rpc_s_ok
Success.
rpc_ss_free is the exception-returning version of this function and has no status output parameter. No exceptions are raised.
A thread in a multithreaded application may issue a call to rpc_sm_free() or rpc_ss_free() while running in any context state, including TPINVALIDCONTEXT.
Return Values
None.
See Also
rpc_sm_allocate, rpc_ss_allocate(3c)
Programming Oracle Tuxedo ATMI Applications Using TxRPC
rpc_sm_set_client_alloc_free, rpc_ss_set_client_alloc_free(3c)
Name
rpc_sm_set_client_alloc_free(), rpc_ss_set_client_alloc_free()—Sets the memory allocation and freeing mechanisms used by the client stubs.
Synopsis
#include <rpc/rpc.h>
void rpc_sm_set_client_alloc_free(idl_void_p_t (*p_allocate)(unsigned long size), void (*p_free) (idl_void_p_t ptr), unsigned32 *status)
void rpc_ss_set_client_alloc_free(idl_void_p_t (*p_allocate)(unsigned long size), void (*p_free) (idl_void_p_t ptr))
Description
The rpc_sm_set_client_alloc_free() routine overrides the default routines that the client stub uses to manage memory. The input parameters, p_allocate and p_free specify memory allocator and free routines. The default memory management routines are ISO C malloc() and free() except when the remote call occurs within server code in which case the memory management routines must be rpc_ss_allocate() and rpc_ss_free().
The output parameter, status, returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include:
rpc_s_ok
Success.
rpc_s_no_memory
Insufficient memory available to set up necessary data structures.
rpc_ss_set_client_alloc_free is the exception-returning version of this function and has no status output parameter. The following exceptions are raised by this routine:
rpc_x_no_memory
Insufficient memory available to set up necessary data structures.
A thread in a multithreaded application may issue a call to rpc_sm_set_client_alloc_free() or rpc_ss_set_client_alloc_free() while running in any context state, including TPINVALIDCONTEXT.
Return Values
None.
See Also
rpc_sm_allocate, rpc_ss_allocate(3c), rpc_sm_free, rpc_ss_free(3c)
Programming Oracle Tuxedo ATMI Applications Using TxRPC
rpc_sm_swap_client_alloc_free, rpc_ss_swap_client_alloc_free(3c)
Name
rpc_sm_swap_client_alloc_free(), rpc_ss_swap_client_alloc_free()—Exchanges current memory allocation and freeing mechanism used by client stubs with one supplied by client.
Synopsis
#include <rpc/rpc.h>
void rpc_sm_swap_client_alloc_free(idl_void_p_t (*p_allocate)(unsigned long size),
void (*p_free) (idl_void_p_t ptr), idl_void_p_t (**p_p_old_allocate)(unsigned long size),
void (**p_p_old_free)( idl_void_p_t ptr), unsigned32 *status)
void rpc_ss_swap_client_alloc_free(idl_void_p_t (*p_allocate)(unsigned long size),
void (*p_free) (idl_void_p_t ptr), idl_void_p_t (**p_p_old_allocate)(unsigned long size),
void (**p_p_old_free)( idl_void_p_t ptr))
Description
The rpc_sm_swap_client_alloc_free() routine exchanges the current allocate and free mechanisms used by the client stubs for routines supplied by the caller. The input parameters, p_allocate and p_free, specify new memory allocation and free routines. The output parameters, p_p_old_allocate and p_p_old_free return the memory allocation and free routines in use before the call to this routine.
When a callable routine is an RPC client, it may need to ensure which allocate and free routines are used, despite the mechanism its caller had selected. This routine allows scoped replacement of the allocation/free mechanism to allow this.
The output parameter, status, returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include:
rpc_s_ok
Success.
rpc_s_no_memory
Insufficient memory available to set up necessary data structures.
rpc_ss_swap_client_alloc_free is the exception-returning version of this function and has no status output parameter. The following exceptions are raised by this routine:
rpc_x_no_memory
Insufficient memory available to set up necessary data structures.
A thread in a multithreaded application may issue a call to rpc_sm_swap_client_alloc_free() or rpc_ss_swap_client_alloc_free() while running in any context state, including TPINVALIDCONTEXT.
Return Values
None.
See Also
rpc_sm_allocate, rpc_ss_allocate(3c), rpc_sm_free, rpc_ss_free(3c), rpc_sm_set_client_alloc_free, rpc_ss_set_client_alloc_free(3c)
Programming Oracle Tuxedo ATMI Applications Using TxRPC.
setlocale(3c)
Name
setlocale()—Modifies and queries a program’s locale.
Synopsis
#include <locale.h>
char *setlocale (int category, const char *locale);
Description
setlocale() selects the appropriate piece of the program’s locale as specified by the category and locale arguments. The category argument may have the following values:
LC_CTYPE
LC_NUMERIC
LC_TIME
LC_COLLATE
LC_MONETARY
LC_MESSAGES
LC_ALL
These names are defined in the locale.h header file. For the Oracle Tuxedo ATMI system compatibility functions, setlocale() allows only a single locale for all categories. Setting any category is treated the same as LC_ALL, which names the program’s entire locale.
A value of “C” for locale specifies the default environment.
A value of "" for locale specifies that the locale should be taken from an environment variable. The environment variable LANG is checked for a locale.
At program startup, the equivalent of
setlocale(LC_ALL, "C")
is executed. This has the effect of initializing each category to the locale described by the environment “C”.
If a pointer to a string is given for locale, setlocale() attempts to set the locale for all the categories to locale. The locale must be a simple locale, consisting of a single locale. If setlocale() fails to set the locale for any category, a NULL pointer is returned and the program’s locale for all categories is not changed. Otherwise, locale is returned.
A NULL pointer for locale causes setlocale() to return the current locale associated with the category. The program’s locale is not changed.
A thread in a multithreaded application may issue a call to setlocale() while running in any context state, including TPINVALIDCONTEXT.
Files
$TUXDIR/locale/C/LANGINFO - time and money database for the C locale
$TUXDIR/locale/
locale/* - locale specific information for each
locale $TUXDIR/locale/C/*_CAT - text messages for the C locale
Note
A composite locale is not supported. A composite locale is a string beginning with a “/”, followed by the locale of each category, separated by a “/”.
See Also
mklanginfo(1)
ctime(3c), ctype(3c), getdate(3c), localeconv(3c), strftime(3c), strtod(3c), printf(3S), environ(5) in a UNIX system reference manual
setURLEntityCacheDir(3c)
Name
setURLEntityCacheDir() - Specifies a Xerces class method for setting the directory where the DTD, schema and Entity files are to be cached.
Synopsis
void setURLEntityCacheDir (const char* cachedir)
Description
setURLEntityCacheDir() is method called when caching is turned on and you want the DTD, schema and Entity files to be cached to a specific directory. cachedir specifies the absolute path to the location of the files.
If this method is not called and caching is turned on either by calling the method setURLEntityCaching() or by not setting the environment variable, then the files are cached in the current directory. This method is exclusively used in conjunction with the following two Xerces objects:
setURLEntityCaching(3c)
Name
setURLEntityCaching() - Specifies a Xerces class method for setting or unsetting DTD, schema or Entity file caching for the XML parser.
Synopsis
void setURLEntityCaching (bool UseCache)
Description
setURLEntityCaching()is a method that caches the DTD, schema and Entity files by default. It allows you to turn caching of the files on or off. UseCache is set to false if caching is to be turned off and set to true if caching is to be turned on. This method is exclusively used in conjunction with the following two Xerces objects:
strerror(3c)
Name
strerror()—Gets error message string.
Synopsis
#include <string.h>
char *strerror (int errnum);
Description
strerror maps the error number in errnum to an error message string, and returns a pointer to that string. strerror uses the same set of error messages as perror. The returned string should not be overwritten.
A thread in a multithreaded application may issue a call to strerror() while running in any context state, including TPINVALIDCONTEXT.
See Also
perror(3) in a UNIX system reference manual
strftime(3c)
Name
strftime()—Converts date and time to string.
Synopsis
#include <time.h>

size_t *strftime (char *s, size_t maxsize, const char *format, const struct tm *timeptr);
Description
strftime() places characters into the array pointed to by s as controlled by the string pointed to by format. The format string consists of zero or more directives and ordinary characters. All ordinary characters (including the terminating NULL character) are copied unchanged into the array. For strftime(), no more than maxsize characters are placed into the array.
If format is (char *)0, then the locale’s default format is used. The default format is the same as "%c".
Each directive is replaced by appropriate characters as described in the following list. The appropriate characters are determined by the LC_TIME category of the program’s locale and by the values contained in the structure pointed to by timeptr.
 
The difference between %U and %W lies in which day is counted as the first of the week. Week number 01 is the first week in January starting with a Sunday for %U or a Monday for %W. Week number 00 contains those days before the first Sunday or Monday in January for %U and %W, respectively.
If the total number of resulting characters including the terminating NULL character is not more than maxsize, strftime(), returns the number of characters placed into the array pointed to by s not including the terminating NULL character. Otherwise, zero is returned and the contents of the array are indeterminate.
A thread in a multithreaded application may issue a call to strftime() while running in any context state, including TPINVALIDCONTEXT.
Selecting the Output Language
By default, the output of strftime(), appears in U.S. English. The user can request that the output of strftime() be in a specific language by setting the locale for category LC_TIME in setlocale().
Time Zone
The time zone is taken from the environment variable TZ. See ctime(3c) for a description of TZ.
Examples
The example illustrates the use of strftime(). It shows what the string in str would look like if the structure pointed to by tmptr contains the values corresponding to Thursday, August 28, 1986 at 12:44:36 in New Jersey.
strftime (str, strsize, "%A %b %d %j", tmptr)
This results in str containing "Thursday Aug 28 240".
Files
$TUXDIR/locale/locale/LANGINFO—file containing compiled locale-specific date and time information
See Also
mklanginfo(1), setlocale(3c)
tpabort(3c)
Name
tpabort()—Routine for aborting current transaction.
Synopsis
#include <atmi.h>
int tpabort(long flags)
Description
tpabort() signifies the abnormal end of a transaction. When this call returns, all changes made to resources during the transaction are undone. Like tpcommit(), this function can be called only by the initiator of a transaction. Participants (that is, service routines) can express their desire to have a transaction aborted by calling tpreturn() with TPFAIL.
If tpabort() is called while call descriptors exist for outstanding replies, then upon return from the function, the transaction is aborted and those descriptors associated with the caller’s transaction are no longer valid. Call descriptors not associated with the caller’s transaction remain valid.
For each open connection to a conversational server in transaction mode, tpabort() will send a TPEV_DISCONIMM event to the server, whether or not the server has control of a connection. Connections opened before tpbegin() or with the TPNOTRAN flag (that is, not in transaction mode) are not affected.
Currently, the sole argument to the tpabort()function, flags, is reserved for future use and should be set to 0.
In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tpabort().
Return Values
Upon failure, tpabort() returns -1 and sets tperrno to indicate the error condition.
Errors
Upon failure, tpabort() sets tperrno to one of the following values:
[TPEINVAL]
flags is not equal to 0. The caller’s transaction is not affected.
[TPEHEURISTIC]
Due to a heuristic decision, the work done on behalf of the transaction was partially committed and partially aborted.
[TPEHAZARD]
Due to some failure, the work done on behalf of the transaction could have been heuristically completed.
[TPEPROTO]
tpabort() was called improperly (for example, by a participant).
[TPESYSTEM]
An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
[TPEOS]
An operating system error has occurred.
Notices
When using tpbegin(), tpcommit(), and tpabort() to delineate an Oracle Tuxedo ATMI system transaction, it is important to remember that only the work done by a resource manager that meets the XA interface (and is linked to the caller appropriately) has transactional properties. All other operations performed in a transaction are not affected by either tpcommit() or tpabort().
See Also
tpbegin(3c), tpcommit(3c), tpgetlev(3c)
tpacall(3c)
Name
tpacall()—Routine for sending a service request.
Synopsis
#include <atmi.h>
int tpacall(char *svc, char *data, long len, long flags)
Description
tpacall() sends a request message to the service named by svc. The request is sent out at the priority defined for svc unless overridden by a previous call to tpspri(). If data is non-NULL, it must point to a buffer previously allocated by tpalloc() and len should specify the amount of data in the buffer that should be sent. Note that if data points to a buffer of a type that does not require a length to be specified, (for example, an FML fielded buffer), then len is ignored (and may be 0). If data is NULL, len is ignored and a request is sent with no data portion. The type and subtype of data must match one of the types and subtypes recognized by svc. Note that for each request sent while in transaction mode, a corresponding reply must ultimately be received.
The following is a list of valid flags:
TPNOTRAN
If the caller is in transaction mode and this flag is set, then when svc is invoked, it is not performed on behalf of the caller’s transaction. If svc belongs to a server that does not support transactions, then this flag must be set when the caller is in transaction mode. Note that svc may still be invoked in transaction mode but it will not be the same transaction: a svc may have as a configuration attribute that it is automatically invoked in transaction mode. A caller in transaction mode that sets this flag is still subject to the transaction timeout (and no other). If a service fails that was invoked with this flag, the caller’s transaction is not affected.
TPNOREPLY
Informs tpacall() that a reply is not expected. When TPNOREPLY is set, the function returns 0 on success, where 0 is an invalid descriptor. When the caller is in transaction mode, this setting cannot be used unless TPNOTRAN is also set.
TPNOBLOCK
The request is not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). When TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout).
TPNOTIME
This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
TPSIGRSTRT
If a signal interrupts any underlying system calls, then the interrupted system call is reissued.
In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tpacall().
Return Values
Upon successful completion, tpacall() returns a descriptor that can be used to receive the reply of the request sent.
Upon failure, tpacall() returns a value of -1 and sets tperrno to indicate the error condition.
Errors
Upon failure, tpacall() sets tperrno to one of the following values. (Unless otherwise noted, failure does not affect the caller’s transaction, if one exists.)
[TPEINVAL]
Invalid arguments were given (for example, svc is NULL, data does not point to space allocated with tpalloc(), or flags are invalid).
[TPENOENT]
Cannot send to svc because it does not exist or is a conversational service.
[TPEITYPE]
The type and subtype of data is not one of the allowed types and subtypes that svc accepts.
[TPELIMIT]
The caller’s request was not sent because the maximum number of outstanding asynchronous requests has been reached.
[TPETRAN]
svc belongs to a server that does not support transactions and TPNOTRAN was not set.
[TPETIME]
This error code indicates that either a timeout has occurred or tpacall() has been attempted, in spite of the fact that the current transaction is already marked rollback only.
If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout cannot occur if TPNOBLOCK and/or TPNOTIME is specified.)
If a transaction timeout has occurred, then, with one exception, any attempts to send new requests or receive outstanding replies will fail with TPETIME until the transaction has been aborted. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller’s transaction (that is, tpacall() with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set).
When a service fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME.
[TPEBLOCK]
A blocking condition exists and TPNOBLOCK was specified.
[TPGOTSIG]
A signal was received and TPSIGRSTRT was not specified.
[TPEPROTO]
tpacall() was called improperly.
[TPESYSTEM]
An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
[TPEOS]
An operating system error has occurred. If a message queue on a remote location is filled, TPEOS may be returned even if tpacall() returned successfully.
See Also
tpalloc(3c), tpcall(3c), tpcancel(3c), tpgetrply(3c), tpgprio(3c), tpsprio(3c)
tpadmcall(3c)
Name
tpadmcall()—Administers unbooted application.
Synopsis
#include <atmi.h>
#include <fml32.h>
#include <tpadm.h>

int tpadmcall(FBFR32 *inbuf, FBFR32 **outbuf, long flags)
Description
tpadmcall() is used to retrieve and update attributes of an unbooted application. It may also be used in an active application to perform direct retrievals of a limited set of attributes without requiring communication to an external process. This function provides sufficient capability such that complete system configuration and administration can take place through system provided interface routines.
inbuf is a pointer to an FML32 buffer previously allocated with tpalloc() that contains the desired administrative operation and its parameters.
outbuf is the address of a pointer to the FML32 buffer that should contain the results. outbuf must point to an FML32 buffer originally allocated by tpalloc(). If the same buffer is to be used for both sending and receiving, outbuf should be set to the address of inbuf.
Currently, tpadmcall()’s last argument, flags, is reserved for future use and must be set to 0.
MIB(5) should be consulted for generic information on construction of administrative requests. TM_MIB(5) and APPQ_MIB(5) should be consulted for information on the classes that are accessible through tpadmcall().
There are four modes in which calls to tpadmcall() can be made.
Mode 1: Unbooted, Unconfigured Application:
The caller is assumed to be the administrator of the application. The only operations permitted are to SET a NEW T_DOMAIN class object, thus defining an initial configuration for the application, and to GET and SET objects of the classes defined in APPQ_MIB().
Mode 2: Unbooted, Configured Application:
The caller is assigned administrator or other privileges based on a comparison of their UID/GID to that defined in the configuration for the administrator on the local system. The caller may GET and SET any attributes for any class in TM_MIB() and APPQ_MIB() for which they have the appropriate permissions. Note that some classes contain only attributes that are inaccessible in an unbooted application and attempts to access these classes will fail.
Mode 3: Booted Application, Unattached Process:
The caller is assigned administrator or other privileges based on a comparison of their UID/GID to that defined in the configuration for the administrator on the local system. The caller may GET any attributes for any class in TM_MIB() for which they have the appropriate permissions. Similarly, the caller may GET and SET any attributes for any class in APPQ_MIB(), subject to class-specific restrictions. Attributes accessible only while ACTIVE will not be returned.
Mode 4: Booted Application, Attached Process:
Permissions are determined from the authentication key assigned at tpinit() time. The caller may GET any attributes for any class in TM_MIB() for which they have the appropriate permissions. Additionally, the caller may GET and SET any attributes for any class in APPQ_MIB(), subject to class-specific restrictions.
Access to and update of binary Oracle Tuxedo ATMI system application configuration files through this interface routine is controlled through the use of UNIX system permissions on directory names and filenames.
In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tpadmcall().
Environment Variables
The following environment variables must be set prior to calling this routine:
TUXCONFIG
Name of the file or device on which the binary Oracle Tuxedo system configuration file for this application is or should be stored.
Notices
Use of the TA_OCCURS attribute on GET requests is not supported when using tpadmcall(). GETNEXT requests are not supported when using tpadmcall().
Return Values
tpadmcall() returns 0 on success and -1 on failure.
Errors
Upon failure, tpadmcall() sets tperrno to one of the following values:
Note:
Except for TPEINVAL, the caller’s output buffer, outbuf, will be modified to include TA_ERROR, TA_STATUS, and possibly TA_BADFLD attributes to further qualify the error condition. See MIB(5), TM_MIB(5), and APPQ_MIB(5) for an explanation of possible error codes returned in this fashion.
[TPEINVAL]
Invalid arguments were specified. The flags value is invalid or inbuf or outbuf are not pointers to typed buffers of type “FML32.”
[TPEMIB]
The administrative request failed. outbuf is updated and returned to the caller with FML32 fields indicating the cause of the error as is discussed in MIB(5) and TM_MIB(5).
[TPEPROTO]
tpadmcall() was called improperly.
[TPERELEASE]
tpadmcall() was called with the TUXCONFIG environment variable pointing to a different release version configuration file.
[TPEOS]
An operating system error has occurred. A numeric value representing the system call that failed is available in Uunixerr.
[TPESYSTEM]
An Oracle Tuxedo system error has occurred. The exact nature of the error is written to userlog().
Interoperability
This interface supports access and update to the local configuration file and bulletin board only; therefore, there are no interoperability concerns.
Portability
This interface is available only on UNIX system sites running Oracle Tuxedo ATMI release 5.0 or later.
Files
The following library files are required:
${TUXDIR}/lib/libtmib.a, ${TUXDIR}/lib/libqm.a, ${TUXDIR}/lib/libtmib.so.<rel>, ${TUXDIR}/lib/libqm.so.<rel>, ${TUXDIR}/lib/libtmib.lib, ${TUXDIR}/lib/libqm.lib
The libraries must be linked manually when using buildclient. The user must use: -L${TUXDIR}/lib -ltmid -lqm
See Also
ACL_MIB(5), APPQ_MIB(5), EVENT_MIB(5), MIB(5), TM_MIB(5), WS_MIB(5)
Setting Up an Oracle Tuxedo Application
Administering an Oracle Tuxedo Application at Run Time
tpadvertise(3c)
Name
tpadvertise()—Routine for advertising a service name.
Synopsis
#include <atmi.h>
int tpadvertise(char *svcname, void (*func)(TPSVCINFO *))
Description
tpadvertise() allows a server to advertise the services that it offers. By default, a server’s services are advertised when it is booted and unadvertised when it is shutdown.
All servers belonging to a Multiple Server, Single Queue (MSSQ) set must offer the same set of services. These routines enforce this rule by affecting the advertisements of all servers sharing an MSSQ set.
tpadvertise() advertises svcname for the server (or the set of servers sharing the caller’s MSSQ set). svcname should be 127 characters or less, but cannot be NULL or the NULL string (“”). (See *SERVICES section of UBBCONFIG(5).)func is the address of an Oracle Tuxedo ATMI system service function. This function will be invoked whenever a request for svcname is received by the server. func cannot be NULL. Explicitly specified function names (see servopts(5)) can be up to 128 characters long. Names longer than 127 characters are accepted and truncated to 127 characters. Users should make sure that truncated names do not match other service names.
If svcname is already advertised for the server and func matches its current function, then tpadvertise() returns success (this includes truncated names that match already advertised names). However, if svcname is already advertised for the server but func does not match its current function, then an error is returned (this can happen if truncated names match already advertised names).
Service names starting with dot (.) are reserved for administrative services. An error will be returned if an application attempts to advertise one of these services.
Return Values
Upon failure, tpadvertise() returns -1 and sets tperrno to indicate the error condition.
Errors
Upon failure, tpadvertise() sets tperrno to one of the following values:
[TPEINVAL]
svcname is NULL or the NULL string (“”),or begins with a “.” or func is NULL.
[TPELIMIT]
svcname cannot be advertised because of space limitations. (See MAXSERVICES in the RESOURCES section of UBBCONFIG(5).)
[TPEMATCH]
svcname is already advertised for the server but with a function other than func. Although the function fails, svcname remains advertised with its current function (that is, func does not replace the current function).
[TPEPROTO]
tpadvertise() was called in an improper context (for example, by a client).
[TPESYSTEM]
An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
[TPEOS]
An operating system error has occurred.
See Also
tpservice(3c), tpunadvertise(3c)
tpalloc(3c)
Name
tpalloc()—Routine for allocating typed buffers.
Synopsis
#include <atmi.h>
char * tpalloc(char *type, char *subtype, long size)
Description
tpalloc() returns a pointer to a buffer of type type. Depending on the type of buffer, both subtype and size are optional. The Oracle Tuxedo ATMI system provides a variety of typed buffers, and applications are free to add their own buffer types. Consult tuxtypes(5) for more details.
If subtype is non-NULL in tmtype_sw for a particular buffer type, then subtype must be specified when tpalloc() is called. The allocated buffer will be at least as large as the larger of size and dfltsize, where dfltsize is the default buffer size specified in tmtype_sw for the particular buffer type. For buffer type STRING the minimum is 512 bytes; for buffer types FML and VIEW the minimum is 1024 bytes.
Note that only the first eight bytes of type and the first 16 bytes of subtype are significant.
Because some buffer types require initialization before they can be used, tpalloc() initializes a buffer (in an Oracle Tuxedo ATMI system-specific manner) after it is allocated and before it is returned. Thus, the buffer returned to the caller is ready for use. Note that unless the initialization routine cleared the buffer, the buffer is not initialized to zeros by tpalloc().
A thread in a multithreaded application may issue a call to tpalloc() while running in any context state, including TPINVALIDCONTEXT.
Return Values
Upon successful completion, tpalloc() returns a pointer to a buffer of the appropriate type aligned on a long word; otherwise, it returns NULL and sets tperrno to indicate the condition.
Errors
Upon failure, tpalloc() sets tperrno to one of the following values:
[TPEINVAL]
Invalid arguments were given (for example, type is NULL).
[TPENOENT]
No entry in tmtype_sw matches type and, if non-NULL, subtype.
[TPEPROTO]
tpalloc() was called improperly.
[TPESYSTEM]
An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
[TPEOS]
An operating system error has occurred.
Usage
If buffer initialization fails, the allocated buffer is freed and tpalloc() fails returning NULL.
This function should not be used in concert with malloc(), realloc(), or free() in the C library (for example, a buffer allocated with tpalloc() should not be freed with free()).
Two buffer types are supported by any compliant implementation of the Oracle Tuxedo ATMI system extension. Details are in the Introduction to the C Language Application-to-Transaction Monitor Interface.
See Also
tpfree(3c), tprealloc(3c), tptypes(3c)
tpappthrinit(3c)
Name
tpappthrinit() - Routine for creating and initializing a new Tuxedo context in an application-created server thread
Synopsis
#include <atmi.h>
int tpappthrinit(TPINIT *tpthrinfo);
Description
tpappthrinit() creates a new Tuxedo context in an application-created server thread. The context created by tpappthrinit() connects to the domain that the application server is in. It also sets the context of current application thread to the newly created context.
Before an application-created thread in a Tuxedo server process can use Tuxedo ATMI system communication or transaction routines, it first must call tpappthrinit(), or associate itself with a valid context using tpsetctxt().
After tpappthrinit() successfully returns, the application-created server thread can initiate service requests and define transactions.
Note:
The application thread cannot call tpreturn() or tpforward(). The application thread may send, but cannot receive unsolicited messages.
After tpappthrinit() successfully returns, the application-created server thread can get the current context by calling tpgetctxt() and pass it as a tpsetctxt() parameter called by another application-created server thread to associate itself to the context.
Note:
It is not allowed to set the context created by tpappthrinit() in service routine.
The tpappthrinit() argument, tpthrinfo, is a pointer to a TPINIT buffer type and a NULL subtype. TPINIT is a buffer type is defined in the atmi.h header file. The buffer must be allocated via tpalloc() prior to calling tpappthrinit(). It should be released using tpfree() after calling tpappthrinit().
Please refer to the tpinit() routine for description of TPINIT structure. The tpthrinfo members usrname, data, and datalen are used to pass authentication information to tpappthrinit(). The tpthrinfo members cltname, grpname and passwd are currently not used and must be set to a 0-length string. The TPINIT member flags is also not used by tpappthrinit().
tpappthrinit() can only be called in an application created server-thread. The server must be built using the buildserver -t option.
Note:
tpappthrinit() is not allowed in service routines.
Return Values
Upon successfully creating and initializing a Tuxedo context, tpappthrinit() returns 0.
Upon failure, it leaves the calling thread in TPNULLCONTEXT, returns -1, and sets tperrno to indicate the error condition.
Errors
Upon failure, tpappthrinit() sets tperrno to one of the following values:
[TPEINVAL]
Invalid arguments were specified. For example: tpthrinfo is non-NULL but does not point to a TPINIT typed buffer.
[TPEPROTO]
tpappthrinit() has been called improperly. For example: it is called in client program, or service routine, or the server is not built with the buildserver -t option.
[TPENOENT]
The context cannot be created due to space limitations.
[TPEPERM]
The context cannot be created because of authentication failure.
[TPESYSTEM]
An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
[TPEOS]
An operating system error has occurred.
See Also
tpappthrterm(3c), tpinit(3c), tpterm(3c),tpgetctxt(3c), tpsetctxt(3c)
Programming a Multithreaded and Multicontexted ATMI application
tpappthrterm(3c)
Name
tpappthrterm() - Routine for terminating Tuxedo context created by tpappthrinit() in an application-created server thread.
Synopsis
#include<atmi.h>
int tpappthrterm(void);
Description
tpappthrterm() removes the current Tuxedo context, and sets the context of a current application-created server thread to TPNULLCONTEXT. If the application thread is in transaction mode, then the transaction is rolled back. When tpappthrterm() returns successfully, the caller can no longer perform most Tuxedo ATMI operations. Any outstanding conversations are immediately disconnected.
tpappthrterm() can only be used to terminated a context which is created by tpappthrinit(), and it can only be invoked in an application-created server thread, the server must be built using the buildserver -t option .
Notes:
tpappthrterm() is not allowed in service routine, or in application-created server thread which is currently associated with a server-dispatched context.
It is important to avoid calling tpappthrterm() on a context while other application created server-threads are still working on that context.
Return Values
Upon successfully terminating a Tuxedo context, tpappthrterm()returns 0 and sets current context to TPNULLCONTEXT.
Upon failure, tpappthrterm() returns -1 and sets tperrno to indicate the error condition.
Errors
Upon failure, tpappthrterm() sets tperrno to one of the following values:
[TPEPROTO]
tpappthrterm() has been called improperly. For example, it is called in client program, or service routine, or it is called in an application-created server thread which is currently associated with a server-dispatched context.
[TPESYSTEM]
An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
[TPEOS]
An operating system error has occurred.
See Also
tpappthrinit(3c), tpinit(3c), tpgetctxt(3c), tpsetctxt(3c), tpterm(3c)
Programming a Multithreaded and Multicontexted ATMI application
tpbegin(3c)
Name
tpbegin()—Routine for beginning a transaction.
Synopsis
#include <atmi.h>
int tpbegin(unsigned long timeout, long flags)
Description
A transaction in the Oracle Tuxedo ATMI system is used to define a single logical unit of work that either wholly succeeds or has no effect whatsoever. A transaction allows work being performed in many processes, at possibly different sites, to be treated as an atomic unit of work. The initiator of a transaction uses tpbegin() and either tpcommit() or tpabort() to delineate the operations within a transaction. Once tpbegin() is called, communication with any other program can place the latter (of necessity, a server) in “transaction mode” (that is, the server’s work becomes part of the transaction). Programs that join a transaction are called participants. A transaction always has one initiator and can have several participants. Only the initiator of a transaction can call tpcommit() or tpabort(). Participants can influence the outcome of a transaction by the return values (rvals) they use when they call tpreturn(). Once in transaction mode, any service requests made to servers are processed on behalf of the transaction (unless the requester explicitly specifies otherwise).
Note that if a program starts a transaction while it has any open connections that it initiated to conversational servers, these connections will not be upgraded to transaction mode. It is as if the TPNOTRAN flag had been specified on the tpconnect() call.
tpbegin()’s first argument, timeout, specifies that the transaction should be allowed at least timeout seconds before timing out. Once a transaction times out it must be marked abort-only. If timeout is 0, then the transaction is given the maximum number of seconds allowed by the system before timing out (that is, the timeout value equals the maximum value for an unsigned long as defined by the system).
Currently, tpbegin()’s second argument, flags, is reserved for future use and must be set to 0.
In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tpbegin().
Return Values
Upon failure, tpbegin() returns -1 and sets tperrno to indicate the error condition.
Errors
Upon failure, tpbegin() sets tperrno to one of the following values:
[TPEINVAL]
flags is not equal to 0.
[TPETRAN]
The caller cannot be placed in transaction mode because an error occurred starting the transaction.
[TPEPROTO]
tpbegin() was called in an improper context (for example, the caller is already in transaction mode).
[TPESYSTEM]
An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
[TPEOS]
An operating system error has occurred.
Notices
When using tpbegin(), tpcommit(), and tpabort() to delineate an Oracle Tuxedo ATMI system transaction, it is important to remember that only the work done by a resource manager that meets the XA interface (and is linked to the caller appropriately) has transactional properties. All other operations performed in a transaction are not affected by either tpcommit() or tpabort(). See buildserver() for details on linking resource managers that meet the XA interface into a server such that operations performed by that resource manager are part of an Oracle Tuxedo ATMI system transaction.
See Also
tpabort(3c), tpcommit(3c), tpgetlev(3c), tpscmt(3c)
tpbroadcast(3c)
Name
tpbroadcast()—Routine to broadcast notification by name.
Synopsis
#include <atmi.h>

int tpbroadcast(char *lmid, char *usrname, char *cltname,
char *data, long len, long flags)
Description
tpbroadcast() allows a client or server to send unsolicited messages to registered clients within the system. The target client set consists of those clients matching identifiers passed to tpbroadcast(). Wildcards can be used in specifying identifiers.
lmid, usrname, and cltname are logical identifiers used to select the target client set. A NULL value for any argument constitutes a wildcard for that argument. A wildcard argument matches all client identifiers for that field. A 0-length string for any argument matches only 0-length client identifiers. Each identifier must meet the size restrictions defined for the system to be considered valid, that is, each identifier must be between 0 and MAXTIDENT characters in length.
The data portion of the request is pointed to by data, a buffer previously allocated by tpalloc(). len specifies how much of data to send. Note that if data points to a buffer type that does not require a length to be specified (for example, an FML fielded buffer), then len is ignored (and may be 0). Also, data may be NULL, in which case len is ignored. The buffer passes through the typed buffer switch routines just as any other outgoing or incoming message would; for example, encode/decode are performed automatically.
The following is a list of valid flags:
TPNOBLOCK
The request is not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full).
TPNOTIME
This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
TPSIGRSTRT
If a signal interrupts any underlying system calls, then the interrupted system call is reissued. Upon successful return from tpbroadcast(), the message has been delivered to the system for forwarding to the selected clients. tpbroadcast() does not wait for the message to be delivered to each selected client.
In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tpbroadcast().
Return Values
Upon failure, tpbroadcast() returns -1 and sets tperrno to indicate the error condition.
Errors
Upon failure, tpbroadcast()sends no broadcast messages to application clients and sets tperrno to one of the following values:
[TPEINVAL]
Invalid arguments were given (for example, identifiers too long or invalid flags). Note that use of an illegal LMID will cause tpbroadcast() to fail and return TPEINVAL. However, non-existent user or client names will simply successfully broadcast to no one.
[TPETIME]
A blocking timeout occurred. (A blocking timeout cannot occur if TPNOBLOCK and/or TPNOTIME is specified.)
[TPEBLOCK]
A blocking condition was found on the call and TPNOBLOCK was specified.
[TPGOTSIG]
A signal was received and TPSIGRSTRT was not specified.
[TPEPROTO]
tpbroadcast() was called improperly.
[TPESYSTEM]
An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
[TPEOS]
An operating system error has occurred.
Portability
The interfaces described in tpnotify(3c) are supported on native site UNIX-based processors. In addition, the routines tpbroadcast() and tpchkunsol() as well as the function tpsetunsol() are supported on UNIX and MS-DOS workstation processors.
Usage
Clients that select signal-based notification may not be signal-able by the system due to signal restrictions. When this occurs, the system generates a log message that it is switching notification for the selected client to dip-in and the client is notified then and thereafter via dip-in notification. (See the description of the RESOURCES NOTIFY parameter in UBBCONFIG() for a detailed discussion of notification methods.)
Because signaling of clients is always done by the system, the behavior of notification is always consistent, regardless of where the originating notification call is made. Therefore to use signal-based notification:
The ID for the application administrator is identified as part of the configuration for the application.
If signal-based notification is selected for a client, then certain ATMI calls can fail, returning TPGOTSIG due to receipt of an unsolicited message if TPSIGRSTRT is not specified. See UBBCONFIG(5) and tpinit(3c) for more information on notification method selection.
See Also
tpalloc(3c), tpinit(3c), tpnotify(3c), tpterm(3c), UBBCONFIG(5)
tpcall(3c)
Name
tpcall()—Routine for sending service request and awaiting its reply.
Synopsis
int tpcall(char *svc, char *idata, long ilen, char **odata, long \
*olen, long flags)
Description
tpcall() sends a request and synchronously awaits its reply. A call to this function is the same as calling tpacall() immediately followed by tpgetrply(). tpcall() sends a request to the service named by svc. The request is sent out at the priority defined for svc unless overridden by a previous call to tpspri(). The data portion of a request is pointed to by idata, a buffer previously allocated by tpalloc(). ilen specifies how much of idata to send. Note that if idata points to a buffer of a type that does not require a length to be specified, (for example, an FML fielded buffer), then ilen is ignored (and may be 0). Also, idata may be NULL, in which case ilen is ignored. The type and subtype of idata must match one of the types and subtypes recognized by svc.
Note:
If application needs to use an XML buffer as the send buffer in a tpcall(), the sendlen parameter must be specified to accurate length, which is string length of the XML buffer + 1.
odata is the address of a pointer to the buffer where a reply is read into, and olen points to the length of that reply. *odata must point to a buffer originally allocated by tpalloc(). If the same buffer is to be used for both sending and receiving, odata should be set to the address of idata. FML and FML32 buffers often assume a minimum size of 4096 bytes; if the reply is larger than 4096, the size of the buffer is increased to a size large enough to accommodate the data being returned. Also, if idata and *odata were equal when tpcall() was invoked, and *odata is changed, then idata no longer points to a valid address. Using the old address can lead to data corruption or process exceptions. As of release 6.4, the default allocation for buffers is 1024 bytes. Also, historical information is maintained on recently used buffers, allowing a buffer of optimal size to be reused as a return buffer.
Buffers on the sending side that may be only partially filled (for example, FML or STRING buffers) will have only the amount that is used send. The system may then enlarge the received data size by some arbitrary amount. This means that the receiver may receive a buffer that is smaller than what was originally allocated by the sender, yet larger than the data that was sent.
The receive buffer may grow, or it may shrink, and its address almost invariably changes, as the system swaps buffers around internally. To determine whether (and how much) a reply buffer changed in size, compare its total size before tpgetrply() was issued with *len. See “Introduction to the C Language Application-to-Transaction Monitor Interface” for more information about buffer management.
If *olen is 0 upon return, then the reply has no data portion and neither *odata nor the buffer it points to were modified. It is an error for *odata or olen to be NULL.
The following is a list of valid flags:
TPNOTRAN
If the caller is in transaction mode and this flag is set, then when svc is invoked, it is not performed on behalf of the caller’s transaction. Note that svc may still be invoked in transaction mode but it will not be the same transaction: a svc may have as a configuration attribute that it is automatically invoked in transaction mode. A caller in transaction mode that sets this flag is still subject to the transaction timeout (and no other). If a service fails that was invoked with this flag, the caller’s transaction is not affected.
TPNOCHANGE
By default, if a buffer is received that differs in type from the buffer pointed to by *odata, then *odata’s buffer type changes to the received buffer’s type so long as the receiver recognizes the incoming buffer type. When this flag is set, the type of the buffer pointed to by *odata is not allowed to change. That is, the type and subtype of the received buffer must match the type and subtype of the buffer pointed to by *odata.
TPNOBLOCK
The request is not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). Note that this flag applies only to the send portion of tpcall(): the function may block waiting for the reply. When TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout).
TPNOTIME
This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. However, if the caller is in transaction mode, this flag has no effect; it is subject to the transaction timeout limit. Transaction timeouts may still occur.
TPNOCOPY
This flag is only available for Exalogic and used when the Use of Shared Memory for Inter Process Communication feature is enabled (see SHMQ option in UBBCONFIG(5)). It indicates Tuxedo not making safe copy for request buffer during message sending process, thus saving cost of copying large buffers. However, in the event that tpcall() fails, causing the caller application unable to access the request buffer anymore, it is recommended you call tpfree() to release the request buffer. If Use of Shared Memory for Inter Process Communication is not enabled, this flag has no effect.
TPSIGRSTRT
If a signal interrupts any underlying system calls, then the interrupted system call is reissued.
In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tpcall().
Return Values
Upon successful return from tpcall() or upon return where tperrno is set to TPESVCFAIL, tpurcode() contains an application defined value that was sent as part of tpreturn().
Upon failure, tpcall() returns -1 and sets tperrno to indicate the error condition. If a call fails with a particular tperrno value, a subsequent call to tperrordetail(), with no intermediate ATMI calls, may provide more detailed information about the generated error. Refer to the tperrordetail(3c) reference page for more information.
Errors
Upon failure, tpcall() sets tperrno to one of the following values. (Unless otherwise noted, failure does not affect the caller’s transaction, if one exists.)
[TPEINVAL]
Invalid arguments were given (for example, svc is NULL or flags are invalid).
[TPENOENT]
Cannot send to svc because it does not exist, or it is a conversational service, or the name provided begins with a dot (.).
[TPEITYPE]
The type and subtype of idata is not one of the allowed types and subtypes that svc accepts.
[TPEOTYPE]
Either the type and subtype of the reply are not known to the caller; or, TPNOCHANGE was set in flags and the type and subtype of *odata do not match the type and subtype of the reply sent by the service. Neither *odata, its contents, nor *olen is changed. If the service request was made on behalf of the caller’s current transaction, then the transaction is marked abort-only since the reply is discarded.
[TPETRAN]
svc belongs to a server that does not support transactions and TPNOTRAN was not set.
[TPETIME]
This error code indicates that either a timeout has occurred or tpcall() has been attempted, in spite of the fact that the current transaction is already marked rollback only.
If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout cannot occur if TPNOBLOCK and/or TPNOTIME is specified.) In either case, no changes are made to *odata, its contents, or *olen.
If a transaction timeout has occurred, then, with one exception, any attempts to send new requests or receive outstanding replies will fail with TPETIME until the transaction has been aborted. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller’s transaction (that is, tpacall() with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set).
When a service fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME.
[TPESVCFAIL]
The service routine sending the caller’s reply called tpreturn() with TPFAIL. This is an application-level failure. The contents of the service’s reply, if one was sent, is available in the buffer pointed to by *odata. If the service request was made on behalf of the caller’s current transaction, then the transaction is marked abort-only. Note that regardless of whether the transaction has timed out, the only valid communications before the transaction is aborted are calls to tpacall() with TPNOREPLY, TPNOTRAN, and TPNOBLOCK set.
[TPESVCERR]
A service routine encountered an error either in tpreturn(3c) or tpforward(3c) (for example, bad arguments were passed). No reply data is returned when this error occurs (that is, neither *odata, its contents, nor *olen is changed). If the service request was made on behalf of the caller’s transaction (that is, TPNOTRAN was not set), then the transaction is marked abort-only. Note that regardless of whether the transaction has timed out, the only valid communications before the transaction is aborted are calls to tpacall() with TPNOREPLY, TPNOTRAN, and TPNOBLOCK set. If either SVCTIMEOUT in the UBBCONFIG file or TA_SVCTIMEOUT in the TM_MIB is non-zero, TPESVCERR is returned when a service timeout occurs.
[TPEBLOCK]
A blocking condition was found on the send call and TPNOBLOCK was specified.
[TPGOTSIG]
A signal was received and TPSIGRSTRT was not specified.
[TPEPROTO]
tpcall() was called improperly.
[TPESYSTEM]
An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
[TPEOS]
An operating system error has occurred. If a message queue on a remote location is filled, TPEOS may be returned even if tpcall() returned successfully.
See Also
tpacall(3c),tpalloc(3c), tperrordetail(3c), tpforward(3c), tpfree(3c), tpgprio(3c), tprealloc(3c), tpreturn(3c), tpsprio(3c), tpstrerrordetail(3c), tptypes(3c)
tpcancel(3c)
Name
tpcancel()—Routine for canceling a call descriptor for outstanding reply.
Synopsis
#include <atmi.h>
int tpcancel(int cd)
Description
tpcancel() cancels a call descriptor, cd, returned by tpacall(). It is an error to attempt to cancel a call descriptor associated with a transaction.
Upon success, cd is no longer valid and any reply received on behalf of cd will be silently discarded.
In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tpcancel().
Return Values
Upon failure, tpcancel() returns -1 and sets tperrno to indicate the error condition.
Errors
Upon failure, tpcancel() sets tperrno to one of the following values:
[TPEBADDESC]
cd is an invalid descriptor.
[TPETRAN]
cd() is associated with the caller’s transaction. cd remains valid and the caller’s current transaction is not affected.
[TPEPROTO]
tpcancel() was called improperly.
[TPESYSTEM]
An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
[TPEOS]
An operating system error has occurred.
See Also
tpacall(3c)
tpchkauth(3c)
Name
tpchkauth()—Routine for checking if authentication required to join an application.
Synopsis
#include <atmi.h>

int tpchkauth(void)
Description
tpchkauth() checks if authentication is required by the application configuration. This is typically used by application clients prior to calling tpinit() to determine if a password should be obtained from the user.
In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tpchkauth().
Return Values
Upon success, tpchkauth() returns one of the following non-negative values:
TPNOAUTH
Indicates that no authentication is required.
TPSYSAUTH
Indicates that system authentication only is required.
TPAPPAUTH
Indicates that both system and application specific authentication are required.
Upon failure, tpchkauth() returns -1 and sets tperrno to indicate the error condition.
Errors
Upon failure, tpchkauth() sets tperrno to one of the following values:
[TPESYSTEM]
An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
[TPEOS]
An operating system error has occurred.
Interoperability
tpchkauth() is available only on sites running release 4.2 or later.
Portability
The interfaces described in tpchkauth(3c) are supported on UNIX, Windows, and MS-DOS operating systems.
See Also
tpinit(3c)
tpchkunsol(3c)
Name
tpchkunsol()—Routine for checking for unsolicited message.
Synopsis
#include <atmi.h>
int tpchkunsol(void)
Description
tpchkunsol() is used by a client to trigger checking for unsolicited messages. Calls to this routine in a client using signal-based notification do nothing and return immediately. This call has no arguments. Calls to this routine can result in calls to an application-defined unsolicited message handling routine by the Oracle Tuxedo ATMI system libraries.
In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tpchkunsol().
Return Values
Upon successful completion, tpchkunsol() returns the number of unsolicited messages dispatched; otherwise it returns -1 and sets tperrno to indicate the error condition.
Errors
Upon failure, tpchkunsol() sets tperrno to one of the following values:
[TPEPROTO]
tpchkunsol() was called in an improper context (for example, from within a server).
[TPESYSTEM]
An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
[TPEOS]
An operating system error has occurred.
Portability
The interfaces described in tpnotify(3c) are supported on native site UNIX-based processors. In addition, the routines tpbroadcast() and tpchkunsol() as well as the function tpsetunsol() are supported on UNIX and MS-DOS workstation processors.
Clients that select signal-based notification may not be signal-able by the system due to signal restrictions. When this occurs, the system generates a log message that it is switching notification for the selected client to dip-in and the client is notified then and thereafter via dip-in notification. (See the description of the RESOURCES NOTIFY parameter in UBBCONFIG(5) for a detailed discussion of notification methods.)
Because signaling of clients is always done by the system, the behavior of notification is always consistent, regardless of where the originating notification call is made. Therefore to use signal-based notification:
The ID for the application administrator is identified as part of the con