Client API

This chapter describes the APIs used in client program development.

1. Overview

The following is a list of APIs available for client program development. For more information about the functions, refer to Tmax Reference Guide.

  • Connection and Disconnection

    API Description

    tpstart

    Connects client to the Tmax system.

    tpend

    Disconnects client from the Tmax system.

  • Synchronous Communication

    API Description

    tpcall

    Sends a service request through synchronous communication and waits for the response.

  • Asynchronous Communication

    API Description

    tpacall

    Sends a service request message and directly returns without waiting for a result.

    tpgetrply

    Receives a reply for the service that was requested through the tpacall() function.

    tpcancel

    Cancels the reply from the server and client.

  • Interactive Communication

    API Description

    tpconnect

    Establishes a connection and starts communication.

    tpsend

    Sends a message from the connection controller.

    tprecv

    Receives a message from the connection controller.

    tpdiscon

    Server and client closes the interactive communication connection.

  • Unrequests Message Processing

    API Description

    tpsetunsol

    Used by the client to set the routine that processes unsolicited messages.

    tpgetunsol

    Processes unsolicited messages.

  • Timeout Change

    API Description

    tpset_timeout

    Used by the client and server to set the blocking timeout.

    tpsetsvctimeout

    Called within a service to set the service timeout.

  • Bufffer Management

    API Description

    tpalloc

    Used by the client and server to allocate a buffer.

    tprealloc

    Used by the client and server to reallocate a buffer.

    tpfree

    Used by the client and server to release the memory allocated to the buffer.

    tptypes

    Used by the client and server to provide information about the buffer type and sub-type.

  • Transaction Management

    API Description

    tx_begin

    Used by the client and server to start a global transaction.

    tx_commit

    Used by the client and server to commit a transaction.

    tx_rollback

    Used by the client and server to roll back a transaction.

    tx_set_transaction_timeout

    Used by the client and server to set the transaction_timeout property with a timeout value.

    tx_set_transaction_control

    Used by the client and server to set the transaction_control property with a control value.

    tx_set_commit_return

    Used by the client and server to set the commit_return property.

    tx_info

    Used by the client and server to return the global transaction information.

  • RQ System

    API Description

    tpenq

    Used by the client and server to store data in RQ.

    tpdeq

    Used by the client and server to load data from RQ.

    tpqstat

    Used by the client and server to request the statistics of the data stored in RQ.

    tpextsvcname

    Used by the client and server to extract the service name of data that is read from the RQ using tpdeq.

  • APIs using Events

    API Description

    tpsubscribe

    Used by the client and server to register a request for the message of a specific event.

    tpunsubscribe

    Used by the client and server to unregister the request for the message of a specific event.

    tppost

    Used by the client and server to generate a specific event and send a message.

  • Broadcast/Multicast

    API Description

    tpbroadcast

    Used by the client and server to send an unsolicited message to other clients.

  • Windows Environment Programming

    • tmaxmt.dll

      API Description

      WinTmaxAcall

      Connects to Tmax to request a service, replies to the Windows procedure with the result, and then closes the connection.

      WinTmaxAcall2

      Connects to Tmax to request a service and receives the reply with a callback function.

    • WinTmax.dll

      API Description

      WinTmaxStart

      Creates a thread to process a message and initializes the used memory.

      WinTmaxEnd

      Closes the thread that processed a message and releases the used memory.

      WinTmaxSetContext

      Sets the Windows and message number to send data received by Tmax.

      WinTmaxSend

      Allows a client to call a service and process other jobs immediately.

  • Multithread/Multicontext API

    API Description

    tpgetctxt

    Returns the current context.

    tpsetctxt

    Sets the current context.

2. Connection and Disconnection

The following describes functions that are used to connect to Tmax and disconnect from Tmax.

2.1. tpstart

The tpstart function connects a client to a Tmax system. Before using ATMI functions to process service requests or transactions, a client must call tpstart() to establish a connection.

If another ATMI function (e.g., tpalloc() or tpcall()) is called before tpstart(), a tpstart(NULL) is invoked internally by default. To disable this automatic behavior, set the TMAX_ACTIVATE_AUTO_TPSTART environment variable to N. In this case, calling another ATMI function without first calling tpstart() will result in a TPEPROTO error.

After a successful tpstart(), the client can send initial service requests or define a transaction. Calling tpstart() again after a successful connection will also result in a TPEPROTO error.

To use tpstart(), the IP address and port number of the server hosting the Tmax system must be provided.

The following describes environment variables required to find the server information:

Variable Description

TMAX_HOST_ADDR

The IP address of the node to which a client will connect. This variable is used by the client to establish an internal connection to the server when tpstart() is called.

TMAX_HOST_PORT

The port number of the node to which a client will connect. This variable is used together with TMAX_HOST_ADDR to establish an internal connection to the server when tpstart() is called.

The value of TMAX_HOST_PORT must match the TPORTNO setting in the Tmax configuration file. When both the client and server reside on the same node, using a domain socket is more efficient than a TCP/IP socket. In this case, specify PATHDIR instead of the value defined in TPORTNO. See the TPORTNO setting in the DOMAIN and NODE sections of the Tmax configuration file.

TMAX_BACKUP_ADDR

The IP address of a backup Tmax node to be used if the main system (TMAX_HOST_ADDR) fails.

By default, the client first attempts to connect to the Tmax system using TMAX_HOST_ADDR. If this connection fails, the client automatically tries to connect to the backup node configured with TMAX_BACKUP_ADDR.

TMAX_BACKUP_PORT

The port number of the backup node configured with TMAX_BACKUP_ADDR.

TMAX_CONNECT_TIMEOUT

The timeout period for the client to attempt a connection to the Tmax system, specified in microseconds. (For example: 3500000 for 3.5 seconds)

The following shows how to use the function with an example.

  • Prototype

    #include <atmi.h>
int tpstart (TPSTART_T *tpinfo )

  • Parameter

    tpinfo is a pointer to a TPSTART_T structure. This structure uses the TPSTART buffer type, which must be allocated with tpalloc() before calling tpstart(). It is recommended to free the allocated buffer with tpfree() after tpstart() is called. The client uses tpinfo to transfer necessary information when connecting to the system. A tpinfo structure contains client information, notification message handling state, and security information.

    tpinfo can also be set to NULL. In this case, the string lengths for cltid, dompwd, usrname, and usrpwd are set to 0. As a result, Tmax security features are not used, and flags are not applied.

    The following shows the TPSTART_T structure:

    struct TPSTART_T{
      char cltid[MAXTIDENT+2];  /*client name (tpbroadcast())*/
      char dompwd[MAX_PASSWD_LENGTH+2];  /*password for system access security*/
      char usrname[MAXTIDENT+2];   /*account for user authentication security*/
      char usrpwd[MAX_PASSWD_LENGTH+2]; /*password for user authentication sercurity*/
      int flags; /*flag for unsolicited message types and system access methods*/
} ;
    Member Description

    cltid

    A NULL-terminated string up to 30 characters long. Defined by the application, cltid specifies the client to which tpbroadcast() sends unsolicited messages.

    dompwd

    Controls system access according to Tmax security steps. It registers a password for an account set in the OWNER item of the DOMAIN section in the Tmax configuration file.

    usrname

    Used for user authentication in Tmax security steps. Must be an account registered in the passwd file of the Tmax system.

    usrpwd

    The password for the account. When user authentication is enabled, registering a usrname and usrpwd allows the client to connect to the Tmax system and use its services. See the SECURITY item in the DOMAIN section of the Tmax configuration file for details.

    flags

    Option to enable specific features in the client when connecting to the Tmax system.

    The following flags are available.

    • TPUNSOL_POLL

      Receives unsolicited messages.

    • TPUNSOL_HND

      Specifies a function to receive unsolicited messages. For more information, see tpsetunsol.

    • TPUNSOL_IGN

      Ignores unsolicited messages. This is the default setting if no other default is specified.

    • TPMULTICONTEXTS

      Must be set to enable multi-thread or multi-context capabilities.

  • Return Value

    Return Value Description

    0 or 1

    The function call succeeded. The primary host receives 0, and the backup host gets 1.

    -1

    The function call failed. An error code is set in tperrno.

  • Error

    If tpstart() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, tpinfo is NULL or is not a pointer to a TPSTART_T structure.

    [TPEITYPE]

    tpinfo is not a pointer to a TPSTART_T structure.

    [TPEPROTO]

    tpstart() was called under an inappropriate condition. For example, it was used on a server program or recalled while the connection was already established.

    [TPESYSTEM]

    An error occurred in the Tmax system. Detailed information is recorded in the log file.

    [TPEOS]

    An error occurred in the operating system, or an invalid environment variable was set. For example, TMAX_HOST_ADDR or TMAX_HOST_PORT was incorrectly set, causing connection to fail.

  • Example

    #include <stdio.h>
#include <usrinc/atmi.h>
void main(int argc, char *argv[])
{
    int ret;
    char *buf;
    long len;
    TPSTART_T  *tpinfo;

    tpinfo = (TPSTART_T *)tpalloc(“TPSTART”, NULL, sizeof(TPSTART_T));
    if (tpinfo==NULL) { error processing }

    strcpy(tpinfo->cltname, “cli1”);
    strcpy(tpinfo->usrname, “navis”);
    strcpy(tpinfo->dompwd, “tmax”);
    tpinfo->flags = TPUNSOL_HND;
    ret=tpstart(tpinfo);
    if (ret==-1) { error processing }

    buf = (char *)tpalloc(“CARRAY”, NULL, 20);
    if (buf==NULL) {error processing };

    ret=tpcall(“SERVICE”, buf, 20, &buf, &len, TPNOFLAGS);
    if (ret==-1) { error processing }

    data process....
    tpfree((char *) buf);
    tpend();
}

  • Related function

    tpend()

2.2. tpend

The tpend function disconnects a client from the Tmax system. If the client is in transaction mode, the transaction is automatically rolled back. When tpend() successfully returns, the caller can no longer communicate with any program, or participate in transactions. Any interactive service in progress is immediately terminated.

If tpend() is called more than once (i.e., after the client has already disconnected), it returns -1, but this has no effect on the system.

For multi-thread client libraries, the behavior of tpend() is changed starting from the version Tmax 5 SP2 Fix2, as follows:

In setups where a single context is shared by multiple threads via the tpsetctxt() API, tpend() can be called even if other threads sharing the context have not called tpsetctxt(TPNULLCONTEXT). To delete a created context correctly, follow these rules:

  1. Delete the context by explicitly calling tpend() from the thread that most recently used it.

  2. If the context is shared among multiple threads, and all threads call tpsetctxt(TPNULLCONTEXT) after tpend() has been called, the context is implicitly deleted.

In other words, if tpend() has been called at least once for the context, calling tpsetctxt(TPNULLCONTEXT) from all threads sharing the context will delete it. If tpend() has not been called for the context, the context is not deleted and remains connected, even if no other threads share it.

The following shows how to use the function with an example.

  • Prototype

    # include  <atmi.h>
int  tpend (void)

  • Return Value

    Return Value Description

    -1

    The function call failed. An error code is set in tperrno.

  • Error

    If tpend() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEPROTO]

    tpend() was called under an inappropriate condition. For example, the function was called by a server or invoked after the connection had already been terminated.

    [TPESYSTEM]

    An error occurred in the Tmax system. Detailed information is recorded in the log file.

    [TPEOS]

    An error occurred in the operating system.

    [TPEPROTO]

    For a client in a multi-thread setup, another thread sharing the context is currently using it. When this error occurs, the context allocation on that thread is freed, but other threads can continue using the context.

    Additionally, if a thread using the context calls tpend() or tpsetctxt(TPNULLCONTEXT), the connection is automatically terminated.

  • Example

    #include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <usrinc/atmi.h>

void main(int argc, char *argv[])
{
    char    *sndbuf, *rcvbuf;
    long    rcvlen, sndlen;
    int     ret;

    ret=tpstart((TPSTART_T *)NULL)
    if (ret==-1) {error processing }

    buf = (char *)tpalloc(“STRING”, NULL, 0)
    if (buf=NULL) { error processing }

    data process …

    ret=tpcall(“SERVICE”, buf, 0, &buf, &len, TPNOFLAGS);
    if (ret==-1) { error processing }

    data process …
    printf(“ data: %s\n”, buf);
    tpfree((char *)buf);
    tpend();
}

  • Related functions

    tpstart(), tpgetctxt(), tpsetctxt()

3. Synchronous Communication

The following describes functions that are used for synchronous communication.

3.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.

    1. tpalloc() or malloc() failed.

    2. realloc() failed.

    3. 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()

4. Asynchronous Communication

The following describes functions that are used for asynchronous communication.

4.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.

    1. tpalloc() or malloc() failed.

    2. realloc() failed.

    3. 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()

4.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()

4.3. tpcancel

The tpcancel function cancels a server or client response. It cancels cd, a caller description, returned by tpacall().

  • Prototype

    # include <atmi.h>
int tpcancel (int cd)

  • Parameter

    Parameter Description

    cd

    The target to be canceled, which is set by a caller descriptor returned by a tpacall(). Services related to global transactions cannot be canceled. If a service response is canceled, a cd is nullified and all responses received through the cd are ignored.

  • Return Value

    Value Description

    -1

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tpcancel() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEBADDESC]

    An invalid cd.

    [TPETRAN]

    The cd is related to the caller’s global transaction. It is still valid and the caller’s current transaction is not affected.

    [TPEPROTO]

    tpcancel() 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>
