Client API

This chapter describes the APIs used in client program development.

1. Overview

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

  • Connection and Disconnection

    Function Description

    tpstart

    Connects client to the Tmax system.

    tpend

    Disconnects client from the Tmax system.

  • Synchronous Communication

    Function Description

    tpcall

    Sends a service request through synchronous communication and waits for a reply.

  • Asynchronous Communication

    Function Description

    tpacall

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

    tpgetrply

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

    tpcancel

    Cancels a server or client reply.

  • Interactive Communication

    Function 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 close the interactive communication connection.

  • Unsolicited Message Processing

    Function Description

    tpsetunsol

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

    tpgetunsol

    Processes unsolicited messages.

  • Timeout Change

    Function Description

    tpset_timeout

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

    tpsetsvctimeout

    Called in a service to set the service timeout.

  • Buffer Management

    Function 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

    Function 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

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

  • Functions using Events

    Function 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 and Multicast

    Function Description

    tpbroadcast

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

  • Windows Environment Programming

    • tmaxmt.dll

      Function 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

      Function 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 and Multicontext

    Function 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

Connects a client to a Tmax system. Before using ATMI functions to process service requests or transactions, a client must use tpstart() to connect to a Tmax system.

Before tpstart() is called, if another ATMI function (tpalloc() or tpcall()) is called, tpstart(NULL) is called internally. To disable this action, set the TMAX_ACTIVATE_AUTO_TPSTART environment variable to N. In such a case, if another ATMI function is called, a TPEPROTO error is returned without calling tpstart(NULL) internally.

To connect to a Tmax system by using tpstart(), the IP and port number of the server where the Tmax system is installed are required. If tpstart() is returned successfully, the client can send an initial service request or can define a transaction. In this case, if tpstart() is called again, a TPEPROTO error occurs.

The following describes environment variables required to find server information.

Variable Description

TMAX_HOST_ADDR

IP address of a node to which a client is to be connected. This variable is used for a client to be internally connected to a server system when tpstart() is called.

TMAX_HOST_PORT

Port number of a node to which a client is to be connected. This variable is used together with a TMAX_HOST_ADDR for a client to be internally connected to a server system when tpstart() is called.

The port number must be defined in a TPORTNO in a Tmax configuration file. When both a client and a server reside in a node, it is more efficient to use a domain socket rather than a TCP/IP socket when processing a client request. In this case, replace the TPORTNO value with PATHDIR. Refer to the TPORNO item in the DOMAIN and NODE sections of a Tmax configuration file.

TMAX_BACKUP_ADDR

Alternative Tmax system node to use when the node specified by TMAX_HOST_ADDR fails. The client tries to connect to the node specified by TMAX_HOST_ADDR, and, if the attempt fails, to the node specified by TMAX_BACKUP_ADDR.

TMAX_BACKUP_PORT

Tmax system port number of the node with a TMAX_BACKUP_ADDR address.

TMAX_CONNECT_TIMEOUT

Timeout value for connecting to a Tmax system in microseconds. (Example: 3.5)

  • Prototype

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

  • Parameters

    A tpinfo is a pointer for a TPSTART_T structure. This structure uses a TPSTART buffer type, which must be allocated by a tpalloc() before tpstart() is called. After tpstart() has been called, the allocated buffer must be freed by using tpfree(). When connecting to the system, a client transfers necessary information with the tpinfo parameter, which contains client information, unsolicited message processing methods, and security information.

    You can set tpinfo to NULL. In this case, cltid, dompwd, usrname, and usrpwd are given zero-length strings, the Tmax security features is not enabled, and flags are not selected.

    The following shows a 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 security*/
      int flags; /*Unrequested message type and system access method*/
} ;
    Member Description

    cltid

    Character string ending with a NULL value that can be up to 30 characters long. A cltid is a name defined by an application program and is used to specify a client to which tpbroadcast() sends unsolicited messages.

    dompwd

    Password used for system access control of the Tmax security system. It registers a password for an account set to an OWNER item of the DOMAIN section of the Tmax configuration file.

    usrname

    User name used for user authentication of the Tmax security system. A usrname must be an account name registered in the passwd file of a Tmax system.

    usrpwd

    Password for an account. When user authentication is required, a client must register a usrname and usrpwd to connect to the Tmax system and access services. For information about security settings, refer to the SECURITY item in the DOMAIN section of the source config file.

    flags

    Used to determine how to handle unsolicited notifications and how to access the system.

    The following values are available.

    • TPUNSOL_POLL: receives unrequested messages.

    • TPUNSOL_HND: sets a function that receives unrequested messages. For more information, refer to tpsetunsol.

    • TPUNSOL_IGN: ignores unsolicited messages. (Default)

  • Return Values

    Value Description

    0 or 1

    A function call was successful. 0 is returned to the primary host and 1 to a backup host.

    1

    A function call failed. A tperrno is set to an error code.

  • Errors

    The following is a list of error codes to one of which tperrno is set to when tpstart() fails.

    Error Code Description

    [TPEINVAL]

    An invalid parameter. For example, a tpinfo is NULL or not a pointer for a TPSTART_T.

    [TPEITYPE]

    A tpinfo is not a pointer for a TPSTART_T structure.

    [TPEPROTO]

    A tpstart() was called from an invalid state. For example, a tpstart() was called in a server program, or it was called after a connection was already established.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred. Environment variables may be invalid. For example, a connection failed because a TMAX_HOST_ADDR or TMAX_HOST_PORT was invalid.

  • Examples

    #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 Funcitons

    tpend()

2.2. tpend

Disconnects a client from a Tmax system. If a client is in a transaction mode, a transaction will be rolled back automatically. If a tpend() is returned successfully, a caller will not communicate with any other programs and will not participate in any transactions. Maintained interactive connections will be terminated immediately.

If a tpend() is called more than once (if called again after already being disconnected from a Tmax system), a -1 value will be returned without affecting a system.

  • Prototype

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

  • Return Values

    Value Description

    -1

    A function call failed. tperrno is set to an error code.

  • Errors

    When a tpend() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEPROTO]

    tpend() was called from an invalid state. For example, a caller is a server or a tpend() was called after being disconnected.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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()

3. Synchronous Communication

The following describes functions that are used for synchronous communication.

3.1. tpcall

Sends a service request to a svc service named through synchronous communication and receives a reply. It works similar to calling a tpgetrply() successively after calling a tpacall().

If tx_time expires after tx_begin() is called, calling tpcall() occurs the TPETIME error.

  • Prototype

    # include <atmi.h>
int tpcall (char *svc, char *idata, long ilen, char **odata, long *olen,
            long flags)

  • Parameters

    Parameter Description

    svc

    Service that is requested, which must be one provided by a Tmax application server program.

    idata

    Pointer to service request data. The buffer must have been allocated by a tpalloc(). The type and subtype of an idata must be supported by the service specified by svc.

    ilen

    Data length.

    • If an idata points to a variable-length buffer type, such as STRING, STRUCT, X_COMMON, or X_C_TYPE, an ilen is ignored and set to 0 by default.

    • If an idata points to a fixed-length buffer type, such as X_OCTET, CARRAY, or MULTI STRUCTURE, an ilen cannot be set to 0.

    • If an idata is NULL, ilen is ignored.

    *odata

    Pointer to reply data with the length of a value specified by *olen. *odata must have been allocated by using tpalloc().

    If the same buffer is used to both send and receive data, *odata must be set to the idata address. Before tpcall() is completed, the reply buffer size of *odata and the value received by *olen are compared to determine whether to change the reply buffer size. If the reply buffer is smaller than the value of *olen, the reply buffer size is enlarged. Otherwise, the reply buffer size is unchanged. If tpcall() is called when idata and *odata are using the same buffer, the idata address becomes invalid if the reply buffer is too big or if any other occasion causes invalidation.

    If a *olen is returned as 0, no data is received and *odata and the buffer it refers to are not changed. If *odata or *olen is NULL, it is an error.

    *olen

    Reply data length in a *odata.

    flags

    Communication mode option.

    The following values are available.

    • TPNOTRAN

      If a program calls tpcall() to request the svc service with the flag set to TPNOTRAN in transaction mode, the service is executed outside the transaction. Therefore, to call a service that does not support transactions, set the flag to TPNOTRAN to call a tpcall() in transaction mode. When tpcall() is called in transaction mode, it is subject to a transaction timeout (TXTIME) even if the flag is set to TPNOTRAN. For example, a tpacall with a TPNOTRAN flag fails after a transaction times out without calling a service. If a service called with the flag set to TPNOTRAN fails, there is no effect on the current transaction of the caller.

    • TPNOCHANGE

      If a TPNOBLOCK flag is set and a blocking condition (for example, the internal buffer is full with messages to send) occurs, a request fails. A TPNOCHANGE is applied only to a Tx in a tpcall(). If a tpacall() is called without setting a TPNOBLOCK flag and a blocking condition occurs, a caller must wait until it is unblocked or until a transaction or blocking timeout occurs.

    • TPNOTIME

      A caller awaits a reply indefinitely and a blocking timeout is ignored. Timeout will occur even if a tpcall() is called during a transaction timeout.

    • 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 the flag set to TPSIGRSTRT, a function fails and tperrno is set to TPGOTSIG.

  • Return Values

    Value Description

    1

    A function call was successful.

    -1

    A function call failed, and a tperrno is set to an error code.

  • Errors

    If a tpcall() fails, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    Invalid parameter or flag. For example, svc is NULL or data points to a buffer that was not allocated by a tpalloc().

    [TPENOENT]

    The specified svc does not exist.

    [TPEITYPE]

    The svc does not support the idata type or subtype.

    [TPEOTYPE]

    A function caller does not know the type or subtype of a reply buffer, or flags were set to a TPNOCHANGE but the type or the subtype of the buffer pointed to by *odata does not match that of the reply buffer. In this case, the data in *odata and *olen are not changed.

    If a caller requests a service in transaction mode, the transaction is rolled back because a reply is ignored.

    [TPETRAN]

    A xa_start failed due to an error in a database while invoking a transaction service.

    [TPETIME]

    A transaction timeout occurred when a caller was in transaction mode, and the transaction was rolled back. If a caller is not in transaction mode and if neither TPNOTIME nor TPNOBLOCK is specified, a blocking timeout occurs. In that case, *data and *len are not changed. If a transaction timeout occurs, any attempt to receive a new service request or await a reply causes a [TPETIME] error and fails until the transaction is rolled back.

    [TPESVCFAIL]

    A service routine sent a reply by calling a tpreturn() with a TPFAIL because of an application error. Service reply data can be accessed through *odata.

    Communication may be attempted before a transaction is rolled back due to a transaction timeout. Such a communication attempt may succeed or fail. For the communication to succeed, you must specify TPNOTRAN. All operations performed while a 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 a tpreturn() (for example, a wrong argument was passed). If this error occurs, no reply data is returned, and neither *odata nor *olen is changed. This error occurs when a buffer that was not allocated by a tpalloc is used, when the Tmax header of an allocated buffer is affected by an invalid pointer such as memcpy, when a call descriptor of a tpacall or a tpconnect is returned, or when a service includes invalid interactive data while in recv mode. A client will receive this error when attempting to execute a tpreturn.

    When a TPEV_DISCOMN event occurs, which is equivalent to a TPEV_DISCOMN that is returned to a service program after a client forcefully disconnects a conversation, a client receives a tperrno set to TPESVCERR through a tpreturn of a service.

    If the caller is running a transaction, further communication may be attempted before a transaction is rolled back due to a transaction timeout. Such a communication attempt may succeed or fail. For the communications to succeed, you must specify TPNOTRAN. All operations performed while a caller is in transaction mode are rolled back when a transaction is complete.

    A SVCTIMEOUT can be specified for each service. If a service execution time exceeds a specified limit, service execution stops and returns a TPESVCERR. If a SVCTIMEOUT occurs, a tpsvctimeout() is called. Operations such as buffer lock releases and logging can be performed during a tpsvctimeout() as needed.

    [TPEBLOCK]

    Blocking occurred while the flag is set to TPNOBLOCK.

    [TPGOTSIG]

    A signal was received while the flag is not set to TPSIGRSTRT.

    [TPEPROTO]

    A tpcall() was called in an invalid state.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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

