Before a client can make any service request, it must join the application. If a service request (or any ATMI routine) is called before invoking TPINITIALIZE, then it is invoked automatically with a SPACES parameter. This implies that the features mentioned above cannot be used; the default values are used for client naming, unsolicited notification type, and system access mode, the client cannot be associated with a resource manager group, and an application password cannot be specified. To use these features, the application must explicitly invoke the TPINITIALIZE routine. Once invoked (either implicitly or explicitly), the calling process may initiate requests and receive replies. TPTERM removes the process from the application. When TPTERM returns successfully the process must again join the application before communicating with a BEA TUXEDO system server process. A typical client process might begin and end as illustrated in Listing 11-1.
TPCALL sets TP-STATUS to TPOK upon success. On failure, the value of TP-STATUS is set to an appropriate value reflecting the type of error that occurred. Some of the causes for error have already been discussed, while others have transaction implications and will be introduced in Chapter 15, "Error Management." In general, communication calls may fail for a variety of errors. Many of the errors returned on communication calls can be fixed on an application level. They include application defined errors (TPESVCFAIL), errors in processing return arguments (TPESVCERR), typed record errors (TPEITYPE, TPEOTYPE), time-out (TPETIME), and protocol errors (TPEPROTO) among others. They are all discussed in Chapter 15, "Error Management," and are listed on the INTRO and TPCALL manual pages. The communication of these failures will also be explained in the discussion of the TPRETURN routine in Chapter 12, "Writing Service Routines."
The TPACALL routine sends a request message to the service named in SERVICE-NAME IN TPSVCDEF-REC and immediately returns from the call. The three parameters, DATA-REC, LEN IN TPTYPE-REC, and the settings in TPSTATUS-REC, have the same semantics as IDATA-REC, LEN IN ITPTYPE-REC, and the settings in TPSTATUS-REC of the TPCALL routine. Upon successful completion of the call, TPACALL returns a value in COMM-HANDLE IN TPSVCDEF-REC which serves as a communications handle that can be used to get the correct reply for the sent request. While TPACALL is in transaction mode (the topic of Chapter 14, "Global Transactions in the BEA TUXEDO System,"), there may be no outstanding replies when the transaction commits; that is, within a given transaction, for each request sent expecting a reply a corresponding reply must eventually be received.
With the TPSPRIO routine, the programmer can override the priority level the request would normally inherit from the service to which it is dispatched. When TPSPRIO is called, it affects the priority level of the very next request only that is sent by TPCALL or TPACALL or forwarded by a service subroutine. Forwarding requests will be discussed later in Chapter 12, "Writing Service Routines." This routine takes two parameters, TPPRIDEF-REC and TPSTATUS-REC, and the second one indicates how the first one is to be interpreted. The first member, PRIORITY IN TPPRIDEF-REC, is an integer. In the default situation, its sign indicates whether the request's priority should be incremented or decremented in relation to the existing priority. For the first member to be treated as a relative value, the settings must be set to 0. If TPABSOLUTE is set, the priority value of the next request that is sent out will receive the absolute value of the integer contained in PRIORITY. The absolute value of PRIORITY must be in the range of 1 to 100. If the value is not in this range, the system uses the default value, 50. If TPRELATIVE is set, the priority value of the next request is sent out at the relative value of the integer contained in PRIORITY.
Upon successful return, LEN IN TPTYPE-REC contains the actual number of bytes moved into DATA-REC. REC-TYPE and SUB-TYPE, both in TPTYPE-REC, contain the data's type and sub-type, respectively. If the message is larger than DATA-REC, then DATA-REC will contain only as many bytes as will fit in the record. The remainder of the message is discarded and sets TPTRUNCATE. If LEN is 0, upon successful completion, then the message has no data portion and DATA-REC was not modified.