void main(int argc, char *argv[])
{
    char *test[2];
    int ret, i, cd[2];
    long len;

    if (argc != 4) { error processing }
    ret=tpstart((TPSTART_T *)NULL;
    if (ret==-1) { error processing }

    for (i=0; i<3; i++)
    {
        test[i] = tpalloc(“STRING”,NULL,0);
        if (test[I])==NULL} { error processing }
        strcpy(test[i],argv[i+1]);
        cd[i]=tpacall(“SERVICE”, test[i], 0, TPNOTIME);
    )

    ret=tpcancel(cd[1]);         /* Cancel the second response. */
    if (ret==-1) { error processing }
    for (i=0; i<3; i++)
    {
        ret=tpgetrply(&cd[i], (char **)&test[i], &len, TPNOTIME)
        if (ret==-1) printf(“Can’t rcv data from service of %d\n”,cd[i]);
        else prtinf(“%dth rcv data : %s\n”, I+1, test[I]);
        tpfree(test[I]);
    }
    tpend();
}

  • Related function

    tpacall()

5. Interactive Communication

The following describes functions that are used for interactive communication.

5.1. tpconnect

The tpconnect function allows a program to communicate with an interactive service. Communication is half-duplex, which only allows receiving or sending but not both at the same time. During a connection configuration process, a function caller can deliver data to a service routine. Interactive services receives data and len using a TPVCINFO structure, so calling tprecv() is unnecessary to receive data delivered by tpconnect(). This function can be used on both the client and the server.

  • Prototype

    # include  <atmi.h>
int  tpconnect (char  *svc,  char  *data,  long  len,  long  flags)

  • Parameter

    Parameter Description

    svc

    The name of an interactive service.

    data

    A pointer to service request data. Must be a buffer allocated in advance by tpalloc(). The type and subtype of the data must be supported by the specified svc.

    len

    The length of the data to be sent.

    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 no data is sent to the interactive service.

    flags

    The following flags are available.

    • TPNOTRAN

      If the caller requests a service by setting this flag in transaction mode, the service will be excluded from transaction mode before being executed.

      If a service does not support transactions in transaction mode, the TPNOTRAN flag must be set in order to call tpconnect() in transaction mode. When calling tpconnect() in transaction mode, it will still be affected by the transaction timeout (TXTIME) even if TPNOTRAN was set.

      If a service called with TPNOTRAN fails, the caller’s current transaction will not be affected.

    • TPSENDONLY

      After the connection is established, the caller can only send the initial data and start the requested service. In this mode, the caller has initial control over the communication. Either TPSENDONLY or TPRECVONLY must be set.

    • TPRECVONLY

      After the connection is established, the caller can only receive data initially, while the requested service sends the initial data. In this mode, the requested service has initial control over the communication. Either TPSENDONLY or TPRECVONLY must be set.

    • TPNOTIME

      The caller ignores the block timeout and waits indefintely for the response. If tpconnect() is called 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

    Descriptor

    The function call succeeded and returns the descriptor to be referenced for a future connection.

    -1

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tpconnect() fails, one of the following codes is set in tperrno. The caller’s transaction will not be affected unless there is a specific direction.

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the specified service (svc) and data is NULL, the data points to a buffer that was not allocated by tpalloc(), neither TPSENDONLY nor TPRECVONLY was set, or an invalid flag was set.

    [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.

    [TPELIMIT]

    The number of connections has reached the limit, so the caller’s request cannot be sent.

    [TPETRAN]

    xa_start failed because an error occurred in the database while calling 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. 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]

    tpconnect() was called in an invalid state.

    [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>

void main(int argc, char *argv[])
{
    char *buf;
    int ret, cd;
    long len, revent;

    ret=tpstart((TPSTART_T *)NULL);
    if (ret==-1) { error processing }

    buf=tpalloc(“STRING”,NULL,0);
    if (buf=NULL) { error procesing }

    data process ....

    cd = tpconnect(“SERVICE”,sndbuf,0,TPRECVONLY);
    if (cd==-1) { error processing }
    data process....

    ret=tprecv(cd, &buf, &len, TPNOFLAGS, revent);
    if (ret==-1) { error processing }
    tpfree(buf);
    tpend();
}

  • Related functions

    tpalloc(), tpdiscon(), tprecv(), tpsend()

5.2. tpsend

The tpsend function sends data to a peer program in an interactive communication. It is available on both servers and clients. The caller must have control over the communication.

  • Prototype

    # include <atmi.h>
int  tpsend (int  cd,  char  *data,  long  len,  long  flags,  long  *revent)

  • Parameter

    Parameter Description

    cd

    Sets a connection to send data. It is the descriptor returned by tpconnect() or a TPSVCINFO parameter.

    data

    A buffer allocated by tpalloc(). If no application data is received (for example, only the communication control was passed without data), data can be NULL. The data type and its subtype must be recognizable by a connected peer.

    len

    The length of the send buffer. If data points to a buffer that does not require a specified length, len is ignored, and 0 is used by default. If data points to a buffer that requires a specified length, len cannot be 0.

    flags

    The following flags are available.

    • TPNOBLOCK

      If a blocking condition occurs (for example, when the internal buffer is full), no data or events are sent. If tpsend() is called without the TPNOBLOCK flag and a blocking condition occurs, the caller waits until the timeout expires (transaction or block timeout) or the condition is resolved.

    • TPNOTIME

      The caller waits for the response indefinitely, ignoring the block timeout. If tpsend() is executed within the transaction timeout period, the transaction timeout still applies.

    • TPRECVONLY

      The caller initially receives control over the communication. After sending data, control is passed to the peer. While the peer holds control, the caller cannot call tpsend(). The peer receives a TPEV_SENDONLY event, indicating it now has control while receiving data via tprecv(). The peer cannot call tprecv() again until it returns control to the original caller.

    • 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.

    revent

    If an event for the communication descriptor (cd) exists, tpsend() fails and no data is sent. The event type is returned as revent.

    The following events can be returned in revent.

    • TPEV_DISCONIMM

      The communication starter used tpdiscon() to forcefully terminate the connection. This event is received by the communication subordinate.

      This event is also returned when a connection is terminated due to a communication error such as a server, node, or network error.

    • TREV_SVCERR

      This event, received by the communication starter, indicates that the communication subordinate executed tpreturn() without control over the communication.

    • TREV_SVCFAIL

      This event, received by the communication starter, indicates that the communication subordinate executed tpreturn() with TPFAIL and no data (rval = TPFAIL, data = NULL), and did not have control over the communication.

  • Return Value

    If revent is TREV_SVCFAIL, the global variable tpurcode is set to the value of rcode , which is passed when tpreturn() is called.

    Value Description

    0

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tpsend() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the buffer pointed to by data was not allocated by tpalloc() or the flag is invalid.

    [TPEBADDESC]

    The descriptor (CD) is invalid.

    [TPETIME]

    A timeout occurred. If the caller was not in transaction mode and neither TPNOTIME nor TPNOBLOCK was set, a block timeout occurred. In both cases, *data and len remain unchanged. When a transaction timeout occurs, all operations—including sending or receiving messages through interactive communication or starting a new connection—will fail with the [TPETIME] error.

    [TPEEVENT]

    An event occurred. If an error occurs, data will not be sent and an event type will be returned as a revent.

    [TPEBLOCK]

    A blocking condition occurred while TPNOBLOCK is set.

    [TPGOTSIG]

    A signal was received while TPSIGRSTRT was not set. On SUN systems, the function will not fail but wait for the response up to the specified time period even if a signal interrupt occurs.

    [TPEPROTO]

    tpsend() was called under an inappropriate condition. For example, it may have been used in sender mode or called before tpstart() was executed.

    [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 “../sdl/demo.s”

main(int argc,char* argv[])
{
    int ret, cd;
    struct dat *buf;
    long revent, len;

    if (argc!=3) {error processing }
    ret=tpstart((TPSTART_T *)NULL);
    if (ret==-1) { error processing }

    buf=(struct dat *)tpalloc(“STRUCT”, “dat”, 0);
    if (buf==NULL) { error processing }
    strcpy(buf->sdata, argv[1]);
    data process….

    cd=tpconnect(“SERVICE”, buf, 0, TPSENDONLY);
    if (cd==-1) { error processing }
    strcpy(buf->sdata, argv[2]);
    data process….

    ret=tpsend(cd, buf, 0,TPRECVONLY,&revent);
    if (ret==-1) { error processing }

    ret=tprecv(&cd,(char**)&buf,&len,TPNOTIME,&revent);
    if (ret==-1) { error processing }
    data process....

    tpfree(buf);
    tpend();
}

  • Related functions

    tpalloc(), tpconnect(), tpdiscon(), tprecv(), tpreturn()

5.3. tprecv

The tprecv function receives messages in an interactive communication, and is available both on servers and clients. This is used to receive data sent from the peer in an interactive communication. tprecv() can be used only by a server or client program that does not have control over the communication.

  • Prototype

    # include <atmi.h>
int  tprecv (int cd, char **data, long *len, long flags, long *revent)

  • Parameter

    Parameter Description

    cd

    Sets a connection to receive data. This is a descriptor returned either by tpconnect() or a parameter of TPSVCINFO.

    data

    A pointer to the buffer previously allocated by tpalloc(). If the function successfully returns, *data points to the received data.

    len

    The length of the data.

    If len is larger than the total size of the buffer before the call, len becomes the new size of the buffer.

    If len is 0, no data was received, and *data (the buffer pointed to by *data) remains unchanged. If *data or len is NULL, an error occurs.

    flags

    The following flags are available.

    • TPNOCHANGE

      If the received response buffer and the buffer type that *data points to are not the same, the buffer type of *data will be changed to the received response buffer type in the scope that the receiver can recognize. If the TPNOCHANGE flag is set, the buffer type that a *data points to will not be changed. A received response buffer type and subtype must be the same with those of the buffer that a *data points to.

    • TPNOBLOCK

      Does not wait for a response. If a response arrives and data is available, it will be returned. If TPNOBLOCK is not set and no response is available, the caller will wait until the response is received.

    • TPNOTIME

      The caller waits indefinitely for a response, ignoring the block timeout. However, if tprecv() is called 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.

    revent

    The following describes event types that are returned to revent:

    • TPEV_DISCONIMM

      The communication starter used tpdiscon() to forcefully terminate a connection. This event is received by a communication subordinate.

      This event is also returned when a connection is terminated due to a communication error such as a server, node, or network error. Any data being sent may be lost.

      If two programs participate in the same transaction, the transaction will be rolled back. The cd used for the interactive communication will not be valid.

    • TPEV_SENDONLY

      The peer program has relinquished control over the communication.

      A TPEV_SENDONLY event receiver can send data but cannot receive data until control is returned.

    • TPEV_SVCERR

      This event notifies the communication starter of an error that occurred while the communication subordinator executed tpreturn(). The error may occur if an invalid parameter is passed to tpreturn(), or if tpreturn() is called while the service maintains a connection to another subordinator. In such cases, the return code or part of the data cannot be used. The interactive connection will be terminated, and the cd will no longer be valid. If this event occurs during a receiver’s transaction, the transaction will be rolled back.

    • TPEV_SVCFAIL

      This event notifies the communication starter that the service of a communication subordinator was terminated due to a failure. tpreturn() was called with TPFAIL as an argument.

      If the subordinator service has control over the communication when calling tpreturn(), it cannot send data to a connected peer.

      The server process terminates the interactive connection when the service ends. Therefore, the cd will no longer be valid. If this event occurs during a receiver’s transaction, the transaction will be rolled back.

    • TPEV_SVCSUCC

      This event notifies the communication starter that the service of the peer communication subordinator was successfully terminated. tpreturn() was called with TPSUCCESS.

  • Return Value

    If the value of revent is TREV_SVCSUCC or TREV_SVCFAIL, the tpurcode global variable delivered by tpreturn() will be defined by the application. Otherwise, tpurcode returns -1, and tperrno is set to the value corresponding to the error condition. If an event does not indicate an error, tprecv() returns -1, and tperrno is set to [TPEEVENT].

  • Errors

    If tprecv() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEBADDESC]

    The descriptor (CD) is invalid.

    [TPEBLOCK]

    A blocking condition occurred while TPNOBLOCK is set.

    [TPEEVENT]

    An event occurred, and its type is indicated by revent.

    [TPEINVAL]

    The parameter is invalid. For example, the buffer pointed to by *data was not allocated by tpalloc() or the flag is invalid.

    [TPEOS]

    An error occurred in the operating system.

    [TPEOTYPE]

    The specified buffer type or its subtype is unknown to the caller, or when the TPNOCHANGE flag is set, the *data type and its subtype do not match those of the specified buffer. In this case, both *data and *len remain unchanged. If the interactive communication is part of a transaction, the transaction will be rolled back because the operation is ignored.

    If this error occurs, the event for the cd is ignored, and the interactive communication status is not guaranteed. Therefore, the caller must close the interactive communication.

    [TPEPROTO]

    tprecv() was called in an inappropriate condition. For example, it may have been used in sender mode or called before tpstart() was executed.

    [TPESYSTEM]

    An error occurred in the Tmax system. Detailed information is recorded in the log file.

    [TPETIME]

    A timeout occurred. If the caller was not in transaction mode and neither TPNOTIME nor TPNOBLOCK was set, a block timeout occurred. In both cases, *data and len remain unchanged. When a transaction timeout occurs, all operations—including sending or receiving messages through interactive communication or starting a new connection—will fail with the [TPETIME] error.

    [TPGOTSIG]

    A signal was received while TPSIGRSTRT was not set. On SUN systems, the function will not fail but wait for the response up to the specified time period even if a signal interrupt occurs.

  • Example

    #include <stdio.h>
#include <usrinc/atmi.h>
#include “../sdl/demo.s”

main(int argc,char* argv[])
{
    int ret, cd;
    struct dat *buf;
    long revent, len;

    if (argc!=3) {error processing }
    ret=tpstart((TPSTART_T *)NULL);
    if (ret==-1) { error processing }

    buf=(struct dat *)tpalloc(“STRUCT”, “dat”, 0);
    if (buf==NULL) { error processing }
    strcpy(buf->sdata, argv[1]);
    data process….

    cd=tpconnect(“SERVICE”, buf, 0, TPSENDONLY);
    if (cd==-1) { error processing }
    strcpy(buf->sdata, argv[2]);
    data process….

    ret=tpsend(cd, buf, 0,TPRECVONLY,&revent);
    if (ret==-1) { error processing }

    ret=tprecv(cd,(char**)&buf,&len,TPNOTIME,&revent);
    if (ret==-1) { error processing }
    data process....

    tpfree(buf);
    tpend();
}

  • Related functions

    tpalloc(), tpconnect(), tpdiscon(), tpsend()

5.4. tpdiscon

The tpdiscon() function terminates an interactive communication connection. If a service is connected via tpconnect(), in rare cases the connection may terminate immediately, generating a TPEV_DISCONIMM event for the connection partner. This function can be used on both the client and the server.

tpdiscon() can be called only by the side that initiated the interactive communication. A service that provides a descriptor cannot call tpdiscon(). Programs communicating with an interactive service can terminate the connection, but to ensure correct results, tpreturn() should be called to close the connection cleanly.

tpdiscon() forcibly terminates the connection. Any data that has not yet reached the target may be lost. It can be called while the connected program participates in a transaction. In this case, the transaction is canceled, and data may be lost. The caller does not need to have communication control to invoke tpdiscon().

  • Prototype

    # include  <atmi.h>
int  tpdiscon (int cd)

  • Parameter

    Parameter Description

    cd

    The descriptor returned by tpconnect() for reference.

  • Return Value

    Value Description

    -1

    The function call failed. An error code is set in tperrno.

  • Errors

    If tpdiscon() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEBADDESC]

    The cd is invalid, or it is already in use for the interactive service.

    [TPETIME]

    A timeout occurred. The cd is no longer valid.

    [TPEPROTO]

    tpdiscon() was called inappropriately. For example, the function was called without first executing tpstart().

    [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 <stdlib.h>
#include <usrinc/atmi.h>

void main(int argc, char *argv[])
{
    int ret, cd;
    char *buf
    long len, revent;

    ret=tpstart((TPSTART_T *)NULL);
    if (ret==-1) { error processing }

    buf=tpalloc(“STRING”, NULL, 0);
    if (buf==NULL) { error processing }

    data process....
    cd=tpconnect(“SERVICE”,buf,0,TPRECVONLY);

    if (cd==-1) { error processing }
    data process....
    ret=tprecv(cd, (char **)&buf, &len, TPNOFLAGS, &revent);
    if (ret==-1 && revent != TPEV_SENDONLY && revent != TPEV_SVCSUCC)
    { error processing }
    printf(“received data = %s\n”, buf);
    if (atoi(buf)>90) {
        ret=tpdiscon(cd);
        if (ret==-1) {error processing }
        tpfree(buf);
        tpend();
        exit(1);
    }

    data process....
    tpfree(buf);
    tpend();
}

  • Related functions

    tpconnect(), tprecv(), tpreturn(), tpsend()

6. Unsolicited Message Process

These functions are used to send messages unilaterally or to process messages received unilaterally. Not all clients can always receive unsolicited messages (tpbroadcast()) sent by a server. To receive an unsolicited message, the client must be connected to Tmax. When connecting to Tmax, the client must notify the server that it can receive unsolicited messages.

For Tmax to handle data that is sent from a server unilaterally, the flags field of the TPSTART_T structure, which is used when calling tpstart(), must be set to TPUNSOL_POLL or TPUNSOL_HND.

6.1. tpsetunsol

The tpsetunsol function configures a routine to handle unsolicited messages. It is used on the client-side. How unsolicited messages are handled is determined by the application and can be customized by each client.

Before tpsetunsol() is called for the first time, any unsolicited messages received by the Tmax library are ignored. A call to tpsetunsol() with a NULL parameter pointer is also ignored. The function pointer passed must conform to the required parameter definition.

  • Prototype

    # include  <atmi.h>
Unsolfunc *tpsetunsol (void ( *disp ) ( char  *data,  long  len,  long  flags ) )

  • Parameter

    Parameter Description

    data

    Points to a received type buffer. If there is no data, it can be NULL. If the buffer type or subtype for data is unknown to the client, data cannot be recognized. The application cannot delete data, but the system can delete it and nullify the data area to return.

    len

    The length of the data.

    flags

    Currently not used.

  • Return Value

    Return Value Description

    Pointer / NULL

    The function call succeeded.

    • Pointer : Returns the existing pointer to the unsolicited message handling routine.

    • NULL : Indicates that no handling function has been configured. This is also considered a successful return.

    TPUNSOLERR

    The function call failed. An error code is set in tperrno.

  • Error

    If tpsetunsol() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEPROTO]

    tpsetunsol() 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 “../sdl/demo.s”