Sends a service request to a svc service through asynchronous communication and is returned immediately without awaiting a reply. A response can be obtained using tpgetrply() or canceled using tpcancel().

If tx_time expires after tx_begin() is called, tpacall() succeeds only when flags is set to TPNOTRAN or TPNOREPLY; otherwise, the TPETIME error occurs.

  • Prototype

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

  • Parameters

    Parameter Description

    svc

    Service to call. Must be provided by a Tmax application server program.

    data

    Pointer to a buffer allocated by a tpalloc().

    len

    Length of data to be sent.

    • If data points to a variable-length buffer type, such as STRING, STRUCT, X_COMMON, or X_C_TYPE, len is ignored and 0 is used.

    • If data points to a fixed-length buffer type, such as X_OCTET, CARRAY, or MULTI STRUCTURE, len cannot be 0.

    • If data is NULL, len is ignored and a service request is received without data. The data type and subtype must be supported by svc. If a service request is sent in transaction mode, a reply must be received.

    flags

    Calling mode option.

    The following values are available.

    • TPBLOCK

      If a tpacall is used without a flag, a normal reply is returned even if a called service does not exist in svc or if an invalid result is returned. An error is returned when a tpgetrply is called. If a TPBLOCK is used to call a tpacall(), the service state can be checked.

    • TPNOTRAN

      If a service does not support transactions in transaction mode, you must set the flag to TPNOTRAN to call tpacall(). If a caller requests the svc service by setting a flag in transaction mode, the service is executed outside the transaction. When tpacall() is called in transaction mode, the call is affected by a transaction timeout even if TPNOTRAN is specified. For example, a tpacall with the flag set to TPNOTRAN will fail after a transaction times out without calling a service. If a service called with the flag set to TPNOTRAN fails, there is no effect on the current transaction of the caller.

    • TPNOREPLY

      If tpacall() is used to send a service request, tpacall is returned immediately without awaiting a reply. A client can retrieve results by using tpgetrply() through the descriptor returned by tpacall(). If the flag is set to TPNOREPLY, tpacall() does not await a reply and returns 0 if a service is called successfully. If a caller is in transaction mode, you must specify TPNOREPLY together with TPNOTRAN. When TPNOREPLY is specified, you must specify TPBLOCK if you want to check a service state. If TPBLOCK is not specified, an error is returned even if a service is NRDY.

    • TPNOBLOCK

      If there is a blocking condition such as when an internal buffer is full of messages to send, this option causes a request to fail. If a tpacall() is called without setting the flag to TPNOBLOCK and if a blocking condition occurs, a caller must wait until a transaction or a blocking timeout occurs.

    • TPNOTIME

      A caller must wait indefinitely until a reply is received. Blocking timeouts are ignored. A timeout will occur even if a tpacall() is called during a transaction timeout.

    • TPSIGRSTRT

      Allows signal interrupts. If a system function call is interrupted by a signal, it will be re-executed. If a signal interrupt occurs without this flag set, a function will fail and tperrno will be set to TPGOTSIG.

    flags

    Flags are listed in the following table.

  • Return Values

    Value Description

    Descriptor

    A function call is successful. A returned descriptor is used to get a service reply.

    -1

    A function call failed, and tperrno is set to an error code.

  • Errors

    If a tpacall() fails, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    Invalid parameter. For example, when a svc is NULL, data will point to a buffer that was not allocated by a tpalloc(), or a flag will be invalid.

    [TPENOENT]

    The specified svc does not exist.

    [TPEITYPE]

    The data type or subtype is not supported by the svc. For a struct, this error occurs when the struct is not declared in a SDLFILE file.

    [TPELIMIT]

    The maximum number of unprocessed asynchronous service requests has been reached. A request was not sent.

    [TPETIME]

    A transaction timeout occurred when a caller was in transaction mode, and a transaction was rolled back. If a caller is not in transaction mode, and if neither TPNOTIME nor TPNOBLOCK is specified, a blocking timeout occurs. In that case, the data in *data and *len are not changed. If a transaction timeout occurs, any attempt to receive a new service request or await a reply causes a [TPETIME] error and fails until the transaction is rolled back.

    [TPEBLOCK]

    Blocking occurred while the flag is set to TPNOBLOCK.

    [TPGOTSIG]

    A signal was received while the flag is not set to TPSIGRSTRT.

    [TPEPROTO]

    A tpacall() was called in an invalid state. For example, a TPNOREPLY was called in a transaction mode without setting a TPNOTRAN.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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

Used to get a reply for an asynchronous service request made through a tpacall(). This function can be used on both a client and a server.

  • Prototype

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

  • Parameters

    Parameter Description

    cd

    Call descriptor returned by a tpacall(). In general, tpgetrply waits until a reply for a cd is received or until a timeout occurs. In general, cd becomes invalid after tpgetrply receives a valid reply.

    *data

    Pointer to a buffer allocated by a tpalloc().

    len

    Length of data received from a tpgetrply(). If necessary, the buffer size can be increased to store a reply.

    You can change the size of *data for various reasons such as when the buffer is smaller than the received data. Before tpgetrply is called, if a len is greater than the total size of a buffer, the buffer size will be set to the value of len. If len is returned as 0, no reply is received and buffers pointed to by a *data and len are not changed.

    If a *data or a len is NULL, it is an error.

    flags

    The following values are available.

    • TPGETANY

      Ignores the cd value specified for a reply and returns a reply that can be received. In general, tpgetrply() waits until a reply is received. If TPGETANY is not specified, *cd becomes null without additional settings. If TPGETANY is specified, cd can be used for an error response. If an error occurs before a response is returned, cd is set to 0. This does not affect a current transaction for a caller unless there are additional settings.

    • TPNOCHANGE

      The buffer type that *data points to cannot be changed. If the types of the reply buffer and *data do not match, the *data type is changed to the reply buffer type. If TPNOCHANGE is specified, the buffer type is not changed. The buffer type and subtype of a reply buffer must be the same as those of *data.

    • TPNOBLOCK

      Does not wait for a response, but returns a valid response if available. If a TPNOBLOCK flag is not set, and there is no available response, a caller waits until a reply is received or until a transaction or a blocking timeout occurs.

    • TPNOTIME

      A caller waits indefinitely until a reply is received. Blocking timeouts are ignored and timeout will occur even if a tpgetrply() is called during a transaction timeout.

    • TPSIGRSTRT

      Allows signal interrupts. If a system function call is interrupted by a signal, it is re-executed. If a signal interrupt occurs without this flag specified, the function will fail and a tperrno will be set to TPGOTSIG.

  • Return Values

    Value Description

    1

    A function call was successful. When a tpgetrply() returns successfully or a tperrno is [TPESVCFAIL], the global variable tpurcode returned by a tpreturn() will be set to a value defined in the application.

    -1

    A function call failed. tperrno is set to an error code.

  • Errors

    If a tpgetrply() fails, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    An invalid parameter. For example, a cd, data, *data, or a len is NULL or a flags is invalid. If a cd is not NULL, it is valid even if an error occurs, and a function will continue to wait for a response.

    [TPEBADDESC]

    An invalid cd.

    [TPEOTYPE]

    A caller does not know the type or subtype of a response buffer.

    In this case, flags are set to TPNOCHANGE but the type or subtype of *data does not match that of the response buffer, so the data in *data and *len are not changed. If the caller received a response in a transaction mode, the transaction will be rolled back because the response will be ignored.

    [TPETIME]

    A transaction timeout occurred when a caller is in a transaction mode, and the transaction is rolled back. If a caller is not in a transaction mode, a block timeout will occur if both a TPNOTIME and a TPNOBLOCK are not set. In such cases, the data in a *data and a *len are not changed. 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 a reply by calling a tpreturn() with a TPFAIL because an error occurred in an application program. Service reply data can be accessed through a *data. If a caller is in a transaction mode, the transaction will be rolled back.

    When a transaction timeout occurs, other communication may be attempted before a transaction is rolled back. For such attempts to be successful, a TPNOTRAN must be set. All operations performed while a caller is in a transaction mode are rolled back when the transaction is complete.

    [TPEBLOCK]

    Blocking occurred while a TPNOBLOCK was set. A cd is valid.

    [TPGOTSIG]

    A signal was received while a TPSIGRSTRT was not set.

    [TPEPROTO]

    A tpcall() was called in an invalid state.

    [TPETRAN]

    A xa_start failed due to an error in the database while invoking a transaction service.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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

