API
This chapter describes how to use the APIs for the XA library and gateway, and how to configure them.
The APIs are used for requesting Tmax services. The XA library provides synchronous and asynchronous calls.
1. Synchronous Call
The tpcall function is used for making synchronous calls. It is used in the tmax client and server libraries, and can also be used in the XA library.
1.1. tpcall
The tpcall function sends a service request to the specified service through synchronous communication and receives the response. Its behavior is equivalent to calling tpacall() followed immediately by tpgetrply().
-
Prototype
# include <atmi.h> int tpcall (char *svc, char *idata, long ilen, char **odata, long *olen, long flags) -
Parameter
Parameter Description svc
A service to call. Must be provided by a Tmax application server program.
idata
A pointer to service request data. Must be a buffer allocated in advance by tpalloc(). The type and subtype of an idata must be supported by the svc.
ilen
The length of the data to send.
If the idata points to a variable-length buffer type, such as STRING, STRUCT, X_COMMON, or X_C_TYPE, the ilen will be ignored and 0 will be used. If the idata points to a fixed-length buffer type, such as X_OCTET, CARRAY, or MULTI STRUCTURE, the ilen cannot be 0.
If the idata is NULL, ilen will be ignored.
*odata
Response data buffer pointer with the length of an *olen. Must be allocated by tpalloc().
If the same buffer is used for both sent and received data, the *odata must be set to an idata address. To detect change in the response buffer size, compare the response buffer size allocated to the *odata before a tpcall() is complete and the size of the returned *olen. If the *olen size is larger, the allocated response buffer size will be increased. Otherwise, it will remain the same.
If tpcall() is called when the idata and *odata are using the same buffer, the address indicated by the idata will no longer be valid if the *odata is changed. The *odata may be changed if received data is too big or for other reasons.
If the *olen is returned as 0, no data will be received and the *odata and buffer pointed to by the *odata will not be changed. If *odata or *olen are NULL, an error will occur.
*olen
The length of the response returned by the *odata.
flags
Specifies the communication mode.
The following options are supported.
-
TPNOTRAN
If a service does not support transactions in transaction mode, the TPNOTRAN flag must be set in order to call tpcall() in transaction mode.
If the caller requests a service by setting a flag in transaction mode, the service will be excluded from transaction mode before being executed.
When a process using tx_begin() to start a transaction invokes tpcall() in transaction mode, it will be affected by the transaction timeout (TXTIME) even if TPNOTRAN was set. For example, tpcall with the TPNOTRAN flag will fail after the transaction times out without calling the service.
If a service called with TPNOTRAN fails, the caller’s current transaction will not be affected.
-
TPNOCHANGE
If the TPNOBLOCK flag is set and a blocking condition (e.g., the internal buffer is full with messages to send) occurs, the request will fail.
TPNOCHANGE is applied only to transactions in tpcall().
If tpcall() is called without setting the TPNOBLOCK flag and a blocking condition occurs, the caller must wait until it is unblocked or timeout (transaction or blocking timeout) occurs.
-
TPNOTIME
The caller waits indefinitely until receiving the response, ignoring the blocking timeout. If tpcall() is invoked within the transaction timeout period, the timeout still applies.
-
TPSIGRSTRT
Allows signal interrupts. If a system function is interrupted by a signal, the system function will be executed again. If a signal interrupt occurs without this flag, a function will fail and a tperrno will be set to TPGOTSIG.
-
-
Return Value
Value Description 1
The function call succeeded.
-1
The function call failed, and an error code is set in tperrno.
-
Errors
If tpcall() fails, one of the following codes is set in tperrno.
Error Code Description [TPEINVAL]
The parameter or flag is invalid. For example, the specified service (svc) is NULL, or the data points to a buffer that was not allocated by tpalloc().
[TPENOENT]
The service (svc) is not available because it does not exist.
[TPEITYPE]
The type or subtype of the data is not supported by svc.
[TPEOTYPE]
The type or subtype of the received response buffer is unknown to the caller.
When the flag is set to TPNOCHANGE, and the type and subtype of the buffer pointed by *odata do not match those of the received response buffer, both the *odata and *olen remain unchanged. If the caller requested a service in transaction mode, the transaction is rolled back because the response for the transaction was ignored.
[TPETRAN]
xa_start failed due to an error in the database while invoking a transaction service.
[TPETIME]
A transaction timeout occurred when the caller was in transaction mode, and the transaction was rolled back. If the caller is not in transaction mode, and neither TPNOTIME nor TPNOBLOCK was set, a block timeout will occur. In such cases, both the *odata and *olen remain unchanged. If a transaction timeout occurs, any new service requests and processes waiting for the response will fail due to a [TPETIME] error until the transaction is rolled back.
[TPESVCFAIL]
A service routine sent a response by calling tpreturn() with TPFAIL because an error occurred in the application program. Service response data can be accessed through the *odata.
When a transaction timeout occurs, other communication may be attempted before the transaction is rolled back. For such attempts to be successful, TPNOTRAN must be set. All operations performed while the caller is in transaction mode are rolled back when the transaction is complete.
[TPESVCERR]
An error occurred during the execution of a service routine or tpreturn() (e.g., a wrong argument was passed).
If this error occurs, no response data will be returned (i.e., neither *odata nor *olen is changed). This error occurs when a buffer that was not allocated by tpalloc is used, the Tmax header of an allocated buffer is affected by an invalid pointer (due to memcpy, etc.), a call descriptor of tpacall or tpconnect is returned, or when the service includes invalid conversational data while in Recv mode. The client will receive this error when attempting to execute tpreturn.
When a TPEV_DISCOMN event occurs (e.g., after the client forcibly disconnects a conversation, the service program will receive a TPEV_DISCOMN) the client will receive this error through tpreturn for the service.
When the caller is in transaction mode, other communication may be attempted before the transaction is rolled back and a timeout occurs. For such attempts to be successful, TPNOTRAN must be set. All operations performed while the caller is in transaction mode are rolled back when the transaction is complete.
A SVCTIMEOUT can be specified for each service. If the service execution time exceeds the specified limit, the service will stop executing and will return a TPESVCERR. If the SVCTIMEOUT occurs, tpsvctimeout() will be called. Operations such as buffer lock releases and logging can be performed during tpsvctimeout() as needed.
[TPEBLOCK]
A blocking condition occurred while TPNOBLOCK was set.
[TPGOTSIG]
A signal was received while TPSIGRSTRT was not set. On SUN systems, even if a signal interrupt occurs, the function does not fail but instead waits for the response until the specified timeout.
[TPEPROTO]
tpcall() was called under an inappropriate condition.
[TPESYSTEM]
An error occurred in the Tmax system. Detailed information is recorded in the log file.
[TPEOS]
A system call error occurred. If the system errno is set to EPIPE, a TPEBLOCK error occurs during TPECLOSE. If errono is set to EAGAIN or EWOULDBLOCK, a TPEBLOCK error occurs as well. In all other cases, TPEOS is returned.
The error may occur under the following conditions.
-
tpalloc() or malloc() failed.
-
realloc() failed.
-
The connection was lost during send/receive in a session connected to the CLH. (AIX/SUN only)
-
-
Example
#include <stdio.h> #include <usrinc/atmi.h> void main(int argc, char *argv[]) { int ret; char *sndbuf, *rcvbuf; long sndlen, rcvlen; ret=tpstart((TPSTART_T *)NULL); if (ret==-1) { error processing } sndbuf = (char *)tpalloc(“CARRAY”, NULL, 20); if (sndbuf==NULL) {error processing }; rcvbuf = (char *)tpalloc(“CARRAY”, NULL, 20); if (rcvbuf==NULL) {error processing }; data process.... sndbuf=strlen(sndbuf); ret=tpcall(”SERVICE”, sndbuf, sndlen, &rcvbuf, &rcvlen, TPNOCHANGE); if (ret==-1) { error processing } data process.... tpfree((char *)sndbuf); tpfree((char *)rcvbuf); tpend(); } -
Related functions
tpalloc(), tpacall(), tpgetrply(), tpreturn()
2. Asynchronous Call
The tpacall function is used for making asynchronous calls, and tpgetrply for receiving replies. The tpacall and tpgetrply functions are used in the Tmax client and server libraries, and can also be used in the XA library.
2.1. tpacall
The tpacall function sends a service request between the server and client by sending a message to the specified service through asynchronous communication. After sending a message through asynchronous communication, it returns without waiting the result. The result can be retrieved later using tpgetrply(), or the response can be canceled using tpcancel().
After tx_begin is invoked and tx_time has elapsed, tpacall can only succeed if the call is configured with the TPNOTRAN or TPNOREPLY flag. All others calls result in a TPETIME error.
When tpacall succeeds, the return value is a positive integer in the range 1 to 2,147,438,647.
-
Prototype
# include <atmi.h> int tpacall (char *svc, char *data, long len, long flags)
-
Parameter
Parameter Description svc
A service to call. Must be provided by a Tmax application server program.
data
If the value is not NULL, must be a pointer to a buffer allocated by tpalloc().
len
The length of the data to send.
If the data points to a variable-length buffer type, such as STRING, STRUCT, X_COMMON, or X_C_TYPE, the len will be ignored and 0 will be used by default. If the data points to a fixed-length buffer type, such as X_OCTET, CARRAY, or MULTI STRUCTURE, the len cannot be 0.
If the data is NULL, len will be ignored and the service request is sent without data.
The type and subtype of a data must be supported by the svc. If the service request is sent in transaction mode, the request must be received.
flags
Specifies the call mode.
The following options are supported.
-
TPBLOCK
If tpacall() is used without setting this flag, the call may appear to succeed even if the target service (svc) does not exist, and an incorrect result may be returned. In such cases, the error is reported only when tpgetrply() is called.
When tpacall() is invoked with the TPBLOCK flag, the function checks whether the target service is currently running.
-
TPNOTRAN
If a service does not support transactions in transaction mode, the TPNOTRAN flag must be set in order to call tpacall() in transaction mode. If the caller requests a service by setting a flag in transaction mode, the service will be excluded from transaction mode before being executed.
When a process using tx_begin() to start a transaction invokes tpacall() in transaction mode, it will be affected by the transaction timeout (TXTIME) even if TPNOTRAN was set. For example, tpacall with the TPNOTRAN flag will fail after the transaction times out without calling the service. tpacall with the TPNOTRAN|TPNOREPLY flags are allowed exceptionally.
If a service called with TPNOTRAN fails, the caller’s current transaction will not be affected.
-
TPNOREPLY
A service call sent through tpacall() returns immediately without waiting for a response. Normally, the result can be retrieved later using tpgetrply() with the descriptor returned by tpacall(). However, when the TPNOREPLY flag is set, no response is expected. In this case, tpacall() returns 0 if the service call is successfully issued.
If the caller is in transaction mode, the TPNOTRAN flag must also be set for TPNOREPLY to take effect. To verify the service status, the TPBLOCK flag must be specified as well. Without TPBLOCK, no error is reported even if the target service is in the NRDY state.
-
TPNOBLOCK
TPNOBLOCK causes a service request to fail in a blocking condition (e.g., the internal buffer is full with messages to send).
If tpacall() is called without setting the TPNOBLOCK flag and a blocking condition occurs, the caller must wait until it is unblocked or timeout (transaction or blocking timeout) occurs.
-
TPNOTIME
The caller waits indefinitely until receiving the response, ignoring the blocking timeout. If tpacall() is invoked within the transaction timeout period, the timeout still applies.
-
TPSIGRSTRT
Allows signal interrupts. If a system function is interrupted by a signal, the system function will be executed again. If a signal interrupt occurs without this flag, a function will fail and a tperrno will be set to TPGOTSIG.
-
TPNOCALLBACK
When invoking tpacall() from usrmain() in UCS, a callback function can be registered using tpregcb(). If the TPNOCALLBACK flag is set, the response is not delivered to the callback function but must instead be retrieved explicitly through tpgetrply().
-
-
Return Value
Value Description Descriptor
The function call succeeded. The returned descriptor receives the response to the service request.
-1
The function call failed. An error code is set in tperrno.
-
Errors
If tpacall() fails, one of the following codes is set in tperrno.
Error Code Description [TPEINVAL]
The parameter is invalid. For example, the specified service (svc) is NULL, or the data points to a buffer that was not allocated by tpalloc().
[TPENOENT]
The service (svc) is not available because it does not exist.
[TPEITYPE]
The type or subtype of the data is not supported by svc. For structures, this error occurs if the struct has not been declared in the SDLFILE.
[TPELIMIT]
The number of asynchronous service requests has reached the limit, so the caller’s request cannot be sent.
[TPETIME]
A transaction timeout occurred when the caller was in transaction mode, and the transaction was rolled back. If the caller is not in transaction mode, and neither TPNOTIME nor TPNOBLOCK was set, a block timeout will occur. If a transaction timeout occurs, any new service requests and processes waiting for the response will fail due to a [TPETIME] error until the transaction is rolled back.
[TPEBLOCK]
A blocking condition occurred while TPNOBLOCK was set.
[TPGOTSIG]
A signal was received while TPSIGRSTRT was not set. On SUN systems, even if a signal interrupt occurs, the function does not fail but instead waits for the response until the specified timeout.
[TPEPROTO]
tpacall() was called in an invalid state. For example, TPNOREPLY was called in transaction mode without setting a TPNOTRAN.
[TPESYSTEM]
An error occurred in the Tmax system.
[TPEOS]
A system call error occurred. If the system errno is set to EPIPE, a TPEBLOCK error occurs during TPECLOSE. If errono is set to EAGAIN or EWOULDBLOCK, a TPEBLOCK error occurs as well. In all other cases, TPEOS is returned.
The error may occur under the following conditions.
-
tpalloc() or malloc() failed.
-
realloc() failed.
-
The connection was lost during send/receive in a session connected to the CLH. (AIX/SUN only)
-
-
Example
#include <stdio.h> #include <usrinc/atmi.h> void main(int argc, char *argv[]) { char *buf; int ret,cd; long len; ret=tpstart((TPSTART_T *)NULL); if (ret<0) { error processing } buf = (char *)tpalloc(“CARRAY”, NULL, 20); if (buf==NULL) {error processing } data process.... cd = tpacall(“SERVICE”, sndbuf, 20, TPNOTIME); if (cd<0) {error processing } data process.... ret=tpgetrply(&cd, (char **)&buf, &len, TPNOTIME); if (ret<0) { error processing } data process.... tpfree((char *)buf); tpend(); } -
Related functions
tpalloc(), tpcall(), tpcancel(), tpgetrply()
2.2. tpgetrply
The tpgetrply function receives the response for an asynchronous service request sent by tpacall(). This function can be used both on clients and servers.
-
Prototype
# include <atmi.h> int tpgetrply(int *cd, char **data, long *len, long flags)
-
Parameter
Parameter Description cd
The call descriptor returned by tpacall(). In general, tpgetrply waits until the response matching the cd is received or until a timeout occurs. Generally, once the response is received, the cd is no longer valid.
*data
A pointer to the buffer allocated in advance by tpalloc().
len
The length of the data received by tpdeq(). If the response is larger than the specified buffer, tpdeq() can automatically increase the buffer size.
The received data is stored in *data, and len is updated to the size of the received data. If the size of the received data exceeds the current buffer, *data may be reallocated to a larger buffer. If len returns 0, no data is received, and the contents of *data and len remain unchanged.
If *data or len is NULL, an error occurs.
flags
The following flags are available.
-
TPGETANY
Ignores the specified call descriptor (cd) for the response and returns the response that can be received. In general, tpgetrply() will wait until the response is received.
If TPGETANY is not set, the *cd becomes null unless there is no specific configuration. If set, the cd can be used for an error response. If an error occurs before the response is returned, the cd will be set to 0. Unless otherwise specified, this does not affect the current transaction for the caller.
-
TPNOCHANGE
The buffer type that the *data points to cannot be changed.
If the types of the response buffer and the *data buffer do not match, the *data buffer type will be changed to the type of the response buffer. If the TPNOCHANGE flag is set, the buffer type will not be changed. The buffer type and subtype of the response buffer must be the same as those of the *data buffer.
-
TPNOBLOCK
Returns a valid response available without waiting for the response. If the TPNOBLOCK flag is not set, and there is no available response, the caller will wait until the response is received or a timeout (transaction or block timeout) occurs.
-
TPNOTIME
The caller waits indefinitely until receiving the response, ignoring the blocking timeout. If tpgetrply() is invoked within the transaction timeout period, the timeout still applies.
-
TPSIGRSTRT
Allows signal interrupts. If a system function is interrupted by a signal, the system function will be executed again. If a signal interrupt occurs without this flag, the function will fail and a tperrno will be set to TPGOTSIG.
-
-
Return Value
Value Description 1
The function call succeeded. When tpgetrply() returns successfully or a tperrno is [TPESVCFAIL], the global variable tpurcode returned by tpreturn() will be set to a value defined in the application.
-1
The function call failed, and an error code is set in tperrno.
-
Errors
If tpgetrply() fails, one of the following codes is set in tperrno.
Error Code Description [TPEINVAL]
The parameter is invalid. For example, the cd, data, *data, or len is NULL or the flag is invalid. If the cd is not NULL, it is valid even if an error occurs, and the function will continue to wait for the response.
[TPEBADDESC]
The cd is invalid.
[TPEOTYPE]
The type or the subtype of the received response is unknown to the caller.
When the flag is set to TPNOCHANGE, and the type and subtype of the *data do not match those of the response sent by the service, the *data and *len remain unchanged. If the response is received when the caller is in transaction mode, the transaction is rolled back because the response is ignored.
[TPETIME]
A transaction timeout occurred when the caller is in transaction mode, and the transaction is rolled back. If the caller is not in transaction mode, a block timeout will occur if neither TPNOTIME nor TPNOBLOCK is set. In such cases, the *data and *len remain unchanged. If a transaction timeout occurs, any new service requests and processes waiting for a response will fail due to a [TPETIME] error until the transaction is rolled back.
[TPESVCFAIL]
A service routine sent the response by calling tpreturn() with TPFAIL because an error occurred in the application program. Service reply data can be accessed through the *data. If the caller is in transaction mode, the transaction will be rolled back.
When a transaction timeout occurs, other communication may be attempted before the transaction is rolled back. For such attempts to be successful, TPNOTRAN must be set. All operations performed while the caller is in transaction mode are rolled back when the transaction is complete.
[TPEBLOCK]
A blocking occurred while TPNOBLOCK was set. The cd remains valid.
[TPGOTSIG]
A signal was received while TPSIGRSTRT was not set. On SUN systems, even if a signal interrupt occurs, the function does not fail but instead waits for the response until the specified timeout.
[TPEPROTO]
tpgetrply() was called under an inappropriate condition.
[TPETRAN]
xa_start failed because an error occurred in the database while calling a transaction service.
[TPESYSTEM]
An error occurred in the Tmax system.
[TPEOS]
An error occurred in the operating system.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> void main(int argc, char *argv[]) { int ret; long len; char *buf; ret=tpstart((TPSTART_T *)NULL); if (ret==-1) { error processing } buf = (char *)tpalloc(“STRING”, NULL, 0); if (buf==NULL) { error processing } data process.... cd = tpacall(“SERVICE”, buf, 0, TPNOFLAGS); if (cd==-1) { error procesing } data process.... ret=tpgetrply(&cd, &buf, &len, TPNOTIME); if (ret==-1) { error processing } data process.... tpfree(buf); tpend(); } -
Related functions
tpacall(), tpalloc(), tpreturn()