void get_unsol(char *data, long len, long flags)
{
    printf(“get unsolicited data = %s\n”, data);
    data process....
}

void main(int argc, char *argv[])
{
    int ret;
    char *buf;
    long len;

    ret=tpstart((TPSTART_T *)NULL);
    if (ret==-1) { error processing }
    ret=tpsetupsol_flag(TPUNSOL_HND);
    if (ret==-1) { error processing }

    ret=tpsetunsol(get_unsol);
    if (ret==TPUNSOLERR) { error processing }

    buf = (char *)tpalloc(“CARRAY”, NULL, 20);
    if (buf==NULL) {error processing };
    data process...

    ret=tpcall(“SERVICE”, buf, 20, (char **)&buf, &len, TPNOFLAGS);
    if (ret==-1) { error processing }
    data process...

    tpfree((char *)buf);
    tpend();
}

  • Related functions

    tpstart(), tpend(), tpgetunsol()

6.2. tpgetunsol

The tpgetunsol() function handles unsolicited messages, which are sent unilaterally without a client request. These messages can be sent via tpbroadcast(), tpsendtoci(), or tppost() executed by the sender.

Any unsolicited messages sent before tpgetunsol() is executed are ignored. To receive unsolicited messages through tpgetunsol(), the TPUNSOL_POLL or TPUNSOL_HND flag must be set when connecting to the Tmax system via tpstart(). When tpgetunsol() is called, even if the tpstart() flag is set to TPUNSOL_IGN, it internally defaults to TPUNSOL_POLL, enabling reception of unsolicited messages from the server.

  • Prototype

    #include <tmaxapi.h>
int  tpgetunsol (int type, char **data, long *len, long flags)

  • Parameter

    Parameter Description

    type

    The type of the message sent by the server. One of UNSOL_TPPOST, UNSOL_TPBROADCAST, or UNSOL_TPSENDTOCLI.

    data

    A pointer to the received message. It may be an unknown buffer type or subtype, in the case of which the data cannot be sent.

    len

    The total length of the message.

    flags

    Option to enable blocking.

    The following flags are available:

    • TPBLOCK

      Waits for unsolicited messages in block state when calling tpgetunsol().

    • TPNOCHANGE

      If the received response buffer does not match the buffer pointed to by *data, the pointer will be updated to reference the received buffer, within the allowable range recognized by the receiver.

      If this flag is set, the type of the buffer pointed to by *data cannot be changed. The type and subtype of the received response buffer must match those of the buffer pointed to by *data.

    • TPNOTIME

      The caller waits for the response indefinitely, ignoring the block timeout. If tpgetrply() is executed in transaction mode, the transaction timeout still applies.

    • TPSIGRSTRT

      Allows signal interrupts. When a system function call is interrupted, the call is automatically retried. If a signal interrupt occurs while this flag is not set, the function call fails and tperrno is set to TPGOTSIG.

    • TPGETANY

      Returns the first available response, ignoring the input call descriptor (cd). The returned response’s call descriptor is assigned to cd. If no response is available, tpgetrply() continues to wait by default.

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set in tperrno.

  • Error

    If tpgetunsol() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEPROTO]

    tpgetunsol() was called under an inappropriate condition. tpstart() was not executed and the TMAX_ACTIVATE_AUTO_TPSTART=N option was set.

    [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 <string.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=tpalloc(“STRING”, NULL, 0);
    if (buf==NULL) { error processing }
    data process....

    while(1)
    {
        ret=tp_sleep(2);
        if (ret==-1) { error processing }

        if (ret==0)
            printf(“nothing happened\n”);
        else {
            ret=tpgetunsol(UNSOL_TPSENDTOCLI, (char **)&buf, &len, TPNOCHANGE);
            if (ret==-1) { error processing }
            printf(“received data : %s\n”, buf);
        }

        data process....
        if (strncmp(buf, “end”, 3)==0) break;
    }

    data process....
    tpfree(buf);
    tpend();
}

  • Related functions

    tpbroadcast(), tpsetunsol(), tpstart(), tpend()

7. Timeout Change

The following describes functions that are used to change timeout.

7.1. tpset_timeout

The tpset_timeout function sets a block timeout, which is the maximum time a server waits for a service response. It is available on both servers and clients. If a timeout is set with tpset_timeout(), the caller waits up to the specified time for the response. If no response is received within that time, a timeout error occurs and the service request fails without waiting further.

The timeout applies to service requests made after tpset_timeout() is called. It remains in effect until tpset_timeout() is called again or the client/server process terminates. If tpset_timeout() is not used, the BLOCKTIME parameter in the Tmax configuration file is applied as the block timeout.

  • Prototype

    #include <tmaxapi.h>
int  tpset_timeout (int sec)

  • Parameter

    Parameter Description

    sec

    The block timeout in seconds.

  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tpset_timeout() fails, one of the following codes is set in tperrno.

    Error Code Description

    [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 *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=tpset_timeout(4);
    if (ret==-1) { error processing }

    ret=tpcall(“SERVICE”, sndbuf, sndlen, &rcvbuf, &rcvlen, TPNOCHANGE);
    if (ret==-1) { error processing }
    data process....

    tpfree((char *)sndbuf);
    tpfree((char *)rcvbuf);
    tpend();
}

7.2. tpsetsvctimeout

The tpsetsvctimeout() function sets the timeout period for a service registered on a server. When a service timeout is configured using tpsetsvctimeout(), the service timeout period is adjusted to the specified value (in seconds). If no response is received within this period, a timeout error occurs, and a service failure value is returned without waiting for the service response.

After tpsetsvctimeout() is called, the configured timeout applies regardless of the SVCTIMEOUT setting in the configuration file.

  • Prototype

    #include <tmaxapi.h>