Cancels a server or client response. It cancels the caller description, cd, returned by a tpacall().

  • Prototype

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

  • Parameters

    Parameter Description

    cd

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

  • Return Values

    Value Description

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tpcancel() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEBADDESC]

    An invalid cd.

    [TPETRAN]

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

    [TPEPROTO]

    A tpcanceled() was called from an invalid state.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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]);         /* Cancels 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 Functions

    tpacall()

5. Interactive Communication

The following describes functions that are used for interactive communication.

5.1. tpconnect

Allows a program to communicate with an interactive service svc. Communication is half-duplex, which only allows one process to either receive or send a message 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 a tprecv() is unnecessary to receive data delivered by tpconnect(). This function can be used on both a client and a server.

  • Prototype

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

  • Parameters

    Parameter Description

    svc

    Service name of an interactive service.

    data

    A buffer must be allocated by a tpalloc() for a caller to deliver data.

    len

    Length of data to be sent.

    • If data points to a buffer type that does not require a specified length, such as a STRING, STRUCT, X_COMMON, or X_C_TYPE, a len will be ignored and 0 will be used.

    • If data points to a buffer type that requires a specified length, such as a X_OCTET, CARRAY, or MULTI STRUCTURE, a len cannot be 0.

    If data is NULL, a len will be ignored and a service request will be received without data. The data type and subtype must be supported by a svc.

    flags

    The following values are available.

    • TPNOTRAN

      If a tpconnect() caller requests a svc service by setting a TPNOTRAN flag in a transaction mode, the svc service will be excluded from a transaction mode and then executed. If svc does not support transactions in a transaction mode and tpconnect() is called in transaction mode, a flag must be set to TPNOTRAN. If tpconnect() is called in a transaction mode, it is affected by a transaction timeout even if TPNOTRAN is set. If a service called with the flag set to TPNOTRAN fails, there is no effect on the current transaction of the caller.

    • TPSENDONLY

      After a connection is made, a caller can only send data and only the requested services can be performed. The caller gets the communication control first. The flag must be set to either TPSENDONLY or TPRECVONLY.

    • TPRECVONLY

      After a connection is made, a caller can only receive data and a requested service will send data, so at first, a requested service only has communication control. Either a TPSENDONLY or TPRECVONLY must be set.

    • TPNOTIME

      A function caller must wait indefinitely until a response is received. Blocking timeouts are ignored. If a tpacall() is called during a transaction timeout, a transaction timeout will be applied.

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

    Value Description

    Descriptor

    A function call was successful and a descriptor used for a following connection is returned.

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    If a function call fails, a caller’s transaction will not be affected unless there is a specific direction. When a tpconnect() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    An invalid parameter. For example, a svc is NULL, data points to a buffer that was not allocated by a tpalloc(), or a flag is invalid.

    [TPENOENT]

    Cannot request a service because a service corresponding to a svc does not exist.

    [TPEITYPE]

    A svc does not support a data type or subtype.

    [TPELIMIT]

    A maximum number of connections has been reached. Cannot request a service.

    [TPETRAN]

    A xa_start failed because a problem occurred in a database when a transaction service was requested.

    [TPETIME]

    A timeout occurred. If a transaction timeout occurs when a function caller is in a transaction mode, the transaction will be rolled back. If the function caller is not in a transaction mode, a block timeout will occur if neither a TPNOTIME nor a TPNOBLOCK is set.

    In these cases, *data content and *len are not changed. If a transaction timeout occurs, new service requests and processes waiting for a response fail with the [TPETIME] error until the transaction is rolled back.

    [TPEBLOCK]

    A blocking state occurred when a TPNOBLOCK was set.

    [TPGOTSIG]

    A signal was received when a TPSIGRSTRT was not set.

    [TPEPROTO]

    A tpconnect() was called from an invalid state.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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

Available in a server and a client. This function sends data to a partner program in an interactive communication. A caller must have communication control.

  • Prototype

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

  • Parameters

    Parameter Description

    cd

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

    data

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

    len

    A buffer length to receive. If data points to a buffer that does not need to be specified, a len will be ignored and 0 will be used. If data points to a buffer which must be specified, a len cannot be 0.

    flags

    The following values are available.

    • TPNOBLOCK

      If a blocking situation occurs, for example if an internal buffer is filled with messages to be sent, data and events will not be sent. If a tpsend() is called without setting a TPNOBLOCK flag or if a blocking state occurs, a caller will wait until either a transaction or a block timeout occurs or a state is resolved.

    • TPNOTIME

      A function caller waits for a response and infinitely ignores a block timeout. If a tpsend() is used within a transaction timeout, the transaction time will still apply.

    • TPRECVONLY

      A caller sends a communication control to a partner after receiving data. A caller cannot call a tpsend() until it receives a communication control again. A communication partner will receive a TPEV_SENDONLY event, which means a communication control will be received when receiving data using a tprecv(). A receiver cannot call a tprecv() until receiving a communication control from a partner.

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

    revent

    If an event exists for a descriptor cd, a tpsend() will fail and data will not be received. The event type will be returned as a revent.

    The events that can be delivered to revent are as follows:

    • TPEV_DISCONIMM

      A communication starter used a tpdiscon() to forcefully terminate a connection. This event is received by a communication subordinate and is returned when a connection is terminated due to a communication error such as server, node, or network error.

    • TREV_SVCERR

      This event is received by a communication starter and notifies that a communication subordinator performed a tpreturn() without a communication control being in a TPEV_SVCFAIL state.

    • TREV_SVCFAIL

      This event is received by a communication starter and notifies that a communication subordinator performed a tpreturn() without a communication control, and that a tpreturn() was called as a TPFAIL without data and that it was performed as a TPFAIL rval and had data with a NULL value.

  • Return Values

    If a revent is a TREV_SVCFAIL, a tpurcode global variable is set to a rcode value, which is delivered when calling a tpreturn().

    Value Description

    0

    A function call was successful.

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tpsend() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    An invalid parameter. For example, a svc is NULL, data points to a buffer that was not allocated by a tpalloc(), or a flag is invalid.

    [TPEBADDESC]

    An invalid cd.

    [TPETIME]

    A timeout occurred. If a transaction timeout occurs when a function caller is in a transaction mode, a transaction will be rolled back. If a function caller is not in a transaction mode, a block timeout will occur if neither a TPNOTIME nor a TPNOBLOCK is set.

    In these cases, a *data content and a *len will not be changed. If a transaction timeout occurs, new service requests and processes waiting for a response will fail with a [TPETIME] error until a transaction is rolled back.

    [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 state occured when a TPNOBLOCK was set.

    [TPGOTSIG]

    A signal that is received when a TPSIGRSTRT was not set.

    [TPEPROTO]

    A tpsend() was called from an invalid state. For example, a tpsend() was called in a receiver mode.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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

Available in a server and a client. This function receives messages in an interactive communication. This is used to receive data sent from a partner in an interactive communication. A tprecv() can be used only by a program (on a server or a client) which does not have communication control.

  • Prototype

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

  • Parameters

    Parameter Description

    cd

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

    data

    Pointer to a buffer allocated by a tpalloc(). If a function successfully returns, a *data will point to received data.

    len

    The length of data to be sent.

    If the value of a len is bigger than the total size of a buffer before calling it, the size of the buffer will be set to the value of len.

    If the value of a len is 0, no data will be received and neither *data nor a buffer, which a *data points to, will be changed.

    flags

    The following values are available.

    • TPNOCHANGE

      If a received response buffer and a buffer type that a *data points to are not the same, the buffer type of a *data will be changed to a received response buffer type in a scope that a receiver can recognize. If a 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 data. If there is receivable data the data will be returned. If a TPNOBLOCK flag is not set, and there is no receivable data, a caller will wait for data.

    • TPNOTIME

      A function caller waits infinitely until a response is received, and ignores block timeouts. If a tprecv() is used within a transaction timeout, a transaction time will be applied.

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

    revent

    The event types returned to a revent are as follows:

    • TPEV_DISCONIMM

      A communication starter used a 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. a cd used by an interactive communication will not be valid.

    • TPEV_SENDONLY

      A connected partner program gave up on a communication control. A TPEV_SENDONLY event receiver can send data but cannot receive any data until a receiver returns a control.

    • TPEV_SVCERR

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

    • TPEV_SVCFAIL

      This event notifies a communication starter of information that a service of a communication subordinator was terminated due to a failure. A tpreturn() was called using a TPFAIL as an argument. If a communication subordinator service has a communication control when calling a tpreturn(), a service cannot send data to a connected partner. A server process terminates an interactive connection when a service is terminated. Therefore, a cd will not be valid anymore. If this event occurs to a receiver transaction process, the transaction will be rolled back.

    • TPEV_SVCSUCC

      This event notifies a communication starter that a service of a communication subordinator was terminated successfully. A tpreturn() was called using a TPSUCCESS as an argument.

  • Return Values

    If a revent value is TREV_SVCSUCC or TREV_SVCFAIL, a tpurcode global variable that is delivered by a tpreturn() will be defined by an application. Otherwise, a -1 will be returned and a tperrno will be set to the value corresponding to a state. If an event has no error, a tprecv() will return a -1 and a tperrno will be set to [TPEEVENT].

  • Errors

    When a tprecv() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEBADDESC]

    An invalid cd.

    [TPEBLOCK]

    A blocking state occurred when a TPNOBLOCK was set.

    [TPEEVENT]

    An event occurred. Use a revent to find the event type.

    [TPEINVAL]

    An invalid parameter. For example, a svc is NULL, a *data points to a buffer that was not allocated by a tpalloc(), or a flag is invalid.

    [TPEOS]

    An operating system error occurred.

    [TPEOTYPE]

    The type or subtype of an entered buffer is unknown to a caller, or a TPNOCHANGE flag was set but the type or subtype of a buffer pointed to by a *data did not match the type or subtype of an entered buffer. In this case, both the contents of a *data and a *len are not changed. If interactive communication is a part of a transaction, the transaction will be rolled back because a reply will be ignored.

    If an error occurred, the event for a cd will be ignored and an interactive communication state cannot be guaranteed. Therefore a caller must terminate an interactive communication.

    [TPEPROTO]

    A tprecv() was called from an invalid state. For example, a tprecv() was called in a sender mode.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPETIME]

    A timeout occurred. If a transaction timeout occurs when a function caller is in a transaction mode, a transaction will be rolled back. If a function caller is not in a transaction mode, a block timeout will occur if neither a TPNOTIME nor a TPNOBLOCK are set.

    In these cases, a *data content and a *len are not changed. If a transaction timeout occurs, new service requests and processes waiting for a response will fail with a [TPETIME] error until a transaction is rolled back.

    [TPGOTSIG]

    A signal was received when a TPSIGRSTRT was not set.

  • Examples

    #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

Terminates an interactive communications connection. If a service is connected by a tpconnect(), in extremely rare cases the connection will immediately terminate and a TPEV_DISCONIMM event will occur for the connection partner. This function can be used on both a client and a server.

A tpdiscon() can be called only by the side that started an interactive communication. The service that provides a descriptor cannot call a tpdiscon(). A program that communicates with an interactive service can terminate communication. To ensure correct results, a tpreturn() must be called to terminate the connection.

A tpdiscon() terminates a connection forcibly, which may result in data that did reach a target to become lost. It can be called while a connected program participates in a caller’s transaction. In this case a transaction is canceled and data may be lost. A function caller does not need to have communication control.

  • Prototype

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

  • Parameters

    Parameter Description

    cd

    A descriptor returned by a tpconnect().

  • Return Values

    Value Description

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tpdiscon() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEBADDESC]

    An invalid cd, or a cd is already in use by an interactive service.

    [TPETIME]

    A timeout occurred due to an invalid cd.

    [TPEPROTO]

    A tpdiscon() was called from an invalid state.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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 Processing

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

Available in a client. This function sets a routine that processes unrequested and received messages. How a system receives unrequested messages is determined by each application and can be changed by each client.

Any unrequested messages received by Tmax libraries before a tpsetunsol() is called will be ignored. A tpsetunsol() that is called by a NULL function pointer is also ignored. The function pointer delivered by a call must be suitable for a parameter definition.

  • Prototype

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

  • Parameters

    Parameter Description

    data

    Points to a received type buffer. If there is no data, a DATA can be NULL. If a buffer type or subtype of a DATA are unknown by a client, data cannot be recognized. An application cannot delete a DATA, instead a system deletes it and nullify a data area to return.

    len

    Data length

    flags

    Not currently supported.

  • Return Values

    Value Description

    Pointer / NULL

    A function call was a success.

    • Pointer: Returns the pointer of a routine for an unrequested message process that was previously set.

    • NULL: A message process function was not previously set. A return will be successful.

    TPUNSOLERR

    A function call failed. An error code will be set in tperrno.

  • Errors

    When a tpsetunsol() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEPROTO]

    A tpsetunsol() was called from an invalid state.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information will be recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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

Processes a message that was received unilaterally without a client request. The message is sent through a tpbroadcast(), tpsendtocli(), tppost() from a sender.

All messages received before calling a tpgetunsol() will be ignored. To receive unrequested messages through a tpgetunsol(), a TPUNSOL_POLL or a TPUNSOL_HND must be set when connecting to a Tmax system through a tpstart(). If a tpgetunsol() is called from a program, a client will receive an unrequested message from a server because a flag has been changed to TPUNSOL_POLL internally even though the flag of a tpstart() was initially set to TPUNSOL_IGN.

  • Prototype

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

  • Parameters

    Parameter Description

    type

    A message type delivered from a server. The types are UNSOL_TPPOST, UNSOL_TPBROADCAST, and UNSOL_TPSENDTOCLI.

    data

    A pointer to a delivered message. If this is a buffer type or subtype that is not known by a client, "data" cannot be used.

    len

    The total length of a message.

    flags

    Determines whether to block a message.

    The following values are available.

    • TPBLOCK

      A caller waits for a reply in a blocking state.

    • TPNOCHANGE

      In general, if a received response buffer and the buffer type pointed to by a *data do not match, the *data buffer type will be changed to a received response buffer in a scope that a receiver can recognize. If this is set, the buffer type pointed to by a *data cannot be changed. A received response buffer type and subtype must match those of a buffer pointed to by a *data.

    • TPNOTIME

      A function caller must wait indefinitely until a response is received. Blocking a timeout will be ignored. If a tpgetrply() is called during a transaction timeout, a transaction timeout will be applied.

    • 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 tperrno will be set to TPGOTSIG.

    • TPGETANY

      Ignores a cd as an input value and returns any receivable responses. A cd will become a caller descriptor for a returned response. If there is no response, a tpgetrply() will wait until a response is received.

  • Return Values

    Value Description

    1

    A function call was successful.

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tpgetunsol() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEPROTO]

    A tpgetunsol() was called from an invalid state. For example, it was called from a server.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information will be recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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

Available in a server and a client. This function sets a block timeout, a service limited time set in a server. If a timeout is set using a tpset_timeout(), the response for a service request will wait during the specified amount of time. If a response is not received during the specified amount of time, a timeout error will occur and the service request will be returned as a failure without waiting for a response.

A tpset_timeout() applies to service requests that were received after this function was called. The function is valid until a tpset_timeout() is called again, or a client or server process is terminated. If a tpset_timeout() is not used, a BLOCKTIME set in a Tmax configuration file will be used as a block timeout.

  • Prototype

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

  • Parameters

    Parameter Description

    sec

    Sets a block time in seconds.

  • Return Values

    Value Description

    0

    A function call was successful.

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tpset_timeout() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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

Available in a server. This function sets a service timeout in a server. If a service time is set using a tpsetsvctimeout(), a service request will wait for a response during the time set by this function. If a response was not received during the set time, a timeout error will occur and a service request will be returned as a service failure without waiting for a response.

  • Prototype

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

  • Parameters

    Parameter Description

    sec

    Sets a service timeout in seconds.

    flags

    Not currently supported.

  • Return Values

    Value Description

    0

    A function call was successful.

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tpsetsvctimeout() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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

Allocates a typed buffer. A buffer cannot be set by malloc(), realloc(), or free() of C library. For example, the buffer allocated with tpalloc() cannot be deleted through free().The tpalloc function allocates a typed buffer in servers and clients. It cannot be used along with malloc(), realloc(), or free() of C library. For example, a buffer allocated by tpalloc() cannot be released by free().In this case, tpfree() must be used.

The tpalloc function allocates a buffer of the type specified by "type", and it returns the pointer to the buffer. The buffer subtype and size can also be specified for some types. Some types of buffers require initialization, so tpalloc() initializes and returns pointers to these buffers. The buffer returned to the caller can be used immediately. If tpalloc() fails to initialize the buffer to 0, the allocated buffer becomes free.

  • Prototype

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

  • Parameters

    Parameter Description

    type

    Buffer type. Input options:

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

    Value Description

    Buffer Pointer

    A function call was successful and a proper buffer pointer is returned.

    NULL

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tpalloc() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

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

    [TPENOENT]

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

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred. Memory cannot be allocated.

    [TPEOTYPE]

    Buffer type is STRUCT but the server is compiled without a structure file.

  • Examples

    #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

Reallocates a buffer pointed to by a ptr in bytes, and returns a pointer for a new buffer (when a buffer is changed).

Like a tpalloc(), a buffer size must be larger than the default size (1024 bytes). A buffer type is kept the same even after it is reallocated. When a function successfully returns a pointer, the returned pointer is used to refer to a reallocated buffer. At this time, a ptr cannot be used any more. If a reallocated buffer size is smaller than a previous buffer size, the original ptr content cannot be ensured.

Some buffer types need to be initialized to be used. A tprealloc() re-initializes a re-allocated buffer and then returns it. Therefore, a buffer returned to a caller can be used immediately. If it fails to reinitialize a buffer, a tprealloc() will returns a NULL and data in a buffer pointed by a ptr will not be valid.

  • Prototype

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

  • Parameters

    Parameter Description

    ptr

    A pointer to a buffer to be allocated.

    size

    The size of a buffer to be allocated.

  • Return Values

    Value Description

    Buffer Pointer

    A function call was successful and a proper buffer pointer is returned.

    NULL

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tprealloc() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    An invalid parameter. For example, a buffer pointed by a ptr is not the one allocated by a tpalloc().

    [TPEPROTO]

    A tprealloc() was called from an invalid state.

    [TPENOENT]

    A buffer pointed to by a ptr was not allocated by a tpalloc().

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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()

This function cannot be used together with a malloc(), realloc(), or free() from a C library. For example, it is impossible to free a buffer allocated by a tprealloc() by using a free().

8.3. tpfree

Releases memory that is allocated to a typed buffer by a tpalloc() or a tprealloc(). This function can be used on both a client and a server.

  • Prototype

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

  • Parameters

    Parameter Description

    ptr

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

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

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

  • Return Values

    A tpfree() function does not return any value to a function caller.

  • Examples

    #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()

This function cannot be used together with a malloc(), a realloc(), or a free() from a C library. For example, it is impossible to free a buffer allocated by a tpalloc() by using a free().

8.4. tptypes

Provides information about the type and subtype of a buffer. This function is available both in a server and a client. A tptypes() 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)

  • Parameters

    Parameter Description

    ptr

    Must indicate a buffer allocated by a tpalloc().

    type, subtype

    Types and subtypes will have type and subtype names of each buffer respectively for the string they indicate if they are not NULL. If names have a maximum length (8 characters for a type, and 16 characters for a subtype), a string could not end with a NULL. If there is no subtype, the arrangement indicated by a subtype will contain a NULL string.

    Only the first 8 bytes of a type and 16 bytes of a subtype have valid values.

  • Return Values

    Value Description

    Buffer Size

    A function call was successful and a proper buffer pointer is returned.

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tptypes() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    An invalid parameter. For example, a buffer pointed to by a ptr is not allocated by a tpalloc().

    [TPEPROTO]

    A tptypes() was called from an invalid state.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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

Begins a global transaction, for which a function caller becomes a transaction mode. This function is available for both servers and clients. To start a transaction, a calling process must be first connected to a resource manager with a tx_open(), then, it will return a [TX_PROTOCOL_ERROR]. A tx_begin() function will fail if a caller is already in a transaction mode or a tx_open() is not called first.

Once a transaction begins, a calling process must call a tx_commit() or a tx_rollback() in order to complete a current transaction. There are also chaining transactions that do not need to call a tx_begin() directly in order to begin. For further information, see tx_commit and tx_rollback.

  • Prototype

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

  • Return Values

    Value Description

    TX_OK

    A function call was successful.

    Negative Value

    A function call failed.

  • Errors

    When a tx_begin() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TX_OUTSIDE]

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

    [TX_PROTOCOL_ ERROR]

    A tx_begin() was called from an invalid state. For example, a caller is already in a transaction mode. This error does not affect current transactions.

    [TX_ERROR]

    A transaction manager or a resource manager momentarily encountered an error while starting a transaction. When this error is returned, a caller is not in a transaction mode. Exact causes of the error depend on product characteristics.

    [TX_FAIL]

    A transaction manager or a resource manager encountered a critical error. The manager can no longer execute jobs for an application program. When this error is returned, a caller is not in a transaction mode. Exact causes of the error differ depending on product characteristics.

  • Examples

    #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

Commits a global transaction. This function is available for both servers and clients.

When a transaction_control property value is TX_UNCHAINED, a caller will not be in a transaction mode anymore when a tx_commit() returns. However, if the value is TX_CHAINED, the caller will remain in the transaction mode for a new transaction when the tx_commit() returns. For detailed information, see tx_set_transaction_control.

  • Prototype

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

  • Return Values

    Value Description

    TX_OK

    A function call was successful.

    Negative Value

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tx_commit() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TX_NO_BEGIN]

    Occurs only when a transaction_control property is a TX_CHAINED. A transaction was successfully committed, but new transactions cannot be started, and a caller will no longer be in a transaction mode.

    [TX_ROLLBACK]

    A transaction is rolled back. If a transaction_control property is TX_CHAINED, a new transaction will begin.

    [TX_ROLLBACK_NO_ BEGIN]

    Occurs only when a transaction_control property is TX_CHAINED. A transaction is rolled back, but new transactions cannot be started, and a caller is no longer in a transaction mode.

    [TX_HAZARD]

    Portions of a transaction may be committed while others may be rolled back due to an error. If a transaction_control property is TX_CHAINED, a new transaction will be started.

    [TX_HAZARD_NO_ BEGIN]

    Occurs only when a transaction_control property is TX_CHAINED. Portions of a transaction are committed while others are rolled back. A new transaction cannot be started and a caller will no longer be in a transaction mode.

    [TX_PROTOCOL_ ERROR]

    A tx_commit() was called from an invalid state. For example, a caller was not in a transaction mode. a caller’s status is not affected by the transaction.

    [TX_FAIL]

    A transaction manager or a resource manager encountered a critical error. A manager can no longer execute jobs for an application program. Exact causes of the error differ depending on product characteristics. The caller’s status related to the transaction is unknown.

  • Examples

    #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

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

  • Prototype

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

  • Parameters

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

    A TXINFO structure is composed as follows:

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

    If a tx_info() is called in a transaction mode, a xid will be the current transaction branch ID, and a transaction_state will be the current transaction state. If a caller is not in a transaction mode, a xid will be a NULL XID (See <tx.h> for further information).

    In addition, regardless of whether a caller is in transaction mode or not, when_return, transaction_control, and transaction_timeout will contain the current settings of a commit_return, transaction_control property, and a transaction timeout value in seconds.

    A returned transaction timeout value is used when a next transaction begins. It may not be a timeout value for a caller’s current global transaction, because the caller might have changed the transaction timeout by calling a tx_set_transaction_timeout() after a current transaction began. If info is NULL, a TXINFO structure will not be returned.

    Continuous tx_info() calling in the same global transaction ensures provision of a XID of the same gtrid (global transaction identifier). However, it does not ensure a same bqual (local transaction identifier). Thus, XIDs may not be the same.

  • Return Values

    Value Description

    1

    A caller is in a transaction mode and a function call was successful.

    0

    A caller is not in a transaction mode and a function call was successful.

    Negative Value

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tx_info() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TX_PROTOCOL_ ERROR]

    A tx_info() was called from an invalid state. For example, a tx_open() was not yet called.

    [TX_FAIL]

    A transaction manager encountered a critical error. The manager can no longer execute jobs for an application program. Exact causes of the error differ depending on product characteristics.

  • Examples

    #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

Used to roll back a global transaction. This function is available for both servers and clients.

If a transaction_control property is TX_UNCHAINED, a caller will not be in a transaction mode any more when a tx_rollback() returns. If a transaction_control property is TX_CHAINED, however, a caller will remain in a transaction mode for a new transaction when a tx_rollback() returns. For detailed information about a transaction_control property, see tx_set_transaction_control.

  • Prototype

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

  • Return Values

    Value Description

    TX_OK

    A function call was successful.

    Negative Value

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tx_rollback() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TX_NO_BEGIN]

    Occurs only when a transaction_control property is TX_CHAINED. New transactions cannot be started, and a caller is no longer in a transaction mode.

    [TX_MIXED]

    Portions of a transaction may be committed while others may be rolled back due to an error. If a transaction_control property is TX_CHAINED, a new transaction will be started.

    [TX_MIXED_NO_ BEGIN]

    Occurs only when a transaction_control property is TX_CHAINED. Portions of a transaction are committed while others are rolled back. A new transaction cannot be started and a caller will no longer be in a transaction mode.

    [TX_HAZARD]

    Portions of a transaction may be committed while others may be rolled back due to an error. If a transaction_control property is TX_CHAINED, a new transaction will be started.

    [TX_HAZARD_NO_ BEGIN]

    Occurs only when a transaction_control property is TX_CHAINED. Portions of a transaction are committed while others are rolled back. A new transaction cannot be started and a caller will no longer be in a transaction mode.

    [TX_COMMITTED]

    A transaction was committed independently. If a transaction_control property is TX_CHAINED, a new transaction will be started.

    [TX_COMMITTED_ NO_BEGIN]

    Occurs only when a transaction_control property is TX_CHAINED. A transaction was successfully committed, but new transactions cannot be started, and a caller will no longer be in a transaction mode.

    [TX_PROTOCOL_ ERROR]

    A tx_rollback() was called from an invalid state. For example, a caller was not in a transaction mode. A caller’s status is not affected by a transaction.

    [TX_FAIL]

    A transaction manager or a resource manager encountered a critical error. A manager can no longer execute jobs for an application program. Exact causes of an error differ depending on product characteristics. A caller’s status related to a transaction is unknown.

  • Examples

    #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

Sets a transaction_timeout property for a timeout value. This function is available for both servers and clients. This value indicates the time in which a transaction must be completed before a transaction timeout occurs. In other words, it is the interval between a tx_begin() and a tx_commit(), or a tx_begin() and a tx_rollback().

A tx_set_transaction_timeout() function can be called regardless of whether a function caller is in a transaction mode or not. If a tx_set_transaction_timeout() is called in a transaction mode, a new timeout value will be applied from a following transaction.

  • Prototype

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

  • Parameters

    Parameter Description

    timeout

    Specifies a time allowed until a transaction timeout occurs, in seconds. It can be set up to a maximum value of a long type defined for each system. Default setting of a transaction_timeout is 0, which means there is no timeout limit.

  • Return Values

    Value Description

    TX_OK

    A function call was successful.

    Negative Value

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tx_set_transaction_timeout() fails to execute, tperrno will be set to one of the following values and a transaction_timeout value will be unchanged.

    Error Code Description

    [TX_EINVAL]

    An invalid timeout value.

    [TX_PROTOCOL_ ERROR]

    A tx_set_transaction_timeout() was called from an invalid state. For example, a tx_open() was not yet called.

    [TX_FAIL]

    A transaction manager encountered a critical error. A manager can no longer execute jobs for an application program. Exact causes of the error differ depending on product characteristics.

  • Examples

    #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

Sets a transaction_control property with a control value. This function is available for both servers and clients.

This property determines whether to or not start a new transaction before a tx_commit() and a tx_rollback() returns to a caller. tx_set_transaction_control() can be called regardless of whether an application program is in a transaction mode or not. This setting is valid until it is changed as tx_set_transaction_control() is called again.

  • Prototype

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

  • Parameters

    Values available for control are as follows:

    Configuration Value Description

    TX_UNCHAINED

    The initial value of transaction_control property. Does not start a new transaction until a tx_commit() or a tx_rollback() is returned to a caller. In this case, a caller must execute a tx_begin() in order to begin a new transaction.

    TX_CHAINED

    Allows a new transaction to start before a tx_commit() or a tx_rollback() is returned to a caller.

  • Return Values

    Value Description

    TX_OK

    A function call was successful.

    Negative Value

    A function call failed. A tperrno is set to an error code.

  • Errors

    When tx_set_transaction_control() fails to execute, tperrno will be set to one of the following values and a previous transaction_control property will be unchanged.

    Error Code Description

    [TX_EINVAL]

    A control parameter is neither TX_UNCHAINED nor TX_CHAINED.

    [TX_PROTOCOL_ ERROR]

    A tx_set_transaction_control() was called from an invalid state. For example, a tx_open() was not yet called.

    [TX_FAIL]

    A transaction manager encountered a critical error. The manager can no longer execute jobs for an application program. Exact causes of the error differ depending on product characteristics.

  • Examples

    #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

Sets a commit_return property with a when_return value. This function is available for both servers and clients.

This property determines the method how a tx_commit() function returns a control to a caller. A tx_set_commit_return() can be called regardless of whether a function caller is in a transaction mode. This setting is valid until it is changed as a tx_set_commit_return() is called again. Initial setting of a commit_return property depends on the situation when the function is executed.

  • Prototype

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

  • Parameters

    Values available for when_return are as follows:

    Configuration Value Description

    TX_COMMIT_ DECISION_ LOGGED

    This flag causes a tx_commit() to return before the second phase of a Two-Phase Commit (2PC) protocol is completed after it was logged in a first phase. This allows a tx_commit() to respond to a caller more quickly. However, there is a danger that a transaction may have a heuristic result. In this case, a caller cannot understand the situation generated by the code returned from a tx_commit(). In normal cases, a transaction participant scheduled to commit a transaction in a first phase can normally commit a transaction in a second phase. In abnormal cases such as a network failure or a node fail lasting too long, it may be impossible to complete a second phase and a heuristic result may be resulted. A transaction manager can select this property not to be supported, using a parameter. At this time, a tx_commit() returns [TX_NOT_SUPPORTED], indicating that this property is not supported.

    TX_COMMIT_ COMPLETED

    This flag causes a tx_commit() to return after a 2PC protocol is completed. This setting shows a function caller return code indicating that a transaction produced a heuristic result or a probability. A transaction manager can select this property not to be supported, using a parameter. At this time a tx_commit() returns a [TX_NOT_SUPPORTED], indicating that this property is not supported.

  • Return Values

    When successfully completed, a tx_set_commit_return() returns a [TX_OK] of a value other than a negative value.

    If a when_return is set to a TX_COMMIT_COMPLETED or a TX_COMMIT_DECISION_LOGGED, a function will return a [TX_NOT_SUPPORTED] instead of a negative value and a previously used commit_return property will still be valid. A transaction manager must set a when_return to either a TX_COMMIT_COMPLETED or a TX_COMMIT_DECISION_ LOGGED.

  • Errors

    When a tmax_chk_conn() fails to execute, a tperrno will be set to one of the following values, and a commit_return property will be unchanged.

    Error Code Description

    [TX_EINVAL]

    A when_return is not set to TX_COMMIT_COMPLETED or TX_COMMIT_DECISION_LOGGED.

    [TX_PROTOCOL_ ERROR]

    A tx_set_commit_return() was called from an invalid state. For example, a tx_open() was not yet called.

    [TX_FAIL]

    A transaction manager or a resource manager encountered a critical error. The managers could no longer execute jobs for an application program. Exact causes of the error differ depending on product characteristics. A caller’s status, related to the transaction, is unknown.

  • Examples

    #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 failure 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 guaranteed data integrity.

10.1. tpenq

The Tmax system ensures the integrity of data stored in a RQ even when a system fault or error causes an out of service status. A tpenq() saves data to a RQ. If a system crashes, it will continue processing data once the system recovers.

If a service is requested through a tpcall() or a tpacall(), requests will be queued if there are other requests waiting to be processed. If a system error or failure causes a system shutdown, queued data will be lost. To prevent data loss and to improve data consistency, a tpenq() saves data in a RQ for each service request.

Although a tpenq() is executed in a transaction mode, it is excluded from transaction modes. If an error occurs while this function is being executed in a transaction mode, a transaction will not be affected.

  • Prototype

    # include  <tmaxapi.h>
int  tpenq (char *qname, char *svc, char *data, long len, long flags)

  • Parameters

    Parameter Description

    qname

    A RQ that saves data. A name must be specified and registered in a configuration file.

    svc

    Stores data to a RQ and immediately requests a service unless a 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, a function caller must request the service again using a tpdeq(). If a system fault occurs when there is no service named svc or a 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 a tpdeq() or processed as an error.

    data

    This is a pointer to a buffer allocated by a tpalloc() unless the value is NULL,. The type and subtype of data must be supported by a 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 a STRING, STRUCT, X_COMMON, or X_C_TYPE, a len will be ignored and 0 will be used.

    • If data points to a buffer type that requires a specified length, such asa X_OCTET, CARRAY, or MULTI STRUCTURE, a len cannot be 0.

    • If data is NULL, len is ignored and a service request will be received without data.

    flags

    The following values are available.

    • TPRQS

      When a svc is not NULL, a function caller will request a svc service and store service results in a RQ. To receive service results,a tpdeq() must be called. If a svc is NULL, data will be stored in a RQ but a service will not be performed.

    • TPNOREPLY

      When a svc is not NULL, a function caller will request a svc service and will not store results in a RQ. If a svc is NULL, data will be stored in a RQ but a service will not be performed.

    • TPFUNC

      Manages RQ data by service. If a TPFUNC is not set, data stored by a tpenq() will be de-queued when it is initially stored. If data must be de-queued before it is stored, a TPFUNC must be set when calling a tpenq().

    • 0 (zero)

      Stores service results to a client buffer of a Tmax system that is connected to a function caller. Service is requested through a RQ, but the results are saved to a client’s buffer similarly to a tpcall() function. Once this flag is set, a 0 (zero) must also be set when calling a tpdeq() in order to receive service results.

  • Return Values

    Value Description

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tpenq() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    An invalid parameter. For example, a svc is NULL, data points to a buffer that was not allocated by a tpalloc(), or a flag is invalid.

    [TPENOENT]

    A qname does not exist.

    [TPEQFULL]

    A maximum queue length reached due to continuous service results.

    [TPGOTSIG]

    A signal that is received when a TPSIGRSTRT is not set.

    [TPEPROTO]

    A tpenq() was called from an invalid state.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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

Loads data from a RQ. It receives the result of a service request or sets a service name to NULL and then reads stored data by using a tpenq() function. However, if a TPNOREPLY is set when a tpenq() is called, a service cannot receive any results, so even if an error occurs while executing a tpdeq() in a transaction mode, a transaction will not be affected.

  • Prototype

    # include  <tmaxapi.h>
int  tpdeq (char *qname, char *svc, char **data, long *len, long flags)

  • Parameters

    Parameter Description

    qname

    A RQ that saves data. A name must be specified and registered in a configuration file.

    svc

    A svc must be set to a service name when a tpenq() is called. In other words, if a tpenq() is called with a service name, a service will automatically be requested and the results will be stored in a RQ. In order to receive service results, the same service name must be specified.

    If the service name is NULL when a tpenq() is called, the same service name must be entered for a tpdeq_ctl(). If the service name is NULL, all data accumulated in a queue can be loaded individually regardless of the service name.

    To call a tpdeq() for data saved in a fail queue due to an error or a system failure, a svc must be set to _rq_sub_queue_name[TMAX_FAIL_QUEUE].

    *data

    A pointer to a buffer allocated by a tpalloc(). When a function is successfully returned, received data will be stored in a *data.

    len

    Size of the data received by a tpdeq(). A tpdeq() can increase a buffer size if a reply is larger than the buffer.

    Returned results are stored in a *data, and a len will be the size of received data. A *data can be modified if the size of received data is too large. If a len is larger than the total size of a previously called buffer, a larger buffer size will be allocated. If a len returns a 0, no data will be received and nothing will be changed in the buffer indicated by a *data and a len.

    If a *data or a len is NULL, an error will occur.

    flags

    The following values are available.

    • TPRQS

      Loads service results from a reply queue (RQ).

    • TPFUNC

      Manages RQ data by service. If a TPFUNC is not set, data stored by a tpenq() will be dequeued when it is initially stored. If data must be dequeued before it is stored, a TPFUNC must be set when calling a tpenq().

    • TPBLOCK

      Waits until a message is returned during a block timeout.

    • TPNOTIME

      If a TPNOTIME and a TPBLOCK are both set, a function will wait until a reply is returned regardless of a block timeout.

    • 0 (zero)

      Loads data from the buffer of a client that a function caller is connected to.

  • Return Values

    Value Description

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tpdeq() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    An invalid parameter. For example, a svc is NULL, data points to a buffer that was not allocated by a tpalloc(), or a flag is invalid.

    [TPGOTSIG]

    A signal that is received when a TPSIGRSTRT was not set.

    [TPEMATCH]

    When a service name is wrong or there is no data to be dequeued, no data will be found for a given key.

    [TPENOENT]

    An invalid qname.

    [TPEPROTO]

    A tpdeq() was called from an invalid state.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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

Used to get the data statistics accumulated in a current RQ. This function is available both in a server and a client. A RQ internally consists of three queues: a _fail queue, a _request queue, and a _ reply queue. A 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)

  • Parameters

    Parameter Description

    qname

    A RQ that saves data. A name must be specified and registered in a configuration file.

    flags

    A target data type.

    The following values are available.

    • 0(TMAX_ANY_QUEUE): Retrieves the statistics about all data stored in a _fail queue, _request queue, and _reply queue.

    • 1(TMAX_FAIL_QUEUE): Retrieves the data statistics stored in a _fail queue.

    • 2(TMAX_REQ_QUEUE): Retrieves the data statistics stored in a _request queue.

    • 3(TMAX_RPLY_QUEUE): Retrieves the data statistics stored in a _reply queue.

  • Return Values

    Value Description

    -1

    A function call was successful. A tperrno is set to an error code.

  • Errors

    When a tpqstat() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    An invalid parameter. For example, when a qname is NULL, there will be no queue with a corresponding name, or a flag will be invalid.

    [TPEPROTO]

    A tpqstat() was called from an invalid state.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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

Extracts a service name from the data read from a RQ by using a tpdeq(). This function is generally used to read data stored in a Fail Queue and can be used on both a client and a server.

  • Prototype

    # include <tmaxapi.h>
int  tpextsvcname (char *data, char *svc)

  • Parameters

    Parameter Description

    data

    A pointer allocated by a tpalloc() that stores read data from a RQ through a tpdeq().

    svc

    A pointer that receives the service name of data.

  • Return Values

    Value Description

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tpextsvcname() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    An invalid parameter. For example, a svc is NULL, data points to a buffer that was not allocated by a tpalloc(), or a flag is invalid.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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. Functions using 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.

Occurred events' data and results are not included in the transaction.

11.1. tpsubscribe

Subscribes to an event or set of events named by an eventname. It is used to request a notification for an event when an event is posted. This function is available for both servers and clients.

  • Prototype

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

  • Parameters

    Parameter Description

    eventname

    A string ending with NULL that has up to a 63-character length.

    A wildcard character or partial-matching is not supported. Only a name that matches an entire string can be registered.

    filter

    Reserved for future-use. NULL must be set in this parameter.

    ctl

    A structure that receives a message when an event occurs. It works differently depending on the subject of a tpsubscribe(). If a client used a tpsubscribe(), a ctl must always be NULL and a message will be delivered to a client as an unsolicited data type. Afterwards, the client will handle the received data using a tpsubscribe() or a tpgetunsol().

    flags

    Currently, only a TPNOTIME can be used.

    If a tpsubscribe() is executed by a server, a ctl must not be NULL and it must be 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

    Not currently supported. Set to 0.

    post_flags

    Not currently supported. Set to 0.

    qname

    When using a qname, a message will be queued in a RQ via a tpenq (qname, NULL, data, len, TPNOFLAGS).

    svc

    When using a svc, a message will be sent to a server in a similar manner to a tpacall (svc, data, len, TPNOREPLY) and a response from the server will be ignored. Only one qname or svc can be used at a time.

  • Return Values

    Value Description

    descriptor

    A function call was successful and a descriptor to be used for a tpunsubscribe() is returned.

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tpsubscribe() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information will be recorded in a system log file. For a client program, a network error is the most common error.

    [TPEOS]

    An operating system error occurred. Memory cannot be allocated.

    [TPEINVAL]

    An invalid parameter.

    [TPENOENT]

    A RQ or a server corresponding to a specified qname or svc of a TPEVCTL structure does not exist.

    [TPEPROTO]

    A ctl is not NULL in a client and a server.

    [TPETIME]

    A timeout occurred.

  • Related Functions

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

11.2. tpunsubscribe

Removes an event subscription or a set of event subscriptions registered by a tpsubscribe() from a Tmax system’s list of subscriptions. If all subscriptions are removed, a Tmax system will delete the table containing the events.

  • Prototype

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

  • Parameters

    Parameter Description

    sd

    A return value received when registering for a subscription with a tpsubscribe().

    flags

    Currently, only a TPNOTIME can be used.

  • Return Values

    Value Description

    Positive Value

    A function call was successful.

    Negative Value

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tpunsubscribe() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information will be recorded in a system log file. For a client program, a network error is the most common error.

    [TPEOS]

    An operating system error occurred. Memory cannot be allocated.

    [TPEINVAL]

    An invalid parameter.

    [TPETIME]

    A timeout occurred.

  • Related Functions

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

11.3. tppost

Generates a specific event from a server or client and delivers a message. A tppost() notifies the occurrence of an event to all clients and server processes that registered for the event by using the eventname in a tpsubscribe(). If required, a message can be delivered.

  • Prototype

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

  • Parameters

    Parameter Description

    eventname

    A string that ends with a NULL, and has up to a 63-character length. Wildcard or partial-matching is not supported.

    data

    A pointer to a buffer for messages to be sent. Must be a buffer allocated by a tpalloc().

    len

    The length of a buffer to be sent.

    • If data indicates a buffer that does not require a data length to be provided, a len will be ignored (0 is used by default).

    • If data indicates a buffer that requires a data length, a len must not be 0.

    • If data is NULL, a len will be ignored.

    flags

    Currently, only a TPNOTIME can be used.

  • Return Values

    Value Description

    Positive Value

    A function call was successful.

    Negative Value

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tppost() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information will be recorded in a system log file. For a client program, a network error is the most common error.

    [TPEOS]

    An operating system error occurred.

    [TPEINVAL]

    An invalid parameter.

    [TPENOENT]

    When using a tpsubscribe(), this error indicates that a RQ, a server corresponding to a qname, or a svc of a TPEVCTL structure does not exist.

    [TPEPROTO]

    When a tpsubscribe() is executed in a client, a ctl is not NULL. When a tpsubscribe() is executed in a server, a ctl is NULL.

    [TPETIME]

    A timeout occurred.

  • Related Functions

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

12. Broadcast and 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

Broadcasts notifications to clients registered in the Tmax system. To receive a notification, 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)

  • Parameters

    Parameter Description

    nodename,

    usrname,

    cltname

    Logical names used to select target clients. The name length must be 63 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 through 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.

    • len is also ignored if data is NULL.

    flags

    The following values are available.

    • TPNOBLOCK

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

    • TPNOTIME

      Function caller must wait indefinitely until a response is received. Blocking timeout is ignored. If tpbroadcast() is called during a transaction timeout, transaction timeout 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 Values

    Value Description

    1

    A function call was successful.

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tpbroadcast() fails to execute and no messages can be transmitted to a client, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    An invalid parameter. For example, an identifier is too long or a flag is invalid. If a nodename is incorrect, a tpbroadcast() will fail and return a TPEINVAL. However, if a usrname or cltname is invalid, a message will not be transmitted, but a function will be considered to have executed successfully.

    [TPETIME]

    Blocking timeout occurred while TPNOBLOCK or TPNOTIME is not set.

    [TPEBLOCK]

    A blocking state occurred when a TPNOBLOCK was set.

    [TPGOTSIG]

    A signal that is received when a TPSIGRSTRT is not set.

    [TPEPROTO]

    A tpbroadcast() was called from an invalid state.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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++, BC++, 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

Available in a client in a Windows system environment. This funciton performs the same functions as a tpacall() in a multi-threaded environment. It creates a new thread and invokes a tpstart() → tpacall() → tpgetrply() in the thread. After calling a tpgetrply(), it invokes a 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)

  • Parameters

    Parameter Description

    sinfo

    The structure that is used when sending client information to a Tmax system. Identical to the parameter of a tpstart().

    wHandle

    A Windows Handler used to receive messages.

    msgtype

    An arrival message. Generally, a WM_USER is freely defined by a developer. Specify a service name registered in a svc Tmax configuration file.

    svc

    A service to send a request.

    sndbuf

    Data to be sent when calling a service. If not null, it must use a buffer allocated using a tpalloc().

    len

    The length of data to be sent. It must be specified for CARRAY, X_OCTET, and Structure array types.

    flags

    Identical to the flags of a tpacall().

    The following values are available.

    • TPBLOCK

      If a tpacall was used without flags, a normal result will be returned even if a called service does not exist in a svc or an invalid result is returned If a tpacall() is called using a TPBLOCK, a service state can be checked if it is normal or not.

    • TPNOTRAN

      If a service does not support transactions in a transaction mode, flags must be set to a TPNOTRAN for a tpacall() to be called in the transaction mode. If a tpacall() caller requests a svc service by setting a TPNOTRAN in a transaction mode, a svc service will be executed by being excluded from the transaction mode. When calling a tpacall() in a transaction mode, a call will still affected by a transaction timeout even if a tpacall() is set to TPNOTRAN. In other words, calling a tpacall that is set as a TPNOTRAN after a transaction timeout will fail except when calling a tpacall that has been set as a TPNOTRAN|TPNOREPLY. If a service with a flag set to a TPNOTRAN fails, this does not affect a caller’s transaction.

    • TPNOREPLY

      If a tpacall() is used to send a service request, a tpacall will return immediately without waiting for a response. A client can retrieve results by using a tpgetrply() with a descriptor returned by a tpacall(). If a TPNOREPLY is set, a response for a service request will not be received. If set to a TPNOREPLY, a tpacall() will return a 0 if a service is called normally. If a function caller is in a transaction mode, a TPNOREPLY must be set along with a TPNOTRAN. In case of a TPNOREPLY, to check if a service state is normal or not, a TPBLOCK also must be set. If a TPBLOCK is not set, an error will not be returned even a service is NRDY.

    • TPNOBLOCK

      Upon encountering a blocking condition with this flag, for example, an internal buffer is filled with messages to be transmitted, a service request will fail. When calling a tpacall() function without setting a TPNOBLOCK flag, if a blocking condition is encountered, a function caller must wait until blocking is released or a timeout (transaction timeout or blocking timeout) occurs.

    • TPNOTIME

      A function caller must wait indefinitely until a response is received and blocking timeouts are ignored. If a tpacall() is called during a transaction timeout, a transaction timeout will be applied.

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

  • Return Values

    Value Description

    Descriptor

    A function call was successful. A returned descriptor is used to receive a response for a sent service request.

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a WinTmaxAcall() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    An invalid parameter. For example, a svc is NULL, data points to a buffer that was not allocated by a tpalloc(), or a flag is invalid.

    [TPENOENT]

    A specified svc does not exist.

    [TPEITYPE]

    A svc does not support a data type or subtype. For a structure, this error occurs when the structure is not declared in a SDLFILE file.

    [TPELIMIT]

    A maximum number of unprocessed asynchronous service requests was reached. Service requests from a caller cannot be sent.

    [TPETIME]

    A timeout occurred. If a transaction timeout occurs when a function caller is in a transaction mode, a transaction will be rolled back. If a function caller is not in a transaction mode, a block timeout will occur if neither a TPNOTIME nor a TPNOBLOCK is set.

    In these cases, a *data content and a *len will not be changed. If a transaction timeout occurs, new service requests and processes waiting for a response will fail with a [TPETIME] error until a transaction is rolled back.

    [TPEBLOCK]

    A blocking state occurred when a TPNOBLOCK was set.

    [TPGOTSIG]

    A signal that is received when a TPSIGRSTRT is not set.

    [TPEPROTO]

    A WinTmaxAcall() was called from an invalid state. For example, a TPNOREPLY was called in a transaction mode, but a TPNOTRAN was not set.

    [TPESYSTEM]

    A Tmax system error occurred.

    [TPEOS]

    An operating system error occurred.

  • 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

Available in a client in a Windows system environment. This function performs the same function as a tpacall() in a multi thread environment. It issues a new thread and invokes a tpstart() → tpacall() → tpgetrply() in the thread. After calling a tpgetrply(), it delivers 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)

  • Parameters

    Parameter Description

    sinfo

    The structure used when sending information about a client to a Tmax system. Identical to the parameters of a tpstart().

    fn

    Sets a Callback function to receive a response for a service request.

    svc

    Sets a service name registered in a Tmax environment configuration file.

    sndbuf

    Data to be sent when calling a service. If not null, it must use a buffer allocated through a tpalloc().

    len

    The length of data to be sent. It must be specified for CARRAY, X_OCTET, and Structure array types.

    flags

    Identical to the flags of a tpacall().

    The following values are available.

    • TPBLOCK

      If tpacall was used without flags, a normal result is returned even if a called service does not exist in a svc or an invalid result is returned. If a tpacall() is called using a TPBLOCK, a service state can be checked if it is normal or not.

    • TPNOTRAN

      If a service does not support transactions in a transaction mode, flags must be set to a TPNOTRAN for a tpacall() to be called in the transaction mode. If a tpacall() caller requests a svc service by setting a TPNOTRAN in a transaction mode, a svc service will be executed by being excluded from the transaction mode. When calling a tpacall() in a transaction mode, a call will still affected by a transaction timeout even if a tpacall() is set to TPNOTRAN. If a service with a flag set to a TPNOTRAN fails, this does not affect a caller’s transaction.

    • TPNOREPLY

      If a tpacall() is used to send a service request, a tpacall will return immediately without waiting for a response. A client can retrieve results by using a tpgetrply() with a descriptor returned by a tpacall().

      If a TPNOREPLY is set, a response for a service request will not be received. If set to a TPNOREPLY, a tpacall() will return a 0 if a service is called normally. If a function caller is in a transaction mode, a TPNOREPLY must be set along with a TPNOTRAN. In case of a TPNOREPLY, to check if a service state is normal or not, a TPBLOCK also must be set. If a TPBLOCK is not set, an error will not be returned even a service is NRDY.

    • TPNOBLOCK

      Upon encountering a blocking condition with this flag, for example, an internal buffer is filled with messages to be transmitted, a service request will fail. When calling a tpacall() function without setting a TPNOBLOCK flag, if a blocking condition is encountered, a function caller must wait until blocking is released or a timeout (transaction timeout or blocking timeout) occurs.

    • TPNOTIME

      A function caller must wait indefinitely until a response is received and blocking timeouts are ignored. If a tpacall() is called during a transaction timeout, a transaction timeout will be applied.

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

  • Return Values

    Value Description

    1

    A function call was successful.

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a WinTmaxAcall2() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    An invalid parameter. For example, a svc is NULL, data points to a buffer that was not allocated by a tpalloc(), or a flag is invalid.

    [TPENOENT]

    A specified svc does not exist.

    [TPEITYPE]

    A svc does not support a data type or subtype. For a structure, this error occurs when the structure is not declared in a SDLFILE file.

    [TPELIMIT]

    A maximum number of unprocessed asynchronous service requests was reached. Service requests from a caller cannot be sent.

    [TPETRAN]

    A svc does not support transactions, and a TPNOTRAN was not set.

    [TPETIME]

    A timeout occurred. If a transaction timeout occurs when a function caller is in a transaction mode, a transaction will be rolled back. If a function caller is not in a transaction mode, a block timeout will occur if neither a TPNOTIME nor a TPNOBLOCK is set.

    In these cases, a *data content and a *len will not be changed. If a transaction timeout occurs, new service requests and processes waiting for a response will fail with a [TPETIME] error until a transaction is rolled back.

    [TPEBLOCK]

    A blocking state occurred when a TPNOBLOCK was set.

    [TPGOTSIG]

    A signal that is received when a TPSIGRSTRT is not set.

    [TPEPROTO]

    A WinTmaxAcall2() was called from an invalid state. For example, a TPNOREPLY was called in a transaction mode, but a TPNOTRAN was not set.

    [TPESYSTEM]

    A Tmax system error occurred.

    [TPEOS]

    An operating system error occurred.

  • Examples

    #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

Available in a client in a Windows system environment. This function is used to connect to a Tmax system in a multi-Windows environment. This function is identical to a tpstart(). When using multiple threads, connections must be respectively established per thread through a WinTmaxStart().

  • Prototype

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

  • Parameters

    Refer to tpstart for more information about a TPSTART_T.

  • Return Values

    Value Description

    1

    A function call was successful.

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a WinTmaxStart() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    An invalid parameter. For example, a tpinfo is NULL or not a pointer for a TPSTART_T.

    [TPEITYPE]

    A tpinfo is not a pointer for a TPSTART_T structure.

    [TPEPROTO]

    A WinTmaxStart() was called in an inappropriate condition. For example, a WinTmaxStart() was called in a server program, or it was called after a connection was already established.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred. Environment variables may be invalid. For example, a connection failed because a TMAX_BACKUP_ADDR or TMAX_BACKUP_PORT was invalid.

  • Related Functions

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

13.4. WinTmaxEnd

Available in a client in a Windows system environment. This funciton closes a connection to a Tmax system. It functions identically to a tpend(). In a multi-threaded environment, a client is connected to each thread via a WinTmaxStart(), so a WinTmaxEnd() must be used for each thread to close the connection.

  • Prototype

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

  • Return Values

    Value Description

    1

    A function call was successful.

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a WinTmaxEnd() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPETIME]

    Cannot access a critical section due to an internal system error. Check the system status.

    [TPEPROTO]

    A WinTmaxEnd() was called from an invalid state. For example, a WinTmaxEnd() was called after a connection was already closed.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Related Functions

    tpend(), WinTmaxStart()

13.5. WinTmaxSetContext

Available in a client in a Windows system environment. This function controls window handles and message types.

This function, used in a Windows environment, manages specified Windows handles and message types by storing them in a vacant slot of a library. Using this information, when a working thread receives a reply, it will send data to the specified Windows in the specified type. The following is the data transmission format:

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

In a Windows environment, a WARM corresponds to a msg and a LARA corresponds to a callRet. A msg is a TPSVCINFO structure and a callRet indicates a result of the process. If a proper message is received, a callRet is 0, and if an improper message is received, a callRet is -1.

For example, if a service is processed as atpreturn (TPSUCCESS, …), or a service fails with a tpreturn (TPFAIL, …), or an unrequested message is received, a callRet becomes 0, since it will be considered as a proper message was received. However, if a synchronous or conversational message is delivered, a callRet will be -1 because those message types cannot be used in a multi Window environment. If a callRet value is -1, a tperrno value can be checked to know the error cause.

  • Prototype

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

  • Parameters

    Parameter Description

    winhandle

    A windows handle to process received data.

    msgType

    A message type.

    slot

    Indicates a slot used to allocate a specified Windows handle and message type. The maximum available number of slots is 256, and 0 and 1 are internally specified in a system for a default display and error respectively. Thus, if an error occurs while receiving data or a Windows for display is not specified, a default Windows is used.

    The default slots can be redefined by a user. In case of an unrequested message, a user defined Windows will not exists, so messages are delivered to the number 0 default display Windows.

    The following values are available.

    • –1: Allocates a specified Windows handle and message type by automatically searching for vacant slots in a system.

    • A value greater than or equal to 0: Allocates a specified Windows and message type to a slot specified with a given index.

  • Return Values

    Value Description

    index

    A function call was successful and an index for a slot was returned. As well, an index is used as a first parameter of a WinTmaxSend().

    -1

    A function call failed. A tperrno is set to an error code.

  • ErrorsWhen a WinTmaxSetContext() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPESYSTEM]

    A Tmax system error occurred.

    [TPEOS]

    An operating system error occurred.

  • Examples

    ...
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 error = [%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

Available in a client in a Window system environment. This function sends data and requests a service in a multi-windows environment.

  • Prototype

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

  • Parameters

    Parameter Description

    recvContext

    Sets a Windows for receiving a response from a Tmax system. It is the return value of a WinTmaxSetContext().

    svc

    A service name.

    data

    A buffer allocated through a tpalloc(). The data used to request a service is stored.

    len

    Data length. The length must be correctly defined when using a CARRAY or a multiple Structure buffer.

    flags

    Flag values are listed in the following table.

    A WinTmaxSend() works similarly to a tpacall() function. It requests a service and is returned immediately without waiting for a response. A response is processed by the thread that was created when calling a WinTmaxStart(), and the response result will be sent to a Windows set by a WinTmaxSetContext(), so a separate API is not provided to receive the response.

    The following example finds a vacant slot to store (hwd, 0x300) and returns an index. The return value a rc of a WinTmaxSetContext() is used as a recvContext parameter of a WinTmaxSend(). If a response is received after calling a WinTmaxSend(rc, svc, data, len, 0), a 0 x 300 message and a response result will be sent to a hwd windows.

    rc = WinTmaxSetContext(hwd, 0x300, -1);
int nSendResult = WindTmaxSend(rc, (LPSTR)(LPCSTR)strService, (Char*)tpbuf, nLen, TPNOFLAGS);
/*
  The internal thread processes the response message and sends the result to the Windows
  SendMessage(hwd, 0x300, (UINT) &msg, callRet);
*/

    A Windows that receives a message will receive a response data through a WPARAM and a response result through a LPARAM. If a callRet is 0, it means the response will be normal, and -1 means that an error occurred. The cause of an error can be known through a tperrno value.

    A WinTmaxSend() does not support transactions due to its structure and is not affected by a BLOCKTIME in a Tmax configuration file or a tpsettimeout(). However, when calling a WinTmaxSend(), if a TPBLOCK flag is given, a BLOCKTIME will be applied according to a corresponding flag.

    The following are possible flag values.

    Flag Description

    TPBLOCK

    If a WinTmaxSend() function is used without this flag, a normal result will be returned even if a called service did not exist in a svc or an invalid result was returned. Errors can be checked at the time of receiving a result.

    Using this flag, it is possible to check whether a service status is normal or not normal at the time of calling a function. In other words, a WinTmaxSend() checks if a request service can be processed normally within a BLOCKTIME and returns the result. If a service cannot be processed, an error will be stored in a tperrno and a -1 will be returned.

    If it is impossible to check if a requested service can be processed within a BLOCKTIME, a TPETIME error will be returned. In this case, a client cannot know whether a requested service is processed or not, so an error routine must be written carefully. If a request must be sent again, an error routine must be to check if a previous request was processed.

    TPNOREPLY

    Immediately returns a service request sent with a WinTmaxSend() function without waiting for a response. A worker thread receives the result and sends it to the specified Windows. However, a TPNOREPLY flag will be set to not receive a response for the service.

    TPNOTRAN

    If a WinTmaxSend() function caller requests a svc service by setting this flag in a transaction mode, the svc service will be executed while being excluded from the transaction mode.

    If a svc does not support transactions in a transaction mode, a flag must be set to a TPNOTRAN when a WinTmaxSend() function is called in the transaction mode. If called in the transaction mode, the WinTmaxSend() function will still be affected by a transaction timeout even though a service flag was set to TPNOTRAN. If the service called with a TPNOTRAN fails, it will not affect a caller’s transaction.

    TPNOBLOCK

    Upon encountering a blocking condition with this flag set (for example, an internal buffer is filled with messages to be transmitted), a service request will fail. When calling a WinTmaxSend() function without setting a TPNOBLOCK flag and encountering a blocking condition, a function caller will wait until blocking is released or a timeout (transaction timeout or blocking timeout) occurs.

    TPNOTIME

    A function caller must wait indefinitely until a response is received and blocking timeouts are ignored. If a WinTmaxSend() is called during a transaction timeout, a transaction timeout will be applied.

    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 a TPGOTSIG.

  • Return Values

    Value Description

    Descriptor

    A function call was successful and a descriptor is returned. Currently this descriptor is not used.

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a WinTmaxSend() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPENOENT]

    A specified svc does not exist.

    [TPEITYPE]

    A svc does not support a data type or subtype. For a structure, this error occurs when the structure is not declared in a SDLFILE file.

    [TPELIMIT]

    A maximum number of unprocessed asynchronous service requests was reached. Service requests from a caller cannot be sent.

    [TPETIME]

    A timeout occurred. If a transaction timeout occurs when a function caller is in a transaction mode, a transaction will be rolled back. If a function caller is not in a transaction mode, a block timeout will occur if neither a TPNOTIME nor a TPNOBLOCK is set.

    In these cases, a *data content and a *len will not be changed. If a transaction timeout occurs, new service requests and processes waiting for a response will fail with a [TPETIME] error until a transaction is rolled back.

    [TPEBLOCK]

    A blocking state occurred when a TPNOBLOCK was set.

    [TPGOTSIG]

    A signal that is received when a TPSIGRSTRT is not set.

    [TPEPROTO]

    A WinTmaxSend() was called from an invalid state. For example, a TPNOREPLY was called in a transaction mode, but a TPNOTRAN was not set.

    [TPESYSTEM]

    A Tmax system error occurred.

    [TPECLOSE]

    Disconnected from a Tmax system due to various reasons (for example, network issues).

    [TPEOS]

    An operating system error occurred.

    If a LPARAM of a message sent to Windows is -1, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEBADDESC]

    Occurs when a valid descriptor cannot be found when a response message is received.

    [TPEOTYPE]

    Occurs when the buffer types of client and server programs do not match when a response message is received.

    [TPEPROTO]

    A WinTmaxStart() or a WinTmaxEnd() was called from an invalid state.

    [TPESYSTEM]

    A Tmax system error occurred.

    [TPECLOSE]

    Disconnected from a Tmax system due to various reasons (for example, network issues).

    [TPEOS]

    An operating system error occurred.

  • Examples

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

