API
This chapter describes how to use APIs to develop applications.
1. Overview
The APIs for RQ can be divided into two types: APIs that are used directly by RQ and APIs that supplement RQ use. All APIs can be used by the server and the client.
-
APIs used by RQ
API Description Stores data in RQ.
Loads data from RQ.
Re-issues request data from the Fail queue of the RQ to the Request queue.
-
APIs supplementing RQ
API Description Service name of data when reading data from RQ using tpdeq().
Provides detailed information of data when reading data from RQ using tpdeq().
Requests the statistics of data stored in RQ.
Requests the statistics of a specified service among data stored in RQ.
Supports transactions and stores RQ data.
Supports transactions and loads data from RQ.
-
Other APIs
API Description Performs callback to apply deq_time.
2. APIs used by RQ
2.1. tpenq
The Tmax system ensures the integrity of data stored in the request queue (RQ) even if a system fault or error causes the system to go out of service. The tpenq() function saves data to the RQ. If a system crash occurs, processing resumes automatically once the system recovers.
When a service is requested using tpcall() or tpacall(), requests are placed in a queue if others are already waiting. However, if a system error or failure shuts the system down, queued data is lost. To prevent data loss and improve consistency, tpenq() explicitly saves service request data in the RQ.
Although tpenq() can be executed in transaction mode, it is not included in the transaction scope. If an error occurs during execution, the surrounding transaction is not affected.
The maximum number of requests that can be stored in the RQ is 2,097,152 (2 million). If the queue exceeds this limit, a TPEQFULL error is returned.
-
Prototype
# include <tmaxapi.h> int tpenq (char *qname, char *svc, char *data, long len, long flags)
-
Parameter
Parameter Description qname
RQ that saves data. The name must be specified and registered in the configuration file.
svc
Stores data to the RQ and immediately requests a service unless the svc name is NULL.
If the svc name is NULL, data is stored in the RQ but a service will not be performed. In this case, the function caller must request the service again using tpdeq(). If a system fault occurs when there is no service named svc or the service result has not been received after a service was performed, the data will be stored internally in a Fail Queue. This data must be re-requested using tpdeq() , or it is processed as an error.
data
A pointer to a buffer allocated by tpalloc() unless the value is NULL. The type and subtype of data must be supported by svc.
len
The length of data to be sent.
If data points to a buffer type that does not require a specified length, such as STRING, STRUCT, X_COMMON, or X_C_TYPE, len will be ignored and 0 will be used.
If data points to a buffer type that requires a specified length, such as X_OCTET, CARRAY, or MULTI STRUCTURE, len cannot be 0.
If data is NULL, len is ignored and the service request will be sent without data.
flags
The following flags are available.
-
TPRQS
When the svc is not NULL, the function caller will request a svc service and store the service results in the RQ. To receive the service results, tpdeq() must be called. If the svc is NULL, data will be stored in the RQ but the service will not be executed.
-
TPNOREPLY
When the svc is not NULL, the function caller will request a svc service and will not store the results in the RQ. If the svc is NULL, data will be stored in the RQ but the service will not be executed.
-
TPFUNC
Manages RQ data by service. If TPFUNC is not set, data stored by tpenq() will be dequeued when it is initially stored. If data must be dequeued before it is stored, TPFUNC must be set when calling tpenq().
-
0(zero)
Stores the service results to the client buffer of the Tmax system that is connected to the function caller, instead of storing them in the RQ. A service is requested through the RQ, but the results are saved to the client’s buffer similarly to the tpcall() function.
Once this flag is set, 0 (zero) must also be set when calling tpdeq() in order to receive the service results.
-
-
Return Value
Value Description -1
The function call failed, and an error code is set in tperrno.
-
Errors
If tpenq() fails, one of the following codes is set in tperrno.
Error Code Description [TPEINVAL]
The parameter is invalid. For example, the data points to a buffer that was not allocated by tpalloc() or an invalid flag was set.
[TPENOENT]
The qname does not exist.
[TPEQFULL]
The queue has reached its maximum capacity due to excessive enqueued service requests.
[TPGOTSIG]
A signal was received while TPSIGRSTRT was not set.
[TPEPROTO]
tpenq() was called inappropriately.
[TPESYSTEM]
An error occurred in the Tmax system. Detailed information is recorded in the log file.
[TPEOS]
An error occurred in the operating system.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/tmaxapi.h> void main(int argc, char *argv[]) { int ret; char *buf; long len; ret=tpstart((TPSTART_T *)NULL); if (ret==-1) { error processing } buf = (char *)tpalloc(“STRING”, NULL, 0); if (buf==NULL) { error processing } data process.... ret=tpenq(“RQ”, “SERVICE”, (char *)buf, strlen(buf), TPRQS); if (ret==-1) { error processing } data process.... ret=tpdeq(“RQ”, “SERVICE”, (char **)&buf, (long *)&len, TPRQS); if (ret==-1) { error processing } data process.... tpfree(buf); tpend(); } -
Related functions
tpdeq(), tpqstat()
2.2. tpdeq
The tpdeq function loads data from RQ. It receives the result of a service request or sets a service name to NULL and then reads stored data by using the tpenq() function. However, if TPNOREPLY is set when tpenq() is called, the service cannot receive any results, so even if an error occurs while executing tpdeq() in transaction mode, the transaction will not be affected.
-
Prototype
# include <tmaxapi.h> int tpdeq (char *qname, char *svc, char **data, long *len, long flags)
-
Parameter
Parameter Description qname
RQ that saves data. The name must be specified and registered in the configuration file.
svc
A svc must be set to a service name when tpenq() is called. In other words, if tpenq() is called with the service name, the service will automatically be requested and the results will be stored in RQ. In order to receive the service results, the same service name must be specified.
If the service name is NULL when tpenq() is called, the same service name must be entered for tpdeq_ctl(). If the service name is NULL, all data accumulated in the queue can be loaded individually regardless of the service name.
To call tpdeq() for data saved in the fail queue due to an error or a system failure, the svc must be set to _rq_sub_queue_name[TMAX_FAIL_QUEUE].
*data
A pointer to the buffer allocated by tpalloc(). When the function is successfully returned, the received data is stored in *data.
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.
-
TPRQS
Retrieves service results from the reply queue (RQ).
-
TPFUNC
Manages RQ data by service. If TPFUNC is not set, data stored by tpenq() will be dequeued when it is initially stored. If data must be dequeued before it is stored, TPFUNC must be set when calling tpenq().
-
TPBLOCK
Waits until a message is returned during the block timeout period.
-
TPNOTIME
If TPNOTIME and TPBLOCK are both set, the function will wait until the response is returned regardless of the block timeout.
-
0(zero)
Retrieves data from the buffer of the client that the function caller is connected to.
-
-
Return Value
Value Description -1
The function call failed, and an error code is set in tperrno.
-
Errors
If tpdeq() fails, one of the following codes is set in tperrno.
Error Code Description [TPEINVAL]
The parameter is invalid. For example, the data points to a buffer that was not allocated by tpalloc() or an invalid flag was set.
[TPGOTSIG]
A signal was received while TPSIGRSTRT was not set.
[TPEMATCH]
The service name is incorrect, or no data matching the specified conditions is found.
[TPENOENT]
The qname does not exist.
[TPEPROTO]
tpdeq() was called inappropriately.
[TPESYSTEM]
An error occurred in the Tmax system. Detailed information is recorded in the log file.
[TPEOS]
An error occurred in the operating system.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/tmaxapi.h> void main(int argc, char *argv[]) { int ret; char *buf; long len; ret=tpstart((TPSTART_T *)NULL); if (ret==-1) { error processing } buf = (char *)tpalloc(“STRING”, NULL, 0); if (buf==NULL) { error processing } data process.... ret=tpenq(“RQ”, “SERVICE”, (char *)buf, strlen(buf), TPRQS); if (ret==-1) { error processing } data process.... ret=tpdeq(“RQ”, “SERVICE”, (char **)&buf, (long *)&len, TPRQS); if (ret==-1) { error processing } data process.... tpfree(buf); tpend(); } -
Related functions
tpenq(), tpqstat()
2.3. tpreissue
The tpreissue function reissues a request from the fail queue of the RQ. It can be used on both clients and servers.
If a service fails due to a network error or a server-side failure while processing RQ-based services via tpenq(), the request is stored in the fail queue. The tpreissue() function requeues the failed request, allowing it to be processed again. Once requeued, the data in the request queue is sent to the appropriate service, and the results are returned to the reply queue.
-
Prototype
#include <tmaxapi.h> int tpreissue(char *qname, char *filter, long flags)
-
Parameter
Parameter Description qname
The name of the RQ registered in the Tmax system.
filter
Currently not supported. Must be set to NULL.
flags
Currently not supported. Only TPNOFLAGS is available.
-
Return Value
Value Description 0
The function call succeeded.
-1
The function call failed, and an error code is set in tperrno.
-
Errors
If tpreissue() fails, one of the following codes is set in tperrno.
Error Code Description [TPEINVAL]
The parameter is invalid. For example, the qname is NULL, the filter is unsupported, or an invalid flag is set.
[TPENOENT]
No RQ exists for the specified qname.
[TPESYSTEM]
An error occurred in the Tmax system, typically due to a network failure.
-
Related functions
tpenq(), tpdeq()
3. APIs supplementing RQ
3.1. tpextsvcname
The tpextsvcname function extracts a service name from the data read from the RQ by using tpdeq(). This function is generally used to read data stored in the Fail Queue and can be used on both the client and the server.
-
Prototype
# include <tmaxapi.h> int tpextsvcname (char *data, char *svc)
-
Parameter
Parameter Description data
A pointer to the buffer that stores data retrieved from the RQ through tpdeq(). The buffer must be allocated by tpalloc() in advance.
svc
A pointer to receive the data’s service name.
-
Return Value
Value Description -1
The function call failed, and an error code is set in tperrno.
-
Errors
If tpextsvcname() fails, one of the following codes is set in tperrno.
Error Code Description [TPEINVAL]
The parameter is invalid. For example, the received buffer was not allocated by tpalloc().
[TPESYSTEM]
An error occurred in the Tmax system. Detailed information is recorded in the log file.
[TPEOS]
An error occurred in the operating system.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/tmaxapi.h> void main(int argc, char *argv[]) { int ret; char *buf, *svc_name; long len; ret=tpstart((TPSTART_T *)NULL); if (ret==-1) { error processing } buf = (char *)tpalloc(“STRING”, NULL, 0); if (buf==NULL) { error processing } data process.... ret=tpenq(“RQ”, “SERVICE”, (char *)buf, strlen(buf), TPRQS); if (ret==-1) { error processing } data process.... ret=tpdeq(“RQ”, “SERVICE”, (char **)&buf, (long *)&len, TPRQS); if (ret==-1) { error processing } ret=tpextsvcname(buf, svc_name); if (ret==-1) { error processing } printf(“svc name : %s ,”,svc_name); data process.... tpfree(buf); tpend(); } -
Related functions
tpenq(), tpdeq()
3.2. tpextsvcinfo
The tpextsvcinfo function provides detailed information about data retrieved from the RQ through tpdeq() in both the server and the client.
-
Prototype
# include <tmaxapi.h> int tpextsvcinfo (char *data, char *svc, int *type, int *errcode )
-
Parameter
Parameter Description data
A pointer to a buffer allocated by tpalloc() to store data read from the RQ through tpdeq().
svc
A pointer that receives the service name of the data.
type
Indicates the result of processing the data.
The following types are supported.
-
TPREQ(0)
tpenq(), with the svc parameter set to NULL, executed successfully.
-
TPFAIL(1)
tpenq(), with the svc parameter set to the service name, failed to execute. The first parameter of tpreturn will be set to TPFAIL.
-
TPSUCCESS(2)
tpenq(), with the svc parameter set to the service name, executed successfully. The first parameter of tpreturn will be set to TPSUCCESS.
-
TPERR(-1)
tpenq() failed to execute and was sent to a fail queue.
errcode
An error code set when an error occurs.
-
-
Return Value
Value Description -1
The function call failed, and an error code is set in tperrno.
-
Errors
If tpextsvcname() fails, one of the following codes is set in tperrno.
Error Code Description [TPEINVAL]
The parameter is invalid. For example, the data or svc is NULL.
[TPEITYPE]
The parameter is invalid. For example, the data was not retrieved from the RQ.
[TPESYSTEM]
An error occurred in the Tmax system. Detailed information is recorded in the log file.
[TPEOS]
An error occurred in the operating system.
-
Related functions
tpenq(), tpdeq(), tpextsvcname()
3.3. tpqstat
The tpqstat function retrieves the data statistics accumulated in the current RQ. This function is available both on servers and clients. A RQ internally consists of three queues: _fail queue, _request queue, and _reply queue. tpqstat( ) can get the data statistics stored in each of these queues, by using a flag value.
-
Prototype
# include <tmaxapi.h> int tpqstat (char *qname, long flags)
-
Parameter
Parameter Description qname
The name of the RQ registered in the Tmax configuration file.
flags
The type of the data statistics to retrieve.
The following flags are available.
-
0(TMAX_ANY_QUEUE)
Retrieves all data statistics of _fail queue, _request queue, and _reply queue.
-
1(TMAX_FAIL_QUEUE)
Retrieves data statistics of _fail queue.
-
2(TMAX_REQ_QUEUE)
Retrieves data statistics of _request queue.
-
3(TMAX_RPLY_QUEUE)
Retrieves data statistics of _reply queue.
-
-
Return Value
Value Description -1
The function call failed, and an error code is set in tperrno.
-
Errors
If tpqstat() fails, one of the following codes is set in tperrno.
Error Code Description [TPEINVAL]
The parameter is not valid. For example, the qname is NULL, no queue specified by the qname exists, or an invalid flag is set.
[TPEPROTO]
tpqstat() was called under an inappropriate condition.
[TPESYSTEM]
An error occurred in the Tmax system. Detailed information is recorded in the log file.
[TPEOS]
An error occurred in the operating system.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/tmaxapi.h> void main(int argc, char *argv[]) { int ret, i; char *buf; if (argc!=2) { error processing } ret=tpstart((TPSTART_T *)NULL); if (ret==-1) {error processing } buf = (char *)tpalloc(“STRING”, NULL, 0); if (buf==NULL) { error processing } strcpy(buf, argv[1]); data process… ret=tpenq(“RQ”, NULL, (char *)buf, strlen(buf), TPRQS); if (ret==-1) {error processing } printf(“qstat :”); for (i=0;i<4;i++) { ret=tpqstat(“rq”, i); if (ret==-1) {error processing } printf(“ %d”,ret); /* qstat : 1 0 0 1 */ } printf(“\n”); data process… ret=tpenq(“RQ”, “SERVICE”, (char *)buf, strlen(buf), TPRQS); if (ret==-1) {error processing } printf(”qstat :”); for (i=0;i<4;i++) { ret=tpqstat(“rq”, i); if (ret==-1) {error processing } printf(” %d”,ret); /* qstat : 2 0 0 2 */ } printf(“\n”); tpfree((char *)buf); tpend(); } -
Related functions
tpenq(), tpdeq()
3.4. tpqsvcstat
The tpqsvcstat function retrieves the data statistics for a specific service stored in the current RQ. This function is available both on servers and clients. A RQ internally consists of three queues: _fail queue, _request queue, and _reply queue. tpqsvcstat( ) can get the data statistics stored in each of these queues, by using a flag value.
-
Prototype
# include <tmaxapi.h> int tpqsvcstat (char *qname, char * svc, long flags )
-
Parameter
Parameter Description qname
The name of the RQ registered in the Tmax configuration file.
svc
The name of the service for which to retrieve statistics. If set to NULL, the function behaves like tpqstat().
flags
The type of the data statistics to retrieve.
The following flags are available.
-
0(TMAX_ANY_QUEUE)
Retrieves all data statistics of _fail queue, _request queue, and _reply queue.
-
1(TMAX_FAIL_QUEUE)
Retrieves data statistics of _fail queue.
-
2(TMAX_REQ_QUEUE)
Retrieves data statistics of _request queue.
-
3(TMAX_RPLY_QUEUE)
Retrieves data statistics of _reply queue.
-
-
Return Value
Value Description A value other than -1
The function call succeeded.
-1
The function call failed, and an error code is set in tperrno.
-
Errors
If tpqscvstat() fails, one of the following codes is set in tperrno.
Error Code Description [TPEINVAL]
The parameter is not valid. For example, the qname is NULL, no queue specified by the qname exists, or an invalid flag is set.
[TPEPROTO]
tpqscvstat() was called under an inappropriate condition.
[TPESYSTEM]
An error occurred in the Tmax system. Detailed information is recorded in the log file.
[TPEOS]
An error occurred in the operating system.
-
Related functions
tpenq(), tpdeq(), tpqstat()
3.5. tpenq_ctl
The tpenq_ctl function saves data to RQ and supports transactions in both the server and the client. The Tmax system ensures the integrity of data stored in the RQ by saving data even when a system fault or error causes an out of service status. If a system crashes, it will continue to process data once the system recovers.
When a service is requested using tpcall() or tpacall(), requests are placed in a queue if others are already waiting. However, if a system error or failure causes the system to shut down, queued data is lost. To prevent data loss and to improve data consistency, tpenq_ctl() explicitly saves service request data in the RQ.
If tpenq_ctl() is called in transaction mode, it runs as part of the transaction. When multiple calls are grouped into a single transaction, the data cannot be retrieved using tpdeq_ctl() until all calls in the transaction are completed. If an error occurs during the processing of any call, the entire transaction is rolled back.
-
Prototype
#include <usrinc/tmaxapi.h> int tpenq_ctl(char *qname, char *svc, TMQCTL *ctl, char *data, long len, long flags); -
Parameter
Parameter Description qname
RQ that saves data. The name must be specified and registered in the configuration file.
svc
Stores data to the RQ and immediately requests a service unless the svc name is NULL.
If the svc name is NULL, data is stored in the RQ but a service will not be performed. In this case, the function caller must request the service again using tpdeq_ctl(). If a system fault occurs when there is no service named svc or the service result has not been received after a service was performed, the data will be stored internally in a Fail Queue. This data must be re-requested using tpdeq_ctl(), or it is processed as an error.
ctl
If a time value is specified as the third argument of tpenq_ctl() using the TMQCTL det_time field, the service call is scheduled to run after the given delay. In this case, deq_time must be set to the sum of the current time and the specified delay_time. For example, if delay_time is 3, deq_time will be cur_time + 3.
If the TPRQS_NON_PERSISTENT flag is set, messages are stored only in memory and are not written to a file.
data
A pointer to a buffer allocated by tpalloc() unless the value is NULL. The type and subtype of data must be supported by svc.
len
The length of data to be sent.
If data points to a buffer type that does not require a specified length, such as STRING, STRUCT, X_COMMON, or X_C_TYPE, len will be ignored and 0 will be used.
If data points to a buffer type that requires a specified length, such as X_OCTET, CARRAY, or MULTI STRUCTURE, len cannot be 0.
If data is NULL, len is ignored and the service request will be sent without data.
flags
Specifies the data processing type.
The following flags are available.
-
TPRQS
When the svc is not NULL, the function caller will request a svc service and store the service results in the RQ. To receive service results, tpdeq_ctl() must be called. If the svc is NULL, data will be stored in the RQ but the service will not be executed.
-
TPNOREPLY
When the svc is not NULL, the function caller will request a svc service but will not store the results in the RQ. If the svc is NULL, data will be stored in the RQ but the service will not be executed.
-
TPFUNC
Manages RQ data by service. If TPFUNC is not set, data stored by tpenq_ctl() will be dequeued when it is initially stored. If data must be dequeued before it is stored, TPFUNC must be set when calling tpenq_ctl().
-
0(zero)
Stores the service results to the client buffer of the Tmax system that is connected to the function caller, instead of storing them in the RQ. A service is requested through the RQ, but the results are saved to the client’s buffer similarly to the tpcall() function.
Once this flag is set, 0 (zero) must also be set when calling tpdeq_ctl() in order to receive the service results.
-
-
Return Value
Value Description -1
The function call failed, and an error code is set in tperrno.
-
Errors
If tpenq_ctl() fails, one of the following codes is set in tperrno.
Error Code Description [TPEINVAL]
The parameter is invalid. For example, the data points to a buffer that was not allocated by tpalloc() or an invalid flag was set.
[TPENOENT]
The qname does not exist.
[TPEQFULL]
The queue has reached its maximum capacity due to excessive enqueued service requests.
[TPGOTSIG]
A signal was received while TPSIGRSTRT was not set.
[TPEPROTO]
tpenq_ctl() was called inappropriately.
[TPESYSTEM]
An error occurred in the Tmax system. Detailed information is recorded in the log file.
[TPEOS]
An error occurred in the operating system.
-
Example
#include <stdio.h> #include <unistd.h> #include <stdlib.h> #include <string.h> #include <usrinc/atmi.h> #include <usrinc/tmaxapi.h> main(int argc, char *argv[]) { char *sndbuf, *rcvbuf; long rcvlen, sndlen, revent; int ret, i, cd; TMQCTL *ctl; long t; ctl = (TMQCTL*)malloc(sizeof(TMQCTL)); memset(ctl, 0, sizeof(TMQCTL)); time(&t); ctl->deq_time = (int)t + 3; if (argc != 2) { printf(“Usage: toupper string\n”); exit(1); } if ( (ret = tmaxreadenv( “tmax.env”,”TMAX” )) == -1 ){ printf( “tmax read env failed\n” ); exit(1); } if (tpstart((TPSTART_T *)NULL) == -1){ printf(“tpstart failed\n”); exit(1); } if ((sndbuf = (char *)tpalloc(“STRING”, NULL, 0)) == NULL) { printf(“sendbuf alloc failed !\n”); tpend(); exit(1); } if ((rcvbuf = (char *)tpalloc(“STRING”, NULL, 0)) == NULL) { printf(“recvbuf alloc failed !\n”); tpfree((char *)sndbuf); tpend(); exit(1); } ret = tx_begin(); if(ret < 0) { fprintf(stderr, “tx_begin() fail\n”); tpfree((char *)sndbuf); tpfree((char *)rcvbuf); exit(1); } strcpy(sndbuf, argv[1]); cd = tpenq_ctl(“txrq1”, “TOUPPER”, ctl, (char *)sndbuf, 0, TPRQS ); if (cd < 0) { printf(“tpenq failed [%s]\n”, tpstrerror(tperrno)); tpfree((char *)sndbuf); tpfree((char *)rcvbuf); tpend(); exit(1); } cd = tpenq_ctl(“txrq1”, “TOUPPER”, ctl, (char *)sndbuf, 0, TPRQS ); if (cd < 0) { printf(“tpenq failed [%s]\n”, tpstrerror(tperrno)); tpfree((char *)sndbuf); tpfree((char *)rcvbuf); tpend(); exit(1); } data process.... ret = tx_commit(); if(ret < 0) { fprintf(stderr, “tx_commit() fail\n”); tpfree((char *)sndbuf); tpfree((char *)rcvbuf); tx_rollback(); exit(1); } tpfree((char *)sndbuf); tpfree((char *)rcvbuf); tpend(); } -
Related functions
tpdeq_ctl(), tpqstat()
3.6. tpdeq_ctl
The tpdeq_ctl function reads data from tpenq_ctl() service request results or data from tpenq_ctl() with a NULL argument. However, there are no response if tpenq_ctl() has the TPNOREPLY flag set. If tpdeq_ctl() is executed in transaction mode, data load operations from RQ will be processed in a transaction. If two or more calls to tpdeq_ctl() are grouped as one transaction, an error while loading data from RQ will roll back everything.
-
Prototype
#include <usrinc/tmaxapi.h> int tpdeq_ctl(char *qname, char *svc, TMQCTL *ctl, char **data, long *len, long flags); -
Parameter
Parameter Description qname
RQ that saves data. The name must be specified and registered in the configuration file.
svc
A svc must be set to a service name when tpenq_ctl() is called. In other words, if tpenq_ctl() is called with a service name, the service will automatically be requested and the results will be stored in RQ. In order to receive service results, the same service name must be specified.
If the service name is NULL when tpenq_ctl() is called, the same service name must be entered for tpdeq_ctl(). If the service name is NULL, all data accumulated in the queue can be loaded individually regardless of the service name.
To call tpdeq_ctl() for data saved in the fail queue due to an error or a system failure, the svc must be set to _rq_sub_queue_name[TMAX_FAIL_QUEUE].
ctl
-
* flags
-
TPRQS_AUTOACK : Allows deq to delete data from RQS automatically, without a separate acknowledgment.
-
TPRQS_NOAUTOACK : Prevents deletion from RQS during deq.
-
TPRQS_ACK_SUCCESS : Issues an acknowledgment for the queue element corresponding ctl to delete it.
-
TPRQS_ACK_FAIL : Prevents deletion from RQS during deq.
-
-
* exp_time
After deq, no response is received within the given time period, the queue element is returned to its original state for another deq attempt. (Unit: seconds)
data
A pointer to the buffer allocated by tpalloc(). When the function is successfully returned, the received data is stored in data.
len
The length of the data received by tpdeq_ctl(). If the response is larger than the specified buffer, tpdeq_ctl() 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
Specifies the data processing type.
The following flags are available.
-
TPRQS
Retrieves service results from the reply queue (RQ).
-
TPFUNC
Manages RQ data by service. If TPFUNC is not set, data stored by tpenq() will be dequeued when it is initially stored. If data must be dequeued before it is stored, TPFUNC must be set when calling tpenq().
-
TPBLOCK
Waits until a message is returned during the block timeout period.
-
TPNOTIME
If TPNOTIME and TPBLOCK are both set, the function will wait until the response is returned regardless of the block timeout.
-
0(zero)
Retrieves data from the buffer of the client that the function caller is connected to.
-
-
Return Value
Value Description -1
The function call failed, and an error code is set in tperrno.
-
Errors
If tpdeq_ctl() fails, one of the following codes is set in tperrno.
Error Code Description [TPEINVAL]
The parameter is invalid. For example, the data points to a buffer that was not allocated by tpalloc() or an invalid flag was set.
[TPGOTSIG]
A signal was received while TPSIGRSTRT was not set.
[TPEMATCH]
The service name is incorrect, or no data matching the specified conditions is found.
[TPENOENT]
The qname does not exist.
[TPEPROTO]
tpdeq_ctl() was called inappropriately.
[TPESYSTEM]
An error occurred in the Tmax system. Detailed information is recorded in the log file.
[TPEOS]
An error occurred in the operating system.
-
Example
#include <stdio.h> #include <unistd.h> #include <stdlib.h> #include <string.h> #include <usrinc/atmi.h> #include <usrinc/tmaxapi.h> main(int argc, char *argv[]) { char *sndbuf, *rcvbuf; long rcvlen, sndlen, revent; int ret, i, cd; TMQCTL *ctl; ctl = (TMQCTL*)malloc(sizeof(TMQCTL)); memset(ctl, 0, sizeof(TMQCTL)); if (argc != 2) { printf(“Usage: toupper_rq string\n”); exit(1); } if ( (ret = tmaxreadenv( “tmax.env”,”TMAX” )) == -1 ){ printf( “tmax read env failed\n” ); exit(1); } if (tpstart((TPSTART_T *)NULL) == -1){ printf(“tpstart failed\n”); exit(1); } if ((sndbuf = (char *)tpalloc(“STRING”, NULL, 0)) == NULL) { printf(“sendbuf alloc failed !\n”); tpend(); exit(1); } if ((rcvbuf = (char *)tpalloc(“STRING”, NULL, 0)) == NULL) { printf(“recvbuf alloc failed !\n”); tpfree((char *)sndbuf); tpend(); exit(1); } ret = tx_begin(); if(ret < 0) { fprintf(stderr, “tx_begin() fail\n”); tpfree((char *)sndbuf); tpfree((char *)rcvbuf); exit(1); } strcpy(sndbuf, argv[1]); cd = tpdeq_ctl(“txrq1”, “TOUPPER”, ctl, &rcvbuf, &rcvlen, TPRQS ); if (cd < 0) { printf(“tpdeq failed [%s]\n”, tpstrerror(tperrno) ); tpfree((char *)sndbuf); tpfree((char *)rcvbuf); tpend(); exit(1); } cd = tpdeq_ctl(“txrq1”, “TOUPPER”, ctl, &rcvbuf, &rcvlen, TPRQS ); if (cd < 0) { printf(“tpdeq failed [%s]\n”, tpstrerror(tperrno) ); tpfree((char *)sndbuf); tpfree((char *)rcvbuf); tpend(); exit(1); } data process.... ret = tx_commit(); if(ret < 0) { fprintf(stderr, “tx_commit() fail\n”); tpfree((char *)sndbuf); tpfree((char *)rcvbuf); tx_rollback(); exit(1); } tpfree((char *)sndbuf); tpfree((char *)rcvbuf); tpend(); } -
Related functions
tpenq_ctl(), tpqstat()
4. Other APIs
4.1. compute_rq_deqtime
When specifying the 'deq_time' value in the AnyLink gateway, it must be reset whenever an RQ shutdown occurs to prevent delays. However, the AnyLink gateway cannot detect RQ shutdowns or startups, so it cannot readjust 'deq_time' automatically. Additionally, if the AnyLink gateway itself is shut down, the 'deq_time' setting is reset, which may cause the processing order to be lost.
The compute_rq_deqtime function allows the 'deq_time' setting to be configured in the RQ rather than in the AnyLink gateway. Because the RQ cannot determine 'deq_time' on its own, a callback function must be invoked to call the AnyLink library and configure the setting.
Set the following to the RQS environment variable.
RQ_DEQTIME_CALLBACK=libanme.so
This setting executes dlopen to open the specified library and invokes the callback function to apply the deq_time setting.
-
Prototype
int compute_rq_deqtime(TMQCTL *ctl, char *dp, int datasize);
-
Parameter
Parameter Description ctl
-
* deq_time : The function must be implemented so that this value can be stored within the structure. (Unit: seconds)
dp
Pointer to the message content to be checked.
datasize
Length of the message.
-
-
Return Value
Value Description 1
The deq_time was successfully calculated.
0
The magic number in the AnyLink header was not found in the data provided by the callback function, or it did not match. (This indicates that the RQ was likely called by a service other than the AnyLink engine.)
-1
An error occurred during the operation.
-
Related functions
tpenq_ctl(), tpenq()