int  tpsetsvctimeout (int sec, long flags)

  • Parameter

    Parameter Description

    sec

    The service timeout period in seconds.

    flags

    Currently not used.

  • Return Value

    Return Value Description

    0

    The function call succeeded.

    -1

    The function call failed. An error code is set in tperrno.

  • Error

    If tpsetsvctimeout() fails, one of the following codes is set in tperrno.

    Error Code Description

    [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 <stdlib.h>
#include <usrinc/tmaxapi.h>
#include <usrinc/tdlcall.h>

TOUPPER(TPSVCINFO *msg)
{
        int             i;

        if ( tpsetsvctimeout(10, 0) < 0 )
              ;
            //error handle code
        printf("TOUPPER service is started!\n");
        sleep(15);
        printf("INPUT : data=%s\n", msg->data);

        for (i = 0; i < msg->len; i++)
                msg->data[i] = toupper(msg->data[i]);
        printf("OUTPUT: data=%s\n", msg->data);
        tpreturn(TPSUCCESS,0,(char *)msg->data, 0,0);
}

8. Buffer Management

Because memory allocation methods and data types differ according to hardware and operating system, received data may have different data values. Therefore, in a general client/server environment, heterogeneous systems communicate through conversion, which creates network overhead.

The following describes APIs that are used for buffer management.

8.1. tpalloc

A server or client must allocate buffers using tpalloc(). Buffers cannot be managed with the standard C library functions malloc(), realloc(), or free(). For example, a buffer allocated with tpalloc() cannot be released with free()—tpfree() must be used instead.

The tpalloc() function allocates a typed buffer as specified by type and returns a pointer to it. For some types, a subtype and size can also be specified. Certain buffer types require initialization, which tpalloc() performs automatically, so the returned buffer can be used immediately. If initialization fails, the buffer is released.

Dynamic memory allocation through tpalloc() is limited to 1 GB.

  • Prototype

    # include <atmi.h>
char * tpalloc (char *type, char *subtype, long size)

  • Parameter

    Parameter Description

    type

    Buffer type. One of the following:

    • STRING: sends string-type data that ends with NULL.

    • CARRAY, X_OCTET: sends character-type data with a specified length.

    • STRUCT, X_C_TYPE: sends C-language structure type data.

    • X_COMMON: is used for C structures that allow only char, int, and long data types.

    • FDL(FIELD buffer): stores data with an identifier and a corresponding value.

    subtype

    For STRUCT, X_C_TYPE, and X_COMMON type buffers, a subtype must be set. Only the first 8 bytes of type and the first 16 bytes of subtype are used. Any remaining data is truncated. If the specified buffer type does not use a subtype, the subtype is ignored and NULL is used.

    The default allocated buffer size is greater than 1024 bytes.

    size

    If type is CARRY or X_OCTET, size must be specified. size is not required for other buffer types. If size is 0, the default size of each buffer is used.

    The default size of STRING, STRUCT, X_C_TYPE, X_COMMON is 1024 bytes. The default size of CARRY is 0, but the size must be greater than 0 when allocating a buffer.

  • Return Value

    Value Description

    Buffer Pointer

    The function call succeeded and a proper buffer pointer is returned.

    NULL

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tpalloc() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, a type is NULL.

    [TPENOENT]

    Unknown type or subtype. For STRUCT buffers, the subtype (the tag name of a struct) does not exist in the SDLFILE.

    [TPESYSTEM]

    An error occurred in the Tmax system. Detailed information is recorded in the log file.

    [TPEOS]

    An error occurred in the operating system. (e.g., memory allocation failure)

    [TPEOTYPE]

    When the requested server data is a struct buffer, but the server was compiled without the struct file.

  • Example

    #include <stdio.h>
#include <usrinc/atmi.h>
#include “../sdl/demo.s”

void main(int argc, char *argv[])
{
    int ret;
    struct data *buf;
    long len;

    ret=tpstart((TPSTART_T *)NULL);
    if (ret<0) { error processing }
    buf=(struct data *)tpalloc(“STRUCT”, “data”,0);
    data process....

    ret=tpcall(“SERVICE”, (char *)sndbuf, 0, (char **)&rcvbuf, &len, TPNOFLAGS);
    if (ret<0) {error processing }
    data process....
    tpfree((char *)buf);
    tpend();
}

  • Related functions

    tpfree(), tprealloc(), tptypes()

8.2. tprealloc

The tprealloc function reallocates a buffer pointed to by ptr to a new size in bytes and returns a pointer to the new buffer (if the buffer location changes).

Like tpalloc(), the buffer size must be larger than the default size (1024 bytes). The buffer type remains the same after reallocation. When the function successfully returns, the returned pointer should be used to reference the reallocated buffer; the original ptr should no longer be used. If the reallocated buffer size is smaller than the original buffer, the contents of ptr may not be preserved.

Some buffer types require initialization before use. tprealloc() reinitializes the reallocated buffer before returning it. Therefore, the returned buffer can be used immediately. If reinitialization fails, tprealloc() returns NULL, and the data in the original buffer pointed to by ptr is no longer valid.

  • Prototype

    # include <atmi.h>
char  * tprealloc (char *ptr, long size)

  • Parameter

    Parameter Description

    ptr

    A pointer to a buffer to be allocated.

    size

    The size of a buffer to be allocated.

  • Return Value

    Value Description

    Buffer pointer

    The function call succeeded and returns a buffer of the specified type.

    NULL

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tprealloc() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the buffer pointed to by ptr was not allocated by tpalloc().

    [TPEPROTO]

    tprealloc() was called under an inappropriate condition.

    [TPENOENT]

    The buffer pointed to by ptr 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>
void main(int argc, char *argv[])
{
    char *buf;
    buf=tpalloc(“STRING”,NULL,10);
    if (buf==NULL) { error processing }
    buf=tprealloc(buf,20);  /* ok */
    if (buf==NULL) { error processing }

    buf=”test”;
    buf=tprealloc(buf,30);  /*error : TPEINVAL */
    if (buf==NULL) { error processing }
}

  • Related functions

    tpalloc(), tpfree(), tptypes()

tprealloc() cannot be used with malloc(), realloc() or free() in the C library. For example, a buffer allocated using tprealloc() cannot be released using free().

8.3. tpfree

The tpfree function releases memory allocated to a typed buffer by tpalloc() or tprealloc(). This function can be used on both the client and the server.

  • Prototype

    # include <atmi.h>
void  tpfree(char *ptr)

  • Parameter

    Parameter Description

    ptr

    A pointer to a buffer allocated by tpalloc() or tprealloc().

    If ptr is NULL, nothing will happen. If ptr points to a non-typed buffer or a buffer already released by tpfree(), nothing will happen. If ptr points to a buffer sent to a service routine, tpfree() will not free the buffer but instead will return it as it is. To free a typed buffer, related data or the status information must first be removed. tpfree() removes related information before freeing these types of buffers.

    Once tpfree() returns, ptr cannot be transferred to a XATMI routine as a parameter, and it cannot be used in any other way.

  • Return Value

    tpfree() returns no value to the caller.

  • Example

    #include <usrinc/atmi.h>
#include <stdio.h>
#include “../sdl/demo.s”

void main(int argc, char *argv[])
{
    int ret;
    struct data *buf;
    char *message, *message2;

    ret=tpstart((TPSTART_T *)NULL);
    if (ret==-1) { error processing }

    buf=(struct data *)tpalloc(“STRUCT”, “data”,0);
    if (buf==NULL) { error processing }
    message=tpalloc(“STRING”, NULL, 0);
    if (message==NULL) { error processing }

    message2=tpalloc(“CARRAY”, NULL, 20);
    if (message==NULL) { error processing }

    data process....
    tpfree((char *)buf);
    tpfree(message);
    tpfree((char *)message2);
    tpend();
}

  • Related functions

    tpalloc(), tprealloc()

tpfree() cannot be used with malloc(), realloc() or free() in the C library. A buffer allocated by tpalloc() cannot be release by free().

8.4. tptypes

The tptypes function provides information about the type and subtype of a buffer. It is available on both servers and clients. The function receives a pointer for a data buffer, and returns the type and subtype of the buffer.

  • Prototype

    #include <atmi.h>
long  tptypes (char  *ptr, char  *type, char  *subtype )

  • Parameter

    Parameter Description

    ptr

    A pointer to a buffer that must be allocated by tpalloc().

    type, subtype

    Optional. Indicates the buffer type and subtype. Type names can have a maximum of 8 characters, and subtype names up to 16 characters. Strings do not need to end with NULL. If no subtype exists, the subtype field should contain an empty string (""). Only the first 8 bytes of type and 16 bytes of subtype are considered valid.

  • Return Value

    Value Description

    Buffer size

    The function call succeeded.

    -1

    The function call failed. An error code is set in tperrno.

  • Errors

    If tptypes() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the buffer pointed to by ptrwas not allocated using tpalloc().

    [TPEPROTO]

    The function 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 “../sdl/demo.s”
main(int argc, char *argv[])
{
    int ret;
    struct sel_o *rcvbuf;
    char type[9], subtype[17];
    long size;

    ret=tpstart((TPSTART_T *)NULL);
    if (ret==-1) { error processing }
    buf=(struct sel_o*)tpalloc(“STRUCT”,”sel_o”,0);
    if (buf==NULL) {error processing };

    size =tptypes((char*)buf, type,subtype);
    if (size==-1) {error processing };
    printf (“buf : size %d, type %s, subtype %s\n\n”, size, type, subtype);

    /*rcvbuf : size 1024, type STRUCT, subtype sel_o */
    data process...
    tpfree((char *)buf);
    tpend();
}

  • Related functions

    tpalloc(), tpfree(), tprealloc()

9. Transaction Management

The following describes functions that are used for transaction management.

9.1. tx_begin

The tx_begin function starts a global transaction, putting the calling process into transaction mode. This function is available on both servers and clients.

To begin a transaction, the calling process must first be connected to a resource manager using tx_open(). If tx_open() has not been called or the caller is already in transaction mode, tx_begin() fails and returns [TX_PROTOCOL_ERROR].

Once a transaction has started, the calling process must complete it by calling tx_commit() or tx_rollback(). Chained transactions are also supported, which do not require calling tx_begin() explicitly to start. For further information, see tx_commit and tx_rollback.

  • Prototype

    #include <tx.h>
int  tx_begin (void)

  • Return Value

    Value Description

    TX_OK

    The function call succeeded.

    Negative value

    The function call failed.

  • Errors

    If tx_begin() fails, one of the following codes is set.

    Error Code Description

    [TX_OUTSIDE]

    The transaction manager could not start a global transaction because the current calling process was participating in an external global transaction. The global transaction can be started after all outside jobs are complete. This error does not affect the participating transactions.

    [TX_PROTOCOL_ERROR]

    The function was called under an inappropriate condition. For example, the caller was already in transaction mode. This error does not affect the current transaction.

    [TX_ERROR]

    The transaction manager or the resource manager encountered a temporary error while starting a transaction. When this error is returned, the caller is no longer in transaction mode. The exact cause of this error may depend on the product behavior.

    [TX_FAIL]

    A fatal error occurred, and the transaction manager or the resource manager can no longer execute operations for the application. When this error is returned, the caller is no longer in transaction mode. The exact cause of this error may depend on the product behavior.

  • Example

    #include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/tx.h>

void main(int argc, char *argv[])
{
    char *buf;
    int ret,cd;
    long len, revent;

    ret=tpstart((TPSTART_T *)NULL);
    if (ret==-1) { error processing }

    buf = (char *)tpalloc(“CARRAY”, NULL, 20);
    if (buf==NULL) {error processing };

    data process.…

    ret=tx_set_transaction_timeout( 5 );
    if (ret<0) { error processing }

    ret=tx_begin();
    if (ret<0) { error processing }

    cd = tpconnect(“SERVICE”, buf, 20, TPRECVONLY);
    if (cd==-1) { error processing }

    ret = tprecv(cd, (char **)&buf, &len,TPNOFLAGS, &revent)};
    if (ret < 0 && revent != TPEV_SVCSUCC)
        tx_rollback();
    else
        tx_commit();

    data process....

    tpfree((char *)buf);
    tpend();
}

  • Related functions

    tx_commit(), tx_open(), tx_rollback(), tx_set_transaction_timeout()

9.2. tx_commit

The tx_commit function commits a global transaction. This function is available on both servers and clients.

When the transaction_control property value is TX_UNCHAINED, the caller is no longer in transaction mode when tx_commit() returns. However, if the value is TX_CHAINED, the caller remains in transaction mode for a new transaction when tx_commit() returns. For detailed information, see tx_set_transaction_control.

  • Prototype

    # include  <tx.h>
int  tx_commit(void)

  • Return Value

    Value Description

    TX_OK

    The function call succeeded.

    Negative value

    The function call failed and an error code is returned.

  • Errors

    If tx_commit() fails, one of the following codes is set.

    Error Code Description

    [TX_NO_BEGIN]

    The transaction was successfully committed, but new transactions cannot be started, and the caller is no longer in transaction mode. This error occurs only when the transaction_control property is TX_CHAINED.

    [TX_ROLLBACK]

    The transaction was rolled back. If the transaction_control property is set to TX_CHAINED, a new transaction is initiated.

    [TX_ROLLBACK_NO_BEGIN]

    The transaction was rolled back. This error occurs only when the transaction_control property is set to TX_CHAINED. When this error occurs, a new transaction cannot be started, and the caller is no longer in transaction mode.

    [TX_HAZARD]

    The transaction was partially committed or rolled back due to an error. If the transaction_control property is set to TX_CHAINED, a new transaction is initiated.

    [TX_HAZARD_NO_BEGIN]

    The transaction was partially committed or rolled back. This error occurs only when the transaction_control property is set to TX_CHAINED. A new transaction cannot be started and the caller is no longer in transaction mode.

    [TX_PROTOCOL_ERROR]

    The function was called under an inappropriate condition. For example, the caller was not in transaction mode. The transaction-related status of the caller remains unchanged.

    [TX_FAIL]

    A fatal error occurred, and the transaction manager or resource manager can no longer execute operations for the application. The exact cause of this error may depend on the product behavior. The transaction-related status of the caller is unknown.

  • Example

    #include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/tx.h>

void main(int argc, char *argv[])
{
    char *buf;
    int ret,cd;
    long len, revent;

    ret=tpstart((TPSTART_T *)NULL);
    if (ret==-1) { error processing }

    buf = (char *)tpalloc(“CARRAY”, NULL, 20);
    if (buf==NULL) {error processing };

    data process.…

    ret=tx_set_transaction_timeout( 5 );
    if (ret<0) { error processing }

    ret=tx_begin();
    if (ret<0) { error processing }

    cd = tpconnect(“SERVICE”, buf, 20, TPRECVONLY);
    if (cd==-1) { error processing }

    ret = tprecv(cd, (char **)&buf, &len,TPNOFLAGS, &revent)};
    if (ret < 0 && revent != TPEV_SVCSUCC)
       tx_rollback();
    else
       tx_commit();

    data process....
    tpfree((char *)buf);
    tpend();
}

  • Related functions

    tx_begin(), tx_set_commit_return(), tx_set_transaction_control(), tx_set_transaction_timeout()

9.3. tx_info

The tx_info function returns global transaction information. This function is available on both servers and clients. It notifies global transaction information through a structure indicated by info. It also returns a value informing whether the caller is in transaction mode or not.

  • Prototype

    #include  <tx.h>