Returns a context ID, which is set in a thread that calls a function, as its first parameter.

In a multithread/multicontext server, a tpgetctxt returns a value of 1 or greater when the context set in a thread is valid. A tpgetctxt returns a TPNULLCONTEXT(-2) when a context is invalid or not set. A context is valid only while a service thread is processing a service request. If a tpreturn() is called after completing a service request, a context will no longer be valid and a user created thread can no longer use the context.

A tpgetctxt() is used differently in client and server programs. The following information describes the function by separating examples by server and client.

A MultiThread/MultiContext server does not support a Singlecontext.

  • Prototype

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

  • Parameters

    Parameter Description

    ctxtid

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

    • multicontext: Returns a value of 1 or greater.

    • singlecontext: Returns 0.

    flags

    Not currently supported. Set to TPNOFLAGS.

  • Return Values

    Value Description

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tpgetctxt() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEINVAL]

    An invalid parameter. For example, a first parameter is a pointer or a second parameter is not set to 0.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples - 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;
}

  • Examples - 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 Functions

    tpsetctxt()

14.2. tpsetctxt

Sets a current context. The way the function is used differs in a client program and a server program as follows:

  • Client Program

    A client can assign a different previously created context to a current client using a function. Most ATMI functions are based on per-context. To know the current context of a client, the return value of a tpgetctxt() can be checked.

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

  • Server Program

    A service thread processes a service by getting a context, but a user created thread does not have its own context. Most ATMI functions can work after getting a context. Therefore a user created thread must share a context with a service thread if required. A user created thread can share a context with other service threads by using a tpsetctxt().

    A user created thread that calls a tpsetctxt() shares context information with a service thread. For example, if a service thread calls a tpacall(), after that it is possible for a user created thread to receive a response for a request through a tpgetrply().

    A tpsetctxt() cannot be used in a service thread. A service thread has its own context by default, and cannot replace the context with other one. Therefore, if a service thread calls a tpsetctxt(), an error will be returned with a TPEPROTO error code.

    If a user created thread shares a context with a service thread through this function, the user created thread must call a tpsetctxt (TPNULLCONTEXT) before the service thread calls a tpreturn(). In other words, at the time that the service thread calls tpreturn(), the context of the service thread must be changed not to be shared by other user created threads. If this is not kept, tpreturn() will fail and aTPESVCERR error code will be returned to the client. Therefore, the process flow between threads must be controlled through synchronization. The ctxtid parameter of a tpsetctxt() uses the Context-ID which that is retrieved by calling a tpgetctxt() from a service thread.

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

  • Prototype

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

  • Parameters

    Parameter Description

    ctxtid

    Sets a current context at the time point of a function call. In a client program, new context IDs created using a tpstart() can be used. In a server program, the Context-ID of a service thread can be used.

    Other contexts such as a TPNULLCONTEXT can be used but not a TPINVALIDCONTEXT.

    flags

    Not currently supported. Set to TPNOFLAGS.

  • Return Values

    Value Description

    -1

    A function call failed. A tperrno is set to an error code.

  • Errors

    When a tpsetctxt() fails to execute, a tperrno will be set to one of the following values:

    Error Code Description

    [TPEPROTO]

    A function was called from an invalid state. For example, a service thread called a function or a Context ID was delivered as a parameter that was invalid in a server program.

    [TPEINVAL]

    An invalid parameter. A ctxid is set to 0 or TPINVALIDCONTEXT, or flags are set to non-zero.

    In a client program, a tpsetctxt() is called before the program calls a tpstart(). A buffer flag is not set to TPMULTICONTEXTS when this function is called before the tpstart() is called.

    This error occurs when a context ID is set to TPINVALIDCONTEXT or 0.

    [TPENOENT]

    A ctxtid value is not a configurable context.

    [TPESYSTEM]

    A Tmax system error occurred. Detailed error information is recorded in a system log file.

    [TPEOS]

    An operating system error occurred.

  • Examples - 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;
}

  • Examples - 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 Functions

    tpgetctxt()