int tx_info (TXINFO  *info)

  • Parameter

    If info is not NULL, the TXINFO structure indicated by info will be global transaction information.

    The TXINFO structure is as follows.

    struct TXINFO {
       XID                      xid;
       COMMIT_RETURN            when_return;
       TRANSACTION_CONTROL      transaction_control;
       TRANSACTION_TIMEOUT      transaction_timeout;
       TRANSACTION_STATE        transaction_state;
};

    If tx_info() is called while the caller is in transaction mode, xid will contain the current transaction branch ID, and transaction_state will reflect the current transaction state. If the caller is not in transaction mode, xid will be a NULL XID (see <tx.h> for details).

    Regardless of whether the caller is in transaction mode, when_return, transaction_control, and transaction_timeout will contain the current settings for commit_return, the transaction_control property, and the transaction timeout in seconds.

    The returned transaction timeout value is used for the next transaction that begins. It may not reflect the timeout of the caller’s current global transaction, because the caller might have modified the transaction timeout using tx_set_transaction_timeout() after the current transaction started. If the info parameter is NULL, the TXINFO structure will not be returned.

    Repeated calls to tx_info() within the same global transaction will return an XID with the same gtrid (global transaction identifier). However, the bqual (local transaction identifier) may differ, so the complete XID may not be identical.

  • Return Value

    Value Description

    1

    If the caller was in transaction mode, the function call succeeded.

    0

    If the caller was not in transaction mode, the function call succeeded.

    Negative value

    The function call failed, and an error code is set.

  • Errors

    If tx_info() fails, one of the following codes is set.

    Error Code Description

    [TX_PROTOCOL_ERROR]

    The function was called under an inappropriate condition. For example, it was called before the tx_open() was executed.

    [TX_FAIL]

    A fatal error occurred, and the transaction manager can no longer execute operations for the application. The exact cause depends on the product behavior.

  • Example

    #include <stdio.h>
#include <string.h>
#include <usrinc/atmi.h>
#include <usrinc/tx.h>
void main(int argc, char *argv[])
{
    int ret;
    long len;
    char *buf;
    TXINFO info;

    ret=tpstart((TPSTART_T *)NULL);
    if (ret==-1) { error processing }

    buf = (char *)tpalloc(“CARRAY”, NULL, 20);
    if (buf==NULL) {error processing };
    data process....
    ret=tx_begin();
    if (ret<0) { error processing }

    ret=tpcall(“SERVICE”, buf, 20, (char **)&buf, &len, TPNOFLAGS);
    if (ret==-1) { error processing }

    if (tx_info(&info)==1) printf(“In transaction \n”);
    else printf(“Not in transaction \n”);

    if (strncmp(buf, “err”, 3)==0) tx_rollback();
    else  tx_commit();

    data process....
    tpfree((char *)buf);
    tpend();
}

  • Related functions

    tx_open(), tx_set_commit_return(), tx_set_transaction_control(), tx_set_transaction_timeout()

9.4. tx_rollback

The tx_rollback function rolls back a global transaction. It is available on both servers and clients.

If the transaction_control property is TX_UNCHAINED, the caller is no longer in transaction mode when tx_rollback() returns. If transaction_control is TX_CHAINED, the caller remains in transaction mode for a new transaction when tx_rollback() returns. For more information about the transaction_control property, refer to tx_set_transaction_control.

  • Prototype

    #include  <tx.h>
int  tx_rollback(void)

  • Return Value

    Value Description

    TX_OK

    The function call succeeded.

    Negative value

    The function call failed, and an error code is set.

  • Errors

    If tx_rollback() fails, one of the following codes is set.

    Error Code Description

    [TX_NO_BEGIN]

    The transaction was rolled back. This error occurs only when the transaction_control property is TX_CHAINED. A new transaction cannot be started, and the caller is no longer in transaction mode.

    [TX_MIXED]

    The transaction was partially committed and partially rolled back. If the transaction_control property is TX_CHAINED, a new transaction is initiated.

    [TX_MIXED_NO_BEGIN]

    The transaction was partially committed and partially rolled back. This error occurs only when the transaction_control property is TX_CHAINED. A new transaction cannot be started and the caller is no longer in transaction mode.

    [TX_HAZARD]

    The transaction was partially committed or rolled back due to an error If the transaction_control property is TX_CHAINED, a new transaction is initiated.

    [TX_HAZARD_NO_BEGIN]

    The transaction was partially committed or rolled back. This error occurs only when the transaction_control property is TX_CHAINED. A new transaction cannot be started and the caller is no longer in transaction mode.

    [TX_COMMITTED]

    The transaction was independently committed. If transaction_control is TX_CHAINED, a new transaction is initiated.

    [TX_COMMITTED_NO_BEGIN]

    The transaction was independently committed. This error occurs only when transaction_control is TX_CHAINED. A new transaction cannot be started, and the caller is no longer in transaction mode.

    [TX_PROTOCOL_ERROR]

    The function was called under an inappropriate condition. For example, the caller was not in transaction mode. The transaction-related status of the caller remains unchanged.

    [TX_FAIL]

    A fatal error occurred, and the transaction manager or resource manager can no longer execute operations for the application. The exact cause of this error may depend on the product behavior. The transaction-related status of the caller is unknown.

  • Example

    #include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/tx.h>

void main(int argc, char *argv[])
{
    char *buf;
    int ret,cd;
    long len, revent;

    ret=tpstart((TPSTART_T *)NULL);
    if (ret==-1) { error processing }

    buf = (char *)tpalloc(“CARRAY”, NULL, 20);
    if (buf==NULL) {error processing };
    data process.…
    ret=tx_set_transaction_timeout( 5 );
    if (ret<0) { error processing }

    ret=tx_begin();
    if (ret<0) { error processing }

    cd = tpconnect(“SERVICE”, buf, 20, TPRECVONLY);
    if (cd==-1) { error processing }
    ret = tprecv(cd, (char **)&buf, &len,TPNOFLAGS, &revent)};
    if (ret < 0 && revent != TPEV_SVCSUCC)  tx_rollback();
    else    tx_commit();
    data process....

    tpfree((char *)buf);
    tpend();
}

  • Related functions

    tx_begin(), tx_set_transaction_control(), tx_set_transaction_timeout()

9.5. tx_set_transaction_timeout

The tx_set_transaction_timeout function sets the transaction_timeout property. The timeout value specifies the maximum time allowed for a transaction to complete before a transaction timeout occurs. In other words, it defines the interval between tx_begin() and tx_commit(), or tx_begin() and tx_rollback().

The tx_set_transaction_timeout() function can be called regardless of whether the caller is currently in transaction mode. If called while in transaction mode, the new timeout value will take effect starting from the next transaction.

  • Prototype

    # include  <tx.h>
int  tx_set_transaction_timeout (TRANSACTION_TIMEOUT  timeout)

  • Parameter

    Parameter Description

    timeout

    The maximum time allowed for a transaction before a timeout occurs, in seconds. It can be set up to the system-defined maximum value for a long integer. The default value of transaction_timeout is 0, which means there is no timeout limit.

  • Return Value

    Value Description

    TX_OK

    The function call succeeded.

    Negative value

    The function call failed, and an error code is returned.

  • Errors

    If tx_set_transaction_timeout() fails, it returns one of the following codes without changing the existing transaction_timeout setting.

    Error Code Description

    [TX_EINVAL]

    The specified timeout value is invalid.

    [TX_PROTOCOL_ERROR]

    The function was called under an inappropriate condition. For example, tx_open() has not been called yet, or tpstart() was not executed before tx_set_transaction_timeout was called.

    [TX_FAIL]

    A fatal error occurred, and the transaction manager can no longer execute operations for the application. The exact cause of this error may depend on the product behavior.

  • Example

    #include <usrinc/atmi.h>
#include <usrinc/tx.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 };

    ret=tx_set_transaction_timeout( 5 );
    if (ret<0) { error processing }

    ret=tx_begin();
    if (ret<0) { error processing }
    ret = tpcall(“SERVICE”, (char *)buf, strlen(buf), (char **)&buf, &len,
                   TPNOFLAGS);
    if (ret == -1) {
        tx_rollback();
        error processing
    }
    data process ….
    ret = tx_commit();
    if (ret < 0) { error processing }

    data process...
    tpfree((char *)buf);
    tpend();
}

  • Related functions

    tx_begin(), tx_commit(), tx_open(), tx_rollback(), tx_info()

9.6. tx_set_transaction_control

The tx_set_transaction_control function sets the transaction_control property with the specified control value. This function is available on both servers and clients.

The transaction_control property determines whether to start a new transaction before tx_commit() and tx_rollback() return to the caller. The tx_set_transaction_control() function can be called regardless of whether the application program is in transaction mode or not. This setting remains in effect until it is changed by a subsequent call to tx_set_transaction_control().

  • Prototype

    # include  <tx.h>
int  tx_set_transaction_control(TRANSACTION_CONTROL  control)

  • Parameter

    Parameter Description

    control

    The following flags can be set.

    • TX_UNCHAINED

      Prevents tx_commit() and tx_rollback() from starting a new transaction before returning to the caller. In this case, the caller must explicitly call tx_begin() to initiate a new transaction. This is the default setting of the transaction_control property.

    • TX_CHAINED

      Allows tx_commit() and tx_rollback() to start a new transaction before returning to the caller.

  • Return Value

    Value Description

    TX_OK

    The function call succeeded.

    Negative value

    The function call failed, and an error code is returned.

  • Errors

    If tx_set_transaction_control() fails, it returns one of the following error codes without changing the existing transaction_control setting.

    Error Code Description

    [TX_EINVAL]

    The control parameter was not set TX_UNCHAINED or TX_CHAINED.

    [TX_PROTOCOL_ERROR]

    The function was called under an inappropriate condition. For example, tx_open() has not been called yet.

    [TX_FAIL]

    A fatal error occurred, and the transaction manager can no longer execute operations for the application. The exact cause of this error may depend on the product behavior.

  • Example

    #include <usrinc/atmi.h>
#include <usrinc/tx.h>

int main(int argc, char *argv[])
{
    int ret;
    long len;
    char *buf;

    ret = tpstart((TPSTART_T *)NULL);
    if (ret == -1) { error processing }

    buf = (char *)tpalloc(“CARRAY”, NULL, 20);
    if (buf==NULL) {error processing };
    ret = tx_set_transaction_timeout(5);
    if (ret < 0){ error processing }

    ret = tx_set_transaciont_control(TX_UNCHAINED);
    if (ret < 0){ error processing }
    ret = tx_begin();
    if (ret < 0) { error processing }
    data process....

    ret = tpcall(“SERVICE1”, (char *)buf, strlen(buf), (char **)&buf, &len,
                  TPNOFLAGS);
    if (ret == -1)
    {
        tx_rollback();
        error processing
    }

    data process...
    ret = tpcall(“SERVICE2”, (char *)buf, strlen(buf), (char **)&buf, &len,
                   TPNOFLAGS);
    if (ret == -1)
    {
        tx_rollback();
        error processing
    }
    data process ….

    ret = tx_commit();
    if (ret < 0) { error processing }
    data process...

    tpfree((char *)buf);
    tpend();
}

  • Related functions

    tx_begin(), tx_commit(), tx_open(), tx_rollback(), tx_info()

9.7. tx_set_commit_return

The tx_set_commit_return function sets the commit_return property with the specified when_return value. This function is available on both servers and clients.

This property determines how the tx_commit() function returns control to the caller. tx_set_commit_return() can be called regardless of whether the caller is in transaction mode. This setting remains in effect until it is changed by a subsequent call to tx_set_commit_return(). The initial setting of the commit_return property depends on the context when the function is executed.

  • Prototype

    #include  <tx.h>
int  tx_set_commit_return (COMMIT_RETURN  when_return)

  • Parameter

    Parameter Description

    when_return

    The following flags can be set.

    • TX_COMMIT_DECISION_LOGGED

      This flag causes tx_commit() to return before the second phase of a Two-Phase Commit (2PC) protocol is completed, once the first phase has been logged. This allows tx_commit() to respond to the caller more quickly. However, there is a risk that the transaction may result in a heuristic outcome. In this case, the caller cannot determine the exact result from the return code of tx_commit().

      Normally, a transaction participant scheduled to commit a transaction in the first phase will successfully complete the second phase. In abnormal cases, such as a prolonged network failure or node crash, it may be impossible to complete the second phase, potentially resulting in a heuristic outcome. The transaction manager can choose not to support this property. In such cases, tx_commit() returns [TX_NOT_SUPPORTED], indicating that the property is unavailable.

    • TX_COMMIT_COMPLETED

      This flag causes tx_commit() to return only after the 2PC protocol is fully completed. The return code indicates whether the transaction produced a heuristic result or completed successfully. The transaction manager can choose not to support this property. In that case, tx_commit() returns [TX_NOT_SUPPORTED], indicating that this property is unavailable.

  • Return Value

    If the function completes successfully, tx_set_commit_return() returns [TX_OK] (a non-negative value).

    If when_return is not TX_COMMIT_COMPLETED or TX_COMMIT_DECISION_LOGGED, the function returns [TX_NOT_SUPPORTED] (also a non-negative value), and the current commit_return setting remains unchanged. The transaction manager should set when_return to at least one of TX_COMMIT_COMPLETED or TX_COMMIT_DECISION_LOGGED.

    If the function call fails, an error code is returned.

  • Errors

    If tx_set_commit_return() fails, it returns a negative value without changing the commit_return setting.

    Error Code Description

    [TX_EINVAL]

    when_return is not set to TX_COMMIT_COMPLETED or TX_COMMIT_DECISION_LOGGED.

    [TX_PROTOCOL_ERROR]

    The function was called under an inappropriate condition. For example, tx_open() has not been executed yet.

    [TX_FAIL]

    A fatal error occurred, and the transaction manager can no longer execute operations for the application. The exact cause of this error may depend on the product behavior.

  • Example

    #include <usrinc/tx.h>

int main(int argc, char *argv[])
{
    int ret;
    long len;
    char *buf;

    ret = tpstart((TPSTART_T *)NULL);
    if (ret == -1) { error processing }

    buf = (char *)tpalloc(“CARRAY”, NULL, 20);
    if (buf==NULL) {error processing };
    ret = tx_set_transaction_timeout(5);
    if (ret < 0){ error processing }

    ret = tx_set_commit_return(TX_COMMIT_COMPLETED);
    if (ret < 0){ error processing }

    ret = tx_begin();
    if (ret < 0){ error processing }

    data process....
    ret = tpcall(“SERVICE1”, (char *)buf, strlen(buf), (char **)&buf, &len,
                   TPNOFLAGS);
    if (ret == -1)
    {
        tx_rollback();
        error processing
    }

    data process...
    ret = tpcall(“SERVICE2”, (char *)buf, strlen(buf), (char **)&buf, &len,
                   TPNOFLAGS);
    if (ret == -1)
    {
        tx_rollback();
        error processing
    }

    data process ….

    ret = tx_commit();
    if (ret < 0) { error processing }

    data process...

    tpfree((char *)buf);
    tpend();
}

  • Related functions

    tx_commit(), tx_open(), tx_info()

10. RQ System

This section describes functions that are used by RQ. The Tmax system provides the RQ system for reliable queues. ENQSVR works as a queue management process to enqueue/dequeue data to/from RQ. This function cannot be used in Windows NT or 2000.

Even when services cannot be provided due to a system failiure or error, data stored in the queue can guarantee its integrity. If multiple servers are established in a WAN environment or the load is large, RQ can be used to process applications with guaranted data integrity.

10.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()

10.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()

10.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()

10.4. 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()

11. API that Uses Events

Tmax can send messages to service routines and multiple clients. Developers can specify any client and service routine to register, cancel, or generate an event. Client and service routines can register in each event redundantly or register in multiple events simultaneously.

Note that an event data transfer and the results generated by that event do not fall in the scope of the transaction.

11.1. tpsubscribe

The tpsubscribe function subscribes to a specific event or a set of events identified by eventname. It allows the caller to receive a notification whenever the specified event occurs. This function is available on both servers and clients.

  • Prototype

    # include <tmaxapi.h>
long tpsubscribe(char *eventname, char *filter, TPEVCTL *ctl, long flags)

  • Parameter

    Parameter Description

    eventname

    A NULL-terminated string with a maximum length of 15 characters. Wildcards or partial matches are not supported; only the exact name can be registered.

    filter

    Reserved for future-use. This parameter must be set to NULL.

    ctl

    A structure that receives a message when an event occurs. Its behavior depends on the caller: if a client uses tpsubscribe(), ctl must be NULL. The message will then be delivered as unsolicited data, which the client can handle using tpsubscribe() or tpgetunsol().

    flags

    Only TPNOTIME is used.

    When tpsubscribe() is executed from a server, ctl must be NULL and configured as follows:

    struct tpevctl {
    long ctl_flags;
    long post_flags;
    char svc[XATMI_SERVICE_NAME_LENGTH];
    char qname[RQ_NAME_LENGTH];
};
typedef struct tpevctl TPEVCTL;
    Member Description

    ctl_flags

    Reserved for future-use and not currently supported. Set to 0.

    post_flags

    Reserved for future-use and not currently supported. Set to 0.

    svc[XATMI_SERVICE_NAME_LENGTH]

    When using svc, the message is sent to the server in a manner similar to tpacall (svc, data, len, TPNOREPLY), and the server’s return value is ignored. Use only one of qname or svc.

    qname[RQ_NAME_LENGTH]

    When using qname, the message is stored in the RQ through tpenq (qname, NULL, data, len, TPNOFLAGS).

  • Return Value

    Value Description

    descriptor

    The function call succeeded and returns the descriptor to be used when calling tpunsubscribe().

    -1

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tpsubscribe() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPESYSTEM]

    An error occurred in the Tmax system. For clients, this is most often a network error.

    [TPEOS]

    An error occurred in the operating system. This is typically a memory allocation issue.

    [TPEINVAL]

    An incorrect parameter was used.

    [TPENOENT]

    The qname specified for the TPEVCTL struct, or the RQ or server specified by svc does not exist.

    [TPEPROTO]

    CTL is not NULL in the client and server.

    [TPETIME]

    A timeout occurred.

  • Related functions

    tpsetunsol(), tpsetunsol_flag(), tpgetunsol(), tpacall(), tpenq()

11.2. tpunsubscribe

The tpunsubscribe function unsubscribes a specific event subscribed through tpsubscribe(). When all requests for unsubsription are completed, the event’s table is deleted by the Tmax system. This function is available on both servers and clients.

  • Prototype

    # include <tmaxapi.h>
int tpunsubscribe(long sd, long flags)

  • Parameter

    Parameter Description

    sd

    The return value retrieved by tpsubscribe().

    flags

    Only TPNOTIME is used.

  • Return Value

    Value Description

    Positive

    The function call succeeded.

    Negative

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tpunsubscribe() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPESYSTEM]

    An error occurred in the Tmax system. For clients, this is most often a network error.

    [TPEOS]

    An error occurred in the operating system. This is typically a memory allocation issue.

    [TPEINVAL]

    An incorrect parameter was used.

    [TPETIME]

    A timeout occurred.

  • Related functions

    tpsetunsol(), tpsetunsol_flag(), tpgetunsol(), tpacall(), tpenq()

11.3. tppost

The tppost function generates a specific event from a server or client and delivers a message. tppost() notifies the occurrence of an event to all clients and server processes that have been registered for the event with the eventname through tpsubscribe(). If required, a message can be delivered.

  • Prototype

    # include <tmaxapi.h>
int tppost(char *eventname, char *data, long len, long flags)

  • Parameter

    Parameter Description

    eventname

    A NULL-terminated string of up to 15 characters. Wildcards and partial matching are not supported.

    data

    A pointer to the message buffer, which must be allocated in advance using tpalloc().

    len

    The length of the message buffer to send.

    If data indicates a buffer that does not require a specified length, the len will be ignored (0 is used by default). If data indicates a buffer that requires a specified length, the len must not be 0. If data is NULL, the len will be ignored.

    flags

    Only TPNOTIME is used.

  • Return Value

    Value Description

    Positive

    The function call succeeded.

    Negative

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tppost() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPESYSTEM]

    An error occurred in the Tmax system. For clients, this is most typically a network error.

    [TPEOS]

    An error occurred in the operating system. This is typically a memory allocation issue.

    [TPEINVAL]

    An incorrect parameter was used.

    [TPENOENT]

    For tpsubscribe(), the qname in the TPEVCTL structure, or the RQ or server specified by the svc, does not exist.

    [TPEPROTO]

    A protocol error occurred. This happens if tpsubscribe() is executed from the client with ctl not set to NULL, or from the server with ctl set to NULL.

    [TPETIME]

    A timeout occurred.

  • Related functions

    tpsetunsol(), tpsetunsol_flag(), tpgetunsol(), tpacall(), tpenq()

12. Broadcast/Multicast

Tmax can send data to clients in various ways. When sending data to multiple clients for management or development, Tmax can manage all client IDs and send messages to each client. This method, however, is not efficient when there are many concurrent users in the system.

If clients can be divided into several groups, an API can be used to send messages to all related clients. Tmax implements broadcast and multicast by utilizing client access information or events. Both the broadcast and multicast APIs can broadcast and multicast, but they are named so to distinguish them.

12.1. tpbroadcast

The tpbroadcast function sends unsolicited messages to clients registered in the Tmax system. To receive an unsolicited message, a client must be connected to the Tmax system using tpstart(), the client name and flags must be defined correctly, and flag values of the TPSTART_T structure used for tpstart() must be set to TPUNSOL_POLL or TPUNSOL_HND. This function can be used on both the client and the server.

  • Prototype

    # include <atmi.h>
int tpbroadcast (char *nodename, char *usrname, char *cltname,
                 char *data, long len, long flags)

  • Parameter

    Parameter Description

    nodename,

    usrname,

    cltname

    Logical names used to select target clients. The name length must be 15 characters or less. Wildcards (?, *, etc.) can be used to specify names. NULL can also be used as a wildcard corresponding to all clients. A string argument with a length of 0 corresponds only to a client name with a string length of 0.

    cltname is the client name used, which is registered when the client first accesses the Tmax system, when using the tpstart() function.

    data

    A buffer must be allocated by tpalloc() in advance.

    len

    Length of data to receive. For STRING, STRUCT, X_COMMON, and X_C_TYPE buffers, which require no length specification, len is ignored and 0 is used by default. The len value is also ignored if data is NULL.

    flags

    The following flags are available:

    • TPNOBLOCK

      If a blocking condition (e.g., the internal buffer is filled with messages to be transmitted) is encountered, the request is not sent.

    • TPNOTIME

      The function caller must wait indefinitely until the response is received. The blocking timeout is ignored. If tpbroadcast() is called within transaction timeout, the transaction timeout still applies.

    • TPSIGRSTRT

      Allows signal interrupts. If a system function is interrupted by a signal, the system function is executed again. If the signal interrupt occurs without this flag, the function fails and tperrno is 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 tpbroadcast() fails, no message is sent to clients and one of the following codes is set in tperrno.

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the descriptor was too long or the flag was invalid. If the nodename is incorrect, tpbroadcast() fails and returns TPEINVAL. However, if the usrname or cltname is incorrect, no message is sent, but the function completes as if it succeeded.

    [TPETIME]

    A block timeout occurred while neither TPNOBLOCK nor TPNOTIME was set.

    [TPEBLOCK]

    A blocking condition was encountered 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]

    tpbroadcast() 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>
void main(int argc, char *argv[])
{
    int ret;
    char *buf;
    TPSTART_T *tpinfo;

    tpinfo = (TPSTART_T *)tpalloc(“TPSTART”, NULL, sizeof(TPSTART_T));
    if (tpinfo==NULL) { error processing }
    strcpy(tpinfo->cltname, “cli1”);
    strcpy(tpinfo->usrname, “navis”);
    ret=tpstart(tpinfo);
    if (ret==-1) { error processing }

    buf=tpalloc(“STRING”, NULL, 0);
    if (buf==NULL) { error processing }
    data process…

    tpbroadcast(“tmax”, NULL, NULL, buf, 0, TPNOFLAGS);
    data process....

    tpfree(buf);
    tpend();
}

  • Related functions

    tpalloc(), tpend(), tpstart()

13. Environment Program

To develop services for general users, the client program is generally developed in Windows. For development in Windows, Tmax provides interfaces for various development tools. Tmax also provides various types of libraries for developer convenience. According to the library, APIs can be added or replaced.

Tmax supports the following development tools: PowerBuilder, Delphi, VC++, B++, VB, VB .Net, C#, and Net. For more information about each development tool, refer to Tmax Programming Guide (4GL).

The following describes the supported libraries.

Library Description

tmax.lib (dll)

Used for VC++, Delphi, and C#. (cdecl)

tmax4gl. lib (dll)

Used for BC++, PowerBuilder, VB, and VB.Net. (stdcall)

tmaxmt. lib (dll)

Supports multi-thread type. (cdecl)

Wintmax. lib (dll)

Supports multi-windows. (cdecl)

tmaxce.lib (dll)

Supports Windows ce. (cdecl)

  • tmaxmt.dll

    APIs were added to process message-driven type service requests, which are used in the Windows programming environment. The two APIs only differ in whether the message is returned to Windows or to the specified Callback function. Whenever an API is run, a thread is created to process the message. tmaxpi.h is used as the header file.

    • WinTmaxAcall()

    • WinTmaxAcall2()

  • WinTmax.dll

    APIs were added to process message-driven type service requests, which are used in the Windows programming environment. Messages are processed by independent threads, so WinTmaxStart() or WinTmaxEnd() is used instead of tpstart() or tpend().

    • WinTmaxStart()

    • WinTmaxEnd()

    • WinTmaxSetContext ()

    • WinTmaxSend ()

      WinTmax.dll works similarly to tmaxmt.dll but it does not connect to/disconnect from the Tmax system automatically. Also, a thread processes all messages instead of creating a thread for each API. If Windows is not set separately to process error messages and unrequested messages, the messages are ignored.

      For debugging and management, logs can be left in the file specified in the MAX_DEBUG environment variable. WinTmax.h is used as the header file.

13.1. WinTmaxAcall

The WinTmaxAcall function calls an asynchronous service in a multi-threaded environment. It is used on the client side and is supported in Windows environments. The function is functionally equivalent to tpacall() in a multi-threaded context.

WinTmaxAcall first creates a new thread and executes the following sequence within the thread: tpstart() → tpacall() → tpgetrply(). After tpgetrply() completes, it invokes SendMessage(wHandle, msgType, (UINT) &msg, tperrno).

  • Prototype

    # include <tmaxapi.h>
int WinTmaxAcall(TPSTART_T *sinfo, HANDLE wHandle, unsigned int msgtype,
                 char *svc, char *sndbuf, int len, int flags)

  • Parameter

    Parameter Description

    sinfo

    The structure used to send client information to the Tmax system. Equivalent to the parameter of tpstart().

    wHandle

    The Windows handle to receive messages.

    msgtype

    The message identifier. Typically a developer-defined WM_USER is used. Use the service name registered in the Tmax configuration file.

    svc

    The service to request for.

    sndbuf

    Data to be sent when calling a service. If not NULL, the buffer must be allocated by tpalloc().

    len

    The length of the data to be sent. Must be set for the CARRAY, X_OCTET, and structure array types.

    flags

    Same as the flags for tpacall().

    The following flags are available:

    • 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 this flag in transaction mode, the service will be excluded from transaction mode before being executed. When invoking tpacall() in transaction mode, it will still be affected by the transaction timeout even if TPNOTRAN was set.

      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.

  • Return Value

    Value Description

    1

    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.

  • Error

    If WinTmaxAcall() 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, the data points to a buffer that was not allocated by tpalloc(), or an invalid flag was set.

    [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.

    [TPETRAN]

    Executing xa_start failed because a database error occurred while calling a transaction service.

    [TPETIME]

    A timeout occurred. If the caller was in transaction mode, the transaction time limit expired and the transaction was rolled back. If the caller is not in transaction mode, and neither TPNOTIME nor TPNOBLOCK was set, a block timeout occurred. 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.

    [TPEPROTO]

    The function 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]

    An error occurred in the operating system.

  • Example

    ...
#include <usrinc/tmaxapi.h>
#define WM_WINTMAX_RECV WM_USER + 1
...

BEGIN_MESSAGE_MAP(CWinTmaxAcall2TestDlg, CDialog)
...
ON_MESSAGE(WM_WINTMAX_RECV, OnWinTmaxAcall)
...
END_MESSAGE_MAP()

BOOL CWinTmaxAcall2TestDlg::OnInitDialog()
{
    CDialog::OnInitDialog();
    ...
    ret = tmaxreadenv(“tmax.env”, “TMAX”);
    if (ret == -1){
        AfxMessageBox(“tmaxreadenv fail...”);
        return FALSE;
    }
    return TRUE;  // return TRUE  unless you set the focus to a control
}

void CWinTmaxAcall2TestDlg::OnOK()
{
    ...
    GetDlgItemText(IDC_EDIT1, m_Input);
    lstrcpy((LPTSTR)buf, (LPCTSTR)m_Input.operator const char *());
    ...

    buf = tpalloc(“STRING”, NULL, 0);
    if (buf == NULL){
        AfxMessageBox(“buf alloc fail...”);
        return FALSE;
    }

    ret = WinTmaxAcall((TPSTART_T *)NULL, m_hWnd, WM_WINTMAX_RECV,
           “TOUPPER”, buf, 0, TPNOFLAGS);
    if (ret == -1){
        error processing
    }
}

LRESULT CWinTmaxAcall2TestDlg::OnWinTmaxAcall(WPARAM wp, LPARAM lp)
{
    char msg[100];
    memset(msg, 0x00, 100);
    TPSVCINFO *get = (TPSVCINFO *)wp;
    if (lp < 0){
        error processing
    }
    ...
    SetDlgItemText(IDC_EDIT2, get->data);
    return 0;
}

  • Related functions

    tpacall(), WinTmaxAcall2()

13.2. WinTmaxAcall2

The WinTmaxAcall2 function calls an asynchronous service in a multi-threaded environment. It is used on the client side and is supported in Windows environments. The function is functionally equivalent to tpacall() in a multi-threaded context.

WinTmaxAcall first creates a new thread and executes the following sequence within the thread: tpstart() → tpacall() → tpgetrply(). After tpgetrply() completes, it passes received data to a specified callback function.

  • Prototype

    # include <tmaxapi.h>
int WinTmaxAcall2(TPSTART_T *sinfo, WinTmaxCallback fn, char *svc,
                  char *sndbuf, int len, int flags)

  • Parameter

    Parameter Description

    sinfo

    The structure used to send client information to the Tmax system. Equivalent to the parameter of tpstart().

    fn

    The callback function to receive a respones to a service request.

    svc

    The service name registered in the Tmax configuration file.

    sndbuf

    Data to be sent when calling a service. If not NULL, the buffer must be allocated by tpalloc().

    len

    The length of the data to be sent. Must be set for the CARRAY, X_OCTET, and structure array types.

    flags

    Same as the flags for tpacall().

    The following flags are available:

    • 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 this flag in transaction mode, the service will be excluded from transaction mode before being executed. When invoking tpacall() in transaction mode, it will still be affected by the transaction timeout even if TPNOTRAN was set.

      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.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set in tperrno.

  • Error

    If WinTmaxAcall2() 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, the data points to a buffer that was not allocated by tpalloc(), or an invalid flag was set.

    [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.

    [TPETRAN]

    The service (svc) does not support transactions, and TPNOTRAN is not set.

    [TPETIME]

    A timeout occurred. If the caller was in transaction mode, the transaction time limit expired and the transaction was rolled back. If the caller is not in transaction mode, and neither TPNOTIME nor TPNOBLOCK was set, a block timeout occurred. 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.

    [TPEPROTO]

    The function 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]

    An error occurred in the operating system.

  • Example

    #include <usrinc/tmaxapi.h>
#define WM_WINTMAX_RECV WM_USER + 1
int mycallfn(unsigned int, long);
...

BEGIN_MESSAGE_MAP(CWinTmaxAcall2TestDlg, CDialog)
...
END_MESSAGE_MAP()

BOOL CWinTmaxAcall2TestDlg::OnInitDialog()
{
    CDialog::OnInitDialog();
    ...
    ret = tmaxreadenv(“tmax.env”, “TMAX”);
    if (ret == -1){
        AfxMessageBox(“tmaxreadenv fail...”);
        return FALSE;
    }
    return TRUE;  // return TRUE  unless you set the focus to a control
}

void CWinTmaxAcall2TestDlg::OnOK()
{
    ...
    GetDlgItemText(IDC_EDIT1, m_Input);
    lstrcpy((LPTSTR)buf, (LPCTSTR)m_Input.operator const char *());
    ...
    buf = tpalloc(“STRING”, NULL, 0);
    if (buf == NULL){
        AfxMessageBox(“buf alloc fail...”);
        return FALSE;
    }
    ret = WinTmaxAcall2((TPSTART_T *)NULL, (WinTmaxCallback)mycallfn,
                       “TOUPPER”, (char *)buf, 0, TPNOFLAGS);
    if (ret == -1){
        error processing
    }
}

int mycallfn(unsigned int msg, long retval)
{
    TPSVCINFO *svcinfo;
    char infomsg[30];
    memset(infomsg, 0x00, sizeof(infomsg));
    svcinfo = (TPSVCINFO *)msg;
    strncpy(infomsg, svcinfo->data, svcinfo->len);
    if (retval != 0){
        strcpy(infomsg,tpstrerror(retval));
        AfxMessageBox(infomsg);
        return -1;
    } else {
        strncpy(infomsg, svcinfo->data, sizeof(infomsg) - 1);
        AfxMessageBox(infomsg);
        return 1;
    }
}

  • Related functions

    tpacall(),WinTmaxAcall()

13.3. WinTmaxStart

The WinTmaxStart function establishes a connection with the Tmax system in a multi-Windows environment. It is used on the client side and is supported in Windows environments. The function is functionally equivalent to tpstart(). In a multi-thread environment, each thread must call WinTmaxStart() to establish its own connection.

  • Prototype

    # include <WinTmax.h>
int WinTmaxStart(TPSTART_T *tpinfo)

  • Parameter

    For TPSTART_T, see tpstart.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set in tperrno.

  • Error

    If WinTmaxStart() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, tpinfo is NULL or is not a pointer to the TPSTART_T structure.

    [TPEITYPE]

    tpinfo is not a pointer to the TPSTART_T structure.

    [TPEPROTO]

    WinTmaxStart() was called under invalid conditions—for example, from the server side, or after the connection had already been terminated.

    [TPESYSTEM]

    An error occurred in the Tmax system. Detailed information is recorded in the log file.

    [TPEOS]

    An error occurred in the operating system, or an environment variable was incorrectly set. For example, if TMAX_HOST_ADDR or TMAX_HOST_PORT was misconfigured, the connection failed.

  • Related functions

    tpstart(), WinTmaxEnd(), WinTmaxSend(), WinTmaxSetContext()

13.4. WinTmaxEnd

The WinTmaxEnd function terminates a connection with the Tmax system. It is used on the client side and is supported in Windows environments. The function is functionally equivalent to tpend().

In a multi-threaded environment, where each thread must call WinTmaxStart() to establish its own connection, each thread must also call WinTmaxEnd() to terminate its connection.

  • Prototype

    # include <WinTmax.h>
int WinTmaxEnd(void)

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set in tperrno.

  • Error

    If WinTmaxEnd() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPETIME]

    Failed to access the threshold area. This is an internal system error; check the system status.

    [TPEPROTO]

    tpend() was called under invalid conditions—for example, from the server side, or after the connection had already been terminated.

    [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

    tpend(), WinTmaxStart()

13.5. WinTmaxSetContext

The WinTmaxSetContext function sets the Windows handle and message type. It is used on the client side and is supported in Windows environments.

This function is designed for a multi-Windows context. It stores the specified Windows handle and message type in a vacant slot in the library. When the worker thread receives a response, it transmits the data to the specified Windows system using the specified message type, in the following format:

SendMessage(winhandle, msgType, (UINT) &msg, callRet)

In the receiving Windows system, WPARAM corresponds to msg and LPARAM to callRet. Here, msg is a TPSVCINFO structure, and callRet represents the result of the processed service. If a valid message is received, 0 is returned; otherwise, -1.

For example, if the service is handled with tpreturn(TPSUCCESS, …) or tpreturn(TPFAIL, …), or an unsolicited message is received, it is treated as a valid message, and callRet is 0. If a synchronous result or interactive message is received, which is unsupported in a multi-window environment, callRet is -1. In this case, check the tperrno code to determine the cause of the error.

The following describes how to use the function with an example.

  • Prototype

    # include <WinTmax.h>
int WinTmaxSetContext(void *winhandle, unsigned int msgType, int slot)

  • Parameter

    Parameter Description

    winhandle

    The Windows handle to process received messages.

    msgType

    The message type.

    slot

    The slot in which to allocate the Windows handle and message type. Up to 256 slots can be allocated; slots 0 and 1 are reserved internally for the default output and error, respectively. If an error occurs during data transmission, or if the output Windows is not specified, the default Windows system is used.

    A slot can be redefined by the user. For unsolicited messages, no user-defined Windows exists, so such messages are delivered to slot 0, which is the default output Windows.

    The following values can be assigned to slot:

    • –1 : The system automatically finds a vacant slot to allocate the specified Windows handle and message type.

    • 0 or greater : The Windows handle and message type are allocated to the slot with the specified index.

  • Return Value

    Value Description

    index

    The function call succeeded. The index for an available slot is returned, and this index is used as the first parameter in WinTmaxSend().

    -1

    The function call failed. An error code is set in tperrno.

  • Error

    If WinTmaxSetContext() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPESYSTEM]

    An error occurred in the Tmax system.

    [TPEOS]

    An error occurred in the operating system.

  • Example

    ...
int CTMaxGwView::Connect()
{
    CString szTemp, Fname;
    WinTmaxEnd();
    int Ret = tmaxreadenv(TMAXINI, “TMAX117”);
    if(Ret<0)
    {
        szTemp.Format(“tmaxreadenv error”);
        LogDisplay2(2, (char *)(const char *)szTemp, szTemp.GetLength());
        return FALSE;
    }
    if (WinTmaxStart((TPSTART_T *)NULL) == -1) {
        szTemp.Format(“WinTmaxStart 에러 = [%s]”, tpstrerror(tperrno));
        LogDisplay2(2, (char *)(const char *)szTemp, szTemp.GetLength());
        return FALSE;
    }

    WinTmaxSetContext(m_hWnd, WM_TMAX_RECV_RDP, 0);
    WinTmaxSetContext(m_hWnd, WM_TMAX_RECV_ERR, 1);
    WinTmaxSetContext(m_hWnd, WM_TMAX_RECV, 2);

    return TRUE;
}

  • Related functions

    WinTmaxStart(),WinTmaxEnd(), WinTmaxSend()

13.6. WinTmaxSend

The WinTmaxSend function sends a service request. It is used on the client side and is supported in Windows environment. The function transmits data to request a service in a multi-Windows context.

  • Prototype

    # include <WinTmax.h>
int WinTmaxSend(int recvContext, char *svc, char *data, long len, long flags)

  • Parameter

    Parameter Description

    recvContext

    The Windows system to receive a response from the Tmax system. It is the return value of WinTmaxSetContext().

    svc

    The service name.

    data

    The buffer allocated by tpalloc() to store data to transmit to request a service.

    len

    The length of the data. For CARRAY buffers or multi-structure buffers, the length must be specified.

    flags

    Flags available for WinTmaxSend() are listed below.

    WinTmaxSend() works similarly to the tpacall() function. It requests a service and returns immediately without waiting for a response. Responses are handled by the thread created when calling WinTmaxStart(). The response is delivered to the Windows system specified by WinTmaxSetContext(), so no separate API is provided to receive it.

    The following example finds a vacant slot to store (hwd, 0x300) and returns its index. The return value rc of WinTmaxSetContext() is used as the recvContext parameter of WinTmaxSend(). After calling WinTmaxSend(rc, svc, data, len, 0), any response, including the 0x300 message and its result, will be sent to the hwd window.

    rc = WinTmaxSetContext(hwd, 0x300, -1);
int nSendResult = WindTmaxSend(rc, (LPSTR)(LPCSTR)strService, (Char*)tpbuf, nLen, TPNOFLAGS);
/*
  Subsequently, an internal thread processes the response message and send it to the Windows system in the following format:
  SendMessage(hwd, 0x300, (UINT) &msg, callRet);
*/

    The Windows system that receives the message gets the response data (msg) in WPARAM and the response result (callRet) inLPARAM. If the callRet is 0, the response is normal, and if -1, an error occurred. The cause of the error can be identified through the tperrno value.

    WinTmaxSend() does not support transactions due to its structure and is not affected by the BLOCKTIME setting in the Tmax configuration file or tpsettimeout(). However, when calling WinTmaxSend(), while the TPBLOCK flag is set, BLOCKTIME applies based on the corresponding flag behavior.

    The following flags are available:

    Flag Description

    TPBLOCK

    If WinTmaxSend() is used without setting this flag, the call may appear to succeed even if the target service (svc) does not exist or service execution fails. Any error is reported only when the response is received.

    The TPBLOCK flag enables verification of the service status when calling the service. With this flag set, WinTmaxSend() checks whether the requested service can be executed successfully before returning. If the service is unavailable, the function stores the corresponding error in tperrno and returns -1.

    If the service status cannot be verified within the specified BLOCKTIME, a TPETIME error is returned. In this case, the client cannot determine whether the service was successfully executed, so this should be considered when writing an error-handling routine. If the service request needs to be retried, you must first confirm whether the previous request was processed.

    TPNOREPLY

    When this flag is set, service requests sent through WinTmaxSend() return immediately without waiting for a response. Normally, results are received by a worker thread and delivered to the registered Windows system; with TPNOREPLY set, no response is expected.

    TPNOTRAN

    When the TPNOTRAN flag is set, a service request (svc) sent via WinTmaxSend() in transaction mode is executed outside the transaction.

    If a service does not support transactions in transaction mode, TPNOTRAN must be set to call WinTmaxSend(). Even when TPNOTRAN is used, the call is still subject to the transaction timeout. If the service fails while called with TPNOTRAN, the caller’s current transaction remains unaffected.

    TPNOBLOCK

    TPNOBLOCK causes a service request to fail in a blocking condition (e.g., the internal buffer is full with messages to send).

    If WinTmaxSend() 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 WinTmaxSend() 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

    Descriptor

    The function call succeeded and returns the descriptor. However, this descriptor is currently not used.

    -1

    The function call failed and an error code is set in tperrno.

  • Error

    If WinTmaxSend() fails, one of the following codes is set in tperrno.

    Error Code Description

    [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 timeout occurred. While neither TPNOTIME nor TPNOBLOCK was set, a block timeout occurred.

    [TPEBLOCK]

    A blocking condition occurred while TPNOBLOCK was set.

    [TPGOTSIG]

    A signal was received while TPSIGRSTRT was not set.

    [TPEPROTO]

    The function was called in an invalid state. For example, TPNOREPLY was called in transaction mode without setting TPNOTRAN.

    [TPESYSTEM]

    An error occurred in the Tmax system.

    [TPECLOSE]

    The connection with the Tmax system was lost due to a network error or other issues.

    [TPEOS]

    An error occurred in the operating system.

    If LPARAM for the message delivered to Windows is -1, one of the following error codes is set in tperrno.

    Error Code Description

    [TPEBADDESC]

    The response message was received, but no valid descriptor was found.

    [TPEOTYPE]

    The response message was received, but the buffer type used by the client and server did not match.

    [TPEPROTO]

    WinTmaxStart() or WinTmaxEnd() was called in an invalid state.

    [TPESYSTEM]

    An error occurred in the Tmax system.

    [TPECLOSE]

    The connection with the Tmax system was lost due to a network error or other issues.

    [TPEOS]

    An error occurred in the operating system.

  • Example

    ...
int CTMaxGwView::SendData2(char *data, long nLen)
{
    CString szTemp;
    m_send_length.Format(“%d”,nLen);
    UpdateData(FALSE);

    char *tpbuf = tpalloc(“STRING”, NULL, nLen);
    if (tpbuf == NULL) {
        szTemp.Format(“tpalloc Error [%s]”, tpstrerror(tperrno));
        LogDisplay2(2, (char *)(const char *)szTemp, szTemp.GetLength());
        return -1;
    }

   memcpy(tpbuf, data, nLen);

   CString strService;
   strService.Format(“TOUPPER_STRING”);

   int nSendResult=WinTmaxSend(2,(LPSTR)(LPCSTR)strService, (char*)tpbuf, nLen, 0);
   tpfree(tpbuf);
    …
}

  • Related functions

    WinTmaxStart(),WinTmaxEnd()

14. Multithread/Multicontext

Describes functions that are related to multithread/multicontext. Multithread and multicontext server libraries are different from client libraries in the multicontext type.

14.1. tpgetctxt

The tpgetctxt function returns the context ID set in the thread that calls the function, as its first parameter.

In a Multithread/Multicontext server, tpgetctxt() returns a value of 1 or greater if the context set in the thread is valid. If the context is invalid or not set, tpgetctxt() returns TPNULLCONTEXT (-2).

A context is valid only while a service thread is processing a service request. After tpreturn() is called and the service request is completed, the context is no longer valid, and user-created threads can no longer use it.

tpgetctxt() is used differently in client and server programs. The following sections describe its usage separately for servers and clients.

Multithread/Multicontext servers do not support Singlecontext.

  • Prototype

    #include <usrinc/atmi.h>
int tpgetctxt(int *ctxtid, long flags)

  • Parameter

    Parameter Description

    ctxtid

    Retrieves the current context at the time when the function is called.

    • Multicontext : A value that is greater than 1.

    • Singlecontext : A value of 0.

    If the TPFUNC flag is set, the parameter value for the ctxid to retrieve must be specified before calling the function.

    flags

    In multi-thread clients, the following flag can be set.

    • TPFUNC : The number of threads sharing the specified ctxtid is returned. The parameter value must be specified first before calling the function.

    In server programs, set to TPNOFLAGS or 0.

  • Return Value

    Value Description

    0

    The function call succeeded.

    A value greater than 0

    If TPFUNC is set, this indicates the number of threads sharing the specified ctxtid.

    -1

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tpgetctxt() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEINVAL]

    An invalid parameter was specified. For example, the first parameter is set to a pointer value, or the second parameter is set to a value other than 0.

    [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

    • Client program

      int newContext()
{
    int i;
    int id;
    i = tpstart(tpinfo);
    if (i < 0)
    {
        printf(“\t[newContext]tpstart fail[%d][%s]\n",tperrno,
                tpstrerror(tperrno));
        tpfree((char *)tpinfo);
        return -1;
    }
    i = tpgetctxt(&id,TPNOFLAGS);
    if (i < 0)
    {
        printf(“\t[newContext]tpgetctxt fail[%d][%s]\n",tperrno,
                 tpstrerror(tperrno));
        return -1;
    }
    return id;
}

    • Client program (flags TPFUNC)

      int check(int context_id)
{
    int numthr;
    int id;
    id = context_id;
    numthr = tpgetctxt(&id,TPFUNC);
    if (numthr < 0)
    {
        printf(“\ttpgetctxt fail[%d][%s]\n",tperrno, tpstrerror(tperrno));
        return -1;
    }
    return numthr;
}

    • Server program

      typedef param {
    int ctxtid;
    TPSVCINFO *svcinfo;
} param_t;

MSERVICE(TPSVCINFO *svcinfo)
{
    pthread_t tid;
    param_t param;

    printf("MSERVICE service is started!");
    tpgetctxt(&param.ctxtid, TPNOFLAGS);
    param.svcinfo = svcinfo;

    pthread_create(&tid, NULL, THREAD_ROUTINE, &param);
    pthread_join(tid, NULL);

    printf("MSERVICE service is finished!");
    tpreturn(TPSUCCESS, 0, svcinfo->data, 0L, TPNOFLAGS);
}

void *THREAD_ROUTINE(void *arg)
{
    param_t *param;
    TPSVCINFO *svcinfo;

    param = (param_t *)arg;
    svcinfo = param->svcinfo;

    if (tpsetctxt(param->ctxtid, TPNOFLAGS) == -1) {
        printf("tpsetctxt(%d) failed, [tperrno:%d]", param->ctxtid, tperrno);
        return NULL;
    }

    tpcall("MTOUPPER", sndbuf, 0, &rcvbuf, &rcvlen, TPNOFLAGS);

    if (tpsetctxt(TPNULLCONTEXT, TPNOFLAGS) == -1) {
        printf("tpsetctxt(TPNULLCONTEXT) failed, [tperrno:%d]", tperrno);
        return NULL;
    }

    return NULL;
}

  • Related function

    tpsetctxt()

14.2. tpsetctxt

The tpsetctxt function sets the current context. Its usage differs between client programs and server programs:

  • Client Program

    A client can assign a previously created context to the current client. Most ATMI functions are context-based. To check the current context of a client, use the return value of tpgetctxt().

    A client can use multiple contexts, but only one context is active at a time. For example, if tpacall() is called in context1, then tpgetrply() must also be called in context1, even if another context has since been activated.

  • Server Program

    A service thread automatically has its own context, but a user-created thread does not. To execute most ATMI functions, a user-created thread must first obtain a context. Such a thread can share a context with a service thread by calling tpsetctxt().

    If a user-created thread shares a context with a service thread, it can, for example, call tpgetrply() to receive a reply for a request issued by the service thread through tpacall().

    tpsetctxt() cannot be used within a service thread. Because a service thread already has its own context, attempting to replace it results in an error with the TPEPROTO code.

    When a user-created thread shares a context with a service thread, the user-created thread must call tpsetctxt(TPNULLCONTEXT) before the service thread calls tpreturn(). At the moment tpreturn() is invoked, the service thread’s context must no longer be shared. Otherwise, tpreturn() fails and returns TPESVCERR to the client. Synchronization is therefore required to control the process flow between threads.

    The ctxtid parameter of tpsetctxt() uses the context ID retrieved by calling tpgetctxt() from a service thread.

With consideration of the different ways how a function is written depending on the program, the basic information of tpsetctxt() is as follows:

  • Prototype

    #include <usrinc/atmi.h>
int tpsetctxt(int ctxtid, long flags)

  • Parameter

    Parameter Description

    ctxtid

    The context ID to set as the current context at the time of the function call.

    In a client program, a context ID using tpstart() can be used.

    In a server program, the context ID of a service thread can be used.

    Other context constants (such as TPNULLCONTEXT) may also be used, but TPINVALIDCONTEXT is not valid.

    flags

    No supported in the current version. Set to TPNOFLAGS or 0.

  • Return Value

    Value Description

    -1

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tpsetctxt() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEPROTO]

    The function was called under an inappropriate condition. For example, in a server program, it was called by a service thread, or the context ID passed as a parameter was invalid.

    [TPEINVAL]

    The parameter is invalid. For example, the context ID (ctxtid) was set to 0 or TPINVALIDCONTEXT, or the flag was set to a value other than 0.

    In a client program, this error may also occur if the function is called before tpstart() was executed, or if tpstart() was called without setting the buffer flag to TPMULTICONTEXTS.

    [TPENOENT]

    An invalid context was set to ctxtid.

    [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

    • Client program

      int altContext(int id)
{
    int i;
    int ret;
    ret = tpsetctxt(id, TPNOFLAGS);
    if (ret < 0)
    {
       printf(“\t[altContext]tpsetctxt fail[%d][%s]\n"tperrno,
                tpstrerror(tperrno));
       tpfree((char *)tpinfo);
       return -1;
    }
    return 1;
}

    • Server program

      typedef param {
    int ctxtid;
    TPSVCINFO *svcinfo;
} param_t;

MSERVICE(TPSVCINFO *svcinfo)
{
    pthread_t tid;
    param_t param;

    printf("MSERVICE service is started!");
    tpgetctxt(&param.ctxtid, TPNOFLAGS);
    param.svcinfo = svcinfo;

    pthread_create(&tid, NULL, THREAD_ROUTINE, &param);
    pthread_join(tid, NULL);

    printf("MSERVICE service is finished!");
    tpreturn(TPSUCCESS, 0, svcinfo->data, 0L, TPNOFLAGS);
}

void *THREAD_ROUTINE(void *arg)
{
    param_t *param;
    TPSVCINFO *svcinfo;

    param = (param_t *)arg;
    svcinfo = param->svcinfo;

    if (tpsetctxt(param->ctxtid, TPNOFLAGS) == -1) {
        printf("tpsetctxt(%d) failed, [tperrno:%d]", param->ctxtid, tperrno);
        return NULL;
    }

    tpcall("MTOUPPER", sndbuf, 0, &rcvbuf, &rcvlen, TPNOFLAGS);

    if (tpsetctxt(TPNULLCONTEXT, TPNOFLAGS) == -1) {
        printf("tpsetctxt(TPNULLCONTEXT) failed, [tperrno:%d]", tperrno);
        return NULL;
    }

    return NULL;
}

  • Related function

    tpgetctxt()