Function

This chapter describes the functions available in Tmax. For more information about error codes, refer to Tmax Application Development Guide.

1. Server/Client Functions

1.1. gettperrno

The gettperrno function returns an errno, which is an error code set in the client and server, when calling the Tmax System.

  • Prototype

    #include <atmi.h>
    int gettperrno(void)
  • Return Value

    Returns an error code (errno). For more information about errno, refer to Error Codes and Actions or Tmax Application Development Guide.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    void main(int argc, char* argv[])
    {
       int ret, usrerrno=0;
       char *sndbuf, *rcvbuf;
       ret=tpstart((TPSTART_T*)NULL);
       if (ret==-1){
          usrerrno=gettperrno();
          printf(“error no : %d\n”, usrerrno);
       }
       data process…
       tpend();
    }
  • Related Function

    gettpurcode()

1.2. tmax_chk_conn

The tmax_chk_conn function checks the connection status of a client by checking the execution status of the tpstart() function, socket status, and message transmission.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tmax_chk_conn (int sec)
  • Parameter

    Parameter Description

    sec

    Input options:

    • Negative value : Checks whether tpstart() has been executed.

    • 0 : Checks socket status. Equivalent to tpalivechk().

    • Positive value : Checks the connection status by sending a message and waits up to the specified time (in seconds) for a response.

  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEPROTO]

    tpstart() has not been executed.

    [TPESYSTEM]

    Disconnected from the Tmax system.

    [TPEOS]

    An error occurred in the operating system.

    [TPECLOSE]

    Connection with the Tmax system was already lost.

  • Example

    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <usrinc/atmi.h>
    #include <usrinc/fbuf.h>
    #include <usrinc/tmaxapi.h>
    #include “../fdl/demo_fdl.h”
    
    main(int argc, char *argv[])
    {
            FBUF    *sndbuf, *rcvbuf;
            int     fc, fg, ret,  i, chkno;
            char    sndata[30],    rcvdata[30];
            char     input[10], outdata[10];
            long    sndlen, rcvlen;
            int Count = 1;
    
            if (argc != 2)
                error processing…
    
            if ( (ret = tmaxreadenv( “tmax.env”,”TMAX” )) == -1 )
                error processing…
    
            /* Check for tpstart execution */
            /***
            chkno = tmax_chk_conn(-1);
            printf(“chkno = %d\n”, chkno);
            if(chkno < 0)
            {
                  printf(“tpstart is not started\n”);
                  printf(“errno = %d\tstrerror=%s\n”, tperrno, tpstrerror(tperrno) );
            }
            else if(chkno == 0)
            {
                  printf(“tpstart is started\n”);
            }
            ***/
    
            if (tpstart((TPSTART_T *)NULL) == -1)
                  error processing…
            if ((sndbuf = (FBUF *)tpalloc(“FIELD”, NULL, 0)) == NULL)
                  error processing…
            if ((rcvbuf = (FBUF *)tpalloc(“FIELD”, NULL, 0)) == NULL)
                  error processing…
            /* Check socket status */
            /***********
            chkno = tmax_chk_conn(0);
            printf(“chkno = %d\n”, chkno);
            if(chkno < 0)
            {
                  printf(“The situation of socket is bad\n”);
                  printf(“errno = %d\tstrerror=%s\n”, tperrno, tpstrerror(tperrno) );
            }
            else if(chkno == 0)
            {
                  printf(“The situation of socket is good\n”);
            }
            **********/
            printf(“My Count = %d\n”, Count++);
            strcpy(input, “INPUT”);
            strcpy(sndata, argv[1]);
            fc = fbput(sndbuf, fbget_fldkey(input), sndata, 0);
            if (tpcall(“FDLTOUPPER”, (char *)sndbuf, 0, (char **)&rcvbuf,
                        (long *)&rcvlen, TPNOFLAGS) == -1)
                  error processing…
            /* Check connection status by sending a message */
            chkno = tmax_chk_conn(1);
            printf(“chkno = %d\n”, chkno);
            if(chkno < 0)
            {
                  printf(“The situation of connection(Message Transfer) is bad\n”);
                  printf(“errno = %d\tstrerror=%s\n”, tperrno, tpstrerror(tperrno) );
            }
            else if(chkno == 0)
            {
                  printf(“The situation of connection(Message Transfer) is good\n”);
            }
    
            strcpy(outdata, “OUTPUT”);
            fg = fbget(rcvbuf, fbget_fldkey(outdata), rcvdata, 0);
            fbprint(rcvbuf);
            tpfree((char *)sndbuf);
            tpfree((char *)rcvbuf);
            tpend();
    }
  • Related function

    tpalivechk()

1.3. tmax_gq_count

The tmax_gq_count returns the number of data items stored in GQ.

  • Prototype

    #include <tmaxapi.h>
    int tmax_gq_count (void)
  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

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

  • Error

    If tmax_gq_count() fails, the following code is set in tperrno.

    Error Code Description

    [TPENOENT]

    No SQ for the current session exists.

1.4. tmax_gq_get

The tmax_gq_get function uses a key to retrieve data from GQ. By default, tmax_gq_get() deletes data retrieved in a queue. To preserve this data, a TPSQ_PEEK flag must be enabled.

  • Prototype

    #include <tmaxapi.h>
    int tmax_gq_get(char *key, long keylenl, char **data, long *lenl, long flagsl)
  • Parameter

    Parameter Description

    key

    A buffer that stores data from a GQ.

    keylenl

    A key buffer size. (Unit: byte)

    data

    A pointer to a data buffer on a GQ. The buffer must be allocated by a tpalloc().

    lenl

    The size of a data buffer on a GQ. (Unit: byte)

    flagsl

    Only TPSQ_PEEK is available. This flag prevents data from being deleted from a queue.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Error

    If tmax_gq_get() fails, the following code is set in tperrno.

    Error Code Description

    [TPEMATCH]

    No data is found for the specified key.

1.5. tmax_gq_getkeylist

The tmax_gq_getkeylist function retrieves a GQ key list. The key list is of type SQ_KEYLIST_T, and detailed key data can be accessed using functions such as tmax_keylist_count(), tmax_keylist_*(), and tmax_keylist_free(). The key list is sorted in ascending ASCII order by byte value.

When a key value is specified, the function queries the key list for entries greater than or equal to that value, returning the results in sorted order. If the key value is set to NULL, the entire key list is retrieved.

  • Prototype

    #include <tmaxapi.h>
    SQ_KEYLIST_T tmax_gq_getkeylist(char *key, long keylenl)
  • Parameter

    Parameter Description

    key

    A buffer that stores keys.

    keylenl

    A key buffer size. (Unit: byte)

  • Return Value

    Value Description

    SQ_KEYLIST_T

    The function call succeeded.

    NULL

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

  • Error

    If tmax_gq_getkeylist() fails, the following code is set in tperrno.

    Error Code Description

    [TPEMATCH]

    No key greater than or equal to the specified value exists.

1.6. tmax_gq_keygen

The tmax_gq_keygen function generates a system key and stores it in a buffer. The buffer size must be greater than or equal to SQ_SYSKEY_SIZE (16 bytes), the system key size.

  • Prototype

    #include <tmaxapi.h>
    int tmax_gq_keygen(char *key, long keylenl)
  • Parameter

    Parameter Description

    key

    A buffer that stores a generated system key.

    Must be greater than or equal to SQ_SYSKEY_SIZE (16 bytes).

    keylenl

    The key buffer size. Must be greater than or equal to SQ_SYSKEY_SIZE (16 bytes).

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Error

    If tmax_gq_keygen() faile, the following code is set in tperrno.

    Error Code Description

    [TPEINVAL]

    An invalid key was specified.

1.7. tmax_gq_purge

The tmax_gq_purge function deletes GQ data specified by a key. If no key is specified, all data in the GQ will be deleted.

  • Prototype

    #include <tmaxapi.h>
    int tmax_gq_purge(char *key, long keylenl)
  • Parameter

    Parameter Description

    key

    A buffer that stores the key of data to be deleted from GQ. If NULL, all data in the current session’s GQ will be deleted.

    keylenl

    The key buffer size. (Unit: Byte)

  • Return Value

    Value Description

    Number of data items deleted

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

    An invalid key was specified.

    [TPENOENT]

    No SQ exists for the current session.

1.8. tmax_gq_put

The tmax_gq_put function enters data into GQ. Both the key value and data value must be passed. When using a system key generated by tmax_gq_keygen(), the TPSQ_SYSKEY flag must be set. To generate and store a system key, a TPSQ_KEYGEN flag must be set.

  • Prototype

    #include <tmaxapi.h>
    int tmax_gq_put(char *key, long keylenl, char *data, long lenl, long flagsl)
  • Parameter

    Parameter Description

    key

    A buffer that stores the key of data being retrieved from GQ.

    keylenl

    The key buffer size. (Unit: byte)

    data

    A pointer to the data buffer to be retrieved from GQ. The buffer must be allocated by tpalloc().

    lenl

    The size of a data buffer retrieved from GQ (Unit: byte).

    flagsl

    One of the following flag values can be set:

    • TPSQ_UPDATE

      Updates data if the data key already exists in GQ to which the data will be saved. If this flag is not specified, a TPEMATCH error will be returned.

    • TPSQ_SYSKEY

      Uses a system key.

    • TPSQ_KEYGEN

      Generates and stores a system key. When TPSQ_KEYGEN is set, the key must be assigned based on SQ_SYSKEY_SIZE. When keylenl = SQ_SYSKEY_SIZE is set, the value created in the key is stored.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEMATCH]

    The specified key value is already in use.

    [TPELIMIT]

    The maximum number of keys in GQ was exceeded.

1.9. tmax_get_sessionid

The tmax_get_sessionid function returns a current session ID.

  • Prototype

    #include <tmaxapi.h>
    int tmax_get_sessionid(void)
  • Return Value

    Value Description

    A value other than -1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEPROTO]

    The session was already ended.

1.10. tmax_keylist_count

The tmax_keylist_count function retrieves the key count from the keylist handle.

  • Prototype

    #include <tmaxapi.h>
    int tmax_keylist_count(SQ_KEYLIST_T keylist)
  • Parameter

    Parameter Description

    keylist

    A handle obtained from tmax_sq_getkeylist() or tmax_gq_getkeylist().

  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

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

  • Error

    If tmax_keylist_count() fails, the following code is set in tperrno.

    Error Code Description

    [TPEBADDESC]

    The keylist handle is invalid.

1.11. tmax_keylist_free

The tmax_keylist_free function releases memory or other resources of the keylist handle.

  • Prototype

    #include <tmaxapi.h>
    int tmax_keylist_free(SQ_KEYLIST_T keylist)
  • Parameter

    Parameter Description

    keylist

    A handle obtained from tmax_sq_getkeylist() or tmax_gq_getkeylist().

  • Return Value

    Value Description

    Other than -1

    The function call succeeded.

    -1

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

  • Error

    If tmax_keylist_free() fails, the following is set in tperrno.

    Error Code Description

    [TPEBADDESC]

    The keylist handle is invalid.

1.12. tmax_keylist_getakey

The tmax_keylist_getakey function retrieves the n-th key information from the keylist handle.

  • Prototype

    #include <tmaxapi.h>
    int tmax_keylist_getakey(SQ_KEYLIST_T keylist, int nth, SQ_KEYINFO_T *keyinfo)
  • Parameter

    Parameter Description

    keylist

    A handle obtained from tmax_sq_getkeylist() or tmax_gq_getkeylist().

    nth

    The index of the n-th key retrieved from the keylist handle. The value of n must be between 0 and tmax_keylist_count() -1.

    keyinfo

    The structure that stores information about the n-th key. See the section below this table for details.

    The following shows content in the keyinfo structure.

    Structure keyinfo {
         long keylen
         long datalen
         time_t starttime
         char *key
    };
    Member Description

    keylen

    The size of the key. (Unit: Byte)

    datalen

    The size of the data. (Unit: Byte)

    starttime

    The time when data was stored or updated.

    *key

    The buffer containing the key value.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPEBADDESC]

    The keylist handle is invalid.

    [TPELIMIT]

    The value of n exceeds the limit.

1.13. tmax_make_unique_spri_in_domain

The tmax_make_unique_spri_in_domain function creates a unique spri value within the domain.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tmax_make_unique_spri_in_domain(int nodeno, int spri)
  • Parameter

    Parameter Description

    nodeno

    The node number.

    spri

    The server process index.

  • Return Value

    Value Description

    unique_spri

    Unique spri within the domain.

  • Example

    #include <stdio.h>
    #include <usrinc/tmaxapi.h>
    ...
    tpsvrinit(int argc, char **argv)
    {
        uniqspri = tmax_make_unique_spri_in_domain(my_nodeno, my_spri);
    }
  • Related function

    tmax_get_my_unique_spri_in_domain()

1.14. tmax_sq_count

The tmax_sq_count function returns the number of data items currently stored in SQ.

  • Prototype

    #include <tmaxapi.h>
    int tmax_sq_count(void)
  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

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

  • Error

    If tmax_sq_count() fails, the following code is set in tperrno.

    Error Code Description

    [TPENOENT]

    No SQ exists for the current session.

1.15. tmax_sq_get

The tmax_sq_get function retrieves data from SQ. Data can be retrieved by providing an associated key. By default, tmax_sq_get() deletes data in the queue. To preserve this data, the TPSQ_PEEK flag must be set.

  • Prototype

    #include <tmaxapi.h>
    int tmax_sq_get(char *key, long keylenl, char **data, long *lenl, long flagsl)
  • Parameter

    Parameter Description

    key

    The buffer that stores data from SQ.

    keylenl

    The key buffer size. (Unit: byte)

    data

    A pointer to a data buffer on SQ. The buffer must be allocated by tpalloc().

    lenl

    The size of a data buffer on SQ in bytes.

    flagsl

    Only TPSQ_PEEK is available. This flag prevents data from being deleted from the queue.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPENOENT]

    No SQ exists for the current session.

    [TPEMATCH]

    No data matching the specified key was found.

1.16. tmax_sq_getkeylist

The tmax_sq_getkeylist function retrieves a list of keys for the current SQ. A key list is a SQ_KEYLIST_T type handle, and detailed information about each key can be obtained using tmax_keylist_count(), tmax_keylist_getakey(), and tmax_keylist_free(). A key list is sorted by the ASCII values of its bytes, in ascending order.

When a key value is specified, the function retrieves and sorts a list of keys greater than or equal to that value. If the key value is set to NULL, all keys are retrieved.

  • Prototype

    #include <tmaxapi.h>
    SQ_KEYLIST_T tmax_sq_getkeylist(char *key, long keylenl)
  • Parameter

    Parameter Description

    key

    The buffer that stores key values.

    keylenl

    The size of the key buffer. (Unit: Byte)

  • Return Value

    Value Description

    SQ_KEYLIST_T

    The function call succeeded.

    NULL

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

  • Errors

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

    Error Code Description

    [TPENOENT]

    No SQ exists for the current session.

    [TPEMATCH]

    No key that is greater than or equal to the specified value was found.

1.17. tmax_sq_keygen

The tmax_sq_keygen function generates a system key and stores it in a buffer. The buffer size must be greater than or equal to SQ_SYSKEY_SIZE (16 bytes), the system key size.

  • Prototype

    #include <tmaxapi.h>
    int tmax_sq_keygen(char *key, long keylenl)
  • Parameter

    Parameter Description

    key

    A buffer that stores a generated system key.

    Must be greater than or equal to SQ_SYSKEY_SIZE (16 bytes).

    keylenl

    The key buffer size. Must be greater than or equal to SQ_SYSKEY_SIZE (16 bytes).

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPENOENT]

    No SQ exists for the current session.

1.18. tmax_sq_purge

The tmax_sq_purge function deletes SQ data specified by a key. If no key is specified, all data in the SQ will be deleted.

  • Prototype

    #include <tmaxapi.h>
    int tmax_sq_purge(char *key, long keylenl)
  • Parameter

    Parameter Description

    key

    A buffer that stores the key of data to be deleted from SQ. If NULL, all data in the current session’s SQ will be deleted.

    keylenl

    The key buffer size. (Unit: Byte)

  • Return Value

    Value Description

    Number of data items deleted

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPENOENT]

    No SQ exists for the current session.

1.19. tmax_sq_put

The tmax_sq_put function stores server data in SQ. Both the key and data value must be passed.

  • Prototype

    #include <tmaxapi.h>
    int tmax_sq_put(char *key, long keylenl, char *data, long lenl, long flagsl)
  • Parameter

    Parameter Description

    key

    A buffer that stores the key of data being retrieved from SQ.

    keylenl

    The key buffer size. (Unit: byte)

    data

    A pointer to the data buffer to be retrieved from SQ. The buffer must be allocated by tpalloc().

    lenl

    The size of a data buffer retrieved from SQ (Unit: byte).

    flagsl

    One of the following flag values can be set:

    • TPSQ_UPDATE

      Updates data if the data’s key already exists in the SQ to which the data will be saved. If this flag is not specified, a TPEMATCH error will be returned.

    • TPSQ_SYSKEY

      Uses a system key created by a tmax_sq_keygen().

    • TPSQ_KEYGEN

      Generates and stores a system key. When TPSQ_KEYGEN is set, the key must be assigned based on SQ_SYSKEY_SIZE. When keylenl = SQ_SYSKEY_SIZE is set, the value created in the key is stored.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPENOENT]

    No SQ exists for the current session.

    [TPEMATCH]

    The specified key value is already in use.

    [TPELIMIT]

    The maximum SQ count or the maximum key count was exceeded.

1.20. tmaxlastsvc

The tmaxlastsvc function returns a service name before returning results. This information allows a user to find the name of a service in which an error occurred or the name of a server that executed a last routine.

When using tpforward() or tprely(), other service routines are executed in addition to the services called by a user. In this case, when an error occurs during the execution of multiple server routines, a user cannot find the server in which an error occurred.

  • Prototype

    #include <tmaxapi.h>
    char *tmaxlastsvc(char *idata, char *odata, long flags)
  • Parameter

    Parameter Description

    idata, odata

    Uses a send/rcv buffer used in a tpcall.

    flags

    Not currently supported. Set to TPNOFLAGS.

  • Return Value

    Value Description

    Internal buffer pointer

    The function call succeeded.

    NULL

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid.

  • Example

    #include <usrinc/atmi.h>
    main(int argc, char *argv[])
    {
       ...
       if(tpcall(“TOUPPER”, sndbuf, 0, &rcvbuf, &rcvlen, TPNOFLAGS)==-1){
          memset(svc, NULL, 16);
          strcpy((char *)svc, tmaxlastsvc(sndbuf, rcvbuf, TPNOFLAGS));
          printf(“servicename = %s\n”, svc);
          error processing
       }
       ...
    }

1.21. tmaxreadenv

The tmaxreadenv function reads information about a system to be accessed from a file and sets an environment variable value.

To access a Tmax system, several environment parameters must be first registered. By referring to registered environment parameters and using the tpstart() function, the client can access the Tmax system. Generally, UNIX defines csh in <.cshrc> and ksh in <.profile>, while DOS defines environment variables in the <autoexec.bat> file.

To access multiple systems, the client can change the system to be accessed depending on the situation. This function must be executed before accessing the Tmax system because the information required for access must be set in the environment variable.

For more information about registering environment variables in the configuration file, refer to Tmax Administration Guide.

  • Prototype

    #include <tmaxapi.h>
    int tmaxreadenv (char *file, char *label)
  • Parameter

    Parameter Description

    file

    The file that stores configuration information of a system to be accessed. This file must be registered according to a prescribed text format.

    label

    The descriptor of the configuration information registered in a file. I.e., this value identifies each system if information about multiple systems is registered in one file.

  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

    The file or label does not exist.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    void main(int argc, char* argv[])
    {
        tmaxreadenv(“tmax.env”, “tmax”);  /*obtains environment variable from the "tmax" section in "tmax.env"*/
        tpstart((TPSTART_T *)NULL);
        data process…
        tpend();
    }
  • Related Function

    tpstart()

1.22. tp_sleep

The tp_sleep function waits for data to arrive.

In Tmax v5.0 SP2 Fix#1 and previous versions, if a command is executed in tmadmin while executing tp_sleep(), a server library received an event from TMM, and tp_sleep() no longer waited for data. In later versions, if a server library receives an event, the event will be handled and tp_sleep() will wait for data to arrive for the remaining time.

  • Prototype

    #include <tmaxapi.h>
    int tp_sleep (int sec)
  • Parameter

    Parameter Description

    sec

    The period of time to wait. Must be a positive number in seconds.

  • Return Value

    Value Description

    0

    Data did not arrive within a sec.

    -1

    An error occurred. The error code in set in tperrno.

    1

    An event was triggered from CLH. A response to tpacall or an unsolicited message was received.

    2

    An event was triggered from TMM. No event from CLH. The TMM event must be handled through tpschedule().

    3

    Both CLH and TMM triggered events. The TMM event must be handled through tpschedule().

  • Errors

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Related functions

    tpacall(), tpbroadcast(), tpgetrply(), tp_usleep(), tpsleep()

1.23. tp_usleep

The tp_usleep function waits for data to arrive, in microseconds, and immediately returns if the data arrives within the specified time.

  • Prototype

    #include <tmaxapi.h>
    int tp_usleep (int usec)
  • Parameter

    Parameter Description

    usec

    The period of time to wait. Must be a positive number in microseconds.

  • Return Value

    Value Description

    0

    Data did not arrive within the specified time (usec).

    -1

    An error occurred. The error code in set in tperrno.

    1

    An event was triggered from CLH. A response to tpacall or an unsolicited message was received.

    2

    An event was triggered from TMM. No event from CLH. The TMM event must be handled through tpschedule().

    3

    Both CLH and TMM triggered events. The TMM event must be handled through tpschedule().

  • Errors

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    void main(int argc, char *argv[])
    {
        int ret, cd;
        char *buf;
        long 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<0) { error processing }
        while(1)
        {
            ret=tp_usleep(2000000);
            if (ret<0) {error processing }
            if (ret==0) printf("waited 2sec..\n");
            else {
                printf("data received!\n");
                break;
            }
        }
        ret=tprecv(cd, &buf, &len, TPNOFLAGS, &revent);
        if (ret<0) { error processing }
        data process....
        tpend();
    }
  • Related functions

    tmax_get_db_usrname(), tmax_get_db_tnsname()

1.24. tpabort

The tpabort function operates similarly as tx_rollback(). This function is provided for Tuxedo compatibility, allowing programs developed for Tuxedo to run in Tmax without modification.

  • Prototype

    #include <tuxfml.h>
    int tpabort (long flags)
  • Parameter

    Parameter Description

    flags

    Not currently supported. Set to TPNOFLAGS.

  • Return Value

  • Errors

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <tuxinc/tuxfml.h>
    
    void main(int argc, char *argv[])
    {
        char *buf;
        int ret;
        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…
        ret = tpbegin(5, TPNOFLAGS);
        if (ret < 0){ error processing }
    
        ret=tpcall(“SERVICE",(char *)buf,strlen(buf),(char **)&buf,&len,TPNOFLAGS);
        if (ret == -1)
        {
            ret = tpabort(TPNOFLAGS);
            if (ret < 0){ error processing }
            tpfree(buf);
            tpend();
            exit(1);
        }
    
        ret = tpcommit(TPNOFLAGS);
        if (ret < 0){ error processing }
        tpfree(buf);
        tpend();
    }
  • Related function

    tx_rollback()

1.25. tpacall

The tpacall function sends a service request between the server and client by sending a message to the specified service through asynchronous communication. After sending a message through asynchronous communication, it returns without waiting the result. The result can be retrieved later using tpgetrply(), or the response can be canceled using tpcancel().

After tx_begin is invoked and tx_time has elapsed, tpacall can only succeed if the call is configured with the TPNOTRAN or TPNOREPLY flag. All others calls result in a TPETIME error.

When tpacall succeeds, the return value is a positive integer in the range 1 to 2,147,438,647.

  • Prototype

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

    Parameter Description

    svc

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

    data

    If the value is not NULL, must be a pointer to a buffer allocated by tpalloc().

    len

    The length of the data to send.

    If the data points to a variable-length buffer type, such as STRING, STRUCT, X_COMMON, or X_C_TYPE, the len will be ignored and 0 will be used by default. If the data points to a fixed-length buffer type, such as X_OCTET, CARRAY, or MULTI STRUCTURE, the len cannot be 0.

    If the data is NULL, len will be ignored and the service request is sent without data.

    The type and subtype of a data must be supported by the svc. If the service request is sent in transaction mode, the request must be received.

    flags

    Specifies the call mode.

    The following options are supported.

    • TPBLOCK

      If tpacall() is used without setting this flag, the call may appear to succeed even if the target service (svc) does not exist, and an incorrect result may be returned. In such cases, the error is reported only when tpgetrply() is called.

      When tpacall() is invoked with the TPBLOCK flag, the function checks whether the target service is currently running.

    • TPNOTRAN

      If a service does not support transactions in transaction mode, the TPNOTRAN flag must be set in order to call tpacall() in transaction mode. If the caller requests a service by setting a flag in transaction mode, the service will be excluded from transaction mode before being executed.

      When a process using tx_begin() to start a transaction invokes tpacall() in transaction mode, it will be affected by the transaction timeout (TXTIME) even if TPNOTRAN was set. For example, tpacall with the TPNOTRAN flag will fail after the transaction times out without calling the service. tpacall with the TPNOTRAN|TPNOREPLY flags are allowed exceptionally.

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

    • TPNOREPLY

      A service call sent through tpacall() returns immediately without waiting for a response. Normally, the result can be retrieved later using tpgetrply() with the descriptor returned by tpacall(). However, when the TPNOREPLY flag is set, no response is expected. In this case, tpacall() returns 0 if the service call is successfully issued.

      If the caller is in transaction mode, the TPNOTRAN flag must also be set for TPNOREPLY to take effect. To verify the service status, the TPBLOCK flag must be specified as well. Without TPBLOCK, no error is reported even if the target service is in the NRDY state.

    • TPNOBLOCK

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

      If tpacall() is called without setting the TPNOBLOCK flag and a blocking condition occurs, the caller must wait until it is unblocked or timeout (transaction or blocking timeout) occurs.

    • TPNOTIME

      The caller waits indefinitely until receiving the response, ignoring the blocking timeout. If tpacall() is invoked within the transaction timeout period, the timeout still applies.

    • TPSIGRSTRT

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

    • TPNOCALLBACK

      When invoking tpacall() from usrmain() in UCS, a callback function can be registered using tpregcb(). If the TPNOCALLBACK flag is set, the response is not delivered to the callback function but must instead be retrieved explicitly through tpgetrply().

  • Return Value

    Value Description

    Descriptor

    The function call succeeded. The returned descriptor receives the response to the service request.

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the specified service (svc) is NULL, or the data points to a buffer that was not allocated by tpalloc().

    [TPENOENT]

    The service (svc) is not available because it does not exist.

    [TPEITYPE]

    The type or subtype of the data is not supported by svc. For structures, this error occurs if the struct has not been declared in the SDLFILE.

    [TPELIMIT]

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

    [TPETIME]

    A transaction timeout occurred when the caller was in transaction mode, and the transaction was rolled back. If the caller is not in transaction mode, and neither TPNOTIME nor TPNOBLOCK was set, a block timeout will occur. If a transaction timeout occurs, any new service requests and processes waiting for the response will fail due to a [TPETIME] error until the transaction is rolled back.

    [TPEBLOCK]

    A blocking condition occurred while TPNOBLOCK was set.

    [TPGOTSIG]

    A signal was received while TPSIGRSTRT was not set. On SUN systems, even if a signal interrupt occurs, the function does not fail but instead waits for the response until the specified timeout.

    [TPEPROTO]

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

    [TPESYSTEM]

    An error occurred in the Tmax system.

    [TPEOS]

    A system call error occurred. If the system errno is set to EPIPE, a TPEBLOCK error occurs during TPECLOSE. If errono is set to EAGAIN or EWOULDBLOCK, a TPEBLOCK error occurs as well. In all other cases, TPEOS is returned.

    The error may occur under the following conditions.

    1. tpalloc() or malloc() failed.

    2. realloc() failed.

    3. The connection was lost during send/receive in a session connected to the CLH. (AIX/SUN only)

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    void main(int argc, char *argv[])
    {
        char *buf;
        int ret,cd;
        long len;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret<0) { error processing }
    
        buf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (buf==NULL) {error processing }
        data process....
    
        cd = tpacall(“SERVICE”, sndbuf, 20, TPNOTIME);
        if (cd<0) {error processing }
        data process....
    
        ret=tpgetrply(&cd, (char **)&buf, &len, TPNOTIME);
        if (ret<0) { error processing }
        data process....
    
        tpfree((char *)buf);
        tpend();
    }
  • Related functions

    tpalloc(), tpcall(), tpcancel(), tpgetrply()

1.26. tpacallsvg

The tpacallsvg function asynchronously calls a service from a server group in a multi server group environment grouped by COUSIN. The only difference between tpacall and tpacallsvg is that tpacallsvg can call a service from specific a server group.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tpacallsvg (int svgno, char *svc, char *data, long lenl, long flagsl)
  • Parameter

    See tpacall for the parameters other than svgno.

    Parameter Description

    svgno

    The number of a server group that contains a service to be called. The server group number can be found using the tpgetsvglist() API. If the svgno is set to -1, tpacallsvg() behaves the same as tpacall().

    When calling a service from within a service, the tpgetmysvgno() API can be used to look up the current server group number and call other services in the same server group.

  • Return Value

    Value Description

    Descriptor

    The function call succeeded (client descriptor).

    -1

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

  • Errors

    See tpacall for errors.

  • Example

    <Client program>

    #include <usrinc/tmaxapi.h>
    #include “../fdl/demo_fdl.h”
    
    int main(int argc, char *argv[])
    {
        FBUF    *sndbuf, *rcvbuf;
        int     ret, I, cd;
        char    sndata[30],     rcvdata[30];
        long    sndlen, rcvlen;
        struct svglist *svg_list;
        char svc[32];
    
        ret = tmaxreadenv( “tmax.env”,”TMAX” );
        ret = tpstart((TPSTART_T *)NULL);
        sndbuf = (FBUF *)tpalloc(“FIELD”, NULL, 0)};
        rcvbuf = (FBUF *)tpalloc(“FIELD”, NULL, 0));
        strcpy(sndata, argv[1]);
    
        ret = fbput(sndbuf, INPUT, sndata, 0);
        strcpy(svc, “FDLTOUPPER”);
        svg_list = (struct svglist *)tpgetsvglist(svc, 0);
    
        for(i=0; i< svg_list->ns_entry; i++)
        {
            printf(“\n”);
            printf(“ >>> tpcallsvg ( %d th svg )\n”, i+1);
            strcpy(sndata, argv[1]);
            ret = fbput(sndbuf, INPUT, sndata, 0);
            cd = tpacallsvg(svg_list->s_list[i], svc, (char *)sndbuf, 0, 0);
            if(cd < 0)
            {
                printf(“tpacall failed! errno = %d[%s]\n”, tperrno,
                         tpstrerror(tperrno));
                tpfree((char *)sndbuf);
                tpfree((char *)rcvbuf);
                tpend();
                exit(1);
            }
            ret = tpgetrply(&cd, (char **)&rcvbuf, (long *)&rcvlen, 0);
            ret = fbget(rcvbuf, OUTPUT, rcvdata, 0);
            fbprint(rcvbuf);
        }
        tpfree((char *)sndbuf);
        tpfree((char *)rcvbuf);
        tpend();
        return 0;
    }
  • Related functions

    tpacall( ), tpcallsvg( ), tpgetsvglist( ), tpgetmysvgno( )

1.27. tpalivechk

The tpalivechk function displays the connection status of a client by checking the socket status. This function acts the same as the tmax_chk_conn() function if the factor is set to 0.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tpalivechk(void)
  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPEPROTO]

    tpstart() has not beed executed.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <usrinc/atmi.h>
    #include <usrinc/fbuf.h>
    #include <usrinc/tmaxapi.h>
    #include “../fdl/demo_fdl.h”
    
    main(int argc, char *argv[])
    {
        FBUF    *sndbuf, *rcvbuf;
        int     chkno;
        char    sndata[30], rcvdata[30];
        char    input[10], outdata[10];
        long    sndlen, rcvlen;
    
        if ( (ret = tmaxreadenv( “tmax.env”,”TMAX” )) == -1 ){
            printf( “tmax read env failed\n” );
            exit(1);
        }
        if (tpstart((TPSTART_T *)NULL) == -1)
            error processing…
        if ((sndbuf = (FBUF *)tpalloc(“FIELD”, NULL, 0)) == NULL)
            error processing…
        if ((rcvbuf = (FBUF *)tpalloc(“FIELD”, NULL, 0)) == NULL)
            error processing…
        /* Check socket status */
        chkno = tpalivechk();
        printf(“chkno = %d\n”, chkno);
        if(chkno < 0)
        {
            printf(“The situation of socket is bad\n”);
            printf(“errno = %d\tstrerror=%s\n”, tperrno, tpstrerror(tperrno) );
        }
        else if(chkno == 0)
        {
            printf(“The situation of socket is good\n”);
        }
        tpcall…
        data process…
        tpend();
    }
  • Related functions

    tmax_chk_conn()

1.28. tpalloc

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

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

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

  • Prototype

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

    Parameter Description

    type

    Buffer type. One of the following:

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

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

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

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

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

    subtype

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

    The default allocated buffer size is greater than 1024 bytes.

    size

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

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

  • Return Value

    Value Description

    Buffer Pointer

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

    NULL

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

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

    [TPENOENT]

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

    [TPESYSTEM]

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

    [TPEOS]

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

    [TPEOTYPE]

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

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include “../sdl/demo.s”
    
    void main(int argc, char *argv[])
    {
        int ret;
        struct data *buf;
        long len;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret<0) { error processing }
        buf=(struct data *)tpalloc(“STRUCT”, “data”,0);
        data process....
    
        ret=tpcall(“SERVICE”, (char *)sndbuf, 0, (char **)&rcvbuf, &len, TPNOFLAGS);
        if (ret<0) {error processing }
        data process....
        tpfree((char *)buf);
        tpend();
    }
  • Related functions

    tpfree(), tprealloc(), tptypes()

1.29. tpbegin

The tpbegin function executes both tx_set_transaction_timeout() and tx_begin() simultaneously. This function is provided for Tuxedo compatibility, allowing programs developed for Tuxedo to run in Tmax without modification. The global transaction function for tpbegin() is the same as for tx_begin().

  • Prototype

    int tpbegin(unsigned long timeout, long flags);
  • Parameter

    Parameter Description

    timeout

    Transaction timeout. Used in the same manner as tx_set_transaction_timeout(). (Unit: second)

    flags

    Not currently supported. Set to TPNOFLAGS.

  • Return Value

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <tuxinc/tuxfml.h>
    void main(int argc, char *argv[])
    {
        char *buf;
        int ret;
        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…
        ret = tpbegin(5, TPNOFLAGS);
        if (ret < 0){ error processing }
    
        ret = tpcall(“SERVICE”, (char *)buf, strlen(buf),
                     (char **)&buf, &len, TPNOFLAGS);
        if (ret == -1)
        {
            ret = tpabort(TPNOFLAGS);
            if (ret < 0){ error processing }
            tpfree(buf);
            tpend();
            exit(1);
        }
        ret = tpcommit(TPNOFLAGS);
        if (ret < 0){ error processing }
        tpfree(buf);
        tpend();
    }
  • Related functions

    tx_set_transaction_timeout(), tx_begin()

1.30. tpbroadcast

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

  • Prototype

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

    Parameter Description

    nodename,

    usrname,

    cltname

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

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

    data

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

    len

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

    flags

    The following flags are available:

    • TPNOBLOCK

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

    • TPNOTIME

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

    • TPSIGRSTRT

      Allows signal interrupts. If a system function is interrupted by a signal, the system function is executed again. If the signal interrupt occurs without this flag, the function fails and tperrno is set to TPGOTSIG.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Errors

    If tpbroadcast() fails, no message is sent to clients and one of the following codes is set in tperrno.

    Error Code Description

    [TPEINVAL]

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

    [TPETIME]

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

    [TPEBLOCK]

    A blocking condition was encountered while TPNOBLOCK was set.

    [TPGOTSIG]

    A signal was received while TPSIGRSTRT was not set. On SUN systems, even if a signal interrupt occurs, the function does not fail but instead waits for the response until the specified timeout.

    [TPEPROTO]

    tpbroadcast() was called under an inappropriate condition.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    void main(int argc, char *argv[])
    {
        int ret;
        char *buf;
        TPSTART_T *tpinfo;
    
        tpinfo = (TPSTART_T *)tpalloc(“TPSTART”, NULL, sizeof(TPSTART_T));
        if (tpinfo==NULL) { error processing }
        strcpy(tpinfo->cltname, “cli1”);
        strcpy(tpinfo->usrname, “navis”);
        ret=tpstart(tpinfo);
        if (ret==-1) { error processing }
    
        buf=tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processing }
        data process…
    
        tpbroadcast(“tmax”, NULL, NULL, buf, 0, TPNOFLAGS);
        data process....
    
        tpfree(buf);
        tpend();
    }
  • Related functions

    tpalloc(), tpend(), tpstart()

1.31. tpcall

The tpcall function sends a service request to the specified service through synchronous communication and receives the response. Its behavior is equivalent to calling tpacall() followed immediately by tpgetrply().

  • Prototype

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

    Parameter Description

    svc

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

    idata

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

    ilen

    The length of the data to send.

    If the idata points to a variable-length buffer type, such as STRING, STRUCT, X_COMMON, or X_C_TYPE, the ilen will be ignored and 0 will be used. If the idata points to a fixed-length buffer type, such as X_OCTET, CARRAY, or MULTI STRUCTURE, the ilen cannot be 0.

    If the idata is NULL, ilen will be ignored.

    *odata

    Response data buffer pointer with the length of an *olen. Must be allocated by tpalloc().

    If the same buffer is used for both sent and received data, the *odata must be set to an idata address. To detect change in the response buffer size, compare the response buffer size allocated to the *odata before a tpcall() is complete and the size of the returned *olen. If the *olen size is larger, the allocated response buffer size will be increased. Otherwise, it will remain the same.

    If tpcall() is called when the idata and *odata are using the same buffer, the address indicated by the idata will no longer be valid if the *odata is changed. The *odata may be changed if received data is too big or for other reasons.

    If the *olen is returned as 0, no data will be received and the *odata and buffer pointed to by the *odata will not be changed. If *odata or *olen are NULL, an error will occur.

    *olen

    The length of the response returned by the *odata.

    flags

    Specifies the communication mode.

    The following options are supported.

    • TPNOTRAN

      If a service does not support transactions in transaction mode, the TPNOTRAN flag must be set in order to call tpcall() in transaction mode.

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

      When a process using tx_begin() to start a transaction invokes tpcall() in transaction mode, it will be affected by the transaction timeout (TXTIME) even if TPNOTRAN was set. For example, tpcall with the TPNOTRAN flag will fail after the transaction times out without calling the service.

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

    • TPNOCHANGE

      If the TPNOBLOCK flag is set and a blocking condition (e.g., the internal buffer is full with messages to send) occurs, the request will fail.

      TPNOCHANGE is applied only to transactions in tpcall().

      If tpcall() is called without setting the TPNOBLOCK flag and a blocking condition occurs, the caller must wait until it is unblocked or timeout (transaction or blocking timeout) occurs.

    • TPNOTIME

      The caller waits indefinitely until receiving the response, ignoring the blocking timeout. If tpcall() is invoked within the transaction timeout period, the timeout still applies.

    • TPSIGRSTRT

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

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

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

    [TPENOENT]

    The service (svc) is not available because it does not exist.

    [TPEITYPE]

    The type or subtype of the data is not supported by svc.

    [TPEOTYPE]

    The type or subtype of the received response buffer is unknown to the caller.

    When the flag is set to TPNOCHANGE, and the type and subtype of the buffer pointed by *odata do not match those of the received response buffer, both the *odata and *olen remain unchanged. If the caller requested a service in transaction mode, the transaction is rolled back because the response for the transaction was ignored.

    [TPETRAN]

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

    [TPETIME]

    A transaction timeout occurred when the caller was in transaction mode, and the transaction was rolled back. If the caller is not in transaction mode, and neither TPNOTIME nor TPNOBLOCK was set, a block timeout will occur. In such cases, both the *odata and *olen remain unchanged. If a transaction timeout occurs, any new service requests and processes waiting for the response will fail due to a [TPETIME] error until the transaction is rolled back.

    [TPESVCFAIL]

    A service routine sent a response by calling tpreturn() with TPFAIL because an error occurred in the application program. Service response data can be accessed through the *odata.

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

    [TPESVCERR]

    An error occurred during the execution of a service routine or tpreturn() (e.g., a wrong argument was passed).

    If this error occurs, no response data will be returned (i.e., neither *odata nor *olen is changed). This error occurs when a buffer that was not allocated by tpalloc is used, the Tmax header of an allocated buffer is affected by an invalid pointer (due to memcpy, etc.), a call descriptor of tpacall or tpconnect is returned, or when the service includes invalid conversational data while in Recv mode. The client will receive this error when attempting to execute tpreturn.

    When a TPEV_DISCOMN event occurs (e.g., after the client forcibly disconnects a conversation, the service program will receive a TPEV_DISCOMN) the client will receive this error through tpreturn for the service.

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

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

    [TPEBLOCK]

    A blocking condition occurred while TPNOBLOCK was set.

    [TPGOTSIG]

    A signal was received while TPSIGRSTRT was not set. On SUN systems, even if a signal interrupt occurs, the function does not fail but instead waits for the response until the specified timeout.

    [TPEPROTO]

    tpcall() was called under an inappropriate condition.

    [TPESYSTEM]

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

    [TPEOS]

    A system call error occurred. If the system errno is set to EPIPE, a TPEBLOCK error occurs during TPECLOSE. If errono is set to EAGAIN or EWOULDBLOCK, a TPEBLOCK error occurs as well. In all other cases, TPEOS is returned.

    The error may occur under the following conditions.

    1. tpalloc() or malloc() failed.

    2. realloc() failed.

    3. The connection was lost during send/receive in a session connected to the CLH. (AIX/SUN only)

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    
    void main(int argc, char *argv[])
    {
        int ret;
        char *sndbuf, *rcvbuf;
        long sndlen,  rcvlen;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        sndbuf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (sndbuf==NULL) {error processing };
    
        rcvbuf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (rcvbuf==NULL) {error processing };
    
        data process....
    
        sndbuf=strlen(sndbuf);
        ret=tpcall(”SERVICE”, sndbuf, sndlen, &rcvbuf, &rcvlen, TPNOCHANGE);
        if (ret==-1) { error processing }
    
        data process....
    
        tpfree((char *)sndbuf);
        tpfree((char *)rcvbuf);
        tpend();
    }
  • Related functions

    tpalloc(), tpacall(), tpgetrply(), tpreturn()

1.32. tpcallsvg

The tpcallsvg function synchronously calls a service from a server group in a multi server group environment grouped by COUSIN. The only difference between tpcall and tpcallsvg is that the latter can call a service from a specific server group.

When calling a service from within a service, the tpgetmysvgno() API can be used to look up the current server group number and call other services in the same server group.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tpcallsvg (int svgno, char *svc, char *idata, long ilenl, char **odata,
                   long *olen, long flagsl)
  • Parameter

    See tpcall for parameters other than svgno.

    Parameter Description

    svgno

    The number of the server group that contains the service to be called. The server group number can be retrieved using the tpgetsvglist() API. If the svgno is set to -1, tpcallsvg() functions the same as tpcall().

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Errors

    See tpcall for errors.

  • Example

    <Client program>

    #include <usrinc/tmaxapi.h>
    #include “../fdl/demo_fdl.h”
    
    int main(int argc, char *argv[])
    {
        FBUF    *sndbuf, *rcvbuf;
        int     ret, i;
        char    sndata[30],     rcvdata[30];
        long    sndlen, rcvlen;
        struct svglist *svg_list;
        char svc[32];
    
        ret = tmaxreadenv( “tmax.env”,”TMAX” );
        ret = tpstart((TPSTART_T *)NULL);
        sndbuf = (FBUF *)tpalloc(“FIELD”, NULL, 0)};
        rcvbuf = (FBUF *)tpalloc(“FIELD”, NULL, 0));
        strcpy(sndata, argv[1]);
        ret = fbput(sndbuf, INPUT, sndata, 0);
        strcpy(svc, “FDLTOUPPER”);
        svg_list = (struct svglist *)tpgetsvglist(svc, 0);
        for(i=0; i< svg_list->ns_entry; i++)
        {
            printf(“\n”);
            printf(“ >>> tpcallsvg ( %d th svg )\n”, i+1);
            strcpy(sndata, argv[1]);
            ret = fbput(sndbuf, INPUT, sndata, 0);
            if (tpcallsvg(svg_list->s_list[i], svc, (char *)sndbuf, 0,
                (char **)&rcvbuf, &rcvlen, 0) == -1)
            {
               printf("tpcall failed! errno = %d[%s]\n",tperrno,tpstrerror(tperrno));
               tpfree((char *)sndbuf);
               tpfree((char *)rcvbuf);
               tpend();
               exit(1);
            }
            ret = fbget(rcvbuf, OUTPUT, rcvdata, 0);
            fbprint(rcvbuf);
        }
        tpfree((char *)sndbuf);
        tpfree((char *)rcvbuf);
        tpend();
        return 0;
    }
  • Related functions

    tpcall( ), tpacallsvg( ), tpgetsvglist( ), tpgetmysvgno( )

1.33. tpcancel

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

  • Prototype

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

    Parameter Description

    cd

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

  • Return Value

    Value Description

    -1

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

  • Errors

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

    Error Code Description

    [TPEBADDESC]

    An invalid cd.

    [TPETRAN]

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

    [TPEPROTO]

    tpcancel() was called under an inappropriate condition.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    void main(int argc, char *argv[])
    {
        char *test[2];
        int ret, i, cd[2];
        long len;
    
        if (argc != 4) { error processing }
        ret=tpstart((TPSTART_T *)NULL;
        if (ret==-1) { error processing }
    
        for (i=0; i<3; i++)
        {
            test[i] = tpalloc(“STRING”,NULL,0);
            if (test[I])==NULL} { error processing }
            strcpy(test[i],argv[i+1]);
            cd[i]=tpacall(“SERVICE”, test[i], 0, TPNOTIME);
        )
    
        ret=tpcancel(cd[1]);         /* Cancel the second response. */
        if (ret==-1) { error processing }
        for (i=0; i<3; i++)
        {
            ret=tpgetrply(&cd[i], (char **)&test[i], &len, TPNOTIME)
            if (ret==-1) printf(“Can’t rcv data from service of %d\n”,cd[i]);
            else prtinf(“%dth rcv data : %s\n”, I+1, test[I]);
            tpfree(test[I]);
        }
        tpend();
    }
  • Related function

    tpacall()

1.34. tpcommit

The tpcommit function commits a global transaction on both the server and the client. It is equivalent to tx_commit().

This function is provided for Tuxedo compatibility, allowing programs developed for Tuxedo to run in Tmax without modification.

  • Prototype

    #include <tuxfml.h>
    int  tpcommit (long flags)
  • Parameter

    Parameter Description

    flags

    Not used. Set to TPNOFLAGS.

  • Return Value

    See tx_commit.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <tuxinc/tuxfml.h>
    
    void main(int argc, char *argv[])
    {
        char *buf;
        int ret;
        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…
        ret = tpbegin(5, TPNOFLAGS);
        if (ret < 0){ error processing }
    
        ret=tpcall("SERVICE",(char *)buf, strlen(buf), (char **)&buf, &len, TPNOFLAGS);
        if (ret == -1)
        {
            ret = tpabort(TPNOFLAGS);
            if (ret < 0){ error processing }
            tpfree(buf);
            tpend();
            exit(1);
        }
        ret = tpcommit(TPNOFLAGS);
        if (ret < 0){ error processing }
    
        tpfree(buf);
        tpend();
    }
  • Related function

    tx_commit()

1.35. tpconnect

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

  • Prototype

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

    Parameter Description

    svc

    The name of an interactive service.

    data

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

    len

    The length of the data to be sent.

    If the data points to a variable-length buffer type, such as STRING, STRUCT, X_COMMON, or X_C_TYPE, the len will be ignored and 0 will be used by default. If the data points to a fixed-length buffer type, such as X_OCTET, CARRAY, or MULTI STRUCTURE, the len cannot be 0.

    If the data is NULL, len will be ignored and no data is sent to the interactive service.

    flags

    The following flags are available.

    • TPNOTRAN

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

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

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

    • TPSENDONLY

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

    • TPRECVONLY

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

    • TPNOTIME

      The caller ignores the block timeout and waits indefintely for the response. If tpconnect() is called within the transaction timeout period, the timeout still applies.

    • TPSIGRSTRT

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

  • Return Value

    Value Description

    Descriptor

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

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

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

    [TPENOENT]

    The service (svc) is not available because it does not exist.

    [TPEITYPE]

    The type or subtype of the data is not supported by svc.

    [TPELIMIT]

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

    [TPETRAN]

    xa_start failed because an error occurred in the database while calling a transaction service.

    [TPETIME]

    A transaction timeout occurred when the caller was in transaction mode, and the transaction was rolled back. If the caller is not in transaction mode, and neither TPNOTIME nor TPNOBLOCK was set, a block timeout will occur. If a transaction timeout occurs, any new service requests and processes waiting for the response will fail due to a [TPETIME] error until the transaction is rolled back.

    [TPEBLOCK]

    A blocking condition occurred while TPNOBLOCK was set.

    [TPGOTSIG]

    A signal was received while TPSIGRSTRT was not set. On SUN systems, even if a signal interrupt occurs, the function does not fail but instead waits for the response until the specified timeout.

    [TPEPROTO]

    tpconnect() was called in an invalid state.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    
    void main(int argc, char *argv[])
    {
        char *buf;
        int ret, cd;
        long len, revent;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf=tpalloc(“STRING”,NULL,0);
        if (buf=NULL) { error procesing }
    
        data process ....
    
        cd = tpconnect(“SERVICE”,sndbuf,0,TPRECVONLY);
        if (cd==-1) { error processing }
        data process....
    
        ret=tprecv(cd, &buf, &len, TPNOFLAGS, revent);
        if (ret==-1) { error processing }
        tpfree(buf);
        tpend();
    }
  • Related functions

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

1.36. tpdeq

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

  • Prototype

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

    Parameter Description

    qname

    RQ that saves data. The name must be specified and registered in the configuration file.

    svc

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

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

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

    *data

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

    len

    The length of the data received by tpdeq(). If the response is larger than the specified buffer, tpdeq() can automatically increase the buffer size.

    The received data is stored in *data, and len is updated to the size of the received data. If the size of the received data exceeds the current buffer, *data may be reallocated to a larger buffer. If len returns 0, no data is received, and the contents of *data and len remain unchanged.

    If *data or len is NULL, an error occurs.

    flags

    The following flags are available.

    • TPRQS

      Retrieves service results from the reply queue (RQ).

    • TPFUNC

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

    • TPBLOCK

      Waits until a message is returned during the block timeout period.

    • TPNOTIME

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

    • 0(zero)

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

  • Return Value

    Value Description

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the data points to a buffer that was not allocated by tpalloc() or an invalid flag was set.

    [TPGOTSIG]

    A signal was received while TPSIGRSTRT was not set.

    [TPEMATCH]

    The service name is incorrect, or no data matching the specified conditions is found.

    [TPENOENT]

    The qname does not exist.

    [TPEPROTO]

    tpdeq() was called inappropriately.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    void main(int argc, char *argv[])
    {
        int ret;
        char *buf;
        long len;
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf = (char *)tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processing }
        data process....
    
        ret=tpenq(“RQ”, “SERVICE”, (char *)buf, strlen(buf), TPRQS);
        if (ret==-1) { error processing }
        data process....
    
        ret=tpdeq(“RQ”, “SERVICE”, (char **)&buf, (long *)&len, TPRQS);
        if (ret==-1) { error processing }
        data process....
    
        tpfree(buf);
        tpend();
    }
  • Related functions

    tpenq(), tpqstat()

1.37. tpdeq_ctl

The tpdeq_ctl function reads data from tpenq_ctl() service request results or data from tpenq_ctl() with a NULL argument. However, there are no response if tpenq_ctl() has the TPNOREPLY flag set. If tpdeq_ctl() is executed in transaction mode, data load operations from RQ will be processed in a transaction. If two or more calls to tpdeq_ctl() are grouped as one transaction, an error while loading data from RQ will roll back everything.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tpdeq_ctl(char *qname, char *svc, TMQCTL *ctl, char **data,
                  long *len, long flags);
  • Parameter

    Parameter Description

    qname

    RQ that saves data. The name must be specified and registered in the configuration file.

    svc

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

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

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

    ctl

    • * flags

      • TPRQS_AUTOACK : Allows deq to delete data from RQS automatically, without a separate acknowledgment.

      • TPRQS_NOAUTOACK : Prevents deletion from RQS during deq.

      • TPRQS_ACK_SUCCESS : Issues an acknowledgment for the queue element corresponding ctl to delete it.

      • TPRQS_ACK_FAIL : Prevents deletion from RQS during deq.

    • * exp_time

      After deq, no response is received within the given time period, the queue element is returned to its original state for another deq attempt. (Unit: seconds)

    data

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

    len

    The length of the data received by tpdeq_ctl(). If the response is larger than the specified buffer, tpdeq_ctl() can automatically increase the buffer size.

    The received data is stored in *data, and len is updated to the size of the received data. If the size of the received data exceeds the current buffer, *data may be reallocated to a larger buffer. If len returns 0, no data is received, and the contents of *data and len remain unchanged.

    If *data or len is NULL, an error occurs.

    flags

    Specifies the data processing type.

    The following flags are available.

    • TPRQS

      Retrieves service results from the reply queue (RQ).

    • TPFUNC

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

    • TPBLOCK

      Waits until a message is returned during the block timeout period.

    • TPNOTIME

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

    • 0(zero)

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

  • Return Value

    Value Description

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the data points to a buffer that was not allocated by tpalloc() or an invalid flag was set.

    [TPGOTSIG]

    A signal was received while TPSIGRSTRT was not set.

    [TPEMATCH]

    The service name is incorrect, or no data matching the specified conditions is found.

    [TPENOENT]

    The qname does not exist.

    [TPEPROTO]

    tpdeq_ctl() was called inappropriately.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <unistd.h>
    #include <stdlib.h>
    #include <string.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    main(int argc, char *argv[])
    {
        char    *sndbuf, *rcvbuf;
        long    rcvlen, sndlen, revent;
        int ret, i, cd;
        TMQCTL   *ctl;
    
        ctl = (TMQCTL*)malloc(sizeof(TMQCTL));
        memset(ctl, 0, sizeof(TMQCTL));
        if (argc != 2) {
            printf(“Usage: toupper_rq string\n”);
            exit(1);
        }
    
        if ( (ret = tmaxreadenv( “tmax.env”,”TMAX” )) == -1 ){
            printf( “tmax read env failed\n” );
            exit(1);
        }
    
        if (tpstart((TPSTART_T *)NULL) == -1){
            printf(“tpstart failed\n”);
            exit(1);
        }
    
        if ((sndbuf = (char *)tpalloc(“STRING”, NULL, 0)) == NULL) {
            printf(“sendbuf alloc failed !\n”);
            tpend();
            exit(1);
        }
    
        if ((rcvbuf = (char *)tpalloc(“STRING”, NULL, 0)) == NULL) {
            printf(“recvbuf alloc failed !\n”);
            tpfree((char *)sndbuf);
            tpend();
            exit(1);
        }
    
        ret = tx_begin();
        if(ret < 0)
        {
            fprintf(stderr, “tx_begin() fail\n”);
            tpfree((char *)sndbuf);
            tpfree((char *)rcvbuf);
            exit(1);
        }
    
        strcpy(sndbuf, argv[1]);
        cd = tpdeq_ctl(“txrq1”, “TOUPPER”, ctl, &rcvbuf, &rcvlen, TPRQS );
        if (cd < 0)
        {
            printf(“tpdeq failed [%s]\n”, tpstrerror(tperrno) );
            tpfree((char *)sndbuf);
            tpfree((char *)rcvbuf);
            tpend();
            exit(1);
        }
    
        cd = tpdeq_ctl(“txrq1”, “TOUPPER”, ctl, &rcvbuf, &rcvlen, TPRQS );
        if (cd < 0)
        {
            printf(“tpdeq failed [%s]\n”, tpstrerror(tperrno) );
            tpfree((char *)sndbuf);
            tpfree((char *)rcvbuf);
            tpend();
            exit(1);
        }
    
        data process....
        ret = tx_commit();
        if(ret < 0)
        {
            fprintf(stderr, “tx_commit() fail\n”);
            tpfree((char *)sndbuf);
            tpfree((char *)rcvbuf);
            tx_rollback();
            exit(1);
        }
        tpfree((char *)sndbuf);
        tpfree((char *)rcvbuf);
        tpend();
    }
  • Related functions

    tpenq_ctl(), tpqstat()

1.38. tpdiscon

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

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

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

  • Prototype

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

    Parameter Description

    cd

    The descriptor returned by tpconnect() for reference.

  • Return Value

    Value Description

    -1

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

  • Errors

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

    Error Code Description

    [TPEBADDESC]

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

    [TPETIME]

    A timeout occurred. The cd is no longer valid.

    [TPEPROTO]

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

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <stdlib.h>
    #include <usrinc/atmi.h>
    
    void main(int argc, char *argv[])
    {
        int ret, cd;
        char *buf
        long len, revent;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf=tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processing }
    
        data process....
        cd=tpconnect(“SERVICE”,buf,0,TPRECVONLY);
    
        if (cd==-1) { error processing }
        data process....
        ret=tprecv(cd, (char **)&buf, &len, TPNOFLAGS, &revent);
        if (ret==-1 && revent != TPEV_SENDONLY && revent != TPEV_SVCSUCC)
        { error processing }
        printf(“received data = %s\n”, buf);
        if (atoi(buf)>90) {
            ret=tpdiscon(cd);
            if (ret==-1) {error processing }
            tpfree(buf);
            tpend();
            exit(1);
        }
    
        data process....
        tpfree(buf);
        tpend();
    }
  • Related functions

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

1.39. tpenq

The Tmax system ensures the integrity of data stored in the request queue (RQ) even if a system fault or error causes the system to go out of service. The tpenq() function saves data to the RQ. If a system crash occurs, processing resumes automatically once the system recovers.

When a service is requested using tpcall() or tpacall(), requests are placed in a queue if others are already waiting. However, if a system error or failure shuts the system down, queued data is lost. To prevent data loss and improve consistency, tpenq() explicitly saves service request data in the RQ.

Although tpenq() can be executed in transaction mode, it is not included in the transaction scope. If an error occurs during execution, the surrounding transaction is not affected.

The maximum number of requests that can be stored in the RQ is 2,097,152 (2 million). If the queue exceeds this limit, a TPEQFULL error is returned.

  • Prototype

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

    Parameter Description

    qname

    RQ that saves data. The name must be specified and registered in the configuration file.

    svc

    Stores data to the RQ and immediately requests a service unless the svc name is NULL.

    If the svc name is NULL, data is stored in the RQ but a service will not be performed. In this case, the function caller must request the service again using tpdeq(). If a system fault occurs when there is no service named svc or the service result has not been received after a service was performed, the data will be stored internally in a Fail Queue. This data must be re-requested using tpdeq() , or it is processed as an error.

    data

    A pointer to a buffer allocated by tpalloc() unless the value is NULL. The type and subtype of data must be supported by svc.

    len

    The length of data to be sent.

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

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

    If data is NULL, len is ignored and the service request will be sent without data.

    flags

    The following flags are available.

    • TPRQS

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

    • TPNOREPLY

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

    • TPFUNC

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

    • 0(zero)

      Stores the service results to the client buffer of the Tmax system that is connected to the function caller, instead of storing them in the RQ. A service is requested through the RQ, but the results are saved to the client’s buffer similarly to the tpcall() function.

      Once this flag is set, 0 (zero) must also be set when calling tpdeq() in order to receive the service results.

  • Return Value

    Value Description

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the data points to a buffer that was not allocated by tpalloc() or an invalid flag was set.

    [TPENOENT]

    The qname does not exist.

    [TPEQFULL]

    The queue has reached its maximum capacity due to excessive enqueued service requests.

    [TPGOTSIG]

    A signal was received while TPSIGRSTRT was not set.

    [TPEPROTO]

    tpenq() was called inappropriately.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    void main(int argc, char *argv[])
    {
        int ret;
        char *buf;
        long len;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf = (char *)tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processing }
        data process....
    
        ret=tpenq(“RQ”, “SERVICE”, (char *)buf, strlen(buf), TPRQS);
        if (ret==-1) { error processing }
        data process....
    
        ret=tpdeq(“RQ”, “SERVICE”, (char **)&buf, (long *)&len, TPRQS);
        if (ret==-1) { error processing }
        data process....
    
        tpfree(buf);
        tpend();
    }
  • Related functions

    tpdeq(), tpqstat()

1.40. tpenq_ctl

The tpenq_ctl function saves data to RQ and supports transactions in both the server and the client. The Tmax system ensures the integrity of data stored in the RQ by saving data even when a system fault or error causes an out of service status. If a system crashes, it will continue to process data once the system recovers.

When a service is requested using tpcall() or tpacall(), requests are placed in a queue if others are already waiting. However, if a system error or failure causes the system to shut down, queued data is lost. To prevent data loss and to improve data consistency, tpenq_ctl() explicitly saves service request data in the RQ.

If tpenq_ctl() is called in transaction mode, it runs as part of the transaction. When multiple calls are grouped into a single transaction, the data cannot be retrieved using tpdeq_ctl() until all calls in the transaction are completed. If an error occurs during the processing of any call, the entire transaction is rolled back.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tpenq_ctl(char *qname, char *svc, TMQCTL *ctl, char *data, long len,
                  long flags);
  • Parameter

    Parameter Description

    qname

    RQ that saves data. The name must be specified and registered in the configuration file.

    svc

    Stores data to the RQ and immediately requests a service unless the svc name is NULL.

    If the svc name is NULL, data is stored in the RQ but a service will not be performed. In this case, the function caller must request the service again using tpdeq_ctl(). If a system fault occurs when there is no service named svc or the service result has not been received after a service was performed, the data will be stored internally in a Fail Queue. This data must be re-requested using tpdeq_ctl(), or it is processed as an error.

    ctl

    If a time value is specified as the third argument of tpenq_ctl() using the TMQCTL det_time field, the service call is scheduled to run after the given delay. In this case, deq_time must be set to the sum of the current time and the specified delay_time. For example, if delay_time is 3, deq_time will be cur_time + 3.

    If the TPRQS_NON_PERSISTENT flag is set, messages are stored only in memory and are not written to a file.

    data

    A pointer to a buffer allocated by tpalloc() unless the value is NULL. The type and subtype of data must be supported by svc.

    len

    The length of data to be sent.

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

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

    If data is NULL, len is ignored and the service request will be sent without data.

    flags

    Specifies the data processing type.

    The following flags are available.

    • TPRQS

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

    • TPNOREPLY

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

    • TPFUNC

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

    • 0(zero)

      Stores the service results to the client buffer of the Tmax system that is connected to the function caller, instead of storing them in the RQ. A service is requested through the RQ, but the results are saved to the client’s buffer similarly to the tpcall() function.

      Once this flag is set, 0 (zero) must also be set when calling tpdeq_ctl() in order to receive the service results.

  • Return Value

    Value Description

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the data points to a buffer that was not allocated by tpalloc() or an invalid flag was set.

    [TPENOENT]

    The qname does not exist.

    [TPEQFULL]

    The queue has reached its maximum capacity due to excessive enqueued service requests.

    [TPGOTSIG]

    A signal was received while TPSIGRSTRT was not set.

    [TPEPROTO]

    tpenq_ctl() was called inappropriately.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <unistd.h>
    #include <stdlib.h>
    #include <string.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    main(int argc, char *argv[])
    {
        char    *sndbuf, *rcvbuf;
        long    rcvlen, sndlen, revent;
        int ret, i, cd;
        TMQCTL   *ctl;
        long t;
    
        ctl = (TMQCTL*)malloc(sizeof(TMQCTL));
        memset(ctl, 0, sizeof(TMQCTL));
        time(&t);
        ctl->deq_time = (int)t + 3;
    
        if (argc != 2) {
            printf(“Usage: toupper string\n”);
            exit(1);
        }
        if ( (ret = tmaxreadenv( “tmax.env”,”TMAX” )) == -1 ){
            printf( “tmax read env failed\n” );
            exit(1);
        }
        if (tpstart((TPSTART_T *)NULL) == -1){
            printf(“tpstart failed\n”);
            exit(1);
        }
        if ((sndbuf = (char *)tpalloc(“STRING”, NULL, 0)) == NULL) {
            printf(“sendbuf alloc failed !\n”);
            tpend();
            exit(1);
        }
        if ((rcvbuf = (char *)tpalloc(“STRING”, NULL, 0)) == NULL) {
            printf(“recvbuf alloc failed !\n”);
            tpfree((char *)sndbuf);
            tpend();
            exit(1);
        }
        ret = tx_begin();
        if(ret < 0)
        {
            fprintf(stderr, “tx_begin() fail\n”);
            tpfree((char *)sndbuf);
            tpfree((char *)rcvbuf);
            exit(1);
        }
    
        strcpy(sndbuf, argv[1]);
        cd = tpenq_ctl(“txrq1”, “TOUPPER”, ctl, (char *)sndbuf, 0, TPRQS );
        if (cd < 0) {
            printf(“tpenq failed [%s]\n”, tpstrerror(tperrno));
            tpfree((char *)sndbuf);
            tpfree((char *)rcvbuf);
            tpend();
            exit(1);
        }
        cd = tpenq_ctl(“txrq1”, “TOUPPER”, ctl, (char *)sndbuf, 0, TPRQS );
        if (cd < 0) {
            printf(“tpenq failed [%s]\n”, tpstrerror(tperrno));
            tpfree((char *)sndbuf);
            tpfree((char *)rcvbuf);
            tpend();
            exit(1);
        }
        data process....
        ret = tx_commit();
        if(ret < 0)
        {
            fprintf(stderr, “tx_commit() fail\n”);
            tpfree((char *)sndbuf);
            tpfree((char *)rcvbuf);
            tx_rollback();
            exit(1);
        }
    
        tpfree((char *)sndbuf);
        tpfree((char *)rcvbuf);
    
        tpend();
    }
  • Related functions

    tpdeq_ctl(), tpqstat()

1.41. tperrordetail

The tperrordetail function extracts the depth of an error, allowing clients to handle errors quickly by taking an appropriate action. If a system-level error occurs, the client can request for help from administrators. If an application-level error occurs, the client can request help from developers.

  • Prototype

    # include  <atmi.h>
    int  tperrordetail(int errno)
  • Parameter

    Parameter Description

    errno

    Currently not used. An error code is set in tperrno.

  • Return Value

    Value Description

    1

    An application-level error.

    2

    A system-level error.

    -1

    An unknown error.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    void main(int argc, char *argv[])
    {
        int ret;
        char   *buf;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        data process…
    
        ret = tpcall(“SERVICE”, sndbuf, 20, &rcvbuf, &rcvlen, TPNOCHANGE);
        if (ret == -1){
            fprintf(stderr, “tpcall fail,,,[%d][%s]\n”,
                    tperrordetail(tperrno), tpstrerror(tperrno));
            error processing
        }
    
        tpfree(buf);
        tpend();
    }

1.42. tpextsvcinfo

The tpextsvcinfo function provides detailed information about data retrieved from the RQ through tpdeq() in both the server and the client.

  • Prototype

    # include <tmaxapi.h>
    int  tpextsvcinfo (char *data, char *svc, int *type, int *errcode )
  • Parameter

    Parameter Description

    data

    A pointer to a buffer allocated by tpalloc() to store data read from the RQ through tpdeq().

    svc

    A pointer that receives the service name of the data.

    type

    Indicates the result of processing the data.

    The following types are supported.

    • TPREQ(0)

      tpenq(), with the svc parameter set to NULL, executed successfully.

    • TPFAIL(1)

      tpenq(), with the svc parameter set to the service name, failed to execute. The first parameter of tpreturn will be set to TPFAIL.

    • TPSUCCESS(2)

      tpenq(), with the svc parameter set to the service name, executed successfully. The first parameter of tpreturn will be set to TPSUCCESS.

    • TPERR(-1)

      tpenq() failed to execute and was sent to a fail queue.

    errcode

    An error code set when an error occurs.

  • Return Value

    Value Description

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the data or svc is NULL.

    [TPEITYPE]

    The parameter is invalid. For example, the data was not retrieved from the RQ.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Related functions

    tpenq(), tpdeq(), tpextsvcname()

1.43. tpextsvcname

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

  • Prototype

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

    Parameter Description

    data

    A pointer to the buffer that stores data retrieved from the RQ through tpdeq(). The buffer must be allocated by tpalloc() in advance.

    svc

    A pointer to receive the data’s service name.

  • Return Value

    Value Description

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

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

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    void main(int argc, char *argv[])
    {
        int ret;
        char *buf, *svc_name;
        long len;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf = (char *)tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processing }
        data process....
    
        ret=tpenq(“RQ”, “SERVICE”, (char *)buf, strlen(buf), TPRQS);
        if (ret==-1) { error processing }
        data process....
    
        ret=tpdeq(“RQ”, “SERVICE”, (char **)&buf, (long *)&len, TPRQS);
        if (ret==-1) { error processing }
    
        ret=tpextsvcname(buf, svc_name);
        if (ret==-1) { error processing }
        printf(“svc name : %s    ,”,svc_name);
        data process....
    
        tpfree(buf);
        tpend();
    }
  • Related functions

    tpenq(), tpdeq()

1.44. tpfree

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

  • Prototype

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

    Parameter Description

    ptr

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

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

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

  • Return Value

    tpfree() returns no value to the caller.

  • Example

    #include <usrinc/atmi.h>
    #include <stdio.h>
    #include “../sdl/demo.s”
    
    void main(int argc, char *argv[])
    {
        int ret;
        struct data *buf;
        char *message, *message2;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf=(struct data *)tpalloc(“STRUCT”, “data”,0);
        if (buf==NULL) { error processing }
        message=tpalloc(“STRING”, NULL, 0);
        if (message==NULL) { error processing }
    
        message2=tpalloc(“CARRAY”, NULL, 20);
        if (message==NULL) { error processing }
    
        data process....
        tpfree((char *)buf);
        tpfree(message);
        tpfree((char *)message2);
        tpend();
    }
  • Related functions

    tpalloc(), tprealloc()

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

1.45. tpget_timeout

The tpget_timeout function enables the user to check the specified blocking timeout, which is the maximum time for a client program to wait for the service response. This function can be used on both the client and the server.

A blocking time configured with tpset_timeout() can be checked using tpget_timeout(). If tpset_timeout() is not configured, this function displays the value configured in BLOCKTIME of the Tmax configuration file.

  • Prototype

    #include <tmaxapi.h>
    int  tpget_timeout(void)
  • Return Value

    tpget_timeout() returns the currently configured block timeout in seconds, and does not return an error.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    void main(int argc, char *argv[])
    {
        int ret;
        char *sndbuf, *rcvbuf;
        long sndlen,  rcvlen;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        sndbuf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (sndbuf==NULL) {error processing };
        rcvbuf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (rcvbuf==NULL) {error processing };
        data process....
        sndbuf=strlen(sndbuf);
        ret=tpset_timeout(4);
        if (ret==-1) { error processing }
    
        ret=tpget_timeout();
        printf(“block time = %d\n”, sec);
    
        ret=tpcall(“SERVICE”, sndbuf, sndlen, &rcvbuf, &rcvlen, TPNOCHANGE);
        if (ret==-1) { error processing }
        data process....
        tpfree((char *)sndbuf);
        tpfree((char *)rcvbuf);
        tpend();
    }

1.46. tpgetactivesvr

The tpgetactivesvr function retrieves a list of active servers in a node specified by a parameter. This function can be used on both the client and the server.

  • Prototype

    #include <tmaxapi.h>
    int tpgetactivesvr(char *nodename, char **outbufp);
  • Parameter

    Parameter Description

    nodename

    The name of a node from which a list of active servers is retrieved.

    If the nodename is set to NULL and called by the client, the function will retrieve a list of servers in the node to which the Tmax system is currently connected. If it is called by the server, the function will retrieve a list of servers in the node with active servers.

    A list of servers in a node to which an invoking server belongs to is stored in the outbufp.

    outbufp

    A list of servers is saved to a pointer of a buffer to receive.

    The server list is sent to a CARRAY type buffer allocated by tpalloc() in tpgetactivesvr(). After the list has been used, the buffer must be removed by tpfree().

    A NULL acts as a delimiter when listing servers. For example, servers svr10 and svr111 are listed as \{ 's', 'v', 'r', '1', '0', NULL, 's', 'v', 'r', '1', '1', '1', NULL }.

  • Return Value

    Value Description

    Server count

    The function call succeeded and returns the number of active servers.

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    An incorrect parameter was used.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system, typically due to insufficient memory.

    [TPESVRDOWN]

    The call failed because the node where it was scheduled is down.

  • Example

    #include <stdio.h>
    #include <unistd.h>
    #include <stdlib.h>
    #include <string.h>
    #include <usrinc/atmi.h>
    
    main(int argc, char *argv[])
    {
        char    *sndbuf, *rcvbuf, *data;
        long    rcvlen, sndlen;
        int     ret, n, i;
        char nodename[35];
    
        if (argc != 2) {
            printf(“Usage: toupper string\n”);
            exit(1);
        }
        if ( (ret = tmaxreadenv( “tmax.env”,”TMAX” )) == -1 ){
            printf( “tmax read env failed\n” );
            exit(1);
        }
    
        if (tpstart((TPSTART_T *)NULL) == -1){
            printf(“tpstart failed\n”);
           exit(1);
        }
    
        if ((rcvbuf = (char *)tpalloc(“STRING”, NULL, 0)) == NULL) {
            printf(“recvbuf alloc failed !\n”);
            tpfree((char *)sndbuf);
            tpend();
            exit(1);
        }
    
        strcpy(nodename, “starbj”);
        if((n = tpgetactivesvr(nodename, &rcvbuf)) < 0) {
            printf(“getactivesvr failed\n”);
            tpfree((char *)rcvbuf);
            tpend();
            exit(1);
        }
        printf(“Total %d servers\n”, n);
        data = rcvbuf;
        for (i = 0; i < n; i++) {
            printf(“ACTIVE[%s]\n”, data);
            data += strlen(data) + 1;
        }
        tpfree((char *)sndbuf);
        tpfree((char *)rcvbuf);
        tpend();
    }

1.47. tpgetcliaddr

The tpgetcliaddr function retrieves the IP address and port number of a client connecting to the Tmax system.

This function is not supported in IPv6 protocol environments. In these environments, use tpgetcliaddr_ipv6.

  • Prototype

    #include <tmaxapi.h>
    int tpgetcliaddr(int clid, int *ip, int *port, long flags);
  • Parameter

    Parameter Description

    clid

    The client ID to retrieve.

    ip

    The client IP address. Since the IP address is stored in the s_addr field of the sockaddr_in structure, use inet_ntoa() to convert it to dotted-decimal notation.

    port

    The client port.

    flags

    Currently not used. Set to TPNOFLAGS.

  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, it is set to NULL.

    [TPEITYPE]

    The function was called in an IPv6 protocol environment.

    [TPESYSTEM]

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

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    
    TOUPPER(TPSVCINFO *msg)
    {
            int             ret;
            int             clid;
            int             port;
            int*            ip;
            ...
            clid = tpgetclid();
            printf(“clid = %d\n”, clid);
    
            ret = tpgetcliaddr(clid, ip, &port, 0);
            if(ret < 0)
              error routine..
    
            printf(“ip = %s, port = %d\n”, inet_ntoa(ip), port);
            tpreturn(TPSUCCESS,0,(char *)msg->data, 0,0);
    }
  • Related function

    tpgetclid()

1.48. tpgetcliaddr_ipv6

The tpgetcliaddr_ipv6 function retrieves the IP and port number of a client connecting to the Tmax system in an IPv6 protocol environment.

  • Prototype

    #include <tmaxapi.h>
    #include <arpa/inet.h>
    int tpgetcliaddr_ipv6(int clid, struct sockaddr_storage *saddr, long flags);
  • Parameter

    Parameter Description

    clid

    The client ID to retrieve.

    ipaddr

    The client IP address. If the function call succeeded, the IP address and the port number is set. The IP protocol version can be checked by using the ss_family member of the sockaddr_storage struct. To convert the TP address into a string, use inet_ntop(). For the port number, use ntohs() to retrieve it correctly.

    flags

    Currently not used. Set to TPNOFLAGS.

  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, it is set to NULL.

    [TPESYSTEM]

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

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <arpa/inet.h>
    
    TOUPPER(TPSVCINFO *msg)
    {
            int             ret;
            int             clid;
            int             portno;
            struct sockaddr_storage saddr;
            struct sockaddr_in *cli_sin4;
            struct sockaddr_in6 *cli_sin6;
            char ipaddrbuf[INET6_ADDRSTRLEN];
            const char *ipaddr = NULL;
            ...
            clid = tpgetclid();
            printf(“clid = %d\n”, clid);
    
            ret = tpgetcliaddr_ipv6(clid, &ipaddr, 0);
            if(ret < 0)
              error routine..
    
            if (saddr.ss_family == AF_INET) {
                cli_sin4 = (struct sockaddr_in *)&saddr;
                ipaddr = inet_ntop(AF_INET, &(cli_sin4->sin_addr), ipaddrbuf, sizeof(ipaddrbuf));
                portno = ntohs(cli_sin4->sin_port);
            } else if (saddr.ss_family == AF_INET6) {
                cli_sin6 = (struct sockaddr_in *)&saddr;
                ipaddr = inet_ntop(AF_INET6, &(cli_sin6->sin6_addr), ipaddrbuf, sizeof(ipaddrbuf));
                portno = ntohs(cli_sin6->sin6_port);
            }
            if (ipaddr == NULL)
                ipaddr = "unknown";
    
            printf(“ip = %s, port = %d\n”, ipaddr, portno);
            tpreturn(TPSUCCESS,0,(char *)msg->data, 0,0);
    }
  • Related function

    tpgetclid()

1.49. tpgetclid

The tpgetclid function retrieves the unique clid of the caller. A clid is a unique identifier for both clients and servers. For clients, it is assigned by CLH at the time of tpstart. For servers, a value starting from 'spri + max client index' is assigned. When tpgetclid() called from within a service, it returns the clid of the caller that invoked tpcall() or tpacall(). The clid is guaranteed to be unique within the domain system. Even in multi-node domain systems, each client and server is assigned a globally unique number.

When this function is used by a server, it is typically used to retrieve the ID of the client that called the service, so the server can send a message to the client using tpsendtocli(). If another service is called through tpcall or tpacall while the service is executing, the actual client’s clid cannot be retrieved.

When this function is used by a client, it returns the client’s own clid. To retrieve the clid of the original client that initiated the first tpcall() in a service chain (including secondary services relayed through tpforward()), use tpgetfclid().

  • Prototype

    #include <tmaxapi.h>
    int  tpgetclid(void)
  • Return Value

    Value Description

    An integer greater than 0

    The function call succeeded. An integer that is greater than 0, which corresponds the client’s number is returned.

    -1

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

  • Errors

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

    Error Code Description

    [TPESYSTEM]

    tpgetclid() was called under an inappropriate condition. For example, it was used within a client program.

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    SERVICE(TPSVCINFO *msg)
    {
        int ret, clid;
        char *buf;
    
        buf = (char *)tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processing }
        strcpy(buf, msg->data);
        data process…
    
        clid = tpgetclid();
        if (clid==-1) { error process }
    
        ret=tpsendtocli(clid, buf, strlen(buf), 0);
        if (ret==-1) { error processing }
        data process….
    
        tpreturn(TPSUCCESS,0,buf, strlen(buf), 0);
    }
  • Related function

    tpsendtocli()

1.50. tpgetctxt

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

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

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

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

Multithread/Multicontext servers do not support Singlecontext.

  • Prototype

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

    Parameter Description

    ctxtid

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

    • Multicontext : A value that is greater than 1.

    • Singlecontext : A value of 0.

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

    flags

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

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

    In server programs, set to TPNOFLAGS or 0.

  • Return Value

    Value Description

    0

    The function call succeeded.

    A value greater than 0

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

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

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

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    • Client program

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

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

      typedef param {
          int ctxtid;
          TPSVCINFO *svcinfo;
      } param_t;
      
      MSERVICE(TPSVCINFO *svcinfo)
      {
          pthread_t tid;
          param_t param;
      
          printf("MSERVICE service is started!");
          tpgetctxt(&param.ctxtid, TPNOFLAGS);
          param.svcinfo = svcinfo;
      
          pthread_create(&tid, NULL, THREAD_ROUTINE, &param);
          pthread_join(tid, NULL);
      
          printf("MSERVICE service is finished!");
          tpreturn(TPSUCCESS, 0, svcinfo->data, 0L, TPNOFLAGS);
      }
      
      void *THREAD_ROUTINE(void *arg)
      {
          param_t *param;
          TPSVCINFO *svcinfo;
      
          param = (param_t *)arg;
          svcinfo = param->svcinfo;
      
          if (tpsetctxt(param->ctxtid, TPNOFLAGS) == -1) {
              printf("tpsetctxt(%d) failed, [tperrno:%d]", param->ctxtid, tperrno);
              return NULL;
          }
      
          tpcall("MTOUPPER", sndbuf, 0, &rcvbuf, &rcvlen, TPNOFLAGS);
      
          if (tpsetctxt(TPNULLCONTEXT, TPNOFLAGS) == -1) {
              printf("tpsetctxt(TPNULLCONTEXT) failed, [tperrno:%d]", tperrno);
              return NULL;
          }
      
          return NULL;
      }
  • Related function

    tpsetctxt()

1.51. tpgetenv

The tpgetenv function returns the value of an environment variable registered as a name. In general, tpgetenv is equivalent to getenv(). In a Windows client, tpgetenv returns a value that is applied to the autoexec.bat file or a file read by tmaxreadenv(). In Windows NT or Windows 2000, tpgetenv returns a value specified to an environment variable. In a server, tpgetenv returns a value specified in the shell configuration file or the envfile. This function can be used both on clients and servers.

  • Prototype

    #include <tmaxapi.h>
    char *tpgetenv(char *name)
  • Parameter

    Parameter Description

    name

    The name of a registered environment variable.

  • Return Value

    Value Description

    NULL

    The specified environment variable does not exist.

    Pointer

    The specified environment variable exists. The pointer to the environment variable is returned.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    main(int argc, char *argv[])
    {
        char *TMAXD, *SDLFI;
        TMAXD=tpgetenv(“TMAXDIR”);
        SDLFI=tpgetenv(“SDLFILE”);
        printf (“tmaxdir : %s\nsdlfile : %s\n”,TMAXD,SDLFI);
    }
  • Related function

    tpputenv()

1.52. tpgetlev

The tpgetlev function determines whether a transaction is currently active. It can be used in both client and server programs.

  • Prototype

    #include <tuxatmi.h>
    int  tpgetlev(void)
  • Return Value

    Value Description

    1

    Transaction mode is active.

    0

    Transaction mode is not active.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include “../sdl/demo.s”
    
    EXEC SQL include sqlca.h;
    EXEC SQL begin declare section;
    struct emp *buf;
    EXEC SQL end declare section;
    
    DELETE(TPSVCINFO *msg)
    {
        struct emp *buf;
        buf = (struct emp *)msg->data;
        data process...
        if (tpgetlev()) printf(“transaction mode\n”);
        else printf(« nontransaction mode\n »);
        EXEC SQL DELETE FROM emp
        WHERE empno = :buf->empno;
        data process...
        tpreturn(TPSUCCESS,0,buf, strlen(buf), 0);
    }

1.53. tpgetnodelist

The tpgetnodelist function retrieves a list of nodes for currently connected Tmax systems. The returned nodelist structure must not be freed by the caller.

  • Prototype

    #include <tmaxapi.h>
    struct nodelist *tpgetnodelist()
  • Return Value

    Value Description

    Not NULL

    The function call succeeded and returns a list of structures containing nodes list.

    NULL

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

    The following shows a returned structures list and its content.

    • nodelist

      struct nodelist {
          int count;
          struct nodeinfo *nodelist;
      };
      Item Description

      count

      Number of nodes.

      nodelist

      List of structures containing node information.

    • nodeinfo

      struct nodeinfo {
          char nodename[NODE_NAME_SIZE];
          int ipfamily;
          int ipaddr;
          struct in6_addr ipaddr6;
          int port;
      };
      Item Description

      nodename

      Node name.

      ipfamily

      AF_INET or AF_INET6.

      ipaddr

      IP address of the node.

      If ipfamily is AF_INET, the value stored in the ipaddr variable is used as the IP address.

      ipaddr6

      IP address of the node.

      If ipfamily is AF_INET6, the value stored in the ipaddr6 variable is used as the IP address.

      port

      Port of the node.

  • Error

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

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

    [TPEPROTO]

    The function was called without first performing tpstart in the client module.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    
    SVGCALL(TPSVCINFO *msg)
    {
            char *svcname = msg->data;
    
            struct nodelist *node = tpgetnodelist();
            if (node == NULL)
               ...error process
    
            for (i = 0; i < node->count; i++) {
                    printf("[%d] %16s : %x:%p\n", i, node->nodelist[i].nodename,
                            node->nodelist[i].ipaddr, node->nodelist[i].port);
            }
    
            ...
    
            struct svglist *svg = tpgetsvglist_bynode(node->nodelist[1].nodename, svcname, 0);
            if (svg == NULL)
               ...error process
    
            for (i = 0; i < svg->ns_entry; i++) {
                    printf("[%d] %d(%x)\n", i, svg->s_list[i], svg->s_list[i]);
            }
    
            ...
    
            tpreturn(TPSUCCESS,0,(char *)msg->data, msg->len,0);
    }
  • Related function

    tpgetsvglist_bynode()

1.54. tpgetpeername

The tpgetpeername function returns the socket address of a peer node after a connection is established to the Tmax system. This function can be used on both clients and servers.

  • Prototype

    #include <tmaxapi.h>
    int  tpgetpeername(struct sockaddr *name, int *namelen)
  • Parameter

    Parameter Description

    name

    A struct that stores the address.In an IPv6 protocol environment, the sockaddr_in6 struct can be used to check the address information, while the sockaddr_storage struct can be used in both IPv4 and IPv6 environments.

    namelen

    Before tpgetpeername is called, the namelen is initialized to the size of a struct allocated by the name. After the function returns a value, the namelen will be set to the actual size of the struct.

  • Return Value

    Value Description

    Socket address

    The function call succeeded. The peer’s socket address is returned.

    -1

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

  • Errors

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

    Error Code Description

    [TPINVAL]

    The parameter is invalid.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

    [TPEITYPE]

    The size of the name struct (namelen) is smaller than the actual size to be used.

  • Example

    #include <stdio.h>
    #include <netinet/in.h>
    #include <arpa/inet.h>
    #include <usrinc/atmi.h>
    #inlcude <usrinc/tmaxapi.h>
    ...
    DELETE(TPSVCINFO *msg)
    {
        struct sockaddr_in cli;
        char ipAddr[16];
        int cli_len, ret;
    
        data process...
        memset((char *)&cli, 0, sizeof(cli));
        ret = tpgetpeername((struct sockaddr *)&cli, &cli_len);
        if (ret == -1){ error processing }
        else{
            memcpy(ipAddr, inet_ntoa(cli.sin_addr), 16);
        }
        printf(“ip = %s , port = %d\n”, ipAddr, cli.sin_port);
        data process...
    
        tpreturn(TPSUCCESS, 0, 0, 0, 0);
    }

    The following is an example of using the function in an IPv6 protocol environment.

    #include <stdio.h>
    #include <netinet/in.h>
    #include <arpa/inet.h>
    #include <usrinc/atmi.h>
    #inlcude <usrinc/tmaxapi.h>
    ...
    DELETE(TPSVCINFO *msg)
    {
        struct sockaddr_storage cli_saddr;
        struct sockaddr_in *cli_sin4;
        struct sockaddr_in6 *cli_sin6;
        char ipaddrbuf[INET6_ADDRSTRLEN];
        const char *ipaddr = NULL;
        int cli_len, ret;
        int portno;
    
        data process...
        memset((char *)&cli_saddr, 0, sizeof(cli_saddr));
        cli_len = sizeof(cli_saddr);
        ret = tpgetpeername((struct sockaddr *)&cli_saddr, &cli_len);
        if (ret == -1) {
            error processing
        }
        else {
            if (cli_saddr.ss_family == AF_INET) {
                cli_sin4 = (struct sockaddr_in *)&cli_saddr;
                ipaddr = inet_ntop(AF_INET, &(cli_sin4->sin_addr), ipaddrbuf, sizeof(ipaddrbuf));
                portno = ntohs(cli_sin4->sin_port);
            } else if (cli_saddr.ss_family == AF_INET6) {
                cli_sin6 = (struct sockaddr_in *)&cli_saddr;
                ipaddr = inet_ntop(AF_INET6, &(cli_sin6->sin6_addr), ipaddrbuf, sizeof(ipaddrbuf));
                portno = ntohs(cli_sin6->sin6_port);
            }
            if (ipaddr == NULL)
                ipaddr = "unknown";
        }
        printf(“ip = %s , port = %d\n”, ipaddr, portno);
        data process...
    
        tpreturn(TPSUCCESS, 0, 0, 0, 0);
    }
  • Related functions

    tpgetpeer_ipaddr(), tpgetsockname(), tpstart()

1.55. tpgetrcahseqno

The tpgetrcahseqno function returns the RCAH process number, similar to the Tmax tpgetsvrseqno API. This number is assigned sequentially by RCAL.

  • Prototype

    #include <ucs.h>
    int tpgetrcahseqno()
  • Return Value

    Value Description

    0

    The RCAH process order number.

1.56. tpgetrcainfo

The tpgetrcainfo function retrieves the thread information of RCAH.

  • Prototype

    #include <ucs.h>
    void * tpgetrcainfo()
  • Return Value

    Returns a pointer to RCAINFO in the RCA header file.

1.57. tpgetrply

The tpgetrply function receives the response for an asynchronous service request sent by tpacall(). This function can be used both on clients and servers.

  • Prototype

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

    Parameter Description

    cd

    The call descriptor returned by tpacall(). In general, tpgetrply waits until the response matching the cd is received or until a timeout occurs. Generally, once the response is received, the cd is no longer valid.

    *data

    A pointer to the buffer allocated in advance by tpalloc().

    len

    The length of the data received by tpdeq(). If the response is larger than the specified buffer, tpdeq() can automatically increase the buffer size.

    The received data is stored in *data, and len is updated to the size of the received data. If the size of the received data exceeds the current buffer, *data may be reallocated to a larger buffer. If len returns 0, no data is received, and the contents of *data and len remain unchanged.

    If *data or len is NULL, an error occurs.

    flags

    The following flags are available.

    • TPGETANY

      Ignores the specified call descriptor (cd) for the response and returns the response that can be received. In general, tpgetrply() will wait until the response is received.

      If TPGETANY is not set, the *cd becomes null unless there is no specific configuration. If set, the cd can be used for an error response. If an error occurs before the response is returned, the cd will be set to 0. Unless otherwise specified, this does not affect the current transaction for the caller.

    • TPNOCHANGE

      The buffer type that the *data points to cannot be changed.

      If the types of the response buffer and the *data buffer do not match, the *data buffer type will be changed to the type of the response buffer. If the TPNOCHANGE flag is set, the buffer type will not be changed. The buffer type and subtype of the response buffer must be the same as those of the *data buffer.

    • TPNOBLOCK

      Returns a valid response available without waiting for the response. If the TPNOBLOCK flag is not set, and there is no available response, the caller will wait until the response is received or a timeout (transaction or block timeout) occurs.

    • TPNOTIME

      The caller waits indefinitely until receiving the response, ignoring the blocking timeout. If tpgetrply() is invoked within the transaction timeout period, the timeout still applies.

    • TPSIGRSTRT

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

  • Return Value

    Value Description

    1

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

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

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

    [TPEBADDESC]

    The cd is invalid.

    [TPEOTYPE]

    The type or the subtype of the received response is unknown to the caller.

    When the flag is set to TPNOCHANGE, and the type and subtype of the *data do not match those of the response sent by the service, the *data and *len remain unchanged. If the response is received when the caller is in transaction mode, the transaction is rolled back because the response is ignored.

    [TPETIME]

    A transaction timeout occurred when the caller is in transaction mode, and the transaction is rolled back. If the caller is not in transaction mode, a block timeout will occur if neither TPNOTIME nor TPNOBLOCK is set. In such cases, the *data and *len remain unchanged. If a transaction timeout occurs, any new service requests and processes waiting for a response will fail due to a [TPETIME] error until the transaction is rolled back.

    [TPESVCFAIL]

    A service routine sent the response by calling tpreturn() with TPFAIL because an error occurred in the application program. Service reply data can be accessed through the *data. If the caller is in transaction mode, the transaction will be rolled back.

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

    [TPEBLOCK]

    A blocking occurred while TPNOBLOCK was set. The cd remains valid.

    [TPGOTSIG]

    A signal was received while TPSIGRSTRT was not set. On SUN systems, even if a signal interrupt occurs, the function does not fail but instead waits for the response until the specified timeout.

    [TPEPROTO]

    tpgetrply() was called under an inappropriate condition.

    [TPETRAN]

    xa_start failed because an error occurred in the database while calling a transaction service.

    [TPESYSTEM]

    An error occurred in the Tmax system.

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    void main(int argc, char *argv[])
    {
        int ret;
        long len;
        char *buf;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf = (char *)tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processing }
        data process....
    
        cd = tpacall(“SERVICE”, buf, 0, TPNOFLAGS);
        if (cd==-1) { error procesing }
        data process....
    
        ret=tpgetrply(&cd, &buf, &len, TPNOTIME);
        if (ret==-1) { error processing }
        data process....
    
        tpfree(buf);
        tpend();
    }
  • Related functions

    tpacall(), tpalloc(), tpreturn()

1.58. tpgetsockname

The tpgetsockname function retrieves the name of the current socket used internally by the Tmax system.

  • Prototype

    #include <tmaxapi.h>
    int  tpgetsockname (struct sockaddr  *name,  int  *namelen)
  • Parameter

    Parameter Description

    name

    The struct that stores an address. In an IPv6 protocol environment, the sockaddr_in6 struct can be used to check the address information, while the sockaddr_storage struct can be used in both IPv4 and IPv6 environments.

    namelen

    Before tpgetsockname is called, the namelen is initialized to the size of the struct allocated by the name. After the function returns a value, the namelen is set to the actual size of the struct.

  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

    [TPEITYPE]

    The size of the name struct (namelen) is smaller than the actual size to be used.

  • Example

    #include <stdio.h>
    #include <netinet/in.h>
    #include <arpa/inet.h>
    #include <usrinc/atmi.h>
    #inlcude <usrinc/tmaxapi.h>
    ...
    DELETE(TPSVCINFO *msg)
    {
        ...
        struct sockaddr_in cli;
        char ipAddr[16];
        int cli_len, ret, i;
        ...
        memset((char *)&cli, 0, sizeof(cli));
    
        ret = tpgetsockname((struct sockaddr *)&cli_saddr, &cli_len);
        if (ret == -1){
            error processing
        }
        else{
            memcpy(ipAddr, inet_ntoa(cli.sin_addr), 16);
        }
        printf(“ip = %s , port = %d\n”, ipAddr, cli.sin_port);
        ...
    }

    The following is an example of using the function in an IPv6 protocol environment.

    #include <stdio.h>
    #include <netinet/in.h>
    #include <arpa/inet.h>
    #include <usrinc/atmi.h>
    #inlcude <usrinc/tmaxapi.h>
    ...
    DELETE(TPSVCINFO *msg)
    {
        struct sockaddr_storage cli_saddr;
        struct sockaddr_in *cli_sin4;
        struct sockaddr_in6 *cli_sin6;
        char ipaddrbuf[INET6_ADDRSTRLEN];
        const char *ipaddr = NULL;
        int cli_len, ret;
        int portno;
    
        data process...
        memset((char *)&cli_saddr, 0, sizeof(cli_saddr));
        cli_len = sizeof(cli_saddr);
    
        ret = tpgetsockname((struct sockaddr *)&cli_saddr, &cli_len);
        if (ret == -1) {
            error processing
        }
        else {
            if (cli_saddr.ss_family == AF_INET) {
                cli_sin4 = (struct sockaddr_in *)&cli_saddr;
                ipaddr = inet_ntop(AF_INET, &(cli_sin4->sin_addr), ipaddrbuf, sizeof(ipaddrbuf));
                portno = ntohs(cli_sin4->sin_port);
            } else if (cli_saddr.ss_family == AF_INET6) {
                cli_sin6 = (struct sockaddr_in *)&cli_saddr;
                ipaddr = inet_ntop(AF_INET6, &(cli_sin6->sin6_addr), ipaddrbuf, sizeof(ipaddrbuf));
                portno = ntohs(cli_sin6->sin6_port);
            }
            if (ipaddr == NULL)
                ipaddr = "unknown";
        }
        printf(“ip = %s , port = %d\n”, ipaddr, portno);
        ...
    }
  • Related functions

    tpgetpeer_ipaddr(), tpgetpeername(), tpstart()

1.59. tpgetsprlist

The tpgetsprlist function retrieves the index of a server process that the specified service belongs to. tpgetsprlist is used to call a service as a server process unit and it retrieves the starting and ending index numbers of a list of servers containing the service.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tpgetsprlist(char *svc, int svgno, int *starti, int *endi, long flagsl);
  • Parameter

    Parameter Description

    svc

    The service to be called.

    svgno

    The number of a server group that contains the service to be called. The server group number can be found using the tpgetsvglist() API or cfg –g in tmadmin.

    starti

    The index number of the first process of a server that the service belongs to.

    endi

    The index number of the last process of a server that the service belongs to. If the starti is 36 and the endi is 40, the serial number of the process will be from 36 to 40. If the MIN of the server is 5 and MAX is 10, 10 indexes will be retrieved when tpgetsprlist() is called.

    flagsl

    Not currently supported. Set to TPNOFLAGS.

  • Return Value

    Value Description

    1

    The function call succeeded. The starti and endi can be retrieved.

    -1

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

  • Errors

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

    Error Code Description

    [TPESYSTEM]

    An error occurred in the Tmax system.

    [TPEOS]

    An error occurred in the operating system.

    [TPEBLOCK]

    A blocking condition occurred.

  • Example

    main(int argc, char *argv[])
    {
        int     ret;
        int     starti = 0, endi = 0;
    
        if (argc != 2) {
           printf(“Usage: argv[1] string\n”);
           exit(1);
           if((ret = tmaxreadenv( “tmax.env”,”TMAX” )) == -1 ){
              printf(“<%-15s> tmaxreadenv fail [%s]”, __FILE__, tpstrerror(tperrno));
              exit(1);
           }
    
        if (tpstart((TPSTART_T *)NULL) == -1){
            printf(“<%-15s> tpstart fail [%s]”, __FILE__, tpstrerror(tperrno));
            exit(1);
        }
    
        /* tpgetsprlist in client */
        ret = tpgetsprlist(argv[1], 2, &starti, &endi, 0);
        if (ret < 0) {
            printf(“<%-15s> tpgetsprlist fail [%s]”, __FILE__, tpstrerror(tperrno));
            exit(1);
        }
        else {
           printf(“Received Message : starti[%d], endi[%d]\n”, starti, endi);
        }
        tpend();
    }

1.60. tpgetsvglist

The tpgetsvglist function returns information about a server group that the specified service belongs to, or information about its COUSIN server group. The returned structure contains the number of server groups or the sequence number of the server group. This function can be used on both clients and servers.

  • Prototype

    #include <tmaxapi.h>
    struct svglist* tpgetsvglist(char *svc, long flags)
  • Parameter

    Parameter Description

    svc

    The name of the service to retrieve.

    flags

    Not currently supported. Set to TPNOFLAGS.

  • Return Value

    Value Description

    A positive integer

    The function call succeeded. The serial number of a server process is returned.

    NULL

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

    When an error occurs, tpgetsvglist() will return NULL and an error code is set in tperrno. Otherwise, tpgetsvglist() will store a list of server groups that failed to be called into the svglist struct and will return the struct.

    The following is the structure of the svglist struct:

    struct svglist {
        int ns_entry;
        int nf_entry;
        int *s_list;
        int *f_list;
    };
    Member Description

    ns_entry

    The number of server groups the service belongs to.

    nf_entry

    The number of server groups that failed to be called.

    s_list

    A pointer to the serial numbers of server groups that were successfully called. nf_entry and f_list are used for different purposes.

    f_list

    A pointer to the serial numbers of server groups that failed to be called.

  • Errors

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An operating system error occurred. This is typically due to memory allocation failure.

1.61. tpgetsvglist_bynode

The tpgetsvglist_bynode function retrieves a list of server groups that match the specified node name from among the server groups providing the specified service. This function behaves like tpgetsvglist(), except that the returned server group list is filtered based on the node name argument.

  • Prototype

    #include <tmaxapi.h>
    struct svglist *tpgetsvglist_bynode(char *nodename, char *svc, long flags)
  • Parameter

    Parameter Description

    nodename

    The name of the node providing the specified service (svc).

    If set to NULL, behaves the same as tpgetsvglist().

    If the node name is incorrect, a TPEINVAL or TPENOENT error occurs.

    svc

    The name of the service.

    flags

    Currently not used.

  • Return Value

    Value Description

    Not NULL

    The function call succeeded, and returns the list of server groups matching the specified node name.

    NULL

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

    If an error occurs, NULL is returned and the corresponding error code is set in tperrno, or the list of server groups that failed the service call is returned in the struct svglist.

    The following example shows the content in struct svglist.

    struct svglist {
        int ns_entry;
        int nf_entry;
        int *s_list;
        int *f_list;
    };
    Member Description

    ns_entry

    Number of server groups providing the specified service.

    nf_entry

    Number of failed server groups.

    s_list

    Pointer to an array of serial numbers of server groups. This is used differently from nf_entry or f_list. Returns 0 or NULL.

    f_list

    Array of serial numbers of failed server groups.

  • Errors

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

    Error Description

    [TPESYSTEM]

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

    [TPEOS]

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

    [TPEPROTO]

    The function was called without first performing tpstart in the client module.

    [TPEINVAL]

    The node name is incorrect.

    [TPENOENT]

    The specified service or node does not exist in the Tmax system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    
    SVGCALL(TPSVCINFO *msg)
    {
            char *svcname = msg->data;
    
            struct nodelist *node = tpgetnodelist();
            if (node == NULL)
               ...error process
    
            for (i = 0; i < node->count; i++) {
                    printf("[%d] %16s : %x:%p\n", i, node->nodelist[i].nodename,
                            node->nodelist[i].ipaddr, node->nodelist[i].port);
            }
    
            ...
    
            struct svglist *svg = tpgetsvglist_bynode(node->nodelist[1].nodename, svcname, 0);
            if (svg == NULL)
               ...error process
    
            for (i = 0; i < svg->ns_entry; i++) {
                    printf("[%d] %d(%x)\n", i, svg->s_list[i], svg->s_list[i]);
            }
    
            ...
    
            tpreturn(TPSUCCESS,0,(char *)msg->data, msg->len,0);
    }
  • Related function

    tpgetnodelist()

1.62. tpgprio

The tpgprio function retrieves the priority of a service request. On the client side, tpgprio() returns the priority of the last sent request. On the server side, tpgprio() returns the priority of the last received request. This function can be used in both client and server programs.

tpgprio() may be called after tpcall(), in which case it returns the priority of the request that was sent. It may also be called within a service routine to check the priority of an incoming request. Priority indicates the precedence of a request message and can range from 0 to 100. The default value for each service is 50. By using tpsprio() and tpgprio(), a user can control the service priority of request messages.

  • Prototype

    #include <tuxfatmi.h>
    int tpgprio (void)
  • Return Value

    Value Description

    Priority

    The function call succeeded. The service priority is returned.

    -1

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

  • Errors

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

    Error Code Description

    [TPENOENT]

    No request was received after tpgprio() was called, or it was called in an interactive service that sent no request.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    SERVICE(TPSVCINFO *msg)
    {
        int ret, prio;
        prio = tpgprio();
        if (prio==-1) {
            error processing......
         }
        if (prio > 50)
            tpforward(“SERVICE1”, msg->data, msg->len, 0);
        else
            tpforward(“SERVICE2”, msg->data, msg->len, 0);
    }
  • Related functions

    tpacall(), tpcall(), tpsprio()

1.63. tpmcall

In a Tmax environment containing server groups that belong to a COUSIN server group, the tpcall() function calls services within a single server group using Tmax routing. In contrast, tpmcall() calls services across all server groups that belong to the same cousin server group. Thus, a client performs a multicast when invoking a tpmcall().

Calling tpmcall() is similar to calling tpacall(…​, TPNOREPLY) for server groups within a cousin, because tpmcall() does not participate in transactions.

  • Prototype

    #include <tmaxapi.h>
    struct svglist *tpmcall(char *qname, char *svc, char *data, long len, long flags)
  • Parameter

    Parameter Description

    qname

    If a qname is set, tpmcall() requests a service through the RQ. Not supported in this version of Tmax.

    svc, data, len

    Identical to parameters used in a tpcall().

    flags

    Not currently supported. Set to TPNOFLAGS.

  • Return Value

    When an error occurs, tpmcall() will return NULL and an error code is set in tperrno. Otherwise, a list of server groups that failed to be called will be returned in the svglist struct.

    The following will be returned:

    struct svglist {
        int ns_entry;
        int nf_entry;
        int *s_list;
        int *f_list;
    };
    Member Description

    ns_entry

    The number of server groups successfully called.

    nf_entry

    The number of server groups that failed to be called.

    s_list

    A pointer to the serial numbers of server groups successfully called. nf_entry and f_list are used for different purposes. nf_entry is set to 0, and f_list is set to NULL.

    f_list

    A pointer to the serial numbers of server groups that failed to be called.

  • Errors

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

    Error Code Description

    [TPEINVAL]

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

    [TPENOENT]

    The specified qname has not been registered in Tmax.

    [TPEITYPE]

    The type or subtype of the data is not supported by svc.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system. Most typically due to memory allocation failure.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    
    main(int argc, char *argv[])
    {
        char    *sndbuf;
        int     ret;
        …
    
        ret = tpstart((TPSTART_T *)NULL);
        if (ret == -1){  error processing }
    
        sndbuf = (char *)tpalloc(“STRING”, NULL, 0);
        if (sndbuf == NULL){ error processing }
    
        ret = tpmcall(NULL, “TPMCALL”, sndbuf, 0, TPNOFLAGS);
        if (ret == NULL){  error processing  }
        …
    }
  • Related functions

    tpcall(), tpgetsvglist(), tpmcallx()

1.64. tpmcallx

The tpmcallx function is an API designed to support the extended features of tpmcall(). Unlike the original function, tpmcallx waits until responses from all services in a COUSIN server group are received.

The r_list has been added to the svglist structure to store responses indicating successes and failures. Additionally, several new flags have been introduced to control the behavior of the call.

  • Prototype

    #include <usrinc/tmaxapi.h>
    struct svglistx* tpmcallx(char *svc, char *data, long len, long flags)
  • Parameter

    Parameter Description

    svc

    The name of the service to call. It must be provided by a Tmax application server program.

    data

    A pointer to a buffer allocated by tpalloc(). The buffer type and subtype must be supported by the svc.

    len

    The length of the data to be sent.

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

    If data is NULL, len is ignored.

    flags

    Specifies the communication mode to call the function. (Optional)

    The following flags are available.

    • TPNOREPLY

      Only sends data. With this flag set, tpmcall() behaves the same as in the older version.

    • TPBLOCK

      Checks if the data sent successfully reached the CLH.

    • TPNOTIME

      Ignores the block timeout and waits for the response indefinitely.

  • Return Value

    When an error occurs, tpmcallx() will return NULL and an error code is set in tperrno. Otherwise, a list of server groups that failed to be called will be returned in the svglist struct.

    The following shows the the svglist struct.

    struct svglistx {
         int ns_entry; /* number of entries of s_list */
         int nf_entry; /* number of entries of f_list */
         int nr_entry; /* number of entries of r_list */
         int *s_list; /* list of server group numbers */
         int *f_list; /* list of tperrno of each server group */
         int *r_list; /* list of tpurcode of each server group */
    };
    Member Description

    ns_entry

    The number of server groups successfully called.

    nf_entry

    The number of server groups that failed to be called.

    nr_entry

    The number of server groups where the r_list was specified.

    s_list

    A pointer to the serial numbers of server groups successfully called.

    f_list

    A pointer to the serial numbers of server groups that failed to be called.

    r_list

    A pointer to the serial numbers of server groups in which a tpurcode is specified.

  • Errors

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

    Error Code Description

    [TPEINVAL]

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

    [TPENOENT]

    The specified qname has not been registered in Tmax.

    [TPEITYPE]

    The type or subtype of the data is not supported by svc.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system. Most typically due to memory allocation failure.

  • Example

    #include <stdio.h>
    #include <unistd.h>
    #include <stdlib.h>
    #include <string.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    main(int argc, char *argv[])
    {
         char *sndbuf, *rcvbuf;
         long rcvlen, sndlen;
         struct svglistx svglist;
         struct svglistx *psvglist;
         int ret, i;
    
         psvglist = &svglist;
         if (argc != 2) {
              printf("Usage: toupper string\n");
              exit(1);
         }
    
         if ( (ret = tmaxreadenv( "tmax.env","TMAX" )) == -1 ){
              printf( "tmax read env failed\n" );
              exit(1);
         }
    
         if (tpstart((TPSTART_T *)NULL) == -1){
              printf("tpstart failed[%s]\n",tpstrerror(tperrno));
              exit(1);
         }
    
         if ((sndbuf = (char *)tpalloc("STRING", NULL, 0)) == NULL)
         {
              printf("sendbuf alloc failed !\n");
              tpend();
              exit(1);
         }
    
         if ((rcvbuf = (char *)tpalloc("STRING", NULL, 0)) == NULL)
         {
              printf("recvbuf alloc failed !\n");
              tpfree((char *)sndbuf);
              tpend();
              exit(1);
         }
    
         strcpy(sndbuf, argv[1]);
         psvglist = tpmcallx("TOUPPER", sndbuf, 0, TPBLOCK);
         if(psvglist == NULL)
         {
              printf("tpmcall is failed[%s]\n",
              tpstrerror(tperrno));
              tpfree((char *)sndbuf);
              tpfree((char *)rcvbuf);
              tpend();
              exit(1);
         }
    
         printf("send data: %s\n", sndbuf);
         printf("ns_entry = %d\n", psvglist->ns_entry);
         printf("nf_entry = %d\n", psvglist->nf_entry);
         printf("nr_entry = %d\n", psvglist->nr_entry);
    
         for(i=0; i<psvglist->ns_entry; i++)
              printf("psvglist->s_list[%d] = %d\n", i, psvglist->s_list[i]);
         for(i=0; i<psvglist->nf_entry; i++)
              printf("psvglist->f_list[%d] = %d\n", i, psvglist->f_list[i]);
         for(i=0; i<psvglist->nr_entry; i++)
              printf("psvglist->r_list[%d] = %d\n", i, psvglist->r_list[i]);
    
         tpfree((char *)sndbuf);
         tpfree((char *)rcvbuf);
         tpend();
    }
  • Related functions

    tpcall(), tpgetsvglist(), tpmcall()

1.65. tpnotify

The tpnotify function sends an unsolicited message to a specified client from a server.

  • Prototype

    #include <atmi.h>
    int tpnotify(CLIENTID *id, char *data, long len, long flags);
  • Parameter

    Parameter Description

    id

    A pointer to a client ID saved in the TPSVCINFO struct.

    data

    A pointer to the buffer that must be allocated in advance by tpalloc().

    len

    The length of the 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, the 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, the len cannot be 0.

    flags

    The following flags are available.

    • TPACK

      The buffer must be allocated by a tpalloc().

    • TPNOBLOCK

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

    • TPNOTIME

      The caller waits indefinitely for a response, ignoring the block timeout. However, if WinTmaxSend() is called within the transaction timeout period, the timeout still applies.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid.

    [TPENOENT]

    The target client does not exist, or the unsolicited message handler has not been set.

    [TPETIME]

    A timeout occurred. If the caller is in transaction mode, a transaction timeout occurs and the transaction is rolled back. If the caller is not in transaction mode while neither TPNOTIME nor TPNOBLOCK is set, a block timeout occurs.

    [TPEPROTO]

    tpnotify() was called under an inappropriate condition.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/fbuf.h>
    #include “../fdl/demo_fdl.h”
    
    TOUPPER(TPSVCINFO* msg) {
        int i, n;
        char    rdata[100];
        FBUF    *stdata;
    
        stdata=(FBUF *)msg->data;
        memset(rdata, 0x00, sizeof(rdata));
        if (fbget(stdata, INPUT, rdata, 0) == -1){
        printf(“fbget failed errno = %d\n”, fberror);
        }
    
        for (i = 0; i < msg->len; i++) {
            rdata[i] = toupper(rdata[i]);
        }
        if (fbput(stdata, OUTPUT, rdata, 0) == -1)
            printf(“fbput failed\n”);
    
        i = tpnotify(&(msg->cltid), (char*)stdata, 0, TPACK);
        printf(“i= %d\n”, i);
        tpreturn(TPSUCCESS, 0, (char *)stdata, 0, 0);
    }

1.66. tppost

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

  • Prototype

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

    Parameter Description

    eventname

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

    data

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

    len

    The length of the message buffer to send.

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

    flags

    Only TPNOTIME is used.

  • Return Value

    Value Description

    Positive

    The function call succeeded.

    Negative

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

  • Errors

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

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

    [TPEINVAL]

    An incorrect parameter was used.

    [TPENOENT]

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

    [TPEPROTO]

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

    [TPETIME]

    A timeout occurred.

  • Related functions

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

1.67. tpputenv

The tpputenv function applies a name=value string to the process environment variables. If the specified variable already exists, its value is modified; otherwise, a new environment variable is created.

This function is equivalent to putenv() and is available both on clients and servers. The change affects only the current process and any child processes it creates. It does not update permanent configuration files (such as autoexec.bat on Windows or shell configuration files on UNIX).

  • Prototype

    #include <tmaxapi.h>
    int tpputenv(char *string)
  • Parameter

    Parameter Description

    string

    The value to be set to the environment variable. ("name=value")

  • Return Value

    Value Description

    0

    The function call succeeded.

    Negative

    The function call failed. This typically occurs when there is insufficient memory to store the specified environment variable.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    void main(int argc, char *argv[])
    {
        int ret;
        char *SDLFI;
    
        SDLFI=tpgetenv(“SDLFILE”);
        if (SDLFI=NULL) ret=tpputenv(“SDLFILE=/tmax/sample/sdl/test.sdl”);
        if (ret<0) { error processing }
    
        SDLFI=tpgetenv(“SDLFILE”);
        printf (“tmax sdlfile : %s\n”,SDLFI);
    }
  • Related function

    tpgetenv()

1.68. tpqstat

The tpqstat function retrieves the data statistics accumulated in the current RQ. This function is available both on servers and clients. A RQ internally consists of three queues: _fail queue, _request queue, and _reply queue. tpqstat( ) can get the data statistics stored in each of these queues, by using a flag value.

  • Prototype

    # include  <tmaxapi.h>
    int  tpqstat (char *qname, long  flags)
  • Parameter

    Parameter Description

    qname

    The name of the RQ registered in the Tmax configuration file.

    flags

    The type of the data statistics to retrieve.

    The following flags are available.

    • 0(TMAX_ANY_QUEUE)

      Retrieves all data statistics of _fail queue, _request queue, and _reply queue.

    • 1(TMAX_FAIL_QUEUE)

      Retrieves data statistics of _fail queue.

    • 2(TMAX_REQ_QUEUE)

      Retrieves data statistics of _request queue.

    • 3(TMAX_RPLY_QUEUE)

      Retrieves data statistics of _reply queue.

  • Return Value

    Value Description

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    The parameter is not valid. For example, the qname is NULL, no queue specified by the qname exists, or an invalid flag is set.

    [TPEPROTO]

    tpqstat() was called under an inappropriate condition.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    void main(int argc, char *argv[])
    {
        int ret, i;
        char *buf;
    
        if (argc!=2) { error processing }
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) {error processing }
    
        buf = (char *)tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processing }
        strcpy(buf, argv[1]);
    
        data process…
    
        ret=tpenq(“RQ”, NULL, (char *)buf, strlen(buf), TPRQS);
        if (ret==-1) {error processing }
        printf(“qstat :”);
        for (i=0;i<4;i++) {
            ret=tpqstat(“rq”, i);
            if (ret==-1) {error processing }
            printf(“  %d”,ret);        /* qstat :  1  0  0  1 */
        }
        printf(“\n”);
        data process…
    
        ret=tpenq(“RQ”, “SERVICE”, (char *)buf, strlen(buf), TPRQS);
        if (ret==-1) {error processing }
        printf(”qstat :”);
    
        for (i=0;i<4;i++) {
            ret=tpqstat(“rq”, i);
            if (ret==-1) {error processing }
            printf(”  %d”,ret);        /* qstat :  2  0  0  2 */
    
        }
        printf(“\n”);
        tpfree((char *)buf);
        tpend();
    }
  • Related functions

    tpenq(), tpdeq()

1.69. tpqsvcstat

The tpqsvcstat function retrieves the data statistics for a specific service stored in the current RQ. This function is available both on servers and clients. A RQ internally consists of three queues: _fail queue, _request queue, and _reply queue. tpqsvcstat( ) can get the data statistics stored in each of these queues, by using a flag value.

  • Prototype

    # include  <tmaxapi.h>
    int  tpqsvcstat (char *qname, char * svc, long  flags )
  • Parameter

    Parameter Description

    qname

    The name of the RQ registered in the Tmax configuration file.

    svc

    The name of the service for which to retrieve statistics. If set to NULL, the function behaves like tpqstat().

    flags

    The type of the data statistics to retrieve.

    The following flags are available.

    • 0(TMAX_ANY_QUEUE)

      Retrieves all data statistics of _fail queue, _request queue, and _reply queue.

    • 1(TMAX_FAIL_QUEUE)

      Retrieves data statistics of _fail queue.

    • 2(TMAX_REQ_QUEUE)

      Retrieves data statistics of _request queue.

    • 3(TMAX_RPLY_QUEUE)

      Retrieves data statistics of _reply queue.

  • Return Value

    Value Description

    A value other than -1

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    The parameter is not valid. For example, the qname is NULL, no queue specified by the qname exists, or an invalid flag is set.

    [TPEPROTO]

    tpqscvstat() was called under an inappropriate condition.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Related functions

    tpenq(), tpdeq(), tpqstat()

1.70. tprealloc

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

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

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

  • Prototype

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

    Parameter Description

    ptr

    A pointer to a buffer to be allocated.

    size

    The size of a buffer to be allocated.

  • Return Value

    Value Description

    Buffer pointer

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

    NULL

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

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

    [TPEPROTO]

    tprealloc() was called under an inappropriate condition.

    [TPENOENT]

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

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    void main(int argc, char *argv[])
    {
        char *buf;
        buf=tpalloc(“STRING”,NULL,10);
        if (buf==NULL) { error processing }
        buf=tprealloc(buf,20);  /* ok */
        if (buf==NULL) { error processing }
    
        buf=”test”;
        buf=tprealloc(buf,30);  /*error : TPEINVAL */
        if (buf==NULL) { error processing }
    }
  • Related functions

    tpalloc(), tpfree(), tptypes()

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

1.71. tprecv

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

  • Prototype

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

    Parameter Description

    cd

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

    data

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

    len

    The length of the data.

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

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

    flags

    The following flags are available.

    • TPNOCHANGE

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

    • TPNOBLOCK

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

    • TPNOTIME

      The caller waits indefinitely for a response, ignoring the block timeout. However, if tprecv() is called within the transaction timeout period, the timeout still applies.

    • TPSIGRSTRT

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

    revent

    The following describes event types that are returned to revent:

    • TPEV_DISCONIMM

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

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

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

    • TPEV_SENDONLY

      The peer program has relinquished control over the communication.

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

    • TPEV_SVCERR

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

    • TPEV_SVCFAIL

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

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

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

    • TPEV_SVCSUCC

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

  • Return Value

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

  • Errors

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

    Error Code Description

    [TPEBADDESC]

    The descriptor (CD) is invalid.

    [TPEBLOCK]

    A blocking condition occurred while TPNOBLOCK is set.

    [TPEEVENT]

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

    [TPEINVAL]

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

    [TPEOS]

    An error occurred in the operating system.

    [TPEOTYPE]

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

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

    [TPEPROTO]

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

    [TPESYSTEM]

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

    [TPETIME]

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

    [TPGOTSIG]

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

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include “../sdl/demo.s”
    
    main(int argc,char* argv[])
    {
        int ret, cd;
        struct dat *buf;
        long revent, len;
    
        if (argc!=3) {error processing }
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf=(struct dat *)tpalloc(“STRUCT”, “dat”, 0);
        if (buf==NULL) { error processing }
        strcpy(buf->sdata, argv[1]);
        data process….
    
        cd=tpconnect(“SERVICE”, buf, 0, TPSENDONLY);
        if (cd==-1) { error processing }
        strcpy(buf->sdata, argv[2]);
        data process….
    
        ret=tpsend(cd, buf, 0,TPRECVONLY,&revent);
        if (ret==-1) { error processing }
    
        ret=tprecv(cd,(char**)&buf,&len,TPNOTIME,&revent);
        if (ret==-1) { error processing }
        data process....
    
        tpfree(buf);
        tpend();
    }
  • Related functions

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

1.72. tpreissue

The tpreissue function reissues a request from the fail queue of the RQ. It can be used on both clients and servers.

If a service fails due to a network error or a server-side failure while processing RQ-based services via tpenq(), the request is stored in the fail queue. The tpreissue() function requeues the failed request, allowing it to be processed again. Once requeued, the data in the request queue is sent to the appropriate service, and the results are returned to the reply queue.

  • Prototype

    #include <tmaxapi.h>
    int  tpreissue(char *qname, char *filter, long flags)
  • Parameter

    Parameter Description

    qname

    The name of the RQ registered in the Tmax system.

    filter

    Currently not supported. Must be set to NULL.

    flags

    Currently not supported. Only TPNOFLAGS is available.

  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the qname is NULL, the filter is unsupported, or an invalid flag is set.

    [TPENOENT]

    No RQ exists for the specified qname.

    [TPESYSTEM]

    An error occurred in the Tmax system, typically due to a network failure.

  • Related functions

    tpenq(), tpdeq()

1.73. tpremoteconnect

The tpremoteconnect function establishes a connection to a remote node via TCP. It attempts to connect within the specified time period (in seconds). If the time elapses before the connection is established, a connection error occurs.

  • Prototype

    #include <ucs.h>
    int tpremoteconnect(char *host, int portno, int sec)
  • Return Value

    Value Description

    0

    Socket number.

    -1

    The function call failed, and an error code corresponding to the condition is set in tperrno.

1.74. tpscmt

The tpscmt function changes the commit settings in the configuration file. This function is available both on servers and clients.

  • Prototype

    # include <tuxatmi.h>
    int  tpscmt(long  flags)
  • Parameter

    Parameter Description

    flags

    Input options:

    • 1: Sets transaction control to TP_CMT_LOGGED.

    • 2: Sets transaction control to TP_CMT_COMPLETE.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed.

  • Example

    #include <stdio.h>
    #include <usrinc/tuxatmi.h>
    
    int main(int argc, char *argv[])
    {
        ...
        ret = tpstart((TPSTART_T *)NULL);
        if (ret == -1) {
            error processing
        }
        ...
        ret = tpscmt(TP_CMT_COMPLETED);
        if (ret < 0){
            error processing
        }
    
        ret = tpbegin();
        if (ret < 0){
            error processing
        }
        ...
        ret= tpcall(“SERVICE1”,(char*)buf, strlen(buf),(char **)&get,&rlen,TPNOFLAGS);
        if (ret == -1)
        {
            error processing
        }
        ...
        ret= tpcall(“SERVICE2",(char*)buf,strlen(buf),(char **)&get,&rlen,TPNOFLAGS);
        if (ret == -1)
        {
            error processing
        }
    
        ret = tpcommit();
        if (ret < 0) {
            error processing
        }
        ...
    }

1.75. tpsend

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

  • Prototype

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

    Parameter Description

    cd

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

    data

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

    len

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

    flags

    The following flags are available.

    • TPNOBLOCK

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

    • TPNOTIME

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

    • TPRECVONLY

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

    • TPSIGRSTRT

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

    revent

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

    The following events can be returned in revent.

    • TPEV_DISCONIMM

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

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

    • TREV_SVCERR

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

    • TREV_SVCFAIL

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

  • Return Value

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

    Value Description

    0

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

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

    [TPEBADDESC]

    The descriptor (CD) is invalid.

    [TPETIME]

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

    [TPEEVENT]

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

    [TPEBLOCK]

    A blocking condition occurred while TPNOBLOCK is set.

    [TPGOTSIG]

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

    [TPEPROTO]

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

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include “../sdl/demo.s”
    
    main(int argc,char* argv[])
    {
        int ret, cd;
        struct dat *buf;
        long revent, len;
    
        if (argc!=3) {error processing }
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf=(struct dat *)tpalloc(“STRUCT”, “dat”, 0);
        if (buf==NULL) { error processing }
        strcpy(buf->sdata, argv[1]);
        data process….
    
        cd=tpconnect(“SERVICE”, buf, 0, TPSENDONLY);
        if (cd==-1) { error processing }
        strcpy(buf->sdata, argv[2]);
        data process….
    
        ret=tpsend(cd, buf, 0,TPRECVONLY,&revent);
        if (ret==-1) { error processing }
    
        ret=tprecv(&cd,(char**)&buf,&len,TPNOTIME,&revent);
        if (ret==-1) { error processing }
        data process....
    
        tpfree(buf);
        tpend();
    }
  • Related functions

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

1.76. tpset_timeout

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

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

  • Prototype

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

    Parameter Description

    sec

    The block timeout in seconds.

  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    void main(int argc, char *argv[])
    {
        int ret;
        char *sndbuf, *rcvbuf;
        long sndlen,  rcvlen;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        sndbuf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (sndbuf==NULL) {error processing };
        rcvbuf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (rcvbuf==NULL) {error processing };
        data process....
    
        sndbuf=strlen(sndbuf);
        ret=tpset_timeout(4);
        if (ret==-1) { error processing }
    
        ret=tpcall(“SERVICE”, sndbuf, sndlen, &rcvbuf, &rcvlen, TPNOCHANGE);
        if (ret==-1) { error processing }
        data process....
    
        tpfree((char *)sndbuf);
        tpfree((char *)rcvbuf);
        tpend();
    }

1.77. tpsetfd

The tpsetfd function registers a socket file descriptor (fd) in the external socket scheduler of a UCS process. It is used when a UCS-type process manages user-defined sockets.

A UCS scheduler monitors both messages received on a socket fd and messages from TMM and CLH. If a message is received on a user-defined socket, tpschedule() returns a normal result (UCS_USER_MSG) without requiring an additional process. To determine which socket received the message, tpistfd() must be used.

  • Prototype

    #include <ucs.h>
    int  tpsetfd (int  fd)
  • Parameter

    Parameter Description

    fd

    The socket fd to register.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <sys/socket.h>
    #include <netinet/in.h>
    #include <errno.h>
    #include <usrinc/ucs.h>
    ...
    #define SERV_ADDR “168.126.185.129”
    #define SERV_PORT 1500
    
    int fd_read(int, char *, int);
    extern int errno;
    
    int usermain(int argc, char *argv[])
    {
        ...
        int listen_fd, n, newfd;
        struct sockaddr_in my_addr, child_addr;
        socklen_t child_len;
        buf = tpalloc(“STRING”, NULL, 0);
        if (buf == NULL){
            error processing
        }
    
        memset((void *)&my_addr, NULL, sizeof(my_addr));
        memset((void *)&child_addr, NULL, sizeof(child_addr));
        listen_fd = socket(AF_INET, SOCK_STREAM, 0);
        if (listen_fd == -1){
            error processing
        }
    
        my_addr.sin_family = AF_INET;
        inaddr = inet_addr(SERV_ADDR);
        my_addr.sin_port = htons((unsigned short)SERV_PORT);
    
        if (inaddr != -1){
            memcpy((char *)&my_addr.sin_addr, (char *)&inaddr, sizeof(inaddr));
        }
        ret = bind(listen_fd, (struct sockaddr *)&my_addr, sizeof(my_addr));
        if (ret == -1){
            error processing
        }
        ret = listen(listen_fd, 5);
        if (ret == -1){
            error processing
        }
    
        ret = tpsetfd(listen_fd);
        if (ret == -1){
            error processing
        }
        ...
    
        while(1) {
            n = tpschedule(10);
            ...
            if (n == UCS_USER_MSG){
                if (tpissetfd(listen_fd)) {
                    child_len = sizeof(child_addr);
                    newfd = accept(listen_fd, &child_addr, &child_len);
                    if (newfd == -1){
                        error processing
                    }
    
                ret = tpsetfd(newfd);
                if (ret == -1){
                    error processing
                }
            }
    
            if (tpissetfd(newfd)){
                /* Read the buffer from the socket */
                fd_read(newfd, buf, 1024);
                ret = tpcall(“SERVICE”, (char *)buf, sizeof(buf), (char **)&buf,
                               (long *)&rlen, TPNOFLAGS);
                if (ret == -1){
                    error processing
                }
                ...
                tpclrfd(newfd);
                close(newfd);
            }
            ...
        }
        return 1;
    }
  • Related functions

    tpclrfd(), tpissetfd()

1.78. tpsleep

The tpsleep function suspends execution and waits for data. It sleeps for up to the specified timeout period and returns immediately if data arrives before the timeout expires. This function can be used on both servers and clients.

  • Prototype

    #include <tmaxapi.h>
    int  tpsleep (struct  timeval  *timeout)
  • Parameter

    The timeout is a pointer to a timeval structure, defined in <sys/time.h> on UNIX systems). The structure is as follows:

    struct timeval{
          long    tv_sec    /* seconds unit */
          long    tv_usec  /* 0.000001 (micro seconds) unit */
    };
  • Return Value

    Value Description

    Positive integer

    Data arrived within the timeout period.

    0

    No data arrived within the timeout period.

    -1

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

  • Errors

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    void main(int argc, char *argv[])
    {
        int ret, cd;
        char *buf;
    
        struct timeval sl_time, *sleep;
        sl_time.tv_sec =3;
        sl_time.tv_usec=500000;
        sleep=&sl_time;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (buf==NULL)
           {error processing };
        data process....
    
        cd=tpacall(“SERVICE”, buf, 20, TPNOFLAGS);
        if (cd==-1)
           { error processing }
    
        ret=tpsleep(sleep); /* Wait for 3.5 seconds */
        if (ret==-1)
           { error processing }
        if (ret==0)
           printf(“waited 3.5sec\n”);
    
        ret=tpgetrply(&cd, &buf, &len, TPNOTIME);
        if (ret==-1)
            { error processing }
        data process....
    
        tpfree((char *)buf);
        tpend();
    }
  • Related functions

    tp_sleep(), tp_usleep(), tpacall(), tpbroadcast(), tpgetrply()

1.79. tpspracall

The tpspracall function calls a service on a specific server process, selected from the indexes returned by tpgetsprlist(). In asynchronous communication, if the TPBLOCK flag is not set, it sends the message and returns immediately without waiting for the result. If requests are queued, they wait in the CLH queue.

The result can later be received through tpgetrply(), or the request can be canceled using tpcancel(). This function is not supported for servers of type DYN or for servers with the MULTICLH=N setting.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tpspracall(char *svcname, int spri, char *data, long lenl, long flagsl);
  • Parameter

    Parameter Description

    svcname

    The name of the service to send data to.

    spri

    The number of the process to send data to.

    data

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

    lenl

    The length of the data to send.

    flagsl

    The following flag is available.

    • TPBLOCK

      Waits for the response after calling tpspracall.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPENOENT]

    No server process was found for the specified index.

    [TPESYSTEM]

    An error occurred in the Tmax system.

    [TPEOS]

    An error occurred in the operating system.

    [TPEPROTO]

    A service request was sent to a server with the CONV=Y setting in CLH, or a server with the MULTICLH=N setting, and the CLH that received the request was not connected to the server corresponding to the spri given as the argument. This error may also occur if the server type is DYN.

    [TPENOREADY]

    The server corresponding to the spri given as the argument was NOT_READY.

  • Example

    ...
    main(int argc, char *argv[])
    {
        char    *sndbuf, *rcvbuf;
        long    sndlen, rcvlen;
        int     ret, cd;
        int     starti = 0, endi = 0, spri = 0;
        if (argc != 2) {
            printf(“Usage: argv[1] string\n”);
            exit(1);
        }
    
        if ( (ret = tmaxreadenv( “tmax.env”,”TMAX” )) == -1 ){
            printf(“<%-15s> tmaxreadenv fail [%s]”, __FILE__, tpstrerror(tperrno));
            exit(1);
        }
    
        if (tpstart((TPSTART_T *)NULL) == -1){
            printf(“<%-15s> tpstart fail [%s]”, __FILE__, tpstrerror(tperrno));
            exit(1);
        }
    
        if ((sndbuf = (char*)tpalloc(“CARRAY”, 0, 0)) == NULL) {
            printf(“<%-15s> sndbuf tpalloc fail [%s]”, __FILE__, tpstrerror(tperrno));
            exit(1);
        }
    
        if ((rcvbuf = (char*)tpalloc(“CARRAY”, 0, 0)) == NULL) {
            printf(“<%-15s> sndbuf tpalloc fail [%s]”, __FILE__, tpstrerror(tperrno));
            tpfree((char*)sndbuf);
            exit(1);
        }
    
        /* tpgetsprlist in client */
        ret = tpgetsprlist(argv[1], 2, &starti, &endi, 0);
        if (ret < 0) {
            printf(“<%-15s> tpgetsprlist fail [%s]”, __FILE__, tpstrerror(tperrno)
        );
        exit(1);
        } else {
            /*printf(“Received Message from Server :
             starti[%d], endi[%d]\n”, starti, endi);*/
        }
        strcpy((char*)sndbuf, “tpspracall test”);
    
        /* tpspracall in client */
        for(spri = starti; spri <= endi; spri++) {
            cd = tpspracall(argv[1], spri, sndbuf, strlen(sndbuf), 0);
            if(cd < 0) {
                printf(“<%-15s> tpsprcall fail [%s]”, __FILE__, tpstrerror(tperrno));
                exit(1);
            } else {
                ret = tpgetrply(&cd, &rcvbuf, &rcvlen, 0);
                if(ret < 0) {
                    printf(“Received Message from %d spri: tpgetrply fail[%s]\n”,
                             spri, tpstrerror(tperrno));
                } else {
                    printf(“Received Message from %d spri: msg[%s], len[%d]\n”,
                             spri, rcvbuf, rcvlen);
                }
            }
        }
        tpend();
    }

1.80. tpspracall2

The tpspracall2 function is an API designed to support the DYN type, and can also be used with STD and STD_DYN types. The function retrieves the start index from tpgetsprlist() to determine the SPR number order and calls the service on the specified server process.

If the TPBLOCK flag is not set during asynchronous communication, the function returns immediately after sending the message, without waiting for the result. Accumulated requests are queued in CLH.

The result can be retrieved later using tpgetrply(), or the response can be canceled using tpcancel(). This function is not supported for servers with 'MULTICLH=N' setting.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tpspracall2(char *svcname, int startspri, int nth, char *data, long lenl, long flagsl);
  • Parameter

    Parameter Description

    svcname

    The service to send data to.

    startspri

    The starti value retrieved through tpgetsprlist().

    nth

    The spri index.

    data

    Pointer to the service request data. The buffer must be allocated in advance by tpalloc(). The idata type and its subtype must be supported by the specified service (svc).

    lenl

    The length of the data to send.

    flagsl

    The following flag is available.

    • TPBLOCK

      Waits for the response after calling tpspracall.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPENOENT]

    No server process was found for the specified index.

    [TPESYSTEM]

    An error occurred in the Tmax system.

    [TPEOS]

    An error occurred in the operating system.

    [TPEPROTO]

    A service request was sent to a server with the CONV=Y setting in CLH, or a server with the MULTICLH=N setting, and the CLH that received the request was not connected to the server corresponding to the spri given as the argument.

    [TPENOREADY]

    The server corresponding to the spri given as the argument was NOT_READY.

  • Example

    ...
    main(int argc, char *argv[])
    {
        char    *sndbuf, *rcvbuf;
        long    sndlen, rcvlen;
        int     ret, cd;
        int     starti = 0, endi = 0, spri = 0;
        if (argc != 2) {
            printf(“Usage: argv[1] string\n”);
            exit(1);
        }
    
        if ( (ret = tmaxreadenv( “tmax.env”,”TMAX” )) == -1 ){
            printf(“<%-15s> tmaxreadenv fail [%s]”, __FILE__, tpstrerror(tperrno));
            exit(1);
        }
    
        if (tpstart((TPSTART_T *)NULL) == -1){
            printf(“<%-15s> tpstart fail [%s]”, __FILE__, tpstrerror(tperrno));
            exit(1);
        }
    
        if ((sndbuf = (char*)tpalloc(“CARRAY”, 0, 0)) == NULL) {
            printf(“<%-15s> sndbuf tpalloc fail [%s]”, __FILE__, tpstrerror(tperrno));
            exit(1);
        }
    
        if ((rcvbuf = (char*)tpalloc(“CARRAY”, 0, 0)) == NULL) {
            printf(“<%-15s> sndbuf tpalloc fail [%s]”, __FILE__, tpstrerror(tperrno));
            tpfree((char*)sndbuf);
            exit(1);
        }
    
        /* tpgetsprlist in client */
        ret = tpgetsprlist(argv[1], 2, &starti, &endi, 0);
        if (ret < 0) {
            printf(“<%-15s> tpgetsprlist fail [%s]”, __FILE__, tpstrerror(tperrno)
        );
        exit(1);
        } else {
            /*printf(“Received Message from Server :
             starti[%d], endi[%d]\n”, starti, endi);*/
        }
        strcpy((char*)sndbuf, “tpspracall test”);
    
        /* tpspracall2 in client */
        cd = tpspracall2(argv[1], starti, 2, send_data, send_len, TPNOFLAGS);
        if(cd < 0) {
            printf(“<%-15s> tpsprcall fail [%s]”, __FILE__, tpstrerror(tperrno));
            exit(1);
        } else {
            ret = tpgetrply(&cd, &rcvbuf, &rcvlen, 0);
            if(ret < 0) {
                printf(“Received Message from %d spri: tpgetrply fail[%s]\n”,
                         spri, tpstrerror(tperrno));
            } else {
                printf(“Received Message from %d spri: msg[%s], len[%d]\n”,
                         spri, rcvbuf, rcvlen);
            }
        }
        tpend();
    }

1.81. tpsprio

The tpsprio function sets the priority for subsequent tpacall() requests. It is available on both servers and clients. The specified priority affects only requests sent after the function is called.

A priority indicates the service precedence of a request message and can range from 0 to 100. The default priority for each service is 50.

By using tpsprio() and tpgprio(), users can control the service priority of request messages.

  • Prototype

    #include <tuxatmi.h>
    int tpsprio (int prio, long flags)
  • Parameter

    Parameter Description

    prio

    Any integer value between -50 and +50. The specified prio value plus the current priority will be used for the subsequent request.

    flags

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

  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    void main(int argc, char *argv[])
    {
        int ret;
        char *buf;
        long len;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf = (char *)tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) {error processing };
        ret=tpsprio(30,0);
        if (ret==-1) { error processing }
    
        ret=tpcall(“SERVICE”, buf, 0, &buf, &len, TPNOFLAGS);
        if (ret==-1) { error processing }
    
        data process....
    
        ret=tpsprio(-20,0);
        if (ret==-1) { error processing }
    
        ret=tpcall(“SERVICE”, buf, 0, &buf, &len, TPNOFLAGS);
        if (ret==-1) { error processing }
        data process....
    
        tpfree(buf);
        tpend();
    }
  • Related functions

    tpacall(), tpcall(), tpgprio()

1.82. tpsetctxt

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

  • Client Program

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

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

  • Server Program

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

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

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

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

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

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

  • Prototype

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

    Parameter Description

    ctxtid

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

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

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

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

    flags

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

  • Return Value

    Value Description

    -1

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

  • Errors

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

    Error Code Description

    [TPEPROTO]

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

    [TPEINVAL]

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

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

    [TPENOENT]

    An invalid context was set to ctxtid.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    • Client program

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

      typedef param {
          int ctxtid;
          TPSVCINFO *svcinfo;
      } param_t;
      
      MSERVICE(TPSVCINFO *svcinfo)
      {
          pthread_t tid;
          param_t param;
      
          printf("MSERVICE service is started!");
          tpgetctxt(&param.ctxtid, TPNOFLAGS);
          param.svcinfo = svcinfo;
      
          pthread_create(&tid, NULL, THREAD_ROUTINE, &param);
          pthread_join(tid, NULL);
      
          printf("MSERVICE service is finished!");
          tpreturn(TPSUCCESS, 0, svcinfo->data, 0L, TPNOFLAGS);
      }
      
      void *THREAD_ROUTINE(void *arg)
      {
          param_t *param;
          TPSVCINFO *svcinfo;
      
          param = (param_t *)arg;
          svcinfo = param->svcinfo;
      
          if (tpsetctxt(param->ctxtid, TPNOFLAGS) == -1) {
              printf("tpsetctxt(%d) failed, [tperrno:%d]", param->ctxtid, tperrno);
              return NULL;
          }
      
          tpcall("MTOUPPER", sndbuf, 0, &rcvbuf, &rcvlen, TPNOFLAGS);
      
          if (tpsetctxt(TPNULLCONTEXT, TPNOFLAGS) == -1) {
              printf("tpsetctxt(TPNULLCONTEXT) failed, [tperrno:%d]", tperrno);
              return NULL;
          }
      
          return NULL;
      }
  • Related function

    tpgetctxt()

1.83. tpstrerror

The tpstrerror function displays a message corresponding to an error number. It is available on both servers and clients. When an error occurs while using Tmax APIs, the error code is stored in the global variable tperrno. The tpstrerror() function displays a message corresponding to the error code in tperrno.

  • Prototype

    # include <atmi.h>
    char *tpstrerror (int tperrno)
  • Parameter

    Parameter Description

    tperrno

    The error code for which the message will be displayed.

  • Return Value

    Value Description

    Error message

    A message corresponding to the error code, if available.

    NULL

    No message is available for the error code.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    
    void main(int argc, char *argv[])
    {
        int ret;
        char buf;
        TPSTART_T *tpinfo;
    
        tpinfo = (TPSTART_T *)tpalloc(“TPSTART”, NULL, sizeof(TPSTART_T));
    
        if (tpinfo==NULL) { error processing }
        strcpy(tpinfo->dompwd, “tuxedo”);
    
        if (tpstart(tpinfo) == -1){
            printf(“tpstart fail , err = %s\n”, tpstrerror(tperrno));
            exit(1);
        }
    
        buf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (buf==NULL) {error processing };
        data process....
    
        tpfree((char *) buf);
        tpend();
    }

1.84. tpsubqname

The tpsubqname function returns the queue name corresponding to the sub-queue number. It is available on both servers and clients.

  • Prototype

    # include <tmaxapi.h>
    char *tpsubqname(int type)
  • Parameter

    Parameter Description

    type

    Same as described in tpqstat() and tpqsvcstat(). Sub-queue numbers corresponding to the queue name:

    • 0 : RQ_ANY

    • 1 : RQ_FAIL

    • 2 : RQ_REQ

    • 3 : RQ_RPLY

  • Return Value

    Value Description

    Sub-queue name

    The sub-queue name corresponding to the specified sub-queue number.

    NULL

    No sub-queue name is found for the specified sub-queue number.

1.85. tpsubscribe

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

  • Prototype

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

    Parameter Description

    eventname

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

    filter

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

    ctl

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

    flags

    Only TPNOTIME is used.

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

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

    ctl_flags

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

    post_flags

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

    svc[XATMI_SERVICE_NAME_LENGTH]

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

    qname[RQ_NAME_LENGTH]

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

  • Return Value

    Value Description

    descriptor

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

    -1

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

  • Errors

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

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

    [TPEINVAL]

    An incorrect parameter was used.

    [TPENOENT]

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

    [TPEPROTO]

    CTL is not NULL in the client and server.

    [TPETIME]

    A timeout occurred.

  • Related functions

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

1.86. tptypes

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

  • Prototype

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

    Parameter Description

    ptr

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

    type, subtype

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

  • Return Value

    Value Description

    Buffer size

    The function call succeeded.

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

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

    [TPEPROTO]

    The function was called under an inappropriate condition.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include “../sdl/demo.s”
    main(int argc, char *argv[])
    {
        int ret;
        struct sel_o *rcvbuf;
        char type[9], subtype[17];
        long size;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
        buf=(struct sel_o*)tpalloc(“STRUCT”,”sel_o”,0);
        if (buf==NULL) {error processing };
    
        size =tptypes((char*)buf, type,subtype);
        if (size==-1) {error processing };
        printf (“buf : size %d, type %s, subtype %s\n\n”, size, type, subtype);
    
        /*rcvbuf : size 1024, type STRUCT, subtype sel_o */
        data process...
        tpfree((char *)buf);
        tpend();
    }
  • Related functions

    tpalloc(), tpfree(), tprealloc()

1.87. tpunsubscribe

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

  • Prototype

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

    Parameter Description

    sd

    The return value retrieved by tpsubscribe().

    flags

    Only TPNOTIME is used.

  • Return Value

    Value Description

    Positive

    The function call succeeded.

    Negative

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

  • Errors

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

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

    [TPEINVAL]

    An incorrect parameter was used.

    [TPETIME]

    A timeout occurred.

  • Related functions

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

1.88. tuxgetenv

The tuxgetenv function returns the value of an environment variable. In general, it is equivalent to the getenv() function that is used on servers. tuxgetenv() is available on both servers and clients.

On a client, the function returns a value registered in the autoexec.bat file. On a server, the function returns a value applied to each shell configuration file.

  • Prototype

    #include <tuxfml.h>
    char *tuxgetenv(char *name)
  • Parameter

    Parameter Description

    name

    The environment variable to retrieve.

  • Return Value

    Value Description

    Pointer to environment variable

    The specified variable exists.

    NULL

    The specified variable does not exist.

  • Example

    ...
    #include <tuxinc/tuxatmi.h>
    int main(int argc, char *argv[])
    {
        ...
        char hostAddr[20];
        ...
        memset(hostAddr, NULL, sizeof(hostAddr));
        memcpy(hostAddr, tuxgetenv(“TMAX_HOST_ADDR”), sizeof(hostAddr));
        printf(“host address = %s\n”, hostAddr);
        ...
    }
  • Related function

    tuxputenv()

1.89. tuxputenv

The tuxputenv function applies a string of the form name=value to an environment variable. This function is available on both servers and clients. It modifies an existing environment variable if one exists, or adds a new variable if none exists. This function is equivalent to putenv(), executable on the server side.

On a client, the value is applied to the autoexec.bat file. On a server, the value is applied to the relevant shell configuration file.

  • Prototype

    #include <tuxfml.h>
    int tuxputenv(char *string)
  • Parameter

    Parameter Description

    string

    The value to be set to the environment variable.

  • Return Value

    Value Description

    0

    The function call succeeded.

    Negative value

    Insufficient memory is available to store the environment variable.

  • Example

     ...
    #include <tuxinc/tuxatmi.h>
    int main(int argc, char *argv[])
    {
        ...
        char hostAddr[20];
        char envVal[20];
        ...
        ret = tuxputenv(“A=10”);
        if (ret < 0){
            printf(“tuxputenv fail...[%d]\n”, tperrno);
        }
        memset(envVal, NULL, sizeof(envVal));
        memcpy(envVal, tuxgetenv(“A”), sizeof(envVal));
        printf(“envVal = %s\n”, envVal);
        ...
    }
  • Related function

    tuxgetenv()

1.90. tuxreadenv

The tuxreadenv function retrieves environment variables from a file. It is available on both servers and clients. To access the Tmax system, the required environment variables must first be registered. By referencing these registered variables, a client can connect to the Tmax system using the tpstart() function.

On UNIX systems, environment variables are typically defined in .cshrc (for csh) or .profile (for ksh), while on DOS, they are defined in autoexec.bat. If a client needs to access multiple systems, it may choose which system to connect to depending on the situation. However, environment variables cannot hold information for more than one system simultaneously, so the client must register the variables in a separate file.

tuxreadenv() reads system access information from a file and sets the corresponding environment variables. This function should be called before accessing the Tmax system, ensuring that all required variables are properly set.

  • Prototype

    #include <tuxfml.h>
    int tuxreadenv (char *file, char *label)
  • Parameter

    Parameter Description

    file

    The name of the file containing the system access information. This file should be registered according to a prescribed text format.

    label

    The descriptor for the configuration information registered in the file. This value can be used to identify each system when two or more systems have been registered in a file.

  • Return Value

    Value Description

    1

    No data was received within the specified period of time in seconds.

    -1

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

  • Errors

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

    Error Code Description

    [TPEINVAL]

    No file or label exists.

  • Example

    ...
    #include <tuxinc/tuxatmi.h>
    int main(int argc, char *argv[])
    {
        ...
        ret = tuxreadenv( “tmax.env”,”TMAX” );
        if (ret == -1){
            error processing
        }
        ret = tpinit((TPINIT *)NULL);
        if (ret == -1){
            error processing
        }
        ...
        ret = tpcall(“SERVICE”, buf, 0, &buf, &rcvlen, TPNOFLAGS);
        if (ret == -1){
            error processing
        }
        ...
        tpterm();
    }
  • Related function

    tpstart()

For more information about how to register environment variables in a file, refer to Tmax Administration Guide.

1.91. tx_begin

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

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

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

  • Prototype

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

    Value Description

    TX_OK

    The function call succeeded.

    Negative value

    The function call failed.

  • Errors

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

    Error Code Description

    [TX_OUTSIDE]

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

    [TX_PROTOCOL_ERROR]

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

    [TX_ERROR]

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

    [TX_FAIL]

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

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tx.h>
    
    void main(int argc, char *argv[])
    {
        char *buf;
        int ret,cd;
        long len, revent;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (buf==NULL) {error processing };
    
        data process.…
    
        ret=tx_set_transaction_timeout( 5 );
        if (ret<0) { error processing }
    
        ret=tx_begin();
        if (ret<0) { error processing }
    
        cd = tpconnect(“SERVICE”, buf, 20, TPRECVONLY);
        if (cd==-1) { error processing }
    
        ret = tprecv(cd, (char **)&buf, &len,TPNOFLAGS, &revent)};
        if (ret < 0 && revent != TPEV_SVCSUCC)
            tx_rollback();
        else
            tx_commit();
    
        data process....
    
        tpfree((char *)buf);
        tpend();
    }
  • Related functions

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

1.92. tx_commit

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

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

  • Prototype

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

    Value Description

    TX_OK

    The function call succeeded.

    Negative value

    The function call failed and an error code is returned.

  • Errors

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

    Error Code Description

    [TX_NO_BEGIN]

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

    [TX_ROLLBACK]

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

    [TX_ROLLBACK_NO_BEGIN]

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

    [TX_HAZARD]

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

    [TX_HAZARD_NO_BEGIN]

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

    [TX_PROTOCOL_ERROR]

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

    [TX_FAIL]

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

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tx.h>
    
    void main(int argc, char *argv[])
    {
        char *buf;
        int ret,cd;
        long len, revent;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (buf==NULL) {error processing };
    
        data process.…
    
        ret=tx_set_transaction_timeout( 5 );
        if (ret<0) { error processing }
    
        ret=tx_begin();
        if (ret<0) { error processing }
    
        cd = tpconnect(“SERVICE”, buf, 20, TPRECVONLY);
        if (cd==-1) { error processing }
    
        ret = tprecv(cd, (char **)&buf, &len,TPNOFLAGS, &revent)};
        if (ret < 0 && revent != TPEV_SVCSUCC)
           tx_rollback();
        else
           tx_commit();
    
        data process....
        tpfree((char *)buf);
        tpend();
    }
  • Related functions

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

1.93. tx_info

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

  • Prototype

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

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

    The TXINFO structure is as follows.

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

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

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

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

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

  • Return Value

    Value Description

    1

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

    0

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

    Negative value

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

  • Errors

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

    Error Code Description

    [TX_PROTOCOL_ERROR]

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

    [TX_FAIL]

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

  • Example

    #include <stdio.h>
    #include <string.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tx.h>
    void main(int argc, char *argv[])
    {
        int ret;
        long len;
        char *buf;
        TXINFO info;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (buf==NULL) {error processing };
        data process....
        ret=tx_begin();
        if (ret<0) { error processing }
    
        ret=tpcall(“SERVICE”, buf, 20, (char **)&buf, &len, TPNOFLAGS);
        if (ret==-1) { error processing }
    
        if (tx_info(&info)==1) printf(“In transaction \n”);
        else printf(“Not in transaction \n”);
    
        if (strncmp(buf, “err”, 3)==0) tx_rollback();
        else  tx_commit();
    
        data process....
        tpfree((char *)buf);
        tpend();
    }
  • Related functions

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

1.94. tx_rollback

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

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

  • Prototype

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

    Value Description

    TX_OK

    The function call succeeded.

    Negative value

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

  • Errors

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

    Error Code Description

    [TX_NO_BEGIN]

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

    [TX_MIXED]

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

    [TX_MIXED_NO_BEGIN]

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

    [TX_HAZARD]

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

    [TX_HAZARD_NO_BEGIN]

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

    [TX_COMMITTED]

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

    [TX_COMMITTED_NO_BEGIN]

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

    [TX_PROTOCOL_ERROR]

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

    [TX_FAIL]

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

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tx.h>
    
    void main(int argc, char *argv[])
    {
        char *buf;
        int ret,cd;
        long len, revent;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (buf==NULL) {error processing };
        data process.…
        ret=tx_set_transaction_timeout( 5 );
        if (ret<0) { error processing }
    
        ret=tx_begin();
        if (ret<0) { error processing }
    
        cd = tpconnect(“SERVICE”, buf, 20, TPRECVONLY);
        if (cd==-1) { error processing }
        ret = tprecv(cd, (char **)&buf, &len,TPNOFLAGS, &revent)};
        if (ret < 0 && revent != TPEV_SVCSUCC)  tx_rollback();
        else    tx_commit();
        data process....
    
        tpfree((char *)buf);
        tpend();
    }
  • Related functions

    tx_begin(), tx_set_transaction_control(), tx_set_transaction_timeout()

1.95. tx_set_commit_return

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

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

  • Prototype

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

    Parameter Description

    when_return

    The following flags can be set.

    • TX_COMMIT_DECISION_LOGGED

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

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

    • TX_COMMIT_COMPLETED

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

  • Return Value

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

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

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

  • Errors

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

    Error Code Description

    [TX_EINVAL]

    when_return is not set to TX_COMMIT_COMPLETED or TX_COMMIT_DECISION_LOGGED.

    [TX_PROTOCOL_ERROR]

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

    [TX_FAIL]

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

  • Example

    #include <usrinc/tx.h>
    
    int main(int argc, char *argv[])
    {
        int ret;
        long len;
        char *buf;
    
        ret = tpstart((TPSTART_T *)NULL);
        if (ret == -1) { error processing }
    
        buf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (buf==NULL) {error processing };
        ret = tx_set_transaction_timeout(5);
        if (ret < 0){ error processing }
    
        ret = tx_set_commit_return(TX_COMMIT_COMPLETED);
        if (ret < 0){ error processing }
    
        ret = tx_begin();
        if (ret < 0){ error processing }
    
        data process....
        ret = tpcall(“SERVICE1”, (char *)buf, strlen(buf), (char **)&buf, &len,
                       TPNOFLAGS);
        if (ret == -1)
        {
            tx_rollback();
            error processing
        }
    
        data process...
        ret = tpcall(“SERVICE2”, (char *)buf, strlen(buf), (char **)&buf, &len,
                       TPNOFLAGS);
        if (ret == -1)
        {
            tx_rollback();
            error processing
        }
    
        data process ….
    
        ret = tx_commit();
        if (ret < 0) { error processing }
    
        data process...
    
        tpfree((char *)buf);
        tpend();
    }
  • Related functions

    tx_commit(), tx_open(), tx_info()

1.96. tx_set_transaction_control

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

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

  • Prototype

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

    Parameter Description

    control

    The following flags can be set.

    • TX_UNCHAINED

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

    • TX_CHAINED

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

  • Return Value

    Value Description

    TX_OK

    The function call succeeded.

    Negative value

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

  • Errors

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

    Error Code Description

    [TX_EINVAL]

    The control parameter was not set TX_UNCHAINED or TX_CHAINED.

    [TX_PROTOCOL_ERROR]

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

    [TX_FAIL]

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

  • Example

    #include <usrinc/atmi.h>
    #include <usrinc/tx.h>
    
    int main(int argc, char *argv[])
    {
        int ret;
        long len;
        char *buf;
    
        ret = tpstart((TPSTART_T *)NULL);
        if (ret == -1) { error processing }
    
        buf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (buf==NULL) {error processing };
        ret = tx_set_transaction_timeout(5);
        if (ret < 0){ error processing }
    
        ret = tx_set_transaciont_control(TX_UNCHAINED);
        if (ret < 0){ error processing }
        ret = tx_begin();
        if (ret < 0) { error processing }
        data process....
    
        ret = tpcall(“SERVICE1”, (char *)buf, strlen(buf), (char **)&buf, &len,
                      TPNOFLAGS);
        if (ret == -1)
        {
            tx_rollback();
            error processing
        }
    
        data process...
        ret = tpcall(“SERVICE2”, (char *)buf, strlen(buf), (char **)&buf, &len,
                       TPNOFLAGS);
        if (ret == -1)
        {
            tx_rollback();
            error processing
        }
        data process ….
    
        ret = tx_commit();
        if (ret < 0) { error processing }
        data process...
    
        tpfree((char *)buf);
        tpend();
    }
  • Related functions

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

1.97. tx_set_transaction_timeout

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

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

  • Prototype

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

    Parameter Description

    timeout

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

  • Return Value

    Value Description

    TX_OK

    The function call succeeded.

    Negative value

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

  • Errors

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

    Error Code Description

    [TX_EINVAL]

    The specified timeout value is invalid.

    [TX_PROTOCOL_ERROR]

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

    [TX_FAIL]

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

  • Example

    #include <usrinc/atmi.h>
    #include <usrinc/tx.h>
    
    void main(int argc, char *argv[])
    {
        int ret;
        long len;
        char *buf;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf = (char *)tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) {error processing };
    
        ret=tx_set_transaction_timeout( 5 );
        if (ret<0) { error processing }
    
        ret=tx_begin();
        if (ret<0) { error processing }
        ret = tpcall(“SERVICE”, (char *)buf, strlen(buf), (char **)&buf, &len,
                       TPNOFLAGS);
        if (ret == -1) {
            tx_rollback();
            error processing
        }
        data process ….
        ret = tx_commit();
        if (ret < 0) { error processing }
    
        data process...
        tpfree((char *)buf);
        tpend();
    }
  • Related functions

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

1.98. ulogsync

The ulogsync function writes the 'ulog' data from the memory buffer to the <ulog.dat> file on the physical disk using userlog().

  • Prototype

    # include  <userlog.h>
    int ulogsync(void)
  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. No value is stored in tperrno even if an error occurs.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/userlog.h>
    
    void main(int argc, char *argv[])
    {
        int ret, cd;
        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 };
    
        data process....
    
        cd = tpacall(“SERVICE”, (char **)buf, 20, TPNOFLAGS);
        if (cd==-1) { error processing }
    
        ret=tpgetrply(&cd, &buf, &len, TPNOTIME);
        if (ret==-1){ error processing }
    
        ret=userlog(“ error : %s\n“, tpstrerror(errno));
        if (ret==-1) { error processing }
        tpfree((char *)buf);
    
        ret=ulogsync();
        if (ret==-1) { error processing }
    
        tpend();
    }

1.99. userlog

The userlog function writes program-related information to a <ulog.dat> file. It is mainly used by developers to record information needed to detect program logic errors during execution.

A <ulog.dat> file is created in the directory defined by the ULOGDIR item in the Tmax configuration file. Both clients and servers can use this function, and their information is written to the same file.

When userlog() is called, data is not immediately written to the file; instead, it is stored in a buffer until a certain amount accumulates, at which point it is written to the file. Data can also be immediately written from the buffer to the file using the ulogsync() function. The userlog() function uses the same formatting as the C library printf() function, so all escape sequences supported by printf() can be used.

The log file location is determined by the first call to userlog() and does not change for subsequent calls. Therefore, the first call to userlog() establishes where the log will be stored. Even if the ULOGDIR configuration in a client is changed later, it will not affect the file location as long as userlog() has already been called.

  • Prototype

    # include <userlog.h>
    int userlog(const char *fmt, ...)
  • Parameter

    Parameter Description

    fmt

    The string to be logged by the user.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. No value is stored in tperrno even if an error occurs.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/userlog.h>
    
    void main(int argc, char *argv[])
    {
        int ret, cd;
        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 };
        data process....
    
        cd = tpacall(“SERVICE”, (char **)buf, 20, TPNOFLAGS);
        if (cd==-1) { error processing }
    
        ret=tpgetrply(&cd, &buf, &len, TPNOTIME);
        if (ret==-1){
    
        ret=userlog(“error no: %d, urcode : %d”, tperrno, tpurcode”);
        if (ret==-1) { error processing }
    
        data process..
        tpfree((char *)buf);
        tpend();
    }

1.100. UserLog

The UserLog function directly writes to the ulog file without using the memory buffer. It is available on both servers and clients. UserLog() also encompasses ulogsync(), which stores data immediately upon the function call. It serves the same purpose as userlog(). The buffer size is limited to 8 KB.

  • Prototype

    # include <userlog.h>
    int UserLog (const char *fmt, ...)
  • Parameter

    Parameter Description

    fmt

    The string to be logged by the user.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. No value is stored in tperrno even if an error occurs.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/userlog.h>
    
    void main(int argc, char *argv[])
    {
        int ret;
        long len;
        char *buf, *input;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (buf==NULL) {error processing };
        data process....
    
        strcpy(input, buf);
        ret=tpcall(“SERVICE”, buf, 20, (char **)&buf, &len, TPNOFLAGS);
        if (ret==-1) { error processing }
    
        data process ….
    
        UserLog(“input %s -> output : %s\n”,input, buf);
    
        tpfree((char *)buf);
        tpend();
    }

2. Server Functions

2.1. _tmax_check_license

The _tmax_check_license function validates licenses in Anylink and OpenFrame.

  • Prototype

    int _tmax_check_license(char *tmaxdir, int subprod);
  • Parameter

    Parameter Description

    tmaxdir

    The installation directory of the Tmax system ($TMAXDIR).

    subprod

    Determines a product to be checked (either AnyLink or OpenFrame).

    The following is an example of defining a parameter used in a subprod:

    #define SUB_PROD_ANYLINK 0x00200000
    #define SUB_PROD_OPENFRAME 0x00400000
  • Return Value

    Return Value Description

    1

    The license has already been issued.

    -1

    The license has not been issued yet.

2.2. _tmax_event_handler

The tmax_event_handler function is a callback function triggered by SLOG in situations where SVRTYPE is set to EVT_SVR. This function is used to display more information on slog. When a slog event occurs, _tmax_event_handler is called, including detailed logs in its arguments. It can be defined in a server program where SVRTYPE is EVT_SVR. Only a single server can be specified per node.

The log level of an event handler can be specified with the [–h] option in the TMMOPT section of NODE. For more information on the [–h] option, refer to Tmax Administration Guide.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int _tmax_event_handler(char *progname, int pid, int tid, char *msg, int flags);
  • Parameter

    Parameter Description

    progname

    The name of the program that triggered the event.

    pid

    The process ID.

    tid

    The thread ID (for future use).

    msg

    The event message.

    flags

    Reserved for future use. Not supported in the current version.

  • Return Value

    Return Value Description

    0

    The function call succeeded.

    -1

    The function call failed.

  • Example

    <Configuration file>

    *DOMAIN
    tmax1         SHMKEY = 78650, MINCLH = 1, MAXCLH = 3,
                  TPORTNO = 8650, BLOCKTIME = 30
    
    *NODE
    Tmaxh4        TMAXDIR = "/data1/starbj81/tmax",
                  APPDIR  = "/data1/starbj81/tmax/appbin",
                  PATHDIR = "/data1/starbj81/tmax/path",
                  TLOGDIR = "/data1/starbj81/tmax/log/tlog",
                  ULOGDIR = "/data1/starbj81/tmax/log/ulog",
                  SLOGDIR = "/data1/starbj81/tmax/log/slog",
                  TMMOPT = "-h i", SMSUPPORT = Y, SMTBLSIZE = 1000
    
    *SVRGROUP
    svg1          NODENAME = "@HOSTNAME@"
    
    *SERVER
    evtsvr        SVGNAME = svg1, SVRTYPE = EVT_SVR

    <Server program>

    #include <stdio.h>
    #include <stdlib.h>
    #include <usrinc/atmi.h>
    #include <time.h>
    
    int tpsvrinit(int argc, char *argv[])
    {
        printf(“[EVTHND] started\n”);
        return 1;
    }
    
    int svrdone()
    {
        printf(“[EVTHND stopped\n”];
        return 1;
    )
    
    int _tmax_event_handler(char *program, int pid, int tid, char *msg, int flags)
    {
        time_t t1;
        struct tm *tm;
    
        time(&t1);
        tm = localtime(&t1);
        printf(“[EVTHND] %s.%d.%02d%02d%02d:%s\n”, program, pid, tm->tm_hour,
                 tm->tm_min, tm->tm_sec, msg);
        return 0;
    }

    <Makefile.evt>

    # Server makefile
    TARGET  = $(COMP_TARGET)
    APOBJS  = $(TARGET).o
    NSDLOBJ = $(TMAXDIR)/lib64/sdl.o
    
    LIBS    = -lsvrevt -lnodb
    OBJS    = $(APOBJS) $(SVCTOBJ)
    SVCTOBJ = $(TARGET)_svctab.o
    CFLAGS  = -Ae +DA2.0W +DD64 +DS2.0 -O -I$(TMAXDIR)
    
    APPDIR  = $(TMAXDIR)/appbin
    SVCTDIR = $(TMAXDIR)/svct
    LIBDIR  = $(TMAXDIR)/lib64
    
    #
    .SUFFIXES : .c
    
    .c.o:
            $(CC) $(CFLAGS) -c $<
    
    #
    # server compile
    #
    
    $(TARGET): $(OBJS)
            $(CC) $(CFLAGS) -L$(LIBDIR) -o $(TARGET) $(OBJS) $(LIBS) $(NSDLOBJ)
            mv $(TARGET) $(APPDIR)/.
            rm -f $(OBJS)
    
    $(APOBJS): $(TARGET).c
            $(CC) $(CFLAGS) -c $(TARGET).c
    
    $(SVCTOBJ):
            cp -f $(SVCTDIR)/$(TARGET)_svctab.c .
            touch ./$(TARGET)_svctab.c
            $(CC) $(CFLAGS) -c ./$(TARGET)_svctab.c
    
    #
    clean:
    •rm -f *.o core $(APPDIR)/$(TARGET)

2.3. _tmax_main

The _tmax_main function is used when a user program contains a main() function. When creating a server process, the user program must not include main(). However, if main() is already included in a user-created library and cannot be modified, the _tmax_main() function is provided to invoke and process the main() routine within the Tmax server library.

To use this function, create an additional <***.c> file for the server program, define a main function in the file, call _tmax_main() from within the main function. This ensures that the main() routine in the Tmax server library is executed instead of the main() function defined in the user-created library.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int _tmax_main(int argc, char *argv[])
  • Parameter

    Same as the main() function.

    Parameter Description

    argc

    An array of argv.

    argv

    A list of arguments that the user specifies in the CLOPT section.

  • Return Value

    An integer. Same as the main() function.

  • Example

    The following describes the process of using the function.

    1. Create a library as follows:

      #include <stdio.h>
      
      int main(int argc, char* argv[])
      {
          printf(“my lib main called.\n”);
      }
    2. Compile the library and create a file <libmysvr.so>.

      To use the main() function in the Tmax server library instead of the one in a user-created library, create a <mysvr.c> file that defines main(). Inside this main() function, call _tmax_main().

      In this setup, three main() functions exist: one in the user-created library, one in the Tmax server library, and one in <mysvr.c>. When the Tmax system starts, the main() in <mysvr.c> is executed first. This function then calls the main() in the Tmax server library, ensuring that the main() in the user-created library is not invoked.

      #include <stdio.h>
      
      int main(int argc, char *argv[])
      {
          printf(“My main is called\n”);
          _tmax_main(argc, (char **)argv);
          return 0;
      }
    3. Compile the <***.c> file to create an object file, and then link it with the server program to make an integrated executable file.

2.4. CliWatcherCallback

The CliWatcherCallback function is used in UCS processes as a callback to detect client shutdowns. After being implemented by the user, it is passed as the callback argument to the tpsetcliwatcher() function. The callback is invoked when a client shutdown event is detected during a tpschedule() call.

The following describes the behavior of CliWatcherCallback().

  • Prototype

    #include <usrinc/ucs.h>
    typedef void (*CliWatcherCallback)(int clid, int reason, void *args)
  • Parameter

    Parameter Description

    clid

    The ID of a client that shut down.

    reason

    The reason for the client shutdown.

    For tmaxgw_setcliwatcher(), this callback is also invoked if the request is not detected by the CLH.

    args

    The value of the args variable defined by the user in tpsetcliwatcher() or tmaxgw_setcliwatcher(). It is used to pass user-defined data. When using args, take care to properly allocate and release memory.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/ucs.h>
    
    void logout_callback(int clid, int reason, void *args) {
            printf("[%s] clid:%#x, args:%p, reason:%d\n", "CALLBACK", clid, args, reason);
    }
    
    LOGIN(TPSVCINFO *msg) {
            int clid, ret;
            time_t curtime = time(NULL);
    
            clid = tpgetclid();
            ret = tpsetcliwatcher(clid, logout_callback, (void *)curtime, TPNOFLAGS);
    
            printf("[%s] clid:%#x, curtime:%ld, set_watch:%d(%s), data:%s\n",
                            msg->name, clid, curtime, ret, tpstrerror(tperrno), msg->data);
    
            tpreturn(TPSUCCESS, 0, NULL, 0, 0);
    }
  • Related functions

    tpsetcliwatcher(), tpclrcliwatcher()

2.5. tmadmin

The tmadmin function enables dynamic access to statistical information, which can also be retrieved using the tmadmin administrative tool. This function can only be used within a server process.

  • Prototype

    # include <tmadmin.h>
    int tmadmin(int cmd, void *arg, int opt, long flags);
  • Parameter

    Parameter Description

    cmd

    The following flags are available:

    TMADM_DISCON, TMADM_CLIINFO, TMADM_QPURGE, TMADM_BOOT,

    TMADM_DOWN, TMADM_SUSPEND, TMADM_RESUME, TMADM_RESTAT,

    TMADM_SVC_STAT, TMADM_SPR_STAT, TMADM_SVR_STAT,

    TMADM_SVC_STAT_EX, TMADM_SPR_STAT_EX, TMADM_TMAX_INFO,

    TMADM_DOMAIN_CONF, TMADM_NODE_CONF, TMADM_SVG_CONF

    TMADM_SVR_CONF, TMADM_SVC_CONF, TMADM_SMTRC

    arg

    A pointer to a structure that is suitable for each cmd. The data buffer size and offset can be specified.

    opt

    An option flag for each cmd. See the tables below for further details.

    flags

    Not supported in the current version. Reserved for future-use.

    The following are option flags available as opt for each cmd:

    • TMADM_DISCON

      Option flag Description

      TPNOFLAGS

      Does not abort if a client is requesting a service.

      TMADM_FFLAG

      Aborts if a client is requesting a service.

    • TMADM_CLIINFO

      Option flag Description

      TPNOFLAGS

      Passes all client information of a corresponding node.

      TMADM_SFLAG

      Passes the number of all clients of a corresponding node. (arg → header.num_left)

    • TMADM_QPURGE

      Option flag Description

      TMADM_SFLAG

      Purges a service queue.

      TMADM_VFLAG

      Purges a server queue.

    • TMADM_BOOT(TMADM_DOWN)

      Option flag Description

      TMADM_SFLAG

      Starts or shuts down a server using arg→args.name1 as the server name.

      This option is equivalent to the -s option of tmboot/tmdown, which starts or shuts down server processes up to the number specified in args.count.

      When used with TMADM_GFLAG, it affects only the servers within the specified server group. If not used with TMADM_GFLAG, all servers with the same name across all server groups are started or shut down.

      TMADM_USFLAG

      Starts or shuts down a server using arg→args.name1 as the server name.

      This option is equivalent to the -S option of tmboot/tmdown, which starts processes up to the MIN setting value in the configuration file, or shuts down all processes in the specified server.

      When used with TMADM_GFLAG, it affects only the servers within the specified server group. If not used with TMADM_GFLAG, all servers with the same name across all server groups are started or shut down.

      TMADM_GFLAG

      Starts or shuts down a server in the specified server group using arg→args.name2 as the server name.

      TMADM_TFLAG

      Starts or shuts down TMS in the specified server group using arg→args.name1 as the server group name.

      TMADM_FFLAG

      Equivalent to the -i option of tmdown, and available only for TMADM_DOWN.

    • TMADM_SUSPEND(TMADM_RESUME)

      Option flag Description

      TMADM_SFLAG

      Suspends or resumes a service.

      TMADM_VFLAG

      Suspends or resumes a server.

    • TMADM_RESTAT

      Option flag Description

      TMADM_VFLAG

      Resets statistics of a specific server.

      TMADM_AFLAG

      Resets statistics of all servers.

    • TMADM_SVC_STAT (TMADM_SPR_STAT, TMADM_SVR_STAT)

      Option flag Description

      TPNOFLAGS

      Returns the complete statistics data of the specified node.

      TMADM_SFLAG

      Returns only the data that matches the name specified in arg→header.opt_char.

      TMADM_CFLAG

      Returns only the data corresponding to the CLH number specified in arg→header.opt_int.

    • TMADM_SVC_STAT_EX (TMADM_SPR_STAT_EX)

      Option flag Description

      TPNOFLAGS

      Returns the complete statistics data of the specified node. The fail_count, error_count, mintime, and maxtime items are added to TMADM_SVC_STAT (equivalent to the -x option of the stat command in tmadmin).

      TMADM_SFLAG

      Returns only the data that matches the name specified in arg→header.opt_char.

      TMADM_CFLAG

      Returns only the data corresponding to the CLH number specified in arg→header.opt_int.

    • TMADM_SMTRC

      Option flag Description

      TPNOFLAGS

      Uses the tmadm_smtrc structure.

      TMADM_AFLAG

      Uses the tmadm_smtrcall structure. In addition to the existing items, spri, reserved, curtime, svctime, ucputime, and scputime are newly provided.

    • TMADM_TMAX_INFO, TMADM_DOMAIN_CONF, TMADM_NODE_CONF, TMADM_SVG_CONF, TMADM_SVR_CONF, TMADM_SVC_CONF

      Option flag Description

      TPNOFLAGS

      The is the only option available.

  • Return Value

    Return Value Description

    A value larger than 0

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, it may be NULL.

    This error may occur when values such as size, offset, or opt_char, are incorrect. These are the member variables of tmadmin_header, which is a member structure of the second argument.

    [TPENOREADY]

    When using TMADM_CFLAG in the TMADM_SVC_STAT/SPR_STAT/SVR_STAT commands, the corresponding CLH is ‘NOT READY’.

    This error may occur when the specified client does not exist in the TMADM_DISCONN command, or when TMADM_FFLAG is not set while requesting a service.

    [TPEOS]

    An error occurred in the operating system. This is most often an internal buffer allocation issue.

    [TPESYSTEM]

    An error occurred in the Tmax system, most typically due to a communication failure.

    [TPESVCFAIL]

    The TMADM_QPURGE, TMADM_BOOT/DOWN, or TMADM_SUSPEND/RESUME command failed due to an cause other than TPEINVAL, TPEOS, or TPESYSTEM.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmadmin.h>
    
    SERVICE(TPSVCINFO *msg)
    {
       char cmd, *buf, *sndbuf;
       int len;
       long sndlen;
    
       cmd = msg->data[0];
       switch (cmd)
       {
          case TMADM_TMAX_INFO:
             len = tmaxinfo(&buf);
             break;
          case TMADM_SVC_STAT:
             len = svcstat(&buf);
             break;
          case TMADM_SVC_STAT_EX:
             len = svcstatex(&buf);
             break;
          case TMADM_SPR_STAT:
             len = sprstat(&buf);
             break;
          case TMADM_SPR_STAT_EX:
             len = sprstatex(&buf);
             break;
          case TMADM_QPURGE:
             len = qpurge(&buf);
             break;
          default:
             len = -1;
             break;
       }
       if (len < 0){ error processing }
       sndbuf = (char *)tpalloc(“STRING”, NULL, len + 1);
       if (sndbuf==NULL) {error processing }
       memcpy(sndbuf, buf, len);
       sndlen = len;
       tpreturn(TPSUCCESS, 0, sndbuf, sndlen, TPNOFLAGS);
    }
    
    int qpurge(char **buf)
    {
       int n;
       /*n=tmadmin( TMADM_QPURGE, “TOUPPER”,
       TMADM_SFLAG, TPNOFLAGS);*/
       n = tmadmin(TMADM_QPURGE, “toupper”, TMADM_VFLAG, TPNOFLAGS);
       if (n < 0){ error processing   }
       ...
    }
    
    int tmaxinfo(char **buf)
    {
       struct tmadm_tmax_info *info;
       ...
       size = sizeof(struct tmadm_tmax_info) +
       (MAX_NODE - 1) * sizeof (struct tmadm_node_summary);
       info = (struct tmadm_tmax_info *) malloc(size);
       if (info == NULL)}{ error processing }
       memset(info, 0x00, size);
       info->header.version = _TMADMIN_VERSION;
       info->header.size = size;
    
       n = tmadmin(TMADM_TMAX_INFO, info, TPNOFLAGS, TPNOFLAGS);
       if (n < 0)}{ error processing }
       ...
    
       /* Summarize details of structure info and put it in *.buf.
          Returns *buf size. */
    }
    
    int svcstat(char **buf)
    {
       struct tmadm_svc_stat info;
       struct tmadm_svc_stat *stat;
       ...
       memset(&info, 0x00, sizeof(struct tmadm_svc_stat));
       info.header.version = _TMADMIN_VERSION;
       info.header.size = sizeof(struct tmadm_svc_stat);
       n = tmadmin(TMADM_SVC_STAT, &info, TPNOFLAGS, TPNOFLAGS);
       if (n < 0){ error processing }
    
       svccount = info.header.num_entry + info.header.num_left;
       size = sizeof(struct tmadm_svc_stat)+ ((svccount - 1) *
              sizeof (struct tmadm_svc_stat_body));
       stat = (struct tmadm_svc_stat *) malloc(size);
       if (stat == NULL){ error processing }
    
       memset(stat, 0x00, size);
       stat->header.version = _TMADMIN_VERSION;
       stat->header.size = size;
    
       n = tmadmin(TMADM_SVC_STAT, stat, TPNOFLAGS, TPNOFLAGS);
       if (n < 0){ error processing }
       ...
    
       /* Summarize details of structure info and put it in *.buf.
          Returns *buf size. */
    }
    int svcstatex(char **buf)
    {
       struct tmadm_svc_stat_ex info;
       struct tmadm_svc_stat_ex *stat;
       ...
       memset(&info, 0x00, sizeof(struct tmadm_svc_stat_ex));
       info.header.version = _TMADMIN_VERSION;
       info.header.size = sizeof(struct tmadm_svc_stat_ex);
       n = tmadmin(TMADM_SVC_STAT_EX, &info, TPNOFLAGS, TPNOFLAGS);
       if (n < 0){ error processing }
    
       svccount = info.header.num_entry + info.header.num_left;
       size = sizeof(struct tmadm_svc_stat_ex)+ ((svccount - 1) *
              sizeof (struct tmadm_svc_stat_body_ex));
       stat = (struct tmadm_svc_stat_ex *) malloc(size);
       if (stat == NULL){ error processing }
    
       memset(stat, 0x00, size);
       stat->header.version = _TMADMIN_VERSION;
       stat->header.size = size;
    
       n = tmadmin(TMADM_SVC_STAT_EX, stat, TPNOFLAGS, TPNOFLAGS);
       if (n < 0){ error processing }
       ...
    
       /* Summarize details of structure info and put it in *.buf.
         Returns *buf size. */
    }
    
    int sprstat(char **buf)
    {
       struct tmadm_spr_stat info;
       struct tmadm_spr_stat *stat;
       ...
       memset(&info, 0x00, sizeof(struct tmadm_spr_stat));
       info.header.version = _TMADMIN_VERSION;
       info.header.size = sizeof(struct tmadm_spr_stat);
       n = tmadmin(TMADM_SPR_STAT, &info, TPNOFLAGS, TPNOFLAGS);
       if (n < 0){ error processing }
    
       sprcount = info.header.num_entry + info.header.num_left;
       size = sizeof(struct tmadm_spr_stat) + (sprcount - 1) *
              sizeof (struct tmadm_spr_stat_body);
       stat = (struct tmadm_spr_stat *) malloc(size);
       if (stat == NULL)}{ error processing }
    
       memset(stat, 0x00, size);
       stat->header.version = _TMADMIN_VERSION;
       stat->header.size = size;
    
       n = tmadmin(TMADM_SPR_STAT, stat, TPNOFLAGS, TPNOFLAGS);
       if (n < 0))){ error processing }
       ...
    
       /* Summarize details of structure info and put it in *.buf.
         Returns *buf size. */
    }
    int sprstatex(char **buf)
    {
       struct tmadm_spr_stat_ex info;
       struct tmadm_spr_stat_ex *stat;
       ...
       memset(&info, 0x00, sizeof(struct tmadm_spr_stat_ex));
       info.header.version = _TMADMIN_VERSION;
       info.header.size = sizeof(struct tmadm_spr_stat_ex);
       n = tmadmin(TMADM_SPR_STAT_EX, &info, TPNOFLAGS, TPNOFLAGS);
       if (n < 0){ error processing }
    
       sprcount = info.header.num_entry + info.header.num_left;
       size = sizeof(struct tmadm_spr_stat_ex) + ((sprcount - 1) *
              sizeof (struct tmadm_spr_stat_body_ex));
       stat = (struct tmadm_spr_stat_ex *) malloc(size);
       if (stat == NULL)}{ error processing }
    
       memset(stat, 0x00, size);
       stat->header.version = _TMADMIN_VERSION;
       stat->header.size = size;
    
       n = tmadmin(TMADM_SPR_STAT_EX, stat, TPNOFLAGS, TPNOFLAGS);
       if (n < 0))){ error processing }
       ...
    
       /* Summarize details of structure info and put it in *.buf.
         Returns *buf size. */
    }

2.6. tmax_get_db_passwd

The tmax_get_db_password function identifies the password of a username in the database that Tmax is currently connected to.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tmax_get_db_passwd (char *svgname, char *passwd, int type)
  • Parameter

    Parameter Description

    svgname

    The name of server group that a password affects. Ensure the server group is XA-compliant.

    passwd

    A result is returned in a passwd in a second argument. Ensure it is allocated with enough space to hold the returned value.

    type

    The Type of DBMS that is currently being used.

    Choose one of the following:

    • ORACLE_TYPE

    • SYBASE_TYPE

    • INFORMIX_TYPE

    • DB2_TYPE

    • TIBERO_TYPE

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    –1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid.

    For example, the svc is invalid, the type is set to a value undefined in usrinc/tmaxapi.h, or set to INFORMIX_TYPE.

    [TPEITYPE]

    The svgname is set to a NON-XA server group, or the OPENINFO information in the Tmax configuration file is incorrect.

  • Example

    <OPENINFO in the configuration file>

    svg1    NODENAME = @HOSTNAME@, DBNAME = ORACLE,
    OPENINFO =“ORACLE_XA+Acc=P/scott/tiger+SesTm=60+Sqlnet=tmaxi1”,
    TMSNAME = tms_ora

    <Server program>

    #include <stdio.h>
    ...
    SVC_GETPASSWORD( TPSVCINFO *msg )
    {
        char passwd[30];
        printf(“\n   => use right..\n”);
        ret = tmax_get_db_passwd(“svg1”, passwd, ORACLE_TYPE);
        if(ret < 0)
            printf(“tmax_get_db_passwd fail[%s]\n”,tpstrerror(tperrno));
        else
            printf(“\ntmax_get_db_passwd = %s\n”, passwd);
        tpreturn( TPSUCCESS, 0, rcvbuf, 0, 0 );
    }

    <Result>

    tmax_get_db_passwd = tiger
  • Related functions

    tmax_get_db_usrname(), tmax_get_db_tnsname()

2.7. tmax_get_db_tnsname

The tmax_get_db_tnsname function identifies a tnsname in the database to which Tmax is currently connected to.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tmax_get_db_tnsname (char *svgname, char *tnsname, int type)
  • Parameter

    Parameter Description

    svgname

    The name of a server group for identifying its tnsname. Ensure the server group is XA-compliant.

    tnsname

    A buffer to receive the result. Ensure it is allocated with enough space to hold the returned value.

    type

    The Type of DBMS that is currently being used.

    Choose one of the following:

    • ORACLE_TYPE

    • SYBASE_TYPE

    • INFORMIX_TYPE

    • DB2_TYPE

    • TIBERO_TYPE

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the server group name was incorrectly specified, the type was specified with a value not defined in usrinc/tmaxapi.h, or the type was set to INFORMIX_TYPE.

    [TPEITYPE]

    The svgname is set to a NON-XA server group, or the OPENINFO information in the Tmax configuration file is incorrect.

  • Example

    <OPENINFO in the configuration file>

    svg1    NODENAME = @HOSTNAME@, DBNAME = ORACLE,
            OPENINFO = ORACLE_XA+Acc=P/scott/tiger+SesTm=60+Sqlnet=tmaxi1”,
            TMSNAME = tms_ora

    <Server program>

    #include <stdio.h>
    ...
    SVC_GETTNSNAME( TPSVCINFO *msg )
    {
        char tnsname[30];
        printf(“\n   => use right..\n”);
        ret = tmax_get_db_tnsname(“svg1”, tnsname, ORACLE_TYPE);
        if(ret < 0)
            printf(“tmax_get_db_tnsname fail[%s]\n”,tpstrerror(tperrno));
        else
            printf(“\ntmax_get_db_tnsname = %s\n”, passwd);
        tpreturn( TPSUCCESS, 0, rcvbuf, 0, 0 );
    }

    <Result>

    tmax_get_db_tnsname = tmaxi1
  • Related functions

    tmax_get_db_usrname(), tmax_get_db_tnsname()

2.8. tmax_get_db_usrname

The tmax_get_db_usrname identifies a username in the database that Tmax is currently connected to.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tmax_get_db_usrname (char *svgname, char *usrname, int type)
  • Parameter

    Parameter Description

    svgname

    The name of a server group for identifying the username. Ensure the server group is XA-compliant.

    usrname

    A buffer to receive the result. Ensure it is allocated with enough space to hold the returned value.

    type

    The Type of DBMS that is currently being used.

    Choose one of the following:

    • ORACLE_TYPE

    • SYBASE_TYPE

    • INFORMIX_TYPE

    • DB2_TYPE

    • TIBERO_TYPE

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the server group name was incorrectly specified, the type was specified with a value not defined in usrinc/tmaxapi.h, or the type was set to INFORMIX_TYPE.

    [TPEITYPE]

    The svgname is set to a NON-XA server group, or the OPENINFO information in the Tmax configuration file is incorrect.

  • Example

    <OPENINFO in the configuration file>

    svg1    NODENAME = @HOSTNAME@, DBNAME = ORACLE,
            OPENINFO = ORACLE_XA+Acc=P/scott/tiger+SesTm=60+Sqlnet=tmaxi1”,
            TMSNAME = tms_ora

    <Server program>

    #include <stdio.h>
    ...
    SVC_GETUSRNAME( TPSVCINFO *msg )
    {
        char usrname[30];
        printf(“\n   => use right..\n”);
        ret = tmax_get_db_usrname(“svg1”, usrname, ORACLE_TYPE);
        if(ret < 0)
            printf(“tmax_get_db_usrname fail[%s]\n”,tpstrerror(tperrno));
        else
            printf(“\ntmax_get_db_usrname = %s\n”, usrname);
        tpreturn( TPSUCCESS, 0, rcvbuf, 0, 0 );
    }

    <Result>

    tmax_get_db_usrname = scott
  • Related functions

    tmax_get_db_passwd(), tmax_get_db_tnsname()

2.9. tmax_get_my_unique_spri_in_domain

The tmax_get_my_unique_spri_in_domain function retrieves the spri value that is unique in the domain for its processes.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tmax_make_unique_spri_in_domain(void)
  • Return Value

    Return Value Description

    unique_spri

    The spri value thia is unique in the domain.

  • Example

    #include <stdio.h>
    #include <usrinc/tmaxapi.h>
    ...
    tpsvrinit(int argc, char **argv)
    {
        uniqspri = tmax_get_my_unique_spri_in_domain();
        ...
    }
  • Related functions

    tmax_make_unique_spri_in_domain()

2.10. tmax_get_svccnt

The tmax_get_svccnt function returns the number of services in a server. It can be used to allocate a buffer to store the list of services retrieved with tmax_get_svclist().

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tmax_get_svccnt(void)
  • Return Value

    Return Value Description

    Number of services

    The function call succeeded and returns the number of services in the server.

2.11. tmax_get_svclist

The tmax_get_svclist function retrieves the list of services in a server.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tmax_get_svclist(char *buf, int bufsize)
  • Parameter

    Parameter Description

    buf

    A buffer allocated with the following size to retrieve the service names contained in the server:

    Number of services(returned by tmax_get_svccnt()) x XATMI_SERVICE_NAME_LENGTH

    bufsize

    Set as follows:

    Number of services(returned by tmax_get_svccnt()) x XATMI_SERVICE_NAME_LENGTH
  • Return Value

    Return Value Description

    0

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

    The buffer size is smaller than (number of services x XATMI_SERVICE_NAME_LENGTH) or NULL.

  • Example

    <Server program>

    #include <stdio.h>
    #include <stdlib.h>
    #include <usrinc/tmaxapi.h>
    
    GETSVC(TPSVCINFO *msg)
    {
        int     i;
        int len, ret, size;
        char *buf;
        char *ptr;
    
        printf(“GETSVC service is started!\n”);
        len = tmax_get_svccnt();
        if (len < 0) {
            printf(“tmax_get_svccnt fail[%d]\n”, tperrno);
            tpreturn(TPFAIL, 0, 0, 0, 0);
        }
        printf(“SVCCNT = %d\n”, len);
    
        size = len * XATMI_SERVICE_NAME_LENGTH;
        buf = malloc(size);
        if (buf == NULL) {
            printf(“buf is NULL\n”);
            tpreturn(TPFAIL, 0, 0, 0, 0);
        }
        ret = tmax_get_svclist(buf, size);
        if (ret < 0) {
            printf(“tmax_get_svclist fail[%d]\n”, tperrno);
            tpreturn(TPFAIL, 0, 0, 0, 0);
        }
        for (i = 0; i < len; i++) {
            ptr = buf;
            printf(“%dth SVC[%s]\n”, i, ptr);
            buf += XATMI_SERVICE_NAME_LENGTH;
        }
        free(buf);
        tpreturn(TPSUCCESS,0,(char *)msg->data, 0,0);
    }

2.12. tmax_is_restarted

The tmax_is_restarted function checks the restart status of a Tmax AP Server process. It is available only on the server and is used to determine whether the server is restarting after a process failure. This function can be called from within a Tmax AP Server routine.

The function identifies a server restart in one of the following scenarios:

  • Abnormal shutdown due to an AP runtime error

  • Timeout, indicated by tpreturn(TPEXIT)

  • Restart triggered after executing tmdown -i -s AP

The following describes the behavior of tmax_is_restarted.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tmax_is_restarted(void);
  • Return Value

    Return Value Description

    1

    The server process has abnormally shut down and subsequently restarted.

    0

    The application server is normally running without a restart.

  • Example

    <Server program>

    ISRESTARTED(TPSVCINFO *msg)
    {
        int ret;
        ret = tmax_is_restarted()
        if(ret == 1)
            printf(“restarted server process\n”);
        else
            printf(“normal server process\n”);
        tpreturn(TPSUCCESS, 0, (char *)NULL, 0, 0);
    }

2.13. tmax_is_xa

The tmax_is_xa checks whether the server it belongs to is XA or NON-XA.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tmax_is_xa(void);
  • Return Value

    Return Value Description

    XA_MODE(1)

    The server is XA.

    NONXA_MODE(0)

    The srever is Non-XA.

  • Example

    #include <stdio.h>
    SVC_XA( TPSVCINFO *msg )
    {
        ...
        ret = tmax_is_xa();
        if (ret < 0)
            printf(“\ntmax_is_xa func fail [%s]\n”, tpstrerror(tperrno));
    
        if(ret == 1) strcpy(mode, « XA_MODE »);
        else if(ret == 0) strcpy(mode, “NONXA_MODE”);
        else strcpy(mode, “unknown”);
        printf(“ => [SVC_XA] result of tmax_is_xa() : %s\n\n”, mode);
    
        tpreturn( TPSUCCESS, 0, rcvbuf, 0, 0 );
    }

2.14. tmax_my_rminfo

The tmax_my_rminfo function retrieves the OPENINFO information for a server group.

  • Prototype

    #include <tmaxapi.h>
    int tmax_my_rminfo(RM_INFO_T *rminfo, int max_elem)
  • Parameter

    Parameter Description

    rminfo

    A pointer to a structure array buffer to store the RM information.

    max_elem

    The number of structure array elements. Up to 16 server groups can be specified.

    The following shows a rminfo structure.

    Structure rminfo {
         int rmid
         int flags
         char dbname[DBNAME_SIZE + 1]
         char openinfo[RM_STRING_SIZE + 1]
         char closeinfo[RM_STRING_SIZE + 1]
    };
    Member Description

    rmid

    RM ID.

    flags

    Currently not used.

    dbname[DBNAME_SIZE + 1]

    The name of the database defined in the server group.

    Typically, one of ORACLE, TIBERO, DB2_64, SYBASE, INFOMIX, ALTIBASE, DB2_STATIC, or MQ is used. It also can be a user-defined name. In this case, the name must be specified in the $TMAXDIR/config/RM file.

    openinfo[RM_STRING_SIZE + 1]

    Retrieves the openinfo.

    closeinfo[RM_STRING_SIZE + 1]

    Retrieves the closeinfo.

  • Return Value

    Return Value Description

    rmcount

    The number of returned RMs.

2.15. tmax_my_svrinfo

The tmax_my_svrinfo function displays the system configuration of a server process. It provides static information. For dynamic access to various process status information, use tmadmin().

  • Prototype

    #include <tmaxapi.h>
    int tmax_my_svrinfo (TMAXSVRINFO*)
  • Parameter

    The server processes registered in a Tmax configuration file contain hierarchical information such as a node name, a server group name, and a server name. A server group index, server index and a sequence number of a server process, are treated as unique values in a single node and can be displayed. A developer can use the information for various purposes such as process management and classification. The information can be derived from a TMAXSVRINFO structure defined in a <tmaxapi.h>.

    The following shows a TMAXSVRINFO structure defined in <tmaxapi.h>.

    typedef struct {
        int nodeno; /* node index */
        int svgi;   /* server group index;unique in the node */
        int svri;   /* server index; unique in the node */
        int spri;   /* server process index; unique in the node */
        int spr_seqno; /* server process seqno ; unique in the server */
        int min, max;    /* min/max server process number */
        int clhi;         /*  for RDP only, corresponding CLH id */
        char nodename[TMAX_NAME_SIZE];
        char svgname[TMAX_NAME_SIZE];
        char svrname[TMAX_NAME_SIZE];
        char reserved_char[TMAX_NAME_SIZE];
        /* for more detail use tmadmin API */
    } TMAXSVRINFO;
    Member Description

    nodeno

    A node index, which is a unique value in a single domain of the Tmax system.

    svgi

    A unique value in a single node that indicates a server group index.

    svri

    A unique value in a single node that indicates a server index.

    spri

    A unique value in a single node that indicates a server process index.

    spr_seqno

    The sequence number of a server process.

    min , max

    The minimum and maximum number of processes specified in the Tmax configuration file.

    clhi

    A field used in cases where a RDP server process indicates a CLH number which corresponds to a relevant RDP process.

    nodename[TMAX_NAME_SIZE]

    A node name configured in the Tmax configuration file.

    svgname[TMAX_NAME_SIZE]

    A server group name configured in the Tmax configuration file.

    svrname[TMAX_NAME_SIZE]

    A server name configured in the Tmax configuration file.

    reserved_char[TMAX_NAME_SIZE]

    Currently not used. Reserved for future use.

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

    No variable has been specified to store the server process information.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    SERVICE(TPSVCINFO *msg)
    {
        int n;
        TMAXSVRINFO *info;
    
        info = (TMAXSVRINFO *)malloc(sizeof(TMAXSVRINFO));
        if (info == NULL) {
            tpreturn(TPFAIL, -1, NULL, 0, TPNOFLAGS);
        }
        n = tmax_my_svrinfo(info);
    }
  • Related functions

    tmadmin()

2.16. tmgetsmgid

The tmgetsmgid function supports the SysMaster trace function and returns the group id of a calling process. It enables the user to perform a system trace.

To execute the function, a SMSUPPORT in the NODE section of a configuration file should be set to Y. The (st -p -x) tmadmin tool also can be used to display the GID of a server process.

The structure of a GID is as follows. Once a function completes successfully, it will be returned with gid→gid1, gid→gid2, and gid→seqno .

Item Description

GID1 (4Byte)

The unique number of a client connected to a system. (cli for WebtoB) Clients are classified with domain id, node id, hth #, and slot id.

GID2 (4Byte)

The seq number # by using its first three bytes and a unique product ID using the final byte.

SEQNO (4Byte)

The branch number # for synchronous message by using its first two bytes and the seq # for all message by using its last two bytes.

  • Prototype

    #include <usrinc/tmadmin.h>
    int tmgetsmgid(tmax_smgid_t *gid);
  • Parameter

    Return Value Description

    gid

    A unique number for each client in a product.

  • Return Value

    Return Value Description

    0

    The function call succeeded.

    -1

    The function call failed. The gid is NULL.

  • Example

    <svr02.c> : TPNOFLAGS setting

    #include <stdio.h>
    #include <stdlib.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmadmin.h>
    #include “../sdl/demo.s”
    
    GETGID(TPSVCINFO *msg)
    {
        tmax_smgid_t smgid;
        int ret;
        char *buf;
    
        buf = (char *)tpalloc(“STRING”, NULL, 0);
        if(buf == NULL)
            tpreturn(TPFAIL, -1, NULL, 0, 0);
        ret = tmgetsmgid(&smgid);
        memcpy(buf, (char *)&smgid.gid1, 4);
        memcpy(buf+4, (char *)&smgid.gid2, 4);
        memcpy(buf+8, smgid.seqno, 4);
        tpreturn(TPSUCCESS, 0, (char *)buf, strlen(buf), 0);
    }
    
    SMTRACE(TPSVCINFO *msg)
    {
        struct tmadm_smtrc *smtrc;
        int max = 10, size;
        int gid1, gid2, n, i;
        struct smtrace *ptr;
        char *buf;
    
        buf = (char *)tpalloc(“CARRAY”, NULL, 0);
        if(buf == NULL)
            tpreturn(TPFAIL, -1, NULL, 0, 0);
        ptr = (struct smtrace *)msg->data;
        gid1 = ptr->gid1;
        gid2 = ptr->gid2;
    
        /*
        printf(“SMTRACE start: %x %x\n”, gid1, gid2);
        */
    
        size = sizeof(struct tmadm_smtrc) + (max-1) * sizeof(struct tmadm_smtrc_body);
        smtrc = (struct tmadm_smtrc *)malloc(size);
        if(smtrc == NULL)
        {
            printf(“smtrc is null\n”);
            tpreturn(TPFAIL, -1, NULL, 0, 0);
        }
    
        memset(smtrc, 0x00, size);
        smtrc->header.version = _TMADMIN_VERSION;
        smtrc->header.size = size;
        smtrc->header.reserve_int[0] = gid1;
        smtrc->header.reserve_int[1] = gid2;
        n = tmadmin(TMADM_SMTRC, smtrc, TPNOFLAGS, TPNOFLAGS);
        if(n < 0)
        {
            free(smtrc);
            tpreturn(TPFAIL, -1, NULL, 0, 0);
        }
        /*
        printf(“smtrc->header.num_entry = %d\n”, smtrc->header.num_entry);
        */
        for(i=0; i<smtrc->header.num_entry; i++)
        {
            sprintf(buf, “SMTRACE[%d] : gid[%x-%x-%x] seqno[%x] clhno[%x] status
            [%s] name[%s]\n”,i, gid1, gid2, ptr->seqno,
            smtrc->trc[i].seqno,
            smtrc->trc[i].clhno,
            smtrc->trc[i].status,
            smtrc->trc[i].name);
        }
    
        free(smtrc);
        tpreturn(TPSUCCESS, 0, (char *)buf, strlen(buf), 0);
    }

    <svr02_a.c> : TMADM_AFLAG setting

    #include <stdio.h>
    #include <stdlib.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmadmin.h>
    #include "../sdl/demo.s"
    
    GETGID_A(TPSVCINFO *msg)
    {
            tmax_smgid_t smgid;
            int ret;
            char *buf;
    
            buf = (char *)tpalloc("STRING", NULL, 0);
            if(buf == NULL)
                    tpreturn(TPFAIL, -1, NULL, 0, 0);
    
            ret = tmgetsmgid(&smgid);
    
            memcpy(buf, (char *)&smgid.gid1, 4);
            memcpy(buf+4, (char *)&smgid.gid1, 4);
            memcpy(buf+8, smgid.seqno, 4);
    
            tpreturn(TPSUCCESS, 0, (char *)buf, strlen(buf), 0);
    }
    
    SMTRACE_A(TPSVCINFO *msg)
    {
            struct tmadm_smtrcall *smtrcall;
            int max = 10, size;
            int gid1, gid2, n, i;
            struct smtrace *ptr;
            char *buf;
    
            buf = (char *)tpalloc("CARRAY", NULL, 0);
            if(buf == NULL)
                    tpreturn(TPFAIL, -1, NULL, 0, 0);
    
            ptr = (struct smtrace *)msg->data;
            gid1 = ptr->gid1;
            gid2 = ptr->gid2;
    
    /*
            printf("SMTRACE start: %x %x\n", gid1, gid2);
    */
            size = sizeof(struct tmadm_smtrcall) +
                  (max-1) * sizeof(struct tmadm_smtrcall_body);
            smtrcall = (struct tmadm_smtrcall *)malloc(size);
            if(smtrcall == NULL)
            {
                    printf("smtrcall is null\n");
                    tpreturn(TPFAIL, -1, NULL, 0, 0);
            }
    
            memset(smtrcall, 0x00, size);
            smtrcall->header.version = _TMADMIN_VERSION;
            smtrcall->header.size = size;
            smtrcall->header.reserve_int[0] = gid1;
            smtrcall->header.reserve_int[1] = gid2;
    
            n = tmadmin(TMADM_SMTRC, smtrcall, TMADM_AFLAG, TMADM_AFLAG);
            if(n < 0)
            {
                    free(smtrcall);
                    tpreturn(TPFAIL, -1, NULL, 0, 0);
            }
            printf("smtrcall->header.num_entry = %d\n", smtrcall->header.num_entry);
            printf("smtrcall->header.num_left = %d\n", smtrcall->header.num_left);
            n = 0;
            for(i=0; i<smtrcall->header.num_entry + smtrcall->header.num_left; i++)
            {
                    sprintf(buf+n, "SMTRACE[%d] : gid[%x-%x-%x] seqno[%x] clhno[%x]
                            status[%s] name[%s] spri[%d] curtime[%ld], svctime[%ld],
                            ucputime[%ld], scputime[%ld]\n",
                            i, gid1, gid2, ptr->seqno,
                            smtrcall->trc[i].seqno,
                            smtrcall->trc[i].clhno,
                            smtrcall->trc[i].status,
                            smtrcall->trc[i].name,
                            smtrcall->trc[i].spri,
                            smtrcall->trc[i].curtime.tv_sec,
                            smtrcall->trc[i].svctime.tv_sec,
                            smtrcall->trc[i].ucputime.tv_sec,
                            smtrcall->trc[i].scputime.tv_sec);
                    n = n + strlen(buf);
            }
            free(smtrcall);
            tpreturn(TPSUCCESS, 0, (char *)buf, strlen(buf), 0);
    }

    <svr01.c>

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmadmin.h>
    #include “../sdl/demo_sdl.h”
    
    SDLTOUPPER(TPSVCINFO *msg)
    {
        int     i, ret, cd;
        struct  smtrace *stdata;
        tmax_smgid_t smgid;
        char *buf;
        long rcvlen;
    
        buf = (char *)tpalloc(“CARRAY”, NULL, 0);
        ret = tmgetsmgid(&smgid);
        if(ret < 0)
            tpreturn(TPFAIL, -1, NULL, 0, 0);
        stdata = (struct smtrace *)msg->data;
        stdata->gid1 = smgid.gid1;
        stdata->gid2 = smgid.gid2;
        stdata->seqno = smgid.seqno;
    
        cd = tpacall(“SMTRACE”, msg->data, 0, 0);
        ret = tpgetrply(&cd, (char **)&buf, (long *)&rcvlen, 0);
        if(ret < 0)
            tpreturn(TPFAIL, -1, NULL, 0, 0);
        sleep(20);
        tpreturn(TPSUCCESS,0,(char *)buf, strlen(buf),0);
    }

    < client.c>

    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmadmin.h>
    #include “../sdl/demo.s”
    
    main(int argc, char *argv[])
    {
        struct  smtrace *sndbuf, *rcvbuf;
        long    rcvlen, sndlen;
        int     ret;
    
        if (tpstart((TPSTART_T *)NULL) == -1){
            printf(“tpstart failed\n”);
            exit(1);
        }
        ...
        if (tpcall(“SDLTOUPPER”,(char *)sndbuf,0, (char **)&rcvbuf, &rcvlen, 0) == 1)
       {
            printf(“Can’t send request to service SDLTOUPPER =>\n”);
            tpfree((char *)sndbuf);
            tpfree((char *)rcvbuf);
            tpend();
            exit(1);
        }
        printf(“rcvbuf = %s\n”, rcvbuf);
        tpfree((char *)sndbuf);
        tpfree((char *)rcvbuf);
        tpend();
    }

For more information about the tmadmin tool, refer to Tmax Administration Guide.

2.17. tmget_smtrclog

The tmget_smtrclog function stores logging data in a structure buffer. When saving data, the maximum number of logs is set. When displaying data, the number of saved data is stored.

  • Prototype

    #include <usrinc/tmadmin.h>
    int tmget_smtrclog(void *handle, tmax_smtrclog_t *buf, int *count)
  • Parameter

    Item Description

    handle

    A pointer (msg→data) to data sent from a logging service.

    buf

    A buffer to retrieve logging data.

    count

    Logging count.

    The following shows the logging information structure (tmax_smtrclog_t):

    < usrinc/tmadmin.h>

    /* SysMaster Trace Log structure */
    typedef struct {
            tmax_smgid_t gid;
            int     clhno;
            char    status[TMAX_NAME_SIZE];
            char    name[TMAX_NAME_SIZE];
            int     spri;
            int     reserved;
            struct timeval curtime;
            struct timeval svctime;
            struct timeval ucputime;
            struct timeval scputime;
    } tmax_smtrclog_t;
    Member Description

    gid

    SysMaster GID.

    clhno

    CLH number requested.

    status[TMAX_NAME_SIZE]

    Service status.

    name[TMAX_NAME_SIZE]

    Service name.

    spri

    Server process index.

    reserved

    Currently not used.

    curtime

    Current time.

    svctime

    Service execution time.

    ucputime

    User CPU time.

    scputime

    System CPU time.

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid.

    [TPESYSTEM]

    SysMaster or the SysMaster log service was not configured in the node.

    [TPELIMIT]

    The specified count is smaller than the number of actual data stored in the handle.

  • Example

    <svr.c>

    #include <stdio.h>
    #include <stdlib.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmadmin.h>
    
    SMLOGSERVICE(TPSVCINFO *msg)
    {
            tmax_smtrclog_t *smtrclog;
            int ret, count=0, i;
            char *buf;
    
            smtrclog = (tmax_smtrclog_t *)tpalloc("CARRAY", NULL, 1024);
            if(smtrclog == NULL)
            {
                    printf("smtrclog tpalloc fail [%s]\n", tpstrerror(tperrno));
            }
            buf = (char *)tpalloc("STRING", NULL, 0);
            if(buf == NULL)
               tpreturn(TPFAIL, -1, NULL, 0, 0);
    
            memset(buf, 0x00, 1024);
            memset(smtrclog, 0x00, 1024);
            count = tmget_smtrclog_count((char *)msg->data);
            printf("\n###########################\n\n");
            printf("tmget_smtrclog_count = %d\n", count);
    
            count = 100;
            ret = tmget_smtrclog(msg->data, smtrclog, &count);
            printf("count = %d\n", count);
            for(i=0; i<count; i++)
            {
               printf("smtrclog[%d].gid = %d-%d-%d\n", i, smtrclog[i].gid.gid1,
                       smtrclog[i].gid.gid2, smtrclog[i].gid.seqno);
               printf("smtrclog[%d].clhno = %d\n", i, smtrclog[i].clhno);
               printf("smtrclog[%d].status = %s\n", i, smtrclog[i].status);
               printf("smtrclog[%d].name = %s\n", i, smtrclog[i].name);
               printf("smtrclog[%d].spri = %d\n", i, smtrclog[i].spri);
               printf("\n");
            }
            printf("###########################\n\n");
            strcpy(buf, "success\n");
            tpreturn(TPSUCCESS, 0, (char *)buf, 0, 0);
    }

2.18. tmget_smtrclog_count

The tmget_smtrclog_count function returns the number of data items to be logged.

  • Prototype

    ##include <usrinc/tmadmin.h>
    int tmget_smtrclog_count(void *handle)
  • Parameter

    Item Description

    handle

    A pointer to data (msg→data) passed by a logging service.

  • Return Value

    Return Value Description

    Number of logged data items

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

    The parameter is incorrect.

    [TPESYSTEM]

    SysMaster or the SysMaster log service was not configured in the node.

  • Example

2.19. tpadvertise

The tpadvertise function allows a server to advertise a service that it offers. A service name can be advertised using an advertise API. When advertising a service, the service name can be registered in each of the service name tables in CLH managed servers. When this service is called, a function referenced by func will be executed. In summary, advertise enables a server process to advertise any new services provided by a server.

In Tmax versions prior to 5 SP1 Fix#4(r7000) and 5 SP2 Fix#1, only services registered in the configuration file could be advertised, and a new service could not be advertised and released. From the mentioned versions and subsequent versions, new services can be advertised and released.

The following describes how each service is operated:

  • Service registered in a configuration file

    The status of the service is changed to runnable after tpunadvertise is executed. If tpadvertise is executed in another server, it will fail.

  • Service registered with mksvr

    The status of the service changes to runnable after tpunadvertise is executed. If tpadvertise is executed in another server, it will fail. If all server processes have ended, services for which tpadvertise was executed are automatically removed.

  • Newly registered service

    A new service is registered. Its status changes to runnable after tpunadvertise is executed. If tpadvertise is executed in another server, it will fail. If all server processes have ended, services for which tpadvertise was executed are automatically removed. With RESTART = Y in the server section, if tpadvertise is not executed when restarting the server after a shutdown, service calls will fail. Therefore, it is recommended that tpadvertise be called by tpsvrinit. For newly registered services, SVCTIMEOUT and AUTOTRAN cannot be set.

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

  • Prototype

    #include <atmi/usrinc.h>
    int tpadvertise(char svcname, void (func)(TPSVCINFO *));
  • Parameter

    Parameter Description

    svcname

    The name of a service to be registered.

    (func)(TPSVCINFO *)

    The function to be called.

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

    The service name or func is NULL.

    [TPELIMIT]

    The service name exceeds the length limit, or the maximum number of services (MAXSVC) for the node has been reached, preventing new services from being registered.

    [TPEMATCH]

    The service has already been advertised using another function or has already been registered by another server.

    [TPEQPURGE]

    A queued request for a tpadvertise call was purged from the queue due to the queue purge timeout.

    [TPESYSTEM]

    An error occurred in the Tmax system.

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <usrinc/atmi.h>
    
    SVC2TN_NEWSVC1( TPSVCINFO *msg )
    {
        ...
    }
    
    SVC2TN_NEWSVC2( TPSVCINFO *msg )
    {
        ...
    }
    
    SVC2TN_1( TPSVCINFO *msg )
    {
        int     ret;
        char    input[MAXLEN];
        void    (*func)(TPSVCINFO*);
    
        memset(input, 0x00, MAXLEN);
        strncpy(input, msg->data, msg->len);
    
        func = SVC2TN_NEWSVC1;
        ret = tpadvertise(input, func);
        if (ret < 0) {
            tpreturn(TPFAIL, 0, (char*)msg->data, msg->len, 0);
        }
        tpreturn(TPSUCCESS, 0, (char*)msg->data, msg->len, 0);
    }

For more information about the advertise and unadvertise functions, refer to advertise(adv) / unadvertise(unadv) in Tmax Administration Guide.

2.20. tpcancelctx

The tpcancelctx function cancels data stored in a client context using tpsavectx(). Even if tprelay() is not executed, the service routine can terminate normally, and the result will still be returned.

tpgetctx() can be used only in a service routine.

  • Prototype

    #include <ucs.h>
    int tpcancelctx(CTX_T *ctxp);
  • Parameter

    Parameter Description

    ctxp

    Deletes a CTX_T structure saved in a library.

    • CTX_T structure definition

      typedef struct {
          int   version[4];
          char  data[CTX_USR_SIZE - 16];
      } CTX_T;
  • Example

    RELAY_SVC(TPSVCINFO *msg) {
        .....
        ctxp = (CTX_T *)tpsavectx();
        .....
        ret=tpcancelctx(ctxp);
        if (ret<0) {
              error process routine
         }
         .....
         tpreturn(TPFAIL, sqlca.sqlcode, NULL, 0, TPNOFLAGS);
    }

2.21. tpchkclid

The tpchkclid function checks whether a client is currently connected to the node where a server process resides. When developing an RDP-type server program, if a service routine stores a connected client ID and the usermain() routine sends a message using tpsendtocli(), this function can help prevent unnecessary errors.

In RDP-type server programs, tpsendtocli() cannot be used unless the client is directly connected to the node where the server process resides.

  • Prototype

    #include <tmaxapi.h>
    int tpchkclid(int clid)
  • Parameter

    Parameter Description

    clid

    The ID of the client retrieved using tpgetclid().

  • Return Value

    Return Value Description

    -2

    The client is not connected to the local node.

    -1

    The client is not connected.

    1

    The client is correctly connected.

  • Error

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

    Error Code Description

    [TPEINVAL]

    The client is not connected to the local node, or the specified client number is incorrect.

    [TPENOREADY]

    The client is not properly connected.

  • Example

    int _discon(char **buf)
    {
        int clid, n;
        clid = tpgetclid();
        n = tpchkclid(clid);
        if (n < 0) {
            printf(“Invalid Client\n”);
            return -1;
        }
       ...
    }
  • Related function

    tpgetclid()

2.22. tpclrcliwatcher

The tpclrcliwatcher function is used in UCS processes to cancel the detection client shutdown events that were previously registered with tpsetcliwatcher(). After tpclrcliwatcher() is called, the callback is no longer invoked when the client shuts down.

  • Prototype

    #include <usrinc/ucs.h>
    int tpclrcliwatcher(int clid, void **pargs, int flags)
  • Parameter

    Parameter Description

    clid

    The ID of the client to cancel detection of shutdown events.

    pargs

    Returns the args variable specified in tpsetcliwatcher().

    flags

    Currently not used.

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the clid value does not correspond to a valid client, or an argument is incorrect.

    [TPENOENT]

    No shutdown event is found for the specified clid. This may occur if the callback has already been invoked or cleared.

    [TPENOTREADY]

    The client corresponding to the clid value is not connected.

    [TPEOS]

    The call failed due to memory allocation failure.

    [TPESYSTEM]

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

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/ucs.h>
    
    LOGOUT(TPSVCINFO *msg) {
            int clid, ret;
            void *args;
            time_t curtime;
    
            clid = tpgetclid();
            ret = tpclrcliwatcher(clid, &args, TPNOFLAGS);
    
            printf("[%s] clid:%#x, args:%p, clr_watch:%d(%s), data:%s\n",
                            msg->name, clid, args, ret, tpstrerror(tperrno), msg->data);
    
            tpreturn(TPSUCCESS, 0, NULL, 0, 0);
    }
  • Related functions

    CliWatcherCallback(), tpsetcliwatcher()

2.23. tpclrfd

The tpclrfd function turns off a socket fd in an internal fdset of a UCS-type process. It is used for scheduling an external socket in a UCS-type server process.

  • Prototype

    #include <ucs.h>
    int  tpclrfd (int fd)
  • Parameter

    Parameter Description

    fd

    The socket of an internal fdset to be turned off.

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <sys/socket.h>
    #include <netinet/in.h>
    #include <errno.h>
    #include <usrinc/ucs.h>
    ….
    #define SERV_ADDR “168.126.185.129”
    #define SERV_PORT 1500
    
    int fd_read(int, char *, int);
    extern int errno;
    
    int usermain(int argc, char *argv[])
    {
        ...
        int listen_fd, n, newfd;
        struct sockaddr_in my_addr, child_addr;
        socklen_t child_len;
        buf = tpalloc(“STRING”, NULL, 0);
        if (buf == NULL){ error processing }
    
        memset((void *)&my_addr, NULL, sizeof(my_addr));
        memset((void *)&child_addr, NULL, sizeof(child_addr));
        listen_fd = socket(AF_INET, SOCK_STREAM, 0);
        if (listen_fd == -1){ error processing }
        my_addr.sin_family = AF_INET;
        inaddr = inet_addr(SERV_ADDR);
        my_addr.sin_port = htons((unsigned short)SERV_PORT);
        if (inaddr != -1){
            memcpy((char *)&my_addr.sin_addr, (char *)&inaddr, sizeof(inaddr));
        }
    
        ret = bind(listen_fd, (struct sockaddr *)&my_addr, sizeof(my_addr));
        if (ret == -1){ error processing }
        ret = listen(listen_fd, 5);
        if (ret == -1){ error processing }
    
        tpsetfd(listen_fd);
        ...
        while(1) {
            n = tpschedule(10);
            ...
            if (n == UCS_USER_MSG){
            if (tpissetfd(listen_fd)) {
                child_len = sizeof(child_addr);
                newfd = accept(listen_fd, &child_addr, &child_len);
                if (newfd == -1){ error processing }
                tpsetfd(newfd);
            }
    
            if (tpissetfd(newfd)){
                /* Read the buffer from the socket */
                fd_read(newfd, buf, 1024);
                ret = tpcall(“SERVICE”, (char *)buf, sizeof(buf), (char **)&buf,
                             (long *)&rlen, TPNOFLAGS);
                if (ret == -1){ error processing }
                    ...
                ret = tpclrfd(newfd);
                if (ret == -1){ error processing }
                close(newfd);
            }
            ...
       }
       return 1;
    }
  • Related function

    tpissetfd()

2.24. tpclrfd_w

The tpclrfd_w function clears (turns off) a socket file descriptor (FD) from the internal writable FDSET used by a UCS-type process. It is typically used when scheduling an external socket in a UCS-type server process.

Unlike tpclrfd(), which removes a socket FD from the readable FDSET, tpclrfd_w() removes it from the writable FDSET. The fd parameter specifies the socket FD to be deleted from the writable FDSET.

The functions tpissetfd_w(), tpsetfd_w(), and tpclrfd_w() support scheduling of user socket FDs—connected to external hosts or clients—within the UCS scheduler of tpschedule() or tpuschedule(). They also manage TMM and CLH interactions. When a message is ready to be sent to a user-specified FD, tpschedule() returns UCS_USER_MSG. To check which socket FD is ready, use tpissetfd_w().

These socket FD functions (tpissetfd(), tpsetfd(), tpclrfd(), tpissetfd_w(), tpsetfd_w(), and tpclrfd_w()) behave similarly to the standard network programming macros FD_SET, FD_CLR, and FD_ISSET.

  • Prototype

    #include <ucs.h>
    int  tpclrfd_w (int fd)
  • Parameter

    Parameter Description

    fd

    The socket of an internal fdset to be turned off.

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

  • Related functions

    tpissetfd(), tpsetfd(), tpclrfd()

2.25. tpforward

The tpforward function terminates the current service routine and forwards the client’s request to another service routine, specified by svc.

Like tpreturn(), this function must be called within a service routine under Tmax system control. However, unlike tpreturn(), the forwarding service routine does not send a reply to the client. Instead, it transfers the responsibility for replying to the target service. After forwarding, the service routine immediately returns control to the Tmax system and can no longer perform additional operations.

A service request forwarded with tpforward() does not expect a response from the forwarding routine. Therefore, the request can be forwarded to any service without generating forwarding errors. The final service in the chain must eventually call tpreturn() to send a reply to the original client. tpforward() can also forward requests across nodes.

If the service routine is executing in transaction mode, tpforward() does not commit or roll back the transaction. The transaction must be completed by the transaction originator, using tx_commit() or tx_rollback(). If a service routine begins a transaction with tx_begin(), the transaction must be completed (committed or rolled back) before calling tpforward(). All services in a forwarding chain must either participate in the transaction or operate outside transaction mode.

tpforward() must be called only after replies for all outstanding service requests have been received. Any unreceived replies are invalidated, and the forward request will not be sent. tpforward() cannot be used in interactive communications.

The following shows the tpforward function flow:

figure 6 1
Figure 1. tpforward
  • Prototype

    # include <atmi.h>
    void  tpforward (char  *svc, char *data, long len, long flags)
  • Parameter

    Parameter Description

    svc

    The name of a service to receive a buffer.

    data

    If not NULL, must be a pointer to a buffer that has been previously allocated by tpalloc().

    If a buffer is the same as the one transmitted to a service routine, the Tmax system must handle this buffer. If a service routine writer attempts to release the buffer, this attempt will fail. However, if the buffer transmitted to tpforward() is not the same as the one transferred at the time of calling the service, tpforward() will release the buffer.

    len

    The length of data to be transmitted. If data indicates a buffer that does not require a specific length (e.g., a STRUCT Type buffer), len will be ignored and is set to 0. If data is NULL, len will be ignored and a request that has a data length of 0 will be transmitted.

    A service routine writer cannot regain control after calling a tpforward(), blocking transmission in the form that a TPSIGRSTRT is defined implicitly is used. Therefore, if a signal is generated during a tpforward() operation to stop an operation, processing will continued later. If a blocking condition is encountered, it will wait until a timeout occurs and then sends a service request.

    flags

    Not supported in the current version. Set to TPNOFLAGS.

  • Return Value

    A service routine does not return any value to the Tmax system, that is, a caller. In other words, a service routine will be declared as void.

  • Error

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

    Error Code Description

    [TPESVCERR]

    An invalid buffer is used; tpacall()/tpconnect() returns a cd; tpforward() was used instead of tpreturn() during an interactive communication; a TPEV_DISCONIMM event occurred; or an XA operation (tx_begin(), tx_rollback(), and tx_commit()) failed in transaction mode.

    [TPETIME]

    A transaction timeout occurs during a service routine or while a service request is being transmitted.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    
    SWITCH(TPSVCINFO *msg)
    {
        int switch;
        char *buf;
    
        buf = (char *)tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processing }
    
        strcpy(buf, msg->data);
        data process…
    
        if (switch>5)
           tpforward(“SERVICE1”, buf, 0, 0);
        else
           tpforward(“SERVICE2”, buf, 0, 0);
    }
  • Related functions

    tpalloc(), tpconnect(), tpreturn()

2.26. tpgetcliinfo

The tpgetcliinfo function retrieves the information of a client currently connected to the Tmax system.

  • Prototype

    #include <tmadmin.h>
    int tpgetcliinfo(int clid, struct tmadm_cliinfo_body *info)
  • Parameter

    Parameter Description

    clid

    The ID of the client to look for.

    info

    A pointer to a tmadm_cliinfo_body structure that receives information about the specified clid.

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

    The following shows the returned tmadm_cliinfo_body struct:

    struct tmadm_cliinfo_body {
        int no; /* cli index */
        int clid; /* CLID */
        int clhno;
        int count;
        int idle;
        int reserve_int[3];
        char status[TMAX_NAME_SIZE];
        char addr[TMAX_IPADDR_SIZE];
        char usrname[TMAX_NAME_SIZE];
        int qpcount;
        int emaxcount;
        int reserved1;
        int reserved2;
    };
    Member Description

    no

    The client number.

    clid

    The client ID. This is different from the client number.

    clhno

    The CLH number to which the client is currently connected.

    count

    The number of client requests that have been executed.

    idle

    The amount of time elapsed since the client first connected to the CLH.

    (Unit: seconds)

    reserve_int

    Currently not used. Reserved for future use.

    status

    The current status of a client request.

    • RUNNING : The requested service is currently running.

    • READY : The requested service is successfully terminated, or the service request has not been sent yet.

    • QUEUED : The request is waiting.

    addr

    The client’s IP address.

    usrname

    The client’s usrname value stored in tpinfo which was passed as an argument during tpstart.

    qpcount

    The number of client requests that have been purged.

    emaxcount

    The number of client requests that have exceeded the max limit for the queue.

    reserved1

    Currently not used. Reserved for future use.

    reserved2

    Currently not used. Reserved for future use.

  • Error

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. The type is NULL, or the specified clid is incorrect.

    [TPEITYPE]

    The function was called in an IPv6 protocol environment.

    [TPESYSTEM]

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

    [TPEOS]

    Dynamic allocation failed.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    
    PRINTCLIINFO(TPSVCINFO *msg)
    {
       int i, ret, clid;
       struct tmadm_cliinfo_body cliinfo = {0, };
    
       clid = tpgetclid();
       if (clid < 0)
          error routine..
    
        ret = tpgetcliinfo(clid, &cliinfo);
        if (ret < 0)
           error routine..
    
         printf("INPUT : data=%s\n", msg->data);
         printf("CLIINFO : no:%d clid:%d clhno:%d count:%d idle:%d status:%s addr:%s usrname:%s\n",
                 cliinfo.no, cliinfo.clid, cliinfo.clhno, cliinfo.count, cliinfo.idle,
                 cliinfo.status, cliinfo.addr, cliinfo.usrname);
    
           ...
    
         tpreturn(TPSUCCESS,0,(char *)msg->data, 0,0);
    }
  • Related function

    tpgetclid()

2.27. tpgetctx

The tpgetctx function copies the current client information to a CTX_T structure that was declared and allocated by the user. If tpgetctx() is used without tprelay(), the client will continue to wait for a response even after the service routine completes.

The information retrieved by tpgetctx() cannot be canceled with tpcancelctx(). Therefore, tprelay() must be used only in a service routine.

  • Prototype

    #include <tmaxapi.h>
    int tpgetctx (CTX_T *ctxp)
  • Parameter

    Parameter Description

    ctxp

    Retrieves and copies the client information stored with tpsavectx() to the CTX_T structure.

  • Example

    RELAY_SVC(TPSVCINFO *msg)
    {
        CTX_T *ctxp;
        ctxp=(CTX_T *)malloc(sizeof(CTX_T);
        ....
        ret = tpgetctx(ctxp);
        if (ret<0) {
            error process routine
        }
        .....
    }

2.28. tpgetdbsessionid

The tpgetdbsessionid function gets RM session information. When processing RM session information within a service, RM session information can be obtained using the tpsetdbsessionid callback function and the session ID can be retrieved using tpgetdbsessionid.

  • Prototype

    #include <tmaxapi.h>
    char * tpgetdbsessionid(int flags);
  • Parameter

    Parameter Description

    flags

    Not supported in the current version. Set to TPNOFLAGS.

  • Return Value

    Return Value Description

    Currently connected session ID

    The function call succeeded.

  • Example

    #include <usrinc/tmaxapi.h>
    ...
    EXEC SQL include sqlca.h;
    EXEC SQL begin declare section;
    ...
    char  h_ssid[20];
    EXEC SQL end declare section;
    
    int tpsetdbsessionid(char dbsessionid[MAX_DBSESSIONID_SIZE], int flags)
    {
        EXEC SQL SELECT TO_CHAR(USERENV(‘sessionid’)) into :h_ssid FROM dual;
        if ( sqlca.sqlcode != 0 ){
            printf( “getting session id fail = %d\n”,sqlca.sqlcode );
            return -1;
        }
        printf(“RM session id = %s\n”, h_ssid);
        memset(dbsessionid, 0x00, MAX_DBSESSIONID_SIZE);
        strcpy(dbsessionid, h_ssid);
        return 0;
    }
    
    FDLINS( TPSVCINFO *msg )
    {
        char *ssid;
        int ret;
        int flags = 0;
    
        printf(“ >>> current RM session id = %s\n”, h_ssid);
        ssid = tpgetdbsessionid(flags);
        tpreturn( ... );
    }

2.29. tpgetfclid

The tpgetfclid function retrieves the client ID of the client that initiated the first service request. This is useful when the current service was invoked as an n-th service through tpforward() or tprelay().

  • Prototype

    #include <tmaxapi.h>
    int  tpgetfclid(void)
  • Return Value

    Return Value Description

    An integer greater than or equal to 0

    The function call succeeded and returns an integer (greater than or equal to 0) that corresponds to the client number.

    -1

    The function call failed. The service was not running when the function was called.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    SERVICE(TPSVCINFO *msg)
    {
        int ret, clid;
        char *buf;
    
        buf = (char *)tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processing }
        strcpy(buf, msg->data);
        data process…
    
        clid = tpgetfclid();
        if (clid==-1) { error process }
    
        ret=tpsendtocli(clid, buf, strlen(buf), 0);
        if (ret==-1) { error processing }
        data process….
    
        tpreturn(TPSUCCESS,0,buf, strlen(buf), 0);
    }
  • Related function

    tpsendtocli()

2.30. tpgetmaxsvr

The tpgetmaxsvr function returns the maximum number of server processes that can run. It retrieves the value defined in the SERVER section of the configuration file. This function can only obtain the maximum count for the server process it belongs to.

  • Prototype

    #include <tmaxapi.h>
    int  tpgetmaxsvr(void)
  • Return Value

    Return Value Description

    Integer

    The function call succeeded and returns the maximum number of server processes that can run.

    -1

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

  • Error

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    SERVICE(TPSVCINFO *msg)
    {
        char *buf;
        buf = msg->data;
    
        data process...
        printf(“maxsvr : %d\n”,tpgetmaxsvr());
        data process...
        tpreturn(TPSUCCESS,0,buf, strlen(buf), 0);
    }
  • Related function

    tpgetminsvr()

2.31. tpgetmaxuser

The tpgetmaxuser function returns the maximum number of concurrent users on the node the server process belongs to.

  • Prototype

    #include <tmaxapi.h>
    int  tpgetmaxuser(void)
  • Return Value

    Return Value Description

    Integer

    The function call succeeded and returns the maximum number of concurrent users.

    -1

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

  • Error

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    SERVICE(TPSVCINFO *msg)
    {
        char *buf;
        buf = msg->data;
        data process...
        printf(“maxusr : %d\n”,tpgetmaxusr());
        data process...
        tpreturn(TPSUCCESS,0,buf, strlen(buf), 0);
    }

2.32. tpgetminsvr

The tpgetminsvr function returns the minimum number of server processes to run. It retrieves the MIN value defined in the SERVER section of the configuration file. This function can only obtain the minimum count for the server process it belongs to.

  • Prototype

    #include <tmaxapi.h>
    int  tpgetminsvr(void)
  • Return Value

    Return Value Description

    Integer

    The function call succeeded and returns the minimum number of server processes to run.

    -1

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

  • Error

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    SERVICE(TPSVCINFO *msg)
    {
        char *buf;
        buf = msg->data;
        data process...
        printf(“minsvr : %d\n”,tpgetminsvr());
        data process...
        tpreturn(TPSUCCESS,0,buf, strlen(buf), 0);
    }
  • Related function

    tpgetmaxsvr()

2.33. tpgetmynode

The tpgetmynode function retrieves the name and number of a specific node from the server.

  • Prototype

    #include <tmaxapi.h>
    char *tpgetmynode(int *nodeno)
  • Parameter

    Parameter Description

    nodeno

    The node name is returned in char * and the node number in nodeno.

  • Return Value

    Return Value Description

    Node name

    The function call succeeded.

    NULL

    The function call failed. No error number is set in tperrno even if an error occurs.

  • Example

    #include <usrinc/tmaxapi.h>
    SERVICE(TPSVCINFO *msg)
    {
        int i, clid, n;
        char *nodename;
        ...
        for (i = 0; i < msg->len; i++)
            msg->data[i] = toupper(msg->data[i]);
        ...
        if (nodename == NULL){  error processing }
        nodename = tpgetmynode((int *)&n);
        if (nodename == NULL){
            error processing
        }
        else {
            printf(“TOUPPER SERVICE node(%dth node) name = %s\n”, n, nodename);
        }
        ...
        tpreturn(TPSUCCESS,0,(char *)msg->data, 0,TPNOFLAGS);
    }

2.34. tpgetmysvgno

The tpgetmysvgno function retrieves the number of the server group the server belongs to. It is available on servers only. Generally, tpgetmysvgno is used with tpcallsvg() or tpacallsvg(), which requests services from a particular server group. This function enables services in the same server group to be called in a multi-server group environment grouped by COUSIN.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tpgetmysvgno(void);
  • Return Value

    Return Value Description

    Group number

    The function call succeeded and returns the number of the server group the service that called the function belongs to.

  • Example

    <Server program>

    FDLTOUPPER1(TPSVCINFO *msg)
    {
        FBUF    *sndbuf, *rcvbuf;
        int ret, i, mysvgno;
        char sndata[30], rcvdata[30];
        char svc[XATMI_SERVICE_NAME_LENGTH];
    
        sndbuf = (FBUF *)tpalloc(“FIELD”, NULL, 0)};
        rcvbuf = (FBUF *)tpalloc(“FIELD”, NULL, 0))
    
        /* tpcallsvg (mysvgno) */
        ret = func_tpcallsvg_myno(sndbuf, rcvbuf, msg->name);
        if(ret < 0)
            tpreturn(TPFAIL, 0, (char *)NULL, 0, 0);
        tpreturn(TPSUCCESS, 0, (char *)rcvbuf, 0, 0);
    }
    
    int func_tpcallsvg_myno(FBUF *sndbuf, FBUF *rcvbuf, char *svc)
    {
        int ret;
        char sndata[30], rcvdata[30];
        long rcvlen;
        int svgno;
    
        strcpy(sndata, “starbj81”);
        ret = fbput(sndbuf, INPUT, sndata, 0);
        svgno = tpgetmysvgno();
        ret = tpcallsvg(svgno, “FDLTOUPPER2”, (char *)sndbuf, 0, (char **)&rcvbuf,
                         &rcvlen, 0);
        if(ret < 0)
        {
          printf("tpcallsvg[%s] failed![%d][%s]\n",svc,tperrno, tpstrerror(tperrno));
          return -1;
        }
        fbprint(rcvbuf);
        fbinit(sndbuf, 1024);
        fbinit(rcvbuf, 1024);
        return 0;
    }
  • Related functions

    tpcallsvg(), tpacallsvg()

2.35. tpgetmysvrid

The tpgetmysvrid function returns the ID of a server process, which is assigned according to the SERVER section in the configuration file. If multiple instances of the same server process are running, each instance receives a unique server process ID. The IDs start from 0 and increment by 1. This function is available only within a service routine, meaning it can only be used in a server process.

  • Prototype

    #include <tmaxapi.h>
    int  tpgetmysvrid(void)
  • Return Value

    Return Value Description

    Integer

    The function call succeeded and returns an integer value (greater than or equal to 0) that correspond to the server process ID.

    -1

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

  • Error

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

    Error Code Description

    [TPEPROTO]

    The function was called under an inappropriate condition. For example, it was used in a client program.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    SERVICE(TPSVCINFO *msg)
    {
        char *buf;
        buf = msg->data;
        data process...
        printf(“mysvr : %d\n”,tpgetmysvrid());
        data process...
        tpreturn(TPSUCCESS,0,buf, strlen(buf), 0);
    }

2.36. tpgetnodename

The tpgetnodename function retrieves the node name specified by the server.

  • Prototype

    #include <tmaxapi.h>
    char *tpgetnodename(int nodeno)
  • Parameter

    Parameter Description

    nodeno

    The node number corresponding to the node name.

  • Return Value

    Return Value Description

    Node name

    The function call succeeded and returns the node name.

    NULL

    The function call failed. No error number is set in tperrno.

  • Example

    #include <usrinc/tmaxapi.h>
    
    SERVICE(TPSVCINFO *msg)
    {
        int i, clid, n;
        char *nodename;
        ...
        for (i = 0; i < msg->len; i++)
            msg->data[i] = toupper(msg->data[i]);
    
        nodename = (char *)tpgetnodename(n);
        if (nodename == NULL){
            error processing
        }
       else {
           printf(“%dth node name(original node name) = %s\n”, n, nodename);
       }
       ...
       tpreturn(TPSUCCESS,0,(char *)msg->data, 0,TPNOFLAGS);
    }

2.37. tpgetnodeno

The tpgetnodeno function retrieves the node number corresponding to the node name.

  • Prototype

    #include <tmaxapi.h>
    int tpgetnodeno(char *nodename)
  • Parameter

    Parameter Description

    nodename

    The node name corresponding to the node number.

  • Return Value

    Return Value Description

    Node number

    The function call succeeded. The node number is returned.

    -1

    The function call failed. No error number is set in tperrno.

  • Example

    #include <usrinc/tmaxapi.h>
    
    SERVICE(TPSVCINFO *msg)
    {
        int i, clid, n;
        char *nodename;
        ...
        for (i = 0; i < msg->len; i++)
            msg->data[i] = toupper(msg->data[i]);
    
        n = tpgetnodeno(“tmax”);
        if (n < 0){
            error processing
        }
        else {
            printf(“%s’s node no(original node no) = %d\n”, “tmax”, n);
        }
        ...
        tpreturn(TPSUCCESS,0,(char *)msg->data, 0,TPNOFLAGS);
    }

2.38. tpgetorgclh

The tpgetorgclh function retrieves the number of the CLH to which the specified client is currently connected.

  • Prototype

    #include <tmaxapi.h>
    int tpgetorgclh(int clid)
  • Parameter

    Parameter Description

    clid

    The ID of a client currently connected.

  • Return Value

    Return Value Description

    CLH number

    The function call succeeded. Returns the number of the CLH to which the specified client is currently connected.

    -1

    The function call failed. No error number is set in tperrno.

  • Example

    #include <usrinc/tmaxapi.h>
    
    SERVICE(TPSVCINFO *msg)
    {
        int i, clid, n;
        ...
        for (i = 0; i < msg->len; i++)
           msg->data[i] = toupper(msg->data[i]);
    
        n = tpgetorgclh((int)*(msg->cltid.clientdata));
        if (n < 0){
            error processing
        }
        else {
            printf(”clh number = %d\n”, n);
        }
        ...
        tpreturn(TPSUCCESS,0,(char *)msg->data, 0,TPNOFLAGS);
    }

2.39. tpgetorgnode

The tpgetorgnode function returns the number of the node to which the specified client is currently connected.

  • Prototype

    #include <tmaxapi.h>
    int tpgetorgnode(int clid)
  • Parameter

    Parameter Description

    clid

    The ID of a client currently connected.

  • Return Value

    Return Value Description

    Node number

    The function call succeeded. The node number is returned.

    -1

    The function call failed. No error number is set in tperrno.

  • Example

    #include <usrinc/tmaxapi.h>
    
    SERVICE(TPSVCINFO *msg)
    {
        int i, clid, n;
        char *nodename;
        ...
        for (i = 0; i < msg->len; i++)
            msg->data[i] = toupper(msg->data[i]);
    
        n = tpgetorgnode((int)*(msg->cltid.clientdata));
        if (n < 0){
            error processing
        }else {
            printf(”original node number = %d\n”, n);
        }
        ...
        tpreturn(TPSUCCESS,0,(char *)msg->data, 0,TPNOFLAGS);
    }

2.40. tpgetpeer_ipaddr

The tpgetpeer_ipaddr function returns a peer’s IP address (node) after the connection is established with the Tmax system. This function can obtain a peer’s IP address only when the client directly calls for the service.

If the service call is made indirectly, for example, the service the client calls is passed to or makes a call to another service, resulting in a garbage value being entered.

  • Prototype

    #include <tmaxapi.h>
    int  tpgetpeer_ipaddr(struct sockaddr *name,  int *namelen)
  • Parameter

    Parameter Description

    name

    The structure storing the address. In an IPv6 protocol envirionment, the struct sockaddr_in6 struct is used to retrieve the IP address. Additionally, using the struct sockaddr_storage struct allows retrieving the information both in IPv4 and IPv6 environments.

    namelen

    First initialized to the size of the structure passed with the name before calling the function. If the function successfully returns, the actual size of the structure alllocated to the name is saved.

  • Return Value

    Return Value Description

    Socket address

    The function call succeeded. The peer’s socket address is returned.

    -1

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

  • Error

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

    Error Code Description

    [TPINVAL]

    The parameter is invalid.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <netinet/in.h>
    #include <arpa/inet.h>
    #include <usrinc/atmi.h>
    #inlcude <usrinc/tmaxapi.h>
    ...
    
    DELETE(TPSVCINFO *msg)
    {
        struct sockaddr_in cli;
        char ipAddr[16];
        int cli_len, ret;
    
        data process...
        memset((char *)&cli, 0, sizeof(cli));
        ret = tpgetpeer_ipaddr((struct sockaddr *)&cli, &cli_len);
        if (ret == -1){
            error processing
        }
        else {
            memcpy(ipAddr, inet_ntoa(cli.sin_addr), 16);
        }
        printf(“ip = %s , port = %d\n”, ipAddr, ntohs(cli.sin_port));
        data process...
    
        tpreturn(TPSUCCESS, 0, 0, 0, 0);
    }

    The following is an example of using the function in an IPv6 protocol environment.

    #include <stdio.h>
    #include <netinet/in.h>
    #include <arpa/inet.h>
    #include <usrinc/atmi.h>
    #inlcude <usrinc/tmaxapi.h>
    ...
    
    DELETE(TPSVCINFO *msg)
    {
        struct sockaddr_storage cli_saddr;
        struct sockaddr_in *cli_sin4;
        struct sockaddr_in6 *cli_sin6;
        char ipaddrbuf[INET6_ADDRSTRLEN];
        const char *ipaddr = NULL;
        int cli_len, ret;
        int portno;
    
        data process...
        memset((char *)&cli_saddr, 0, sizeof(cli_saddr));
        cli_len = sizeof(cli_saddr);
        ret = tpgetpeer_ipaddr((struct sockaddr *)&cli_saddr, &cli_len);
        if (ret == -1){
            error processing
        }
        else {
            if (cli_saddr.ss_family == AF_INET) {
                cli_sin4 = (struct sockaddr_in *)&cli_saddr;
                ipaddr = inet_ntop(AF_INET, &(cli_sin4->sin_addr), ipaddrbuf, sizeof(ipaddrbuf));
                portno = ntohs(cli_sin4->sin_port);
            } else if (cli_saddr.ss_family == AF_INET6) {
                cli_sin6 = (struct sockaddr_in *)&cli_saddr;
                ipaddr = inet_ntop(AF_INET6, &(cli_sin6->sin6_addr), ipaddrbuf, sizeof(ipaddrbuf));
                portno = ntohs(cli_sin6->sin6_port);
            }
            if (ipaddr == NULL)
                ipaddr = "unknown";
        }
        printf(“ip = %s , port = %d\n”, ipaddr, portno);
        data process...
    
        tpreturn(TPSUCCESS, 0, 0, 0, 0);
    }
  • Related functions

    tpgetpeername(), tpgetsockname(), tpstart()

2.41. tpgetsvcname

The tpgetsvcname function retrieves the name of the service using index. The parameter is defined using the service index value in cltid.clientdata[3] of TPSVCINFO in the Loss service routine which is called when the reply message is discarded. This function is only available in Tmax servers, not in Tmax clients. As the returned buffer is internal static buffer, you should copy it to an additional buffer to use without changing the contents of the buffer.

  • Prototype

    #include <tmaxapi.h>
    char* tpgetsvcname(int svc_index)
  • Parameter

    Parameter Description

    svc_index

    Index of the service.

  • Return Value

    Return Value Description

    Service name

    The function call succeeded and returns the address of the buffer storing the service name.

    NULL

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

  • Error

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

    Error Code Description

    [TPEINVAL]

    The svc_index was passed in an incorrect range.

    [TPENOENT]

    The svc name for the svc_index does not exist.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    SVC01(TPSVCINFO *msg)
    {
       int i;
    
       printf("\nSVC01 service is started!\n");
       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);
       sleep(10);
       tpreturn(TPSUCCESS,0,(char *)msg->data, 0,0);
    }
    
    LOSS_SVC(TPSVCINFO *msg)
    {
       long svcindex;
       char *svcname;
    
       printf("\nLOSS_SVC service is started!\n");
       printf("INPUT : data = %s\n", msg->data);
       printf("TPERROR  : %d\n", msg->cltid.clientdata[1]);
       printf("TPURCODE : %d\n", msg->cltid.clientdata[2]);
    
       svcindex = msg->cltid.clientdata[3];
       printf("SVC INDEX Of Discarded Message : %ld\n", svcindex);
    
       svcname = tpgetsvcname((int)svcindex);
       if(NULL == svcname) {
          printf("tpgetsvcname is failed!!\n");
       } else {
          printf("SVC Name Of Discarded Message  : %s\n", svcname);
       }
       tpreturn(TPSUCCESS, 0, (char*)msg->data, 0, 0);
    }

2.42. tpgetsvrseqno

The tpgetsvrseqno function returns a serial number for server processes of the same server type. This number is used to identify multiple running instances of a server process, as specified by the MIN and MAX values in the SERVER section of the Tmax configuration file. The serial numbers start at 0 and increment by 1 for each operating server process.

For example, if five server processes are running for svr1, the serial numbers will be 0 through 4. If the server process with serial number 3 is stopped, the same serial number (3) will be assigned to it when the server is restarted using tmboot -s or through autorestart.

  • Prototype

    #include <tmaxapi.h>
    int  tpgetsvrseqno(void)
  • Return Value

    Return Value Description

    Integer

    The function call succeeded and returns an integer (greater than or equal to 0) that corresponds to the serial number of the server process.

    -1

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

  • Error

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    SERVICE(TPSVCINFO *msg)
    {
        char *buf;
        printf(“\nINPUT : %s\t processing svr no : %d\n”, msg->data, tpgetsvrseqno());
        data process....
        tpreturn(TPSUCCESS, buf, 0, );
    }

2.43. tpissetfd

The tpissetfd function checks whether data has arrived on a socket FD from a UCS process in a server. It is used to schedule external sockets in UCS-type server processes.

  • Prototype

    #include <ucs.h>
    int  tpissetfd (int fd)
  • Parameter

    Parameter Description

    fd

    The FD in the fdset to test.

  • Return Value

    Return Value Description

    Positive value

    The message arrived.

    0

    No message arrived.

    -1

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

  • Error

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <sys/socket.h>
    #include <netinet/in.h>
    #include <errno.h>
    #include <usrinc/ucs.h>
    ...
    
    #define SERV_ADDR “168.126.185.129”
    #define SERV_PORT 1500
    
    int fd_read(int, char *, int);
    extern int errno;
    
    int usermain(int argc, char *argv[])
    {
        ...
        int listen_fd, n, newfd;
        struct sockaddr_in my_addr, child_addr;
        socklen_t child_len;
    
        buf = tpalloc(“STRING”, NULL, 0);
        if (buf == NULL){ error processing }
    
        memset((void *)&my_addr, NULL, sizeof(my_addr));
        memset((void *)&child_addr, NULL, sizeof(child_addr));
    
        listen_fd = socket(AF_INET, SOCK_STREAM, 0);
        if (listen_fd == -1){ error processing }
    
        my_addr.sin_family = AF_INET;
        inaddr = inet_addr(SERV_ADDR);
        my_addr.sin_port = htons((unsigned short)SERV_PORT);
        if (inaddr != -1)
            memcpy((char *)&my_addr.sin_addr, (char *)&inaddr, sizeof(inaddr));
    
            ret = bind(listen_fd, (struct sockaddr *)&my_addr, sizeof(my_addr));
            if (ret == -1){ error processing }
            ret = listen(listen_fd, 5);
            if (ret == -1){ error processing }
    
            tpsetfd(listen_fd);
            ...
            while(1) {
                n = tpschedule(10);
                ...
                if (n == UCS_USER_MSG){
                    if (tpissetfd(listen_fd)) {
                        child_len = sizeof(child_addr);
                        newfd = accept(listen_fd, &child_addr, &child_len);
                        if (newfd == -1){ error processing }
                        tpsetfd(newfd);
                }
                if (tpissetfd(newfd)){
                    /* Read the buffer from the socket */
                    fd_read(newfd, buf, 1024);
                    ret = tpcall(“SERVICE”, (char *)buf, sizeof(buf), (char **)&buf,
                                  (long *)&rlen, TPNOFLAGS);
                    if (ret == -1){ error processing }
                    ...
                    tpclrfd(newfd);
                    close(newfd);
                }
            ...
            }
        }
        return 1;
    }
  • Related functions

    tpissetfd(), tpsetfd()

2.44. tpissetfd_w

The tpissetfd_w function checks a FDSET used by a UCS-type process to determine whether there is data ready to be sent to a specified socket FD. Unlike tpissetfd(), which checks both the Readable and Writable FDSETs, tpissetfd_w() only checks the Writable FDSET. The FD parameter specifies the socket FD to be checked.

  • Prototype

    #include <ucs.h>
    int tpissetfd_w(int fd)
  • Parameter

    Parameter Description

    fd

    The FD in the fdset to test.

  • Return Value

    Return Value Description

    Positive value

    The message arrived.

    0

    No message arrived.

    -1

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

  • Error

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

    Error Code Description

    [TPESYSTEM]

    The function call succeeded.

    [TPEOS]

    An error occurred in the operating system.

  • Related functions

    tpissetfd(), tpsetfd()

2.45. tpprechk

The tpprechk function is a user-defined callback routine used to check the status of a Resource Manager (RM). This function is called before a client connects to the Tmax system. Any other initialization processes should be handled within tpsvrinit().

If a blocking condition occurs within a tpprechk() routine, the service will remain in a READY state, while the server will be in a NOREADY state. A process can be terminated using the -i option of tmdown.

If tpprechk() is not used and a blocking condition occurs during RM status checking in tpsvrinit(), the service will continue to be scheduled until a reply is received, which means the client must wait until the service timeout expires. Using tpprechk() before tpsvrinit() allows the system to verify RM readiness without causing clients to wait unnecessarily.

  • Prototype

    #include <tmaxapi.h>
    int tpprechk(void)
  • Return Value

    Return Value Description

    Positive value

    The function call succeeded.

    Negative value

    The function call failed. The server should be restarted.

When tpsleep() is used within the tpprechk() function, the following behaviors may occur:

  • If shared memory is being initialized while TmaxTrace is logging tpsleep(), the server name may appear as '$svr'.

  • If the process is not connected to CLL/TMM during this time, a TPEPROTO error may occur while logging.

2.46. tpregancb

The tpregancb function registers a callback function to receive events generated by the admnoti in tmadmin. If no callback function is registered, received events are ignored.

After a callback function of type TPADMNOTI is defined, the name of the function is passed as an argument of tpregancb().

  • Prototype

    # include <tmaxapi.h>
    typedef int (*TPADMNOTI)(int reqno, int len, char *args)
    int  tpregancb(TPADMNOTI callback)
  • Parameter

    Parameter Description

    callback

    The callback function to receive events generated by the admnoti command in tmadmin.

    The following are the parameters passed when the specified callback function is called if an event is received.

    Parameter Description

    reqno

    The number of a request by the admnoti command in tmadmin.

    len

    The length of the notification message string.

    args

    The buffer storing the notification message string. The returned buffer will be freed by the server library.

  • Return Value

    • Return value

      Return Value Description

      1

      The function call succeeded.

      -1

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

    • Return value of a callback function

      The return values for callback functions are currently not effective, but reserved for future use.

      Return Value Description

      Integer (greater than or equal to 0)

      Event handling is successful.

      Negative value

      Event handling failed.

  • Error

    If tpregancb() fails, the following codes is set in tperrno.

    Error Code Description

    [TPEINVAL]

    The function address specified for the callback is incorrect.

  • Example

    ...
    #include <stdio.h>
    #include <usrinc/tmaxapi.h>
    
    int admnoti(int reqno, int len, char *args);
    void foo();
    void bar();
    TMAXSVRINFO svrinfo;
    
    int tpsvrinit(int argc, char *argv[])
    {
       tmax_my_svrinfo(&svrinfo);
       if (tpregancb(admnoti) < 0)
          error processing;
    }
    
    int admnoti(int reqno, int len, char *args)
    {
       printf("svg[%s] svr[%s] spri[%d] reqno[%d] message[%s]",
          svrinfo.svgname, svrinfo.svrname, svrinfo.spri, reqno, args);
       if (strncmp(args, "foo", 3) == 0) {
          foo();
       } else if (strncmp(args, "bar", 3) == 0) {
          bar();
       } else {
          return -1;
       }
       return 0;
    }
  • Related function

    tpunregancb()

2.47. tpregcb

The tpregcb function sets a routine that receives a response for an asynchronous UCS request from a server. This routine is used when a UCS type process receives a response from a server program. It is used instead of tpgetrply() in a UCS-type server process.

  • Prototype

    # include <ucs.h>
    int  tpregcb (UcsCallback)
  • Parameter

    Parameter Description

    UcsCallback

    The callback function that handles a response for an asynchronous request in a UCS.

    The UCSMSGINFO structure contains the response message information used to process asynchronous responses in UCS-type servers. The callback routine registered in the tpregcb() function receives this structure as the argument, and executes the response handling logic.

    The response message contains the user response code, error code, message type, connection descriptor, and the length of the response data and the pointer to the response data itself. The UCSMSGINFO structure is defined in the header file <ucs.h> with the following items:

    typedef struct {
            long    urcode;     /* user response code */
            int     errcode;    /* response error code */
            int     msgtype;    /* message type (used as internal identifier) */
            int     cd;         /* connection descriptor */
            int     len;        /* length of response data */
            char    *data;      /* pointer to the response data */
    } UCSMSGINFO;
    Field Description

    urcode

    The user-defined code in the response message.

    errcode

    The error code for the response.

    msgtype

    The message type identifier that is internally used.

    cd

    The connection descriptor for the response.

    len

    The actual length of the response data.

    data

    The pointer to the response data.

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    ...
    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/ucs.h>
    
    void reply_receive(UCSMSGINFO *reply);
    DUMMY(TPSVCINFO *msg)
    {
        data process ….
    }
    
    int usermain(int argc, char *argv[])
    {
        int ret;
        char *buf
    
        ret = tpregcb(reply_receive);
        if (ret == -1){ error processing }
        buf=tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processing }
        data process…
        while(1)
        {
            ...
            tpschedule(3);
            cd = tpacall(“SERVICE”, buf, strlen(buf), TPNOFLAGS);
            if (cd < 0) { error processing }
            ...
        }
    }
    
    void reply_receive(UCSMSGINFO *reply)
    {
        rtcd = reply->errcode;
    
        if(rtcd != 0)
        {
             printf("[tperrno(%d) : %s]\n", rtcd,tpstrerror(rtcd));
             /* Error handling code */
        }
    
        printf(“data....%s\n”, reply->data);
    }
  • Related function

    tpunregcb()

2.48. tprelay

The tprelay function is available only in a UCS server process. It can be used in multiple nodes. When a client requests a service, this function requests another service with information about the client. Since the service called by the function notices that it was called by the client, not the function, it returns the result to the client.

A service execution result can be sent to a client that called for a request, so a fast response can be induced with a simple structure in a UCS process. In general, this function is useful when processing a service, because it is integrated with an external application which is a program routine that can obtain results after calling a service two or three times.

If a server process is terminated after saving client information using tpsavcctx() or tpgetctx() but before a request is sent to another service using tprelay(), an error response will be sent to the service caller automatically. For more information about error responses, refer to the CTX_EREPLY option in the SERVER section of the environment configuration. These operations are supported for Tmax versions 5 SP2 or later. In earlier versions, an error response will not be sent to the service caller.

  • Prototype

    #include <ucs.h>
    int  tprelay(char *svc, char *data, long len, long flags, CTX_T *ctxp);
  • Parameter

    Parameter Description

    svc

    The service name registered in the Tmax configuration file.

    data

    The data to be sent when the service is called. If not NULL, must use a buffer allocated by tpalloc().

    len

    The length of the data to be sent. For CARRAY and X_OCTET structure array types, this parameter must be specified.

    flags

    Not currently supported. Set to TPNOFLAGS.

    ctxp

    The information structure retrieved by tpgetctx() or tpsavectx().

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, ctxp is NULL, or an incorrect buffer is used.

    [TPESYSTEM]

    An error occurred in the Tmax system.

  • Example

    ...
    #include <stdio.h>
    #include <usrinc/ucs.h>
    CTX_T *ctx = NULL;
    
    DUMMY(TPSVCINFO *msg)
    {
        data process ...
    }
    
    usermain(int argc, char *argv[])
    {
        int ret, i;
        char *rcvbuf, *sndbuf;
        long sndlen;
    
        rcvbuf = (char *)tpalloc(“CARRAY”,NULL, 1024);
        if (rcvbuf == NULL){ error processing }
        i = 0;
    
        while(1) {
            tpschedule(1);
            if (ctx != NULL)
            {
                i++;
                if ((sndbuf = (char *)tpalloc(“CARRAY”,NULL, 1024)) == NULL)
                { error processing }
                else
                {
                     ...
                     ret = tprelay(“TPRETURN”, sndbuf, sndlen, 0, ctx);
                     if (ret==-1) { error processing }
                     data process...
                     ctx = NULL;
                     tpfree(sndbuf);
                 }
            }
        }
    }
    
    int RELAY(TPSVCINFO *rqst)
    {
       ...
       ctx = tpsavectx();
       tpreturn(TPSUCCESS, 0, rqst->data, rqst->len, 0);
    }
  • Related functions

    tpreturn(), tpforward()

2.49. tpresumetx

The tpresumetx function resumes a suspended global transaction.

Suspended global transactions can be resumed using tpresumetx() or tpsuspendtx().

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tpresumetx(TRANID *tranid, int flags)
  • Parameter

    Parameter Description

    tranid

    A pointer to the TRANID structure. The pointer must be the same as the one that was used when calling tpresumetx() or tpsuspendtx().

    flags

    Not supported in the current version. Set to TPNOFLAGS.

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

    The tranid is NULL, or the flag is not set to TPNOFLAGS.

    [TPEPROTO]

    The transaction cannot be resumed.

    [TPETRAN]

    Restarting the transaction failed.

  • Related function

    tpsuspendtx()

2.50. tpreturn

The tpreturn() function indicates the completion of a service routine. It functions similarly to a return statement in the C language. When tpreturn() is called, the service routine returns control to the Tmax system. To return a service routine correctly, tpreturn() must be called from within the service routine itself.

A tpreturn() also sends a reply message for the service. If a program is waiting to receive a reply using tpcall(), tpgetrply(), or tprecv(), the reply will be transferred through the receiver’s buffer once tpreturn() is successfully executed.

In addition, tpreturn() allows interactive services to terminate interactive communication. A service routine cannot call tpdiscon() directly. To ensure correct behavior, a program connected to an interactive service should not call tpdiscon(). Instead, it must wait for a completion notification from the interactive service, such as a TPEV_SVCSUCC or TPEV_SVCFAIL event transmitted via tpreturn().

If a service routine is operating in transaction mode, and the client or service that invoked it did not start a transaction explicitly (i.e., tx_begin was not called), the tpreturn() will commit or roll back as part of a transaction if the return value is TPSUCCESS. A service can be invoked multiple times within the same global transaction; therefore, it will not be fully committed or rolled back until the transaction initiator explicitly calls tx_commit or tx_rollback.

tpreturn() must be called after all replies from services requested by the service routine have been received. Otherwise, a [TPESVCERR] error or a TPEV_SVCERR event may be returned to the program that communicated with the service routine, depending on service characteristics. Any replies that are not received will be automatically ignored by the Tmax system, and the corresponding descriptors will be invalidated.

Similarly, tpreturn() must be called after all interactive communication connections initiated by the service have ended. Failure to do so may result in a [TPESVCERR] error or a TPEV_SVCERR event being returned to the communicating program. Additionally, a forcible disconnection event, such as TPEV_DISCONIMM, may be sent to the service and all associated connections.

In interactive communication, if a service routine lacks communication control when calling tpreturn(), two outcomes are possible:

  1. If tpreturn() is called with rval = TPFAIL and data = NULL, a TPEV_SVCFAIL event will be sent to the communication initiator.

  2. In all other cases, a TPEV_SVCERR event will be sent. Because an interactive service can only have one interactive communication not initiated by the service itself, the Tmax system knows the descriptor to which data or events should be transmitted. For this reason, the descriptor is not passed as a parameter to tpreturn().

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

  • Prototype

    # include <atmi.h>
    void  tpreturn (int  rval, long  rcode, char  *data, long  len, long  flags)
  • Parameter

    Parameter Description

    rval

    The following are available for rval. Any other values than those listed below will all be considered TPFAIL.

    • TPSUCCESS

      The service is successfully completed. If data exists and no error occurs during a tpreturn() execution, the data will be transmitted. If the caller is in transaction mode, a part of this transaction will be determined as it can be committed. It allows the other services belonging to the transaction to be committed if all of them are successfully completed and ready for commit. But the transaction will be rolled back if any of them fails.

      Note that calling tpreturn() does not mean to complete the entire transaction. In addition, if there is any waiting reply or interactive connection or a job performed within the service tries to roll back the transaction, the message will be sent as a failure even though the caller has returned TPSUCCESS. That is, the receiver of the reply will receive a [TPESVCERR] error or TPEV_SVCERR event. Note that, if transaction is rolled back within a service routine, rval is set to TPFAIL. If TPSUCCESS returns in an interactive service, a TPEV_SVCSUCC event will occur.

    • TPFAIL

      The service is terminated due to an error in the application. The error is returned to the program that receives the reply. That is, the call to receive the reply fails and the receiver receives a [TPSVCFAIL] or TPEV_SVCFAIL event. This value cannot sent data.

      If the caller is in transaction mode and uses auto-transaction, tpreturn() will roll back the transaction. The transaction might have already been determined to be rolled back.

    • TPEXIT

      When a service is returned, this flag is used to forcibly terminate the server process. Any process closed via tpexit() can be restarted through TMM.

    • TPDOWN

      Similar to TPEXIT, but a process terminated through TPDOWN cannot be restarted using TMM.

    • TMSUCCESS

      Equivalent to TPSUCCESS.

    • TMFAIL

      Equivalent to TPFAIL.

    rcode

    The rcode is a return code defined by the user in the application. It is transmitted to the program that receives the service reply. This code is sent regardless of the rval value, as long as the reply can be successfully delivered to the client.

    The client is considered to have received the reply successfully in the following cases: * The receiving call was successful. * A reply was returned through [TPSVCFAIL]. * The client received either a TPEV_SVCSUCC or TPEV_SVCFAIL event.

    The rcode value is transferred to the receiver using the global variable tpurcode.

    data

    The reply data to be sent. If not NULL, it must indicate a buffer that was allocated by tpalloc() in advance. If the buffer is the same as the one transferred to the service routine, the Tmax systems will handle it.

    Therefore, the service routine writer does not need to take care of whether to or not to free the buffer. Indeed, if theuser attempts to free the buffer, the attempts will fail. However, if the buffer transferred with tpreturn() is not the same as the one transferred along with the service request, tpreturn() will free the buffer.

    len

    The length of the data sent.

    If the data points to a buffer that does not require a specified length, the len will be ignored (0 is used in general). But if data points to a buffer that requires a specified length, the len must not be 0. If data is NULL, the len is ignored. In this case, if the program that calls the service is waiting for a reply, the reply without any data will be transmitted. If no reply is expected, tpreturn() will free the data and returns without transmitting any reply, accordingly.

    flags

    Not currently supported. Must be set to 0.

    If the service is an interactive type, data would not be transferred in the following two cases:

    The interactive service was already disconnected when tpreturn( ) is called. That is, the caller receives TPEV_DISCONIMM event. In this case, the tpreturn() simply ends the service routine and if it is in a transaction mode, it will roll back the current transaction. In this case, the caller’s data cannot be transferred.

    If the caller does not have the communication control, either TPEV_SVCFAIL or TPEV_SVCERR event will be transferred to the communication starter as mentioned earlier. Regardless of the event that the communication starter receives, no data is transferred. If the communication starter receives the TPEV_SVCFAIL event, the return code could be used as a tpurcode variable of the starter.

  • Return Value

    The service routine does not return any value to the caller, that is, the Tmax systems. It is a rule that the service routine returns with tpreturn(). If the service routine returns using a return sentence of C language, instead of using tpreturn(), the server will return a service error to the service requester. In addition, a connection that has been kept for interactive communication is disconnected forcibly and all the replies that are waiting asynchronously are ignored.

    If the server is in transaction mode, the transaction will be rolled back. In addition, if tpreturn() is used outside the service routine, it will simply return without performing anything.

  • Error

    Since tpreturn() ends a service routine, if an error occurs while a parameter is being processed, it cannot be not transferred to the service routine, the caller. Errors are sent as follows.

    Type Description

    Synchronous/Asynchronous communication

    For programs that receive the service result through tpcall() or tpgetrply(), the tperrno is set to [TPESVCERR].

    Interactive communication

    For programs using tpsend() or tprecv(), a TPEV_SVCERR event is generated.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    
    SERVICE1(TPSVCINFO *msg)
    {
        char *buf;
        long len;
    
        buf=tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processsing }
        buf=msg->data;
        data process....
    
        ret=tpcall(“SERVICE2”, buf, sizeof(buf), &buf, &len, TPNOFLAGS);
        if (ret==-1) { error processing }
        data process....
    
        if (buf !=”SUCCESS”) {
            printf(“svc fail..\n”);
            tpreturn (TPFAIL, -1, NULL,0,0);
        }
        else {
            tpreturn(TPSUCCESS, 0, msg->data, msg->len, 0);
        }
    }
  • Related functions

    tpalloc(), tpcall(), tpconnect(), tpdiscon(), tpgetrply(), tprecv(), tpsend()

2.51. tpsavectx

The tpsavectx function manages client information in a UCS process. This function is used along with tprelay(), which forwards a request to another service. It works in the same way as a general service program, which calls for other services as a tpforward(). Consequently, a called service sends a processing result to the client.

The tpsavectx() function can be used to communicate with an external process that has heterogeneous protocols that are time-consuming and can block channels.

The function can be used in the following format:

Client → svc1 → svc2(service, tpsavectx) → External channel
Client ← svc3 ← svc2(usermain, tprelay) ← External channel
  1. The client sends a service request to svc1.

  2. svc1 calls svc2 using tpforward (...TPNOREPLY).

  3. svc2 is a service which runs in a UCS process, and it calls tpsavectx() in a service routine to save the client information to communicate with an external system.

  4. The result is sent to a usermain and forwarded to svc3 via tprelay(). svc3 considers that svc2 has called it via tpforward(), so it finally sends the result to the client.

In this process, because svc1 calls a service via tpforward with the TPNOREPLY flag, it can prevent channel congestion. This enables a large numbers of clients to be handled with a small number of processes. Additionally, a single UCS process can act as both the sending and receiving processes. It can organize a relatively simple system with efficient system management.

  • Prototype

    #include <ucs.h>
    CTX_T * tpsavectx(void)
  • Return Value

    Return Value Description

    CTX_T

    The function call succeeded.

    NULL

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

  • Error

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

    Error Code Description

    [TPEPROTO]

    The tpsavectx() function must be used within a service routine. If it is used outside a service routine, a TPEPROTO error occurs. It cannot be used in tpsvrinit() or tpsvrdone().

    [TPESYSTEM]

    A memory allocation error occurred.

  • Example

    ...
    #include <stdio.h>
    #include <usrinc/ucs.h>
    
    CTX_T *ctx = NULL;
    
    usermain(int argc, char *argv[])
    {
        int ret, i;
        char *rcvbuf, *sndbuf;
        long sndlen;
    
        rcvbuf = (char *)tpalloc(“CARRAY”,NULL, 1024);
        if (rcvbuf == NULL){ error processing }
    
        i = 0;
        while(1) {
            tpschedule(1);
            if (ctx != NULL)
            {
                i++;
                if ((sndbuf = (char *)tpalloc(“CARRAY”,NULL, 1024)) == NULL)
                { error processing }
                else
                {
                    ...
                    ret = tprelay(“TPRETURN”, sndbuf, sndlen, 0, ctx);
                    if (ret==-1) { error processing }
                    data process...
                    ctx = NULL;
                    tpfree(sndbuf);
                }
            }
        }
    }
    
    int RELAY(TPSVCINFO *rqst)
    {
        ...
        ctx = tpsavectx();
        tpreturn(TPSUCCESS, 0, rqst->data, rqst->len, 0);
    }
  • Related functions

    tpreturn(), tpforward(), tprelay()

2.52. tpschedule

The tpschedule function waits for data sent from a UCS server process. It is available only in UCS-type server processes. The function sleeps for up to the specified maximum timeout period, and if data arrives within this period, it returns immediately.

tpschedule() returns after the service corresponding to the received data has been automatically executed. Therefore, the user must not execute the service manually after the data arrival.

Services are always executed by the system. Keep this in mind, even when running a UCS-type service program.

  • Prototype

    #include <ucs.h>
    int  tpschedule(int timeout)
  • Parameter

    Parameter Description

    timeout

    The amount of time to wait in seconds.

    • -1 : Only checks for data arrival and immediately returns.

    • 0 : Waits indefinitely for data to be arrived.

  • Return Value

    Return Value Description

    Positive integer

    The function call succeeded and data arrived.

    -1

    An error occurred because no data arrived within the timeout period or the function call failed. If no data arrives within the timeout period, -1 is returned and tperrno is set to 13 (TPETIME). In other cases, different error codes are set.

  • Error

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

    [TPETIME]

    No data arrived until the timeout period expired.

    [TPEPROTO]

    The function was called under an inappropriate condition. For example, it was called from within a service.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/ucs.h>
    int usermain(int argc, char *argv[])
    {
        ...
        while(1)
        {
            ...
            tpschedule(3);
            ret = tpcall(“SERVICE”, (char *)buf, strlen(buf), (char **)&buf,
                          (long *)&rlen, TPNOFLAGS);
            if (ret == -1) { error processing}
            ...
        }
    }
  • Related functions

    tpsleep(), tp_sleep(), tp_usleep()

2.53. tpsendtocli

The tpsendtocli function sends an unrequested message to a specified client. It is available only on servers. If tpbroadcast() sends an unsolicited message to any client connected to the Tmax systems, tpsendtocli() sends a message only to a client that has requested the service provided by the server process.

  • Prototype

    # include <tmaxapi.h>
    int  tpsendtocli (int  clid,  char  *data,  long  len,  long  flags)
  • Parameter

    Parameter Description

    clid

    A unique client number retrieved with tpgetclid().

    data

    A buffer allocated by tpalloc(). If data points to a buffer that does not require a specified length, the len value is ignored and 0 is used by default. If data points to a buffer that requires a specified length, len cannot be 0. If data is NULL, len is ignored.

    len

    The length of the buffer to be sent.

    flags

    Determines the function behavior.

    The following flags are available.

    • TPNOFLAG(0)

      Messages must be received by the client. However, if the client cannot process messages quickly enough, it may take a long time to receive the requested result.

    • TPUDP

      This flag does not indicate that communication with the client uses the UDP protocol. If a caller transmits data while the internal buffer (used for message transfer) is full, the data may be discarded. In other words, this flag allows data to be lost in situations similar to UDP communication.

    • TPFLOWCONTROL

      Checks the status of the client to determine whether another request message can be sent. If too many messages are accumulated, tpsendtocli() returns -1, and tperrno is set to TPEQFULL. This flag helps reduce the load on the Tmax system.

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEBADDESC]

    The clid is invalid.

    [TPEPROTO]

    tpsendtocli() was called under an inappropriate condition.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

    [TPEQFULL]

    A duplicate message exists.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    SERVICE(TPSVCINFO *msg)
    {
        int ret, clid;
        char *buf;
    
        buf = (char *)tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processing }
        strcpy(buf, msg->data);
        data process….
        clid = tpgetclid();
        if (clid==-1) { error processing }
    
        ret=tpsendtocli(clid, (char *)buf, 0, 0);
        if (ret==-1) { error processing }
        tpreturn(TPSUCCESS, 0, 0, 0);
    }
  • Related function

    tpbroadcast()

2.54. tpsetcliwatcher

The tpsetcliwatcher function detects a client shutdown and performs subsequent operations in a UCS server. It is used in UCS server processes. When the client corresponding to the specified clid shuts down, a callback function is invoked.

The function returns only after the registration process in the CLH, to which the client is connected, is complete. The callback function is invoked when tpschedule() is called and a client shutdown event is detected.

tpsetcliwatcher() can be called from within a service routine or from usermain().

  • Prototype

    #include <usrinc/ucs.h>
    int tpsetcliwatcher(int clid, CliWatcherCallback callback, void *args, int flags)
  • Parameter

    Parameter Description

    clid

    The client ID retrieved with tpgetclid(). If the clid does not correspond to a client (for example, if it belongs to a server), a TPEINVAL error occurs.

    callback

    The callback function that is invoked when a client shuts down. It must be defined using the CliWatcherCallback type.

    args

    An argument passed to the callback function when it is invoked. It can be defined by the user with any value.

    flags

    Currently not used.

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

    The parameter is invalid. For example, the clid value does not correspond to a client, or an incorrect argument is used.

    [TPENOTREADY]

    The client corresponding to the specified clid is not connected.

    [TPEOS]

    The call failed due to a memory allocation failure.

    [TPESYSTEM]

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

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/ucs.h>
    
    void logout_callback(int clid, int reason, void *args) {
            printf("[%s] clid:%#x, args:%p, reason:%d\n", "CALLBACK", clid, args, reason);
    }
    
    LOGIN(TPSVCINFO *msg) {
            int clid, ret;
            time_t curtime = time(NULL);
    
            clid = tpgetclid();
            ret = tpsetcliwatcher(clid, logout_callback, (void *)curtime, TPNOFLAGS);
    
            printf("[%s] clid:%#x, curtime:%ld, set_watch:%d(%s), data:%s\n",
                            msg->name, clid, curtime, ret, tpstrerror(tperrno), msg->data);
    
            tpreturn(TPSUCCESS, 0, NULL, 0, 0);
    }
  • Related functions

    CliWatcherCallback(), tpclrcliwatcher()

2.55. tpsetdbsessionid

The tpsetdbsessionid() function configures RM session information. It is used as a callback function. By setting the RM session information, it eliminates the need to process TM session information for every service.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tpsetdbsessionid (char dbsessionid[MAX_DBSESSIONID], int flags);
  • Parameter

    Parameter Description

    dbsessionid

    The developer writes a routine to retrieve and store an ID value in dbsessionid. The Tmax engine calls the tpsetdbsessionid() routine each time it connects to RM to update the session ID to the latest value and manage it internally.

    flags

    Not supported in the current version. Set to TPNOFLAGS.

  • Example

    #include <usrinc/tmaxapi.h>
    ...
    EXEC SQL include sqlca.h;
    EXEC SQL begin declare section;
    ...
    char  h_ssid[20];
    EXEC SQL end declare section;
    
    int tpsetdbsessionid(char dbsessionid[MAX_DBSESSIONID_SIZE], int flags)
    {
        EXEC SQL SELECT TO_CHAR(USERENV(‘sessionid’)) into :h_ssid FROM dual;
        if ( sqlca.sqlcode != 0 ){
            printf( “getting session id fail = %d\n”,sqlca.sqlcode );
            return -1;
        }
        printf(“RM session id = %s\n”, h_ssid);
    
        memset(dbsessionid, 0x00, MAX_DBSESSIONID_SIZE);
        strcpy(dbsessionid, h_ssid);
        return 0;
    }
    
    FDLINS( TPSVCINFO *msg )
    {
        ...
    }

2.56. tpsetsvctimeout

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

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

  • Prototype

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

    Parameter Description

    sec

    The service timeout period in seconds.

    flags

    Currently not used.

  • Return Value

    Return Value Description

    0

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <stdlib.h>
    #include <usrinc/tmaxapi.h>
    #include <usrinc/tdlcall.h>
    
    TOUPPER(TPSVCINFO *msg)
    {
            int             i;
    
            if ( tpsetsvctimeout(10, 0) < 0 )
                  ;
                //error handle code
            printf("TOUPPER service is started!\n");
            sleep(15);
            printf("INPUT : data=%s\n", msg->data);
    
            for (i = 0; i < msg->len; i++)
                    msg->data[i] = toupper(msg->data[i]);
            printf("OUTPUT: data=%s\n", msg->data);
            tpreturn(TPSUCCESS,0,(char *)msg->data, 0,0);
    }

2.57. tpsuspendtx

The tpsuspendtx function suspends a currently running global transaction in order to start a new transaction. Resources for a suspended transaction remain in ACTIVE state. For example, if a transaction timeout occurs, the transaction is rolled back. A suspended transaction can be resumed using tpresumetx() or tpsuspendxt().

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tpsuspendtx(TRANID *tranid, int flags)
  • Parameter

    Parameter Description

    tranid

    The current transaction ID. Must be a pointer to the TRANID structure and allocated by the developer.

    flags

    Not supported in the current version. Set to TPNOFLAGS.

  • Example

    SVC_TRAN( TPSVCINFO *msg )
    {
        str  sndbuf;
        char *rcvbuf;
        char tmp[4096];
        int  cd, ret;
        long rlen;
    
        /*********************************************************
        TSR(Transaction Suspend and Resume) - TPTRANID Structure
        *********************************************************/
        TPTRANID *tranid = (TPTRANID *)malloc(sizeof(struct tptranid));
        sndbuf = (str)msg->data;
        rcvbuf=(char *)tpalloc(“STRING”, NULL, 4096);
        h_empno = sndbuf->empno;
        h_sal   = sndbuf->sal;
        strcpy( h_ename, sndbuf->ename );
        strcpy( h_job  , sndbuf->job   );
        strcpy( h_date , sndbuf->date  );
    
        ret = tx_begin();
        cd = tpcall(“ORGTRAN1”, (char *)msg->data, msg->len, (char **)&rcvbuf,
                     (long *)&rlen, 0);
        strcpy(tmp, rcvbuf);
    
        /*********************************************************
        TSR(Transaction Suspend and Resume) - Suspend is Started
        *********************************************************/
        Ret = tpsuspendtx(tranid, 0)
        cd = tpcall(“NEWTRAN”, (char *)msg->data, msg->len, (char **)&rcvbuf,
                    (long *)&rlen, 0);
        strcat(tmp, rcvbuf);
    
        /********************************************************
        TSR(Transaction Suspend and Resume) - Resume is Started
        ********************************************************/
        ret = tpresumetx(tranid, 0);
        cd = tpcall(“ORGTRAN2”, (char *)msg->data, msg->len, (char **)&rcvbuf,
                     (long *)&rlen, 0);
        ret = tx_commit();
        tpreturn( TPSUCCESS, 0, rcvbuf, strlen(rcvbuf), 0 );
    }

2.58. tpsvctimeout

The tpsvctimeout() function is called when a service timeout occurs. When a timeout happens, the server program automatically invokes tpsvctimeout(). If the user redefines this function, the redefined version will be called instead.

When executing tx_commit() or tx_rollback() during a service, if a timeout occurs during the internal steps of xa_commit() or xa_rollback(), tperrno is set to TPETRAN to indicate this, allowing tpsvctimeout() to distinguish internal references.

A built-in tpsvctimeout() is included in the libsvr.so library. By default, this function returns with tpreturn(TPFAIL). If the user redefines tpsvctimeout(), the redefined object file must be linked before the libsvr.so library, ensuring the custom function is correctly called at runtime.

If TPRETURN is configured in the SERVER section, any call to tpreturn() within tpsvctimeout() due to a service timeout will ignore the arguments specified in the source code. Instead, the values defined in the configuration file are forcibly used.

  • Prototype

    # include <tmaxapi.h>
    void  tpsvctimeout(TPSVCINFO *msg)
  • Parameter

    Parameter Description

    msg

    The message used when the timed-out service was called.

  • Return Value

    Since tpsvctimeout() is used by the developer to perform necessary operations when a service timeout occurs, it does not return a value and does not produce an error.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    SERVICE(TPSVCINFO *msg)
    {
        ...
        tpreturn(TPSUCCESS,0,(char *)msg->data, 0,TPNOFLAGS);
    }
    
    void tpsvctimeout(TPSVCINFO *msg)
    {
        ...
        tpreturn(TPFAIL, TPETIME, (char *)buf, sizeof(buf), TPNOFLAGS);
    }

2.59. tpsvrdone

The tpsvrdone() function sets a routine to be executed when a server process is terminated. The Tmax application server’s main program (i.e., the main() provided by the Tmax system) calls tpsvrdone() before ending the process, after handling all service requests. When this routine is executed, the server process remains part of Tmax but no longer provides services. Within the tpsvrdone() routine, it is possible to perform Tmax communication or define a transaction.

If tpsvrdone() is executed while keeping an interactive connection, waiting for asynchronous replies, or during a transaction, Tmax will disconnect the interactive connection, ignore any pending asynchronous replies, and stop the transaction. The server will then be terminated immediately.

If a program does not define a tpsvrdone() routine, a default routine provided by Tmax is used. For servers that belong to a server group handling transactions, the default routine calls tx_close() and userlog() to indicate that the server is terminating. If tpreturn() or tpforward() are called within tpsvrdone(), the routine simply returns without performing any operations.

  • Prototype

    # include <tmaxapi.h>
    int tpsvrdone(void)
  • Return Value

    Since tpsvrdone() is written by the developer to perform necessary operations before terminating a server process, it does not return a value and does not produce an error.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    
    EXEC SQL INCLUDE sqlca.h;
    
    SERVICE(TPSVCINFO *msg)
    {
        int ret, cd;
        char *buf;
    
        EXEC SQL begin declare section;
        ….
        EXEC SQL end declare section;
        EXEC SQL CONNECT : scott IDENTIFIED BY : tiger;
        buf=tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processing }
        data process….
    
        cd=tpgetclid();
        if (cd==-1) { error processing }
        ret=tpsendtocli(cd, buf, 0, TPNOFLAGS);
        if (ret==-1) { error processing }
        data process....
    
        tpreturn(TPSUCCESS,0,buf, strlen(buf), 0);
    }
    
    int tpsvrdone()
    {
        printf(“ Sevice end\n”);
    }
  • Related functions

    tx_close(), tpsvrinit()

2.60. tpsvrdown

The tpsvrdown function properly terminates a UCS-type server process. UCS-type server processes are generally used for communication with external systems, most commonly banking systems. If an error prevents the external system from processing a service request, a countermeasure is needed. tpsvrdown() terminates the UCS-type server process so that no further service calls are sent to the failing external system. This helps prevent unnecessary resource usage and reduces the risk of overloading the external system.

  • Prototype

    #include <ucs.h>
    int  tpsvrdown(void)
  • Return Value

    Since tpsvrdown() is used by the developer to perform necessary operations before terminating a server process, it does not return a value and does not produce an error.

  • Example

    ...
    #include <usrinc/atmi.h>
    #include <usrinc/ucs.h>
    int usermain(int argc, char *argv[])
    {
        count=0;
        ...
        while(1)
        {
            ...
            tpschedule(3);
            cd = tpacall(“SERVICE”, buf, strlen(buf), TPNOREPLY);
            if (cd < 0) { error processing }
            ...
            if (count == 10) tpsvrdown();
        }
    }
    
    void reply_receive(UCSMSGINFO *reply)
    {
        printf(“data....%s\n”, reply->data);
    }
  • Related functions

    tpsvrinit(), tpsvrdone()

2.61. tpsvrinit

The tpsvrinit function initializes a service routine. It is called during the startup of a Tmax application server program, before any service requests are processed. Within the tpsvrinit() routine, it is possible to perform Tmax communication or define a transaction.

If the application program does not provide tpsvrinit(), a default routine provided by Tmax is called instead. For servers that belong to a server group handling transactions, the default tpsvrinit() calls tx_open() and userlog() to indicate that the server has started successfully.

Command-line parameters (CLOPT) of an application program can be passed to the server for processing by tpsvrinit(). See the CLOPT item in the SERVER section of the Tmax configuration file. The parameters are passed via argc and argv.

Since getopt() is used within the Tmax server main, optarg, optind, and opterr are available for parameter parsing and error detection within tpsvrinit().

  • Prototype

    # include <tmaxapi.h>
    int  tpsvrinit (int  argc, char  **argv)
  • Parameter

    Parameter Description

    argc

    The number of command-line parameters.

    argv

    A command-line parameter.

  • Return Value

    Return Value Description

    0

    The function call succeeded.

    Negative value

    The function call failed. No service request is received, the server process shuts down, and no error occurs.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    EXEC SQL INCLUDE sqlca.h;
    tpsvrinit(int argc, char **argv)
    {
        EXEC SQL begin declare section;
        char user_name[30];
        char user_passwd[30];
        EXEC SQL end declare section;
        EXEC SQL CONNECT scott IDENTIFIED BY tiger;
        return(0);
    }
    
    SERVICE(TPSVCINFO *msg)
    {
        int ret, cd;
        char *buf;
        buf=tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processing }
    
        data process....
        cd=tpgetclid();
        if (cd==-1) { error processing }
        ret=tpsendtocli(cd, buf, 0, TPNOFLAGS);
        if (ret==-1) { error processing }
    
        data process....
        printf(“ Sevice end\n”);
        EXEC SQL COMMIT WORK RELEASE;
        tpreturn(TPSUCCESS, buf, strlen(buf), 0);
    }
  • Related functions

    tx_open(), tpsvrdone()

2.62. tpsvrthrdone

The tpsvrthrdone function is available only in Multithread and Multicontext servers. When a server process is terminated, these servers terminate service threads before executing tpsvrdone(). If tpsvrthrdone() is defined, each service thread automatically calls this function when it is terminated.

Developers should implement tpsvrthrdone() to perform any necessary cleanup before a thread ends. Within this function, Tmax communication or transaction operations can be performed. If the function returns before completing required tasks, any incomplete work will be discarded when the thread terminates.

A client can also allocate a previously created context to the current client using context-related functions. Most ATMI functions operate on a per-context basis. While a client can create and use multiple contexts, only one context is active at a time.

For example, if context1 makes a tpacall(), then context1 must also be set as the current context when calling tpgetrply(). Otherwise, tpgetrply() cannot be executed normally if another context is active. For more information, refer to tpsvrdone.

  • Prototype

    # include <tmaxapi.h>
    int tpsvrthrdone(void)
  • Return Value

    Since tpsvrthrdone() is used by the developer to perform necessary operations before terminating a server process, it does not return a value and does not produce an error.

  • Example

    See the example in tpsvrdone.

  • Related function

    tpsvrthrinit()

2.63. tpsvrthrinit

The tpsvrthrinit function is available only in Multithread and Multicontext servers. While a Tmax server provides tpsvrinit() for initialization when a server process starts, Multithread and Multicontext servers also provide tpsvrthrinit() for thread-specific initialization. This function is called when a new service thread is created in the thread pool, after tpsvrinit() has executed.

A thread pool operates according to the MINTHR and MAXTHR settings. When a server process starts, the number of service threads specified in MINTHR is created, and each of these threads calls tpsvrthrinit(). If no idle service threads are available, additional threads are created as needed, up to the value specified in MAXTHR. If MINTHR is set to 0, no service threads are created at startup. In this case, only tpsvrinit() is called, and the process waits until a service request arrives.

The tpsvrthrinit() function is executed after tpsvrinit() and before a thread processes its first service request. It receives the same parameters as tpsvrinit(), which are defined in the CLOPT field of the SERVER section in the configuration file. When implementing this function, developers must ensure that the parameters passed to tpsvrinit() and tpsvrthrinit() are consistent. For more information, refer to tpsvrinit.

  • Prototype

    # include <tmaxapi.h>
    int  tpsvrthrinit (int  argc, char  **argv)
  • Parameter

    Parameter Description

    argc

    The number of command-line parameters.

    argv

    A command-line parameter.

  • Return Value

    If initialization through tpsvrthrinit() fails, the function returns -1, and the server process cancels startup and shuts down.

    Return Value Description

    0

    The function call succeeded.

    Negative value

    The function call failed. The server process cancels startup and shuts down.

  • Example

    #include <stdio.h>
    #include <pthread.h>
    #include <usrinc/atmi.h>
    
    void tpsvrthrinit(int argc, char **argv)
    {
        param_t *param;
        param = get_threadspecificdata();
        if (pthread_create(&param->tid, NULL, THREAD_ROUTINE, (void *)param) != 0) {
            printf("user_create_thread failed\n");
            return -1;
        }
        pthread_mutex_init(&param->mutex, NULL);
        pthread_cond_init(&param->cond, NULL);
        return 0;
    }
    
    void tpsvrthrdone()
    {
        void *ret;
        param_t *param;
    
        param = get_threadspecificdata();
        param->state = EXIT;
        pthread_cond_signal(&param->cond);
        pthread_join(param->tid, &ret);
    
        pthread_mutex_destroy(&param->mutex);
        pthread_cond_destroy(&param->cond);
        printf("user_create_thread destroyed\n");
    }
    
    SERVICE(TPSVCINFO *msg)
    {
        param_t *param;
        param = get_threadspecificdata();
        ...
        ret = tpgetctxt(&param->ctxtid, TPNOFLAGS);
        ret = pthread_cond_signal(&param->cond);
        ...
    }
    
    void *THREAD_ROUTINE(void *arg)
    {
        param_t *param;
        param = (param_t *)arg;
    
        while(1) {
            pthread_mutex_lock(&param->mutex); {
                pthread_cond_wait(&param->cond, &param->mutex);
                if (param->state == EXIT)
                    break;
                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;
                }
                ...
            } pthread_mutex_unlock(&param->mutex);
        }
        return NULL;
    }
  • Related function

    tpsvrthrdone()

2.64. tptsleep

The tptsleep function waits for a server process shutdown event from TMM. When a shutdown massage is received from the TMM, the server exits and proceeds with tpsvrdone().

If waiting is required in the tpprechk() callback function, tptsleep() should be called periodically to ensure that tmdown is executed correctly. Since the server shuts down after this process, the return values of tptsleep() have no meaning.

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tptsleep(struct timeval *timeout)
  • Parameter

    Parameter Description

    timeout

    The period of time to wait for a shutdown event, in seconds. Equivalent to the same parameter of the select() system function.

  • Return Value

    Return Value Description

    1

    A message other than a shutdown message was received from TMM.

    -1

    The function call failed.

  • Example

    int tpprechk(void)
    {
         struct timeval timeout;
         int ret;
         timeout.tv_sec = 5;
         timeout.tv_usec = 0;
         while(1)
         {
              ret = tptsleep(&timeout);
              ...
         }
         return 0;
    }

2.65. tpunadvertise

The tpunadvertise function removes a service, previously provided by a server process, from availability. A specific service name can be both advertised and later unadvertised.

When a server process advertises a new service, the service name is registered in the service name table managed by the CLH for each server. When a service is unadvertised, its name is removed from the table. If a client calls an unadvertised service, tpunadvertise() returns a TPENOENT error.

The following describes the behavior of each service:

  • A service registered in the configuration file

    The service status is changed to UNADV. If the service is called, a TPENOENT error is received.

  • A service registered with mksvr

    The service status is changed to UNADV. If the service is called, a TPENOENT is received. The service itself is automatically deleted when all processes in the server are terminated.

  • A newly registered service

    The service status is changed to UNADV. If the service is called, a TPENOENT is received. The service itself is automatically deleted when all processes in the server are terminated.

The following shows how to use the function.

  • Prototype

    #include <atmi/usrinc.h>
    int tpunadvertise(char *svcname);
  • Parameter

    Return Value Description

    svcname

    The name of the service to be unregistered.

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

    Error Code Description

    [TPEINVAL]

    The service name is NULL.

    [TPENOENT]

    The service does not exist.

    [TPELIMIT]

    The name of the service exceeds the specified length.

    [TPEPROTO]

    The function was called under an inappropriate condition.

    [TPESYSTEM]

    An error occurred in the Tmax system.

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <usrinc/atmi.h>
    
    SVC2TN_2( TPSVCINFO *msg )
    {
        int     ret;
        char    input[MAXLEN];
    
        memset(input, 0x00, MAXLEN);
        strncpy(input, msg->data, msg->len);
    
        ret = tpunadvertise(input);
        if (ret < 0) {
            tpreturn(TPFAIL, tperrno, (char*)msg->data, msg->len, 0);
        }
        tpreturn(TPSUCCESS, 0, (char*)msg->data, msg->len, 0);
    }

2.66. tpunregancb

The tpunregancb function unregisters a callback function that receives events generated by the admnoti command in tmadmin. After this function is executed, all subsequent events are ignored.

  • Prototype

    # include <tmaxapi.h>
    int tpunregancb(void)
  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEPROTO]

    No callback function has been registered.

  • Example

    ...
    #include <stdio.h>
    #include <usrinc/tmaxapi.h>
    
    int admnoti(int reqno, int len, char *args);
    
    int SERVICE_REG(TPSVCINFO *svc)
    {
       if (tpregancb(admnoti) < 0)
          error processing;
    }
    
    int SERVICE_UNREG(TPSVCINFO *svc)
    {
       tpunregancb();
    }
    
    int admnoti(int reqno, int len, char *args)
    {
       /* processing */
       return 0;
    }
  • Related function

    tpregancb()

2.67. tpunregcb

The tpunregcb function resets a routine that receives the response to an asynchronous request. It is used in UCS-type server processes.

  • Prototype

    #include <ucs.h>
    int  tpunregcb (void)
  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    ...
    #include <usrinc/atmi.h>
    #include <usrinc/ucs.h>
    void reply_receive(UCSMSGINFO *reply);
    
    int usermain(int argc, char *argv[])
    {
        ...
        ret = tpregcb(reply_receive);
        if (ret == -1){ error processing  }
    
        ret = tpunregcb();
        if (ret == -1){  error processing  }
        while(1)
        {
            ...
            tpschedule(3);
            cd = tpacall(“SERVICE”, buf, strlen(buf), TPNOFLAGS);
            if (cd < 0) { error processing  }
            ...
        }
    }
    
    void reply_receive(UCSMSGINFO *reply)
    {
        printf(“first reply receive\n”);
        printf(“data....%s\n”, reply->data);
    }
  • Related function

    tpregcb()

2.68. tpuschedule

The tpuschedule function waits for data in microseconds. It is available only in UCS-type server processes. The function sleeps for up to the specified timeout period and returns immediately if data arrives within that time.

  • Prototype

    #include <ucs.h>
    int tpuschedule (int timeout)
  • Parameter

    Parameter Description

    timeout

    The amount of time to wait in microseconds.

    • –1 : Only checks for data arrival and returns immediately.

    • 0 : Waits until data arrives.

  • Return Value

    Return Value Description

    0

    No data arrived until the timeout period expired.

    Positive integer

    Data arrived before the timeout period expired.

    -1

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

  • Error

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    ...
    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/ucs.h>
    
    int usermain(int argc, char *argv[])
    {
        ...
        while(1)
        {
            ...
            tpuschedule(3000000);
            ret = tpcall(“SERVICE”, (char *)buf, strlen(buf), (char **)&buf,
                          (long *)&rlen, TPNOFLAGS);
            if (ret == -1) { error processing }
            ...
         }
    }
  • Related function

    tpschedule()

2.69. tx_close

The tx_close function closes connections with resource managers.

tx_close() terminates the connection between the caller and all resource managers. Because this function replaces individual connection-closing calls for each resource manager, the application program does not need to call specific functions for each resource manager, which improves portability. Since the connection-closing method varies by resource manager, each resource manager is responsible for preparing the necessary information to close its own connections.

The tx_close() function must be called when an application process no longer participates in a global transaction. If the caller is currently in transaction mode, the tx_close() call fails and returns [TX_PROTOCOL_ERROR], while still closing connections with the resource managers.

  • Prototype

    # include  <tx.h>
    int  tx_close(void)
  • Return Value

    Return Value Description

    TX_OK

    The function call succeeded. Connections with all resource managers are terminated.

    Negative value

    The function call failed and an error code is returned.

  • Error

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

    Error Code Description

    [TX_PROTOCOL_ERROR]

    The function was called under an inappropriate conditions. For example, the caller was in transaction mode. Connections with resource managers remain alive.

    [TX_ERROR]

    The transaction manager or the resource manager encountered a temporary error. The exact cause of the error may vary depending on the product behavior. All connections with resources managers are closed.

    [TX_FAIL]

    A fatal error occurred. The transaction manager or the resource manager can no longer execute operations for the application. The exact cause of the error may vary depending on the product behavior.

  • Example

    ...
    int tpsvrinit(int argc, char *argv[])
    {
        int ret;
        ret = tx_close();
        if (ret < 0){ error processing }
        ret = tx_open();
        if (ret < 0){ errror processing }
    }
    
    int tpsvrdone()
    {
        int ret;
        ret = tx_close();
        if (ret < 0) { error processing }
    }
  • Related function

    tx_open()

2.70. tx_open

The tx_open function opens a connection with the associated resource managers. This function is typically called internally, so the user does not need to invoke it manually. Since connection methods vary by resource manager, tx_open() causes the transaction manager to transfer the specific connection information required for each resource manager related to the caller.

tx_open() establishes connections between an application program and all resource managers. By using tx_open(), an application does not need to call individual connection-opening functions for each resource manager, improving portability. Each resource manager must prepare the necessary information to open connections. If the application attempts to access an unconnected resource manager, a specific error for that resource will be returned. tx_open() must successfully return before the process can participate in a transaction.

Once tx_open() returns successfully, additional calls to tx_open() have no effect until tx_close() is called. After the application program is connected to the resource managers, the transaction manager will consider subsequent tx_open() calls successful without re-establishing connections. The tpopen() function behaves the same as tx_open().

  • Prototype

    # include  <tx.h>
    int  tx_open(void)
  • Return Value

    Return Value Description

    TX_OK

    The function call succeeded. Connections are established with some or all resource managers.

    Negative value

    The function call failed and an error code is returned.

  • Error

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

    Error Code Description

    [TX_ERROR]

    The transaction manager or the resource manager encountered a temporary error. No connection is established with any resource manager. The exact cause of the error may vary depending on the product behavior.

    [TX_FAIL]

    A fatal error occurred. The transaction manager or the resource manager can no longer execute operations for the application. The exact cause of the error may vary depending on the product behavior.

  • Example

    int tpsvrinit(int argc, char *argv[])
    {
        int ret;
        ret = tx_close();
        if (ret < 0){
            error processing
        }
        ret = tx_open();
        if (ret < 0){
            errror processing
        }
    }
    
    int tpsvrdoen()
    {
        int ret;
        ret = tx_close();
        if (ret < 0){
            error processing
        }
    }
  • Related function

    tx_close()

3. Client Functions

3.1. gettpurcode

The gettpurcode function returns the urcode value set in a service. It is used by a client to retrieve the second argument of tpreturn(). The urcode can serve as an additional communication mechanism between a client and a service program. For example, it may be used to return a specific error number to the client for custom error-handling routines.

  • Prototype

    #include <atmi.h>
    long gettpurcode(void)
  • Return Value

    The function returns the urcode value.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    
    void main(int argc, char* argv[])
    {
       char *buf;
       long len;
       int ret;
    
       ret=tpstart((TPSTART_T *)NULL);
       if (ret==-1) { error processing }
    
       buf=tpalloc(“STRING”, NULL, 0);
       if (buf==NULL) { error processing }
       data process....
    
       ret=tpcall(“SERVICE”, buf, 0, &buf, &len, TPNOFLAGS);
       if (ret==-1) {error processing }
       printf(“urcode from SERVICE Return: %d”, gettpurcode());
       data process....
    
       tpend();
    }

For more information about the gettpurcode function, refer to Tmax Programming Guide(Dynamic Library).

3.2. tpchkunsol

The tpchkunsol function calls a function to handle unsolicited messages received from the server. It is used on the client side.

The client should invoke that function to handle unsolicited messages after issuing tpsetunsol(), tpcall(), or tpacall(). tpchkunsol() allows the client to check for any unsolicited messages before making tpcall() or tpacall().

  • Prototype

    #include <usrinc/tmaxapi.h>
    int tpchkunsol(void)
  • Return Value

    Return Value Description

    Number of messages

    The function call succeeded. The number of unsolicited messages received from the server is returned.

    -1

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

  • Error

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

    Error Code Description

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

    [TPETIME]

    A timeout occurred. If the caller is in transaction mode, the transaction has expired and is rolled back. Otherwise, a block timeout occurred while neither TPNOTIME nor TPNOBLOCK was set. After a transaction timeout, any new service requests or attempts to receive responses will result in this error until the transaction is rolled back.

    [TPEPROTO]

    The TPUNSOL_HND flag was not set. When invoking tpstart(), the TPUNSOL_HND flag must be set using tpsetunsol_flag() to receive unsolicited messages through the handler. Otherwise, this error occurs.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/ucs.h>
    #include <usrinc/tmaxapi.h>
    
    void get_unsol(char *data, long len, long flag)
    {
        printf(“unsolicited data = %s\n”, data);
    }
    
    int main(int argc, char *argv[]){
        char *sndbuf;
        char *rcvbuf;
        long rcvlen;
        int RecvCnt = 0;
        TPSTART_T *tpinfo;
    
        tpinfo = (TPSTART_T *)tpalloc(« TPSTART », NULL, sizeof(TPSTART_T));
        if (tpinfo == NULL) {
            printf(“tpalloc failed !<-tpinfo\n”);
            exit(1);
        }
        strcpy(tpinfo->usrname, “starbj81”);
        strcpy(tpinfo->cltname, “client”);
        if(tpstart((TPSTART_T *)tpinfo) == -1)
        {
            fprintf(stderr, “tpstart error\n”);
            exit(1);
        }
        tpsetunsol_flag(TPUNSOL_HND);
        tp_sleep(5);
    
        if(tpsetunsol(get_unsol) == TPUNSOLERR)
            printf(“tpsetunsol failed..\n”);
    
        RecvCnt = tpchkunsol();
        if(RecvCnt < 0)
           printf(“tpchkunsol failed\n”);
        else
           printf(“Received Unsol Data Count : %d\n”, RecvCnt);
    
        if((sndbuf = (char *)tpalloc(“CARRAY”, NULL, 1024)) == NULL)
            error processing
        if((rcvbuf = (char *)tpalloc(“CARRAY”, NULL, 1024)) == NULL)
            error processing
        if((cd = tpcall(“LOGIN”, sndbuf, 1024, (char **)&rcvbuf,
            (long *)&rcvbuf,  0)) == -1)
            error processing
    
        printf(“After tpacall() received Message from server:%s\n”, rcvbuf);
        tpfree((char *)sndbuf);
        tpfree((char *)rcvbuf);
        tpend();
    }
  • Related functions

    tpsetunsol(), tpsetunsol_flag()

3.3. tpend

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

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

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

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

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

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

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

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

  • Prototype

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

    Return Value Description

    -1

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

  • Error

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

    Error Code Description

    [TPEPROTO]

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

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

    [TPEPROTO]

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

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

  • Example

    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <usrinc/atmi.h>
    
    void main(int argc, char *argv[])
    {
        char    *sndbuf, *rcvbuf;
        long    rcvlen, sndlen;
        int     ret;
    
        ret=tpstart((TPSTART_T *)NULL)
        if (ret==-1) {error processing }
    
        buf = (char *)tpalloc(“STRING”, NULL, 0)
        if (buf=NULL) { error processing }
    
        data process …
    
        ret=tpcall(“SERVICE”, buf, 0, &buf, &len, TPNOFLAGS);
        if (ret==-1) { error processing }
    
        data process …
        printf(“ data: %s\n”, buf);
        tpfree((char *)buf);
        tpend();
    }
  • Related functions

    tpstart(), tpgetctxt(), tpsetctxt()

3.4. tpgethostaddr

The tpgethostaddr function checks the connection between a client and the Tmax system or retrieves the IP address and port of the currently connected Tmax system.

  • Prototype

    #include <tuxatmi.h>
    int tpgethostaddr(int *ip, int *port, long flags);
  • Parameter

    Parameter Description

    ip

    The client IP address. Since the IP address is stored in the s_addr field of the sockaddr_in structure, inet_ntoa() must be used to convert it to dotted-decimal format.

    port

    The port of the client.

    flags

    The following flags are available:

    • GET_SVR_CON

      Only checks the connection to the Tmax system.

    • GET_CUR_IP

      Retrieves both the IP address and port of the connected server.

  • Return Value

    Return Value Description

    - 1

    Not connected to the Tmax system.

    1

    Connected to the primary Tmax system.

    2

    Connected to a backup Tmax.

3.5. tpgetunsol

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

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

  • Prototype

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

    Parameter Description

    type

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

    data

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

    len

    The total length of the message.

    flags

    Option to enable blocking.

    The following flags are available:

    • TPBLOCK

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

    • TPNOCHANGE

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

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

    • TPNOTIME

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

    • TPSIGRSTRT

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

    • TPGETANY

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

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEPROTO]

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

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <string.h>
    #include <usrinc/tmaxapi.h>
    
    void main(int argc, char *argv[])
    {
        int ret;
        char *buf;
        long len;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
    
        buf=tpalloc(“STRING”, NULL, 0);
        if (buf==NULL) { error processing }
        data process....
    
        while(1)
        {
            ret=tp_sleep(2);
            if (ret==-1) { error processing }
    
            if (ret==0)
                printf(“nothing happened\n”);
            else {
                ret=tpgetunsol(UNSOL_TPSENDTOCLI, (char **)&buf, &len, TPNOCHANGE);
                if (ret==-1) { error processing }
                printf(“received data : %s\n”, buf);
            }
    
            data process....
            if (strncmp(buf, “end”, 3)==0) break;
        }
    
        data process....
        tpfree(buf);
        tpend();
    }
  • Related functions

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

3.6. tpinit

The tpinit function enables migration of programs developed for Tuxedo to Tmax without any modifications. Its functionality is equivalent to tpstart().

  • Prototype

    #include <tuxatmi.h>
    int tpinit (TPINIT *tpinfo)
  • Parameter

    Parameter Description

    tpinfo

    Information about the authentication and Multicontext settings.

  • Return Value

    See tpstart.

  • Example

    #include <stdio.h>
    #include <tuxinc/tuxatmi.h>
    int main(int argc, char *argv[])
    {
        char *buf;
        long len;
        int ret;
    
        ret = tpinit((TPINIT *)NULL);
        if (ret == -1){ error processing }
        buf = (char *)tpalloc(“STRING”, NULL, 0);
        if (buf == NULL){ error processing }
    
        strcpy(buf, argv[1]);
        ret = tpcall(“SERVICE”, buf, 0, &buf, &len, TPNOFLAGS);
        if (ret == -1){ error processing }
    
        printf(“data: %s\n”, buf);
        tpfree(buf);
        tpterm();
    }
  • Related function

    tpstart()

3.7. tpreset

The tpreset function immediately releases the currently connected client. It is used on the client side. If a TPESYSTEM error occurs in a client module, it is usually due to a network issue, and the client must reconnect to the Tmax system.

Use tpreset() to release the current connection and then make a new service request or re-access the Tmax system.

  • Prototype

    # include <tmaxapi.h>
    int  tpreset (void)
  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEPROTO]

    This error occurs when multiple threads share the same context and one of them executes tpreset(). Like the TPEPROTO error for tpend() under the same condition, only the thread that called tpreset() is removed from the context allocation, while the other threads continue using the context.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    void main(int argc, char *argv[])
    {
        int ret;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1){
            if (tperrno=TPESYSTEM)
            {
                printf (“system error \n”);
                ret=tpreset();
                if (ret==-1) { error process }
                tpend();
                exit(1);
            }
            error processing....
         }
        data process..
        tpend();
    }

3.8. tpsetunsol

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

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

  • Prototype

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

    Parameter Description

    data

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

    len

    The length of the data.

    flags

    Currently not used.

  • Return Value

    Return Value Description

    Pointer / NULL

    The function call succeeded.

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

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

    TPUNSOLERR

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

  • Error

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

    Error Code Description

    [TPEPROTO]

    tpsetunsol() was called under an inappropriate condition.

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include “../sdl/demo.s”
    
    void get_unsol(char *data, long len, long flags)
    {
        printf(“get unsolicited data = %s\n”, data);
        data process....
    }
    
    void main(int argc, char *argv[])
    {
        int ret;
        char *buf;
        long len;
    
        ret=tpstart((TPSTART_T *)NULL);
        if (ret==-1) { error processing }
        ret=tpsetupsol_flag(TPUNSOL_HND);
        if (ret==-1) { error processing }
    
        ret=tpsetunsol(get_unsol);
        if (ret==TPUNSOLERR) { error processing }
    
        buf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (buf==NULL) {error processing };
        data process...
    
        ret=tpcall(“SERVICE”, buf, 20, (char **)&buf, &len, TPNOFLAGS);
        if (ret==-1) { error processing }
        data process...
    
        tpfree((char *)buf);
        tpend();
    }
  • Related functions

    tpstart(), tpend(), tpgetunsol()

3.9. tpsetunsol_flag

The tpsetunsol_flag function changes the flag setting for receiving unsolicited messages. It is used on the client side. It resets the flag values used when the client connects to the Tmax system using tpstart().

  • Prototype

    # include <atmi.h>
    int  tpsetunsol_flag  (int  flag)
  • Parameter

    Parameter Description

    flag

    Resets the flag setting for receiving unsolicited messages.

    One of the following values is used:

    • TPUNSOL_IGN : Does not receive unsolicited messages.

    • TPUNSOL_HND, TPUNSOL_POLL : Receives unsolicited messages.

  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An invalid flag was set. Even if an error occurs, no error code is set in tperrno.

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include “../sdl/demo.s”
    
    void get_unsol(char *, long, long);
    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, &buf, &len, TPNOFLAGS);
        if (ret==-1) { error processing }
        data process...
    
        tpfree((char *)buf);
        tpend();
    }
    
    void get_unsol(char *, long, long);
    {
        printf(“get unsolicited data.\n”);
        data process....
    }
  • Related function

    tpstart()

3.10. tpstart

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

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

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

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

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

Variable Description

TMAX_HOST_ADDR

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

TMAX_HOST_PORT

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

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

TMAX_BACKUP_ADDR

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

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

TMAX_BACKUP_PORT

The port number of the backup node configured with TMAX_BACKUP_ADDR.

TMAX_CONNECT_TIMEOUT

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

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

  • Prototype

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

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

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

    The following shows the TPSTART_T structure:

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

    cltid

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

    dompwd

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

    usrname

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

    usrpwd

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

    flags

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

    The following flags are available.

    • TPUNSOL_POLL

      Receives unsolicited messages.

    • TPUNSOL_HND

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

    • TPUNSOL_IGN

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

    • TPMULTICONTEXTS

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

  • Return Value

    Return Value Description

    0 or 1

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

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

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

    [TPEITYPE]

    tpinfo is not a pointer to a TPSTART_T structure.

    [TPEPROTO]

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

    [TPESYSTEM]

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

    [TPEOS]

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

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    void main(int argc, char *argv[])
    {
        int ret;
        char *buf;
        long len;
        TPSTART_T  *tpinfo;
    
        tpinfo = (TPSTART_T *)tpalloc(“TPSTART”, NULL, sizeof(TPSTART_T));
        if (tpinfo==NULL) { error processing }
    
        strcpy(tpinfo->cltname, “cli1”);
        strcpy(tpinfo->usrname, “navis”);
        strcpy(tpinfo->dompwd, “tmax”);
        tpinfo->flags = TPUNSOL_HND;
        ret=tpstart(tpinfo);
        if (ret==-1) { error processing }
    
        buf = (char *)tpalloc(“CARRAY”, NULL, 20);
        if (buf==NULL) {error processing };
    
        ret=tpcall(“SERVICE”, buf, 20, &buf, &len, TPNOFLAGS);
        if (ret==-1) { error processing }
    
        data process....
        tpfree((char *) buf);
        tpend();
    }
  • Related function

    tpend()

3.11. tpterm

The tpterm function disconnects a client from the Tmax system. This function is provided for Tuxedo compatibility, allowing programs developed for Tuxedo to run in Tmax without modification. The functionality is equivalent to tpend()

  • Prototype

    #include <tuxatmi.h>
    int  tpterm(void)
  • Return Value

    See tpend.

  • Example

    ...
    #include <tuxinc/tuxatmi.h>
    int main(int argc, char *argv[])
    {
        int ret;
        long len;
        char *buf;
    
        ret = tpinit((TPINIT *)NULL);
        if (ret == -1){ error processing }
    
        buf=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...
    
        ret = tpterm();
        if (ret ==–1){ error processing }
    }
  • Related function

    tpend()

3.12. tptobackup

The tptobackup function connects a client directly to a Tmax backup system. Normally, clients use tpstart() to connect to Tmax systems. If the primary server is unavailable due to an abnormal state, the client will automatically attempt to connect to a backup system. By contrast, tptobackup() is explicitly used when the client chooses to connect to a backup system.

Unlike tpstart(), tptobackup() does not take a TPSTART_T argument and cannot connect to systems that require security. Therefore, if security-related items are configured, this function cannot be used to connect to a backup system.

To receive unsolicited messages, the reception flag must be set using tpsetunsol_flag(). In addition, TMAX_BACKUP_ADDR and TMAX_BACKUP_PORT must be registered in the system configuration file (e.g., .profile in Korn Shell) to enable tptobackup().

  • Prototype

    #include <tmaxapi.h>
    int  tptobackup(void)
  • Return Value

    Return Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEPROTO]

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

    [TPESYSTEM]

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

    [TPEOS]

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

  • Example

    #include <stdio.h>
    #include <usrinc/atmi.h>
    #include <usrinc/tmaxapi.h>
    
    void main(int argc, char *argv[])
    {
        tpputenv(“TMAX_BACKUP_ADDR=xxx.xxx.xxx.xxx”);
        tpputenv(“TMAX_BACKUP_PORT=xxxx”);
        tptobackup();
        data process....
        tpend();
    }

4. TCP/IP Gateway Functions

4.1. chk_extpong_msg

The chk_extpong_msg function checks messages received from a server in response to a ping. The function is called at intervals specified using set_extping_msg(). It verifies response messages sent from the remote server.

  • Prototype

    int chk_extpong_msg(msg_header_t *hp, char *data, int len)
  • Parameter

    Parameter Description

    hp

    The header of the response message received during channel health checks.

    data

    The body of the received message.

    len

    The length of the received message body.

  • Return Value

    Value Description

    Positive

    The function call succeeded.

    Negative

    The function call failed.

    0

    There is no ping message.

  • Example

    int chk_extpong_msg(msg_header_t *hp, char *data, int len)
    {
        msg_body_t *body;
        char data2[15];
        body = (msg_body_t *)data;
        printf(“chk_extpong_msg : data = %s\n”, body->data);
        return 1;
    }
  • Precaution

    The following must be added in the <register.c> file to use the function.

    #if !defined(_TCPGW_VERSION_OLD) && !defined(_TCPGW_VERSION_1)
    #&& !defined(_TCPGW_VERSION_2)
    #if defined(_TCPGW_USE_EXTPING)
    _tcpgw_regfn(19, NULL);
    _tcpgw_regfn(20, NULL);
    _tcpgw_regfn(21, set_extping_msg);
    _tcpgw_regfn(22, chk_extpong_msg);
    _tcpgw_regfn(23, NULL);
    _tcpgw_regfn(24, reset_extping_msg); /* reset */
    #else
    _tcpgw_regfn(19, set_ping_msg);
    _tcpgw_regfn(20, chk_pong_msg);
    _tcpgw_regfn(21, NULL);
    _tcpgw_regfn(22, NULL);
    _tcpgw_regfn(23, reset_ping_msg); /* reset */
    _tcpgw_regfn(24, NULL);
    #endif
    #else
    _tcpgw_regfn(19, NULL);
    _tcpgw_regfn(20, NULL);
    _tcpgw_regfn(21, NULL);
    _tcpgw_regfn(22, NULL);
    _tcpgw_regfn(23, NULL);
    _tcpgw_regfn(24, NULL);
    #endif

4.2. reset_extping_msg

The reset_extping_msg function is called periodically to reset the PING message for the TCP/IP gateway.

  • Prototype

    int reset_extping_msg(msg_header_t *hp, char *data, int len)
  • Parameter

    Parameter Description

    hp

    The header of the response message received during channel health checks.

    data

    The message body to reset.

    len

    The length of the message body.

  • Return Value

    Value Description

    Positive

    The function call succeeded.

    Negative

    The function call failed.

  • Example

    int reset_extping_msg(msg_header_t *hp, char *data, int len)
    {
        hp->len = 10;
        data = “reset_msg”;
        printf(“reset_extping_msg : data = %s\n”, data);
        return 1;
    }
  • Precaution

    To use reset_extping_msg(), add the following in the <register.c> file:

    #if !defined(_TCPGW_VERSION_OLD) && !defined(_TCPGW_VERSION_1)
    # && !defined(_TCPGW_VERSION_2)
    #if defined(_TCPGW_USE_EXTPING)
    _tcpgw_regfn(19, NULL);
    _tcpgw_regfn(20, NULL);
    _tcpgw_regfn(21, set_extping_msg);
    _         _tcpgw_regfn(22, chk_extpong_msg);
            _tcpgw_regfn(23, NULL);
            _tcpgw_regfn(24, reset_extping_msg); /* reset */
    #else
            _tcpgw_regfn(19, set_ping_msg);
            _tcpgw_regfn(20, chk_pong_msg);
            _tcpgw_regfn(21, NULL);
            _tcpgw_regfn(22, NULL);
            _tcpgw_regfn(23, reset_ping_msg); /* reset */
            _tcpgw_regfn(24, NULL);
    #endif
    #else
            _tcpgw_regfn(19, NULL);
            _tcpgw_regfn(20, NULL);
            _tcpgw_regfn(21, NULL);
            _tcpgw_regfn(22, NULL);
            _tcpgw_regfn(23, NULL);
            _tcpgw_regfn(24, NULL);
    #endif

4.3. set_extping_msg

The set_extping_msg function configures the message that will be sent when performing a PING to the server.

  • Prototype

    int set_extping_msg(msg_header_t *hp, char *data, int len, int *interval,
                        int *binterval, int *timeout, int *mode);
  • Parameter

    Parameter Description

    hp

    The header of the response message received during channel health checks.

    data

    The body of the message to be sent.

    len

    The length of the data.

    interval

    The health check interval for the main channel. If set to 0, the health check is disabled.

    binterval

    A pointer to the interval value for the main channel health check when operating in backup channel mode. If set to 0, the main channel health check is disabled.

    timeout

    The time limit for the channel health check, in seconds. If this time period expires, the function fails and terminates.

    mode

    Choose one of the following values:

    • 0 : Check the OUTBOUND channel.

    • 1 : Check the INBOUND channel.

    • 2 : Check both the OUTBOUND and INBOUND channels.

  • Return Value

    Value Description

    Positive

    The function call succeeded.

    Negative

    The function call failed.

  • Example

    int set_extping_msg(msg_header_t *hp, char *data, int len, int *interval,
                        int *binterval, int *timeout, int *mode)
    {
        msg_body_t *body;
        body = (msg_body_t *)data;
        memset(body->data, 0x00, 52);
        memcpy(body->data, “tmax50”, 7);
        body->data[51] = 0;
        printf(“set_extping_msg : data = %s\n”, body->data);
    
        hp->len = 7;
        *interval = 10;
        *binterval = 20;
        *timeout = 100;
        mode = 0; / OUTBOUND CHANNEL */
        return 1;
    }
  • Precaution

    To use set_extping_msg(), the following must be added in the <register.c> file.

    #if !defined(_TCPGW_VERSION_OLD) && !defined(_TCPGW_VERSION_1)
    #&& !defined(_TCPGW_VERSION_2)
    #if defined(_TCPGW_USE_EXTPING)
    _tcpgw_regfn(19, NULL);
    _tcpgw_regfn(20, NULL);
    _tcpgw_regfn(21, set_extping_msg);
    _tcpgw_regfn(22, chk_extpong_msg);
    _tcpgw_regfn(23, NULL);
    _tcpgw_regfn(24, reset_extping_msg); /* reset */
    #else
    _tcpgw_regfn(19, set_ping_msg);
    _tcpgw_regfn(20, chk_pong_msg);
    _tcpgw_regfn(21, NULL);
    _tcpgw_regfn(22, NULL);
    _tcpgw_regfn(23, reset_ping_msg); /* reset */
    _tcpgw_regfn(24, NULL);
    #endif
    #else
    _tcpgw_regfn(19, NULL);
    _tcpgw_regfn(20, NULL);
    _tcpgw_regfn(21, NULL);
    _tcpgw_regfn(22, NULL);
    _tcpgw_regfn(23, NULL);
    _tcpgw_regfn(24, NULL);
    #endif

5. TDL Functions

For more information about TDL functions, refer to Tmax Programming Guide(Dynamic Library).

5.1. tdlcall

The tdlcall function invokes the latest version of a dynamic module function. This dynamic module function must use the signature of long funcname(void *args). tdlcall works only when the TDL configuration file (tdl.cfg) version is set to 1 or 2. Dynamic modules are loaded when tdlcall() is executed. To avoid performance degradation, they are reused unless an update is triggered with tdlupdate.

  • Prototype

    #include <tdlcall.h>
    int tdlcall(char *funcname, void *args, long *urcode, int flags)
  • Parameter

    Parameter Description

    funcname

    The function name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    args

    A parameter for the dynamic module function to call.

    urcode

    The return value from the dynamic module function.

    flags

    The following flags are available:

    • TDLTRAN : With this flag setting, the global sequence number must be returned through urcode.

    • TDL_RTLD_GLOBAL : Enables the RTLD_GLOBAL option, which allows access to externally defined variables or functions. With this option, other modules can also reference external symbols.

    • TDL_NOFLAGS : No flags are applied.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The module is temporarily inactive.

5.2. tdlcall2

The tdlcall2 function calls the latest version of a dynamic module using the library name and function name as keys. The dynamic module must have the signature of long funcname(void *args). Except for using the library and function names as keys, tdlcall2() behaves the same as tdlcall().

tdlcall2() is available only when the version of the TDL configuration file (tdl.cfg) is set to 3.

  • Prototype

    #include <tdlcall.h>
    int tdlcall2(char *libname, char *funcname, void *args, long *urcode, int flags)
  • Parameter

    Parameter Description

    libname

    The library name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    funcname

    The function name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    args

    A parameter for the dynamic module function to call.

    urcode

    The return value from the dynamic module function.

    flags

    The following flags are available:

    • TDLTRAN : When this flag is set, the global sequence number must be returned through urcode.

    • TDL_RTLD_GLOBAL : Enables the RTLD_GLOBAL option, which allows access to externally defined variables or functions. With this option, other modules can also reference external symbols.

    • TDL_NOFLAGS : No flags are applied.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The module is temporarily inactive.

5.3. tdlcall2s

The tdlcall2 function calls the latest version of a dynamic module using the library name and function name as keys. The dynamic module must have the signature of long funcname(void *input, void *output). Except for using the library and function names as keys, tdlcall2s() behaves the same as tdlcall().

tdlcall2s() is available only when the version of the TDL configuration file (tdl.cfg) is set to 3.

  • Prototype

    #include <tdlcall.h>
    int tdlcall2s(char *libname, char *funcname, void *input, void *output,
                  long *urcode, int flags)
  • Parameter

    Parameter Description

    libname

    The library name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    funcname

    The function name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    input

    Pointer to the input buffer of the calling dynamic module function.

    output

    Pointer to the output buffer of the calling dynamic module function.

    urcode

    The return value from the dynamic module function.

    flags

    The following flags are available:

    • TDLTRAN : When this flag is set, the global sequence number must be returned through urcode.

    • TDL_RTLD_GLOBAL : Enables the RTLD_GLOBAL option, which allows access to externally defined variables or functions. With this option, other modules can also reference external symbols.

    • TDL_NOFLAGS : No flags are applied.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The module is temporarily inactive.

5.4. tdlcall2v

The tdlcall2v function invokes the latest version of a dynamic module, using the library name and function name as keys. The dynamic module function must have the signature of long funcname(int argc, char *argv[]). Except for using the library and function names as keys, tdlcall2v() behaves the same as tdlcall().

tdlcall2v() is available only when the version of the TDL configuration file (tdl.cfg) is set to 3.

  • Prototype

    #include <tdlcall.h>
    int tdlcall2v(char *libname, char *funcname, int argc, char *argv[],
                 long *urcode, int flags)
  • Parameter

    Parameter Description

    libname

    The library name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    funcname

    The function name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    argc

    The number of parameters of the dynamic module function.

    argv

    The parameter vector of the dynamic module function.

    urcode

    The return value from the dynamic module function.

    flags

    The following flags are available:

    • TDLTRAN : When this flag is set, the global sequence number must be returned through urcode.

    • TDL_RTLD_GLOBAL : Enables the RTLD_GLOBAL option, which allows access to externally defined variables or functions. With this option, other modules can also reference external symbols.

    • TDL_NOFLAGS : No flags are applied.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The module is temporarily inactive.

5.5. tdlcallva

The tdlcallva function invokes the latest version of a dynamic module, using the function name as the key. For dynamic module functions with non-fixed prototypes, parameters are passed as-is. All arguments must be of type void *, and in the dynamic module function, all received parameters must also be declared as void *.

tdlcallva() is available only when the version of the TDL configuration file (tdl.cfg) is set to 1 or 2.

  • Prototype

    #include <tdlcall.h>
    int tdlcallva(char *funcname, long urcode, int flags, int rettype, void *retval,
                  int argc, …);
  • Parameter

    Parameter Description

    funcname

    The name of the dynamic module function (Maximum size: TDL_FUNCNAME_SIZE – 1).

    urcode

    Unlike other tdlcall() fmaily functions, this parameter is used only to pass the global sequence number. When not used, set to 0.

    flags

    The following flags are available:

    • TDLTRAN : When this flag is set, the global sequence number must be returned through urcode.

    • TDL_RTLD_GLOBAL : Enables the RTLD_GLOBAL option, which allows access to externally defined variables or functions. With this option, other modules can also reference external symbols.

    • TDL_NOFLAGS : No flags are applied.

    rettype

    The return type of the dynamic module function to call.

    The following settings are available.

    • TDL_VA_CHAR : char type.

    • TDL_VA_SHORT : short type.

    • TDL_VA_INT : int type.

    • TDL_VA_LONG : long type.

    • TDL_VA_FLOAT : float type.

    • TDL_VA_DOUBLE : double type.

    • TDL_VA_PVOID : void * type.

    • TDL_VA_VOID : void type.

    retval

    A pointer to the buffer storing the return value of the dynamic module function called.

    argc

    The number of arguments to be passed with the dynamic module function. Currently up to 10 arguments are supported.

    …​

    Parameters to be passed with the dynamic module function as variable arguments. Must be of the (void *) pointer type.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The module is temporarily inactive.

  • Example

    • Dynamic module call

      int myfunc(double *a, double *b, double *c) {
          double sum;
          return (int)(((double)(*a) + (double)(*b) + (double)(*c))/3);
      }
      
      char * myfunc2(int *type) {
          char *msg;
          switch (*type) {
              case 1: msg = “foo”; break;
              case 2: msg = “bar”;break;
          }
          return msg;
      }
    • Program to be called

      #include <tdlcall.h>
      int main(int argc, char *argv[]) {
          int n;
          long urcode;
          int retval;
          double a, b, c;
          int type;
          char *retmsg;
      
          urcode = tdlgetseqno();
          a = 2.5;
          b = 3.0;
          c = 3.5;
          if ((n = tdlcallva2(“mylib001”, “myfunc”, urcode, TDLTRAN,
                   TDL_VA_INT, &retval, 3, &a, &b, &c)) != TDL_OK) {
              error processing;
          }
      
          type = 1;
          if ((n = tdlcallva2(“mylib001”, “myfunc2”, urcode, TDLTRAN,
                   TDL_VA_PVOID, &retmsg, 1, &type)) != TDL_OK) {
              error processing;
          }
      }

5.6. tdlcallva2

The tdlcallva2 function invokes the latest version of a dynamic module, using the library name and function name as keys. For dynamic module functions with non-fixed prototypes, parameters are passed as-is. All arguments must be of type void *, and in the dynamic module function, all received parameters must also be declared as void *. Except for using the library and function names as keys, tdlcallva2() behaves the same as tdlcallva().

tdlcallva2() is available only when the version of the TDL configuration file (tdl.cfg) is set to 3.

  • Prototype

    #include <tdlcall.h>
    int tdlcallva2(char *libname, char *funcname, long urcode, int flags, int rettype, void *retval, int argc, …);
  • Parameter

    Parameter Description

    libname

    The library name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    funcname

    The function name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    urcode

    Unlike other tdlcall() fmaily functions, this parameter is used only to pass the global sequence number. When not used, set to 0.

    flags

    The following flags are available:

    • TDLTRAN : When this flag is set, the global sequence number must be returned through urcode.

    • TDL_RTLD_GLOBAL : Enables the RTLD_GLOBAL option, which allows access to externally defined variables or functions. With this option, other modules can also reference external symbols.

    • TDL_NOFLAGS : No flags are applied.

    rettype

    The return type of the dynamic module function to call.

    The following settings are available.

    • TDL_VA_CHAR : char type.

    • TDL_VA_SHORT : short type.

    • TDL_VA_INT : int type.

    • TDL_VA_LONG : long type.

    • TDL_VA_FLOAT : float type.

    • TDL_VA_DOUBLE : double type.

    • TDL_VA_PVOID : void * type.

    • TDL_VA_VOID : void type.

    retval

    A pointer to the buffer storing the return value of the dynamic module function called.

    argc

    The number of arguments to be passed with the dynamic module function. Currently up to 127 arguments are supported.

    …​

    Parameters to be passed with the dynamic module function as variable arguments. Must be of the (void *) pointer type.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The module is temporarily inactive.

5.7. tdlclose

The tdlclose function either resets a module’s reference count to 0 or unloads the module from memory.

  • Prototype

    #include <tdlcall.h>
    int tdlclose(char *name, int flags)
  • Parameter

    Parameter Description

    name

    The module name.

    flags

    If set to 0, the module’s reference count is set to 0 and the module will not be unloaded from memory. If set to TDLCLOSE_HARD, the module will be unloaded from memory through dlclose().

  • Return Value

    Value Description

    TDL_OK

    The function call succeeded.

    TDL_ENOLIB

    No module with the specified name exists.

5.8. tdlcreate

The tdlcreate function creates a class instance using a class factory in the latest version of a dynamic module. The instance is created using the library name, namespace, and class name as keys.

tdlcreate() is available only when the TDL configuration file (tdl.cfg) version is set to 4.

An instance created with this function must be destroyed with tdldestroy(). Between tdlcreate() and tdldestroy(), if tdlupdate() is invoked, the current instance continues to operate on the previous version even if the dynamic module has been updated. After destroying the instance with tdldestroy(), invoking tdlcreate() again creates a new instance from the updated dynamic module.

  • Prototype

    #include <tdlcall.h>
    int tdlcreate(char *libname, char *namespace, char *classname, void *args,
                  void *object, long *urcode, int flags)
  • Parameter

    Parameter Description

    libname

    The library name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    namespace

    The namespace. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    classname

    The name of the class to create an instance.

    (Maximum size: TDL_FUNCNAME_SIZE – 1)

    args

    User-defined data to be passed to the tdlcreate_cb() callback function.

    object

    Pointer to a variable that stores the reference to the class instance created by tdlcreate_cb(). After the function returns, the user must cast the object parameter to the appropriate type before using it.

    urcode

    The return value from the tdlcreate_cb() callback function.

    flags

    Set to TDLTRAN. When this flag is set, the global sequence number must be returned through urcode. When using no flag, set to TDL_NOFLAGS.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The module is temporarily inactive.

To use a class factory in a dynamic module, the user must implement a callback function with the following signature: long tdlcreate_cb(char *namespace, char *classname, void *args, void *object). This callback creates the actual class instance using the parameters passed through tdlcreate(). The user implementation must pass the reference to the created instance through the object parameter.

When using a class factory, the dynamic module must implement both the tdlcreate_cb() and tdldestroy_cb() callback functions.

  • Prototype

    long tdlcreate_cb(char *namespace, char *classname, void *args, void *object)
  • Parameter

    Parameter Description

    namespace

    The namespace passed by tdlcreate().

    classname

    The name of the class to create the instance passed by tdlcreate().

    args

    User-defined data.

    object

    Pointer to a variable that stores the reference to the class instance created by the callback function.

5.9. tdldestroy

The tdldestroy function destroys a class instance created using a class factory in the latest version of a dynamic module. The library name, namespace, and class name are used as keys.

tdldestroy() is available only when the TDL configuration file (tdl.cfg) version is set to 4.

An instance created with tdlcreate() must be destroyed with this function. Between tdlcreate() and tdldestroy(), if tdlupdate() is invoked, the current instance continues to operate on the previous version even if the dynamic module has been updated. After destroying the instance with tdldestroy(), invoking tdlcreate() again creates a new instance from the updated dynamic module.

  • Prototype

    #include <tdlcall.h>
    int tdldestroy(char *libname, char *namespcae, char *classname, void *args,
                   void *object, long *urcode, int flags)
  • Parameter

    Parameter Description

    libname

    The library name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    namespace

    The namespace. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    classname

    The name of the class whose instance will be destroyed. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    args

    User-defined data to be passed to the tdldestroy_cb() callback function.

    object

    The reference to the class instance to be destroyed by tdldestroy_cb(). The object must be the one created using tdlcreate().

    urcode

    The return value from tdldestroy_cb().

    flags

    Set to TDLTRAN. When this flag is set, the global sequence number must be returned through urcode. When using no flag, set to TDL_NOFLAGS.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The module is temporarily inactive.

To use a class factory in a dynamic module, the user must implement a callback function with the following signature: long tdldestroy_cb(char *namespace, char *classname, void *args, void *object). This callback destroys the class instance using the parameters passed through tdldestroy(). The user implementation must pass the reference to the instance through the object parameter.

  • Prototype

    long tdldestroy_cb(char *namespace, char *classname, void *args, void *object)
  • Parameter

    namespace The namespace passed by tdlcreate().

    classname

    The name of the class to create the instance passed by tdlcreate().

    args

    User-defined data.

    object

    The reference to the class instance to be destroyed by the callback function.

5.10. tdldone

The tdldone function initializes shared memory.

  • Prototype

    #include <tdlcall.h>
    int tdldone(int flags)
  • Parameter

    Parameter Description

    flags

    Currently not used.

  • Return Value

    Value Description

    TDL_OK

    The function call succeeded.

    Smaller than 0

    The function call failed. See tdlerror.

5.11. tdlend

The tdlend function terminates explicit version consistency maintenance.

  • Prototype

    #include <tdlcall.h>
    int tdlend(void)
  • Return Value

    Value Description

    TDL_OK

    The function call succeeded.

    TDL_TRAN_ERROR

    tdlstart() was executed before the required function call. See tdlcall for more information.

5.12. tdlerror

The tdlerror function converts an error from tdlcall() into a text string. When an error occurs during execution of tdlcall(), tdlerror() returns detailed information about the error.

The return value is a pointer to an internal static variable. Because this memory may be overwritten during the next tdlcall() execution, the data must be copied to another variable if it needs to be preserved or modified.

  • Prototype

    #include <tdlcall.h>
    char* tdlerror(int retval)
  • Parameter

    Parameter Description

    retval

    The return value of the previous tdlcall() execution.

  • Return Value

    Value Description

    dlopen fail

    tdlcall() returned TDL_OPEN_ERROR.

    dlsym fai

    tdlcall() returned TDL_SYM_ERROR.

    dlclose fail

    tdlcall() returned TDL_CLOSE_ERROR.

    etc system call error

    tdlcall() returned TDL_SYSTEM_ERROR.

    TDL lib internal error

    tdlcall() returned TDL_INT_ERROR.

    funcname not found

    tdlcall() returned TDL_ENOFUNC.

    environment not found

    tdlcall() returned TDL_ENV_ERROR.

    shared version mismatch

    tdlcall() returned TDL_VER_ERROR.

    invalid arguments

    tdlcall() returned TDL_ARG_ERROR.

    library not found

    tdlcall() returned TDL_ENOLIB.

    transaction error

    tdlcall() returned TDL_TRAN_ERROR.

    inactive funcation

    tdlcall() returned TDL_EINACTIVE.

5.13. tdlfind

The tdlfind function retrieves the index of a module. It is available when VERSION=1 or VERSION=2 is set in the TDL configuration file (tdl.cfg).

  • Prototype

    #include <tdlcall.h>
    int tdlfind(char *funcname, int flags)
  • Parameter

    Parameter Description

    funcname

    The function name to retrieve.

    flags

    Currently not used.

  • Return Value

    Value Description

    Greater than or equal to 0

    The function call succeeded.

    Smaller than 0

    The function call failed. See tdlerror.

5.14. tdlfind2

The tdlfind2 function retrieves the index of a module. It is available when VERSION=3 is set in the TDL configuration file (tdl.cfg).

  • Prototype

    #include <tdlcall.h>
    int tdlfind2(char *libname, char *funcname, int flags)
  • Parameter

    Parameter Description

    libname

    The library name to retrieve.

    funcname

    The function name to retrieve.

    flags

    Currently not used.

  • Return Value

    Value Description

    Greater than or equal to 0

    The function call succeeded.

    Smaller than 0

    The function call failed. See tdlerror.

5.15. tdlgetseqno

The tdlgetseqno function retrieves and returns a global sequence number.

  • Prototype

    #include <tdlcall.h>
    unsigned int tdlgetseqno(void)
  • Return Value

    Value Description

    Greater than 0

    The function call succeeded.

    0

    The function call failed. See tdlerror.

5.16. tdlinit

The tdlinit function initializes shared memory.

  • Prototype

    #include <tdlcall.h>
    int tdlinit(int flags)
  • Parameter

    Parameter Description

    flags

    Currently not used.

  • Return Value

    Value Description

    TDL_OK

    The function call succeeded.

    Smaller than 0

    The function call failed. See tdlerror.

5.17. tdlload

When a module is invoked for the first time through tdlcall(), initialization may be delayed due to hashtable lookup in shared memory and library loading. To avoid this overhead, the tdlload function performs the hashtable search and library loading in advance, storing the module information in the local cache.

tdlload() is available only when the TDL configuration file (tdl.cfg) version is set to 1 or 2. For version 3, use tdlload2(). For version 4, use tdlload3().

  • Prototype

    #include <tdlcall.h>
    int tdlload(char *funcname, int flags)
  • Parameter

    Parameter Description

    funcname

    The name of the function to load.

    flags

    Currently not used.

  • Return Value

    Value Description

    0

    The function call succeeded.

    TDL_ENOFUNC

    The libname or funcname argument was NULL, or the passed value was not found in the hashtable.

    TDL_OPEN_ERROR

    The dynamic library listed in the hashtable could not be loaded into memory.

    TDL_SYSTEM_ERROR

    Allocation of system resources for creating a local cache failed.

5.18. tdlload2

The tdlload2 function is equivalent to tdlload.

  • Prototype

    #include <tdlcall.h>
    int tdlload2(char *libname, char *funcname, int flags)
  • Parameter

    Parameter Description

    libname

    The name of the library to load.

    funcname

    The name of the function to load.

    flags

    Currently not used.

5.19. tdlresume

The tdlresume function resumes version consistency maintenance that was previously suspended.

  • Prototype

    #include <tdlcall.h>
    int tdlresume(int sd)
  • Parameter

    Parameter Description

    sd

    Descriptor received by tdlsuspend().

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_TRAN_ERROR

    The sd value is invalid. See tdlcall for more information.

5.20. tdlstart

The tdlstart function starts explicit version consistency maintenance.

  • Prototype

    #include <tdlcall.h>
    int tdlstart(void)
  • Return Value

    Value Description

    TDL_OK

    The function call succeeded.

    TDL_TRAN_ERROR

    tdlstart() was executed before the required function call. See tdlcall.

5.21. tdlstat

The tdlstat function displays TDL statistics.

If VERSION=1 or VERSION=2 is set in the TDL configuration file (tdl.cfg), set MONITOR=Y in the configuration file.

  • Prototype

    #include <tdlcall.h>
    int tdlstat(char *funcname, struct timeval svc_time, struct timeval cpu_time)
  • Parameter

    Parameter Description

    funcname

    The name of the function to collect statistics data.

    svc_time

    The service time record.

    cpu_time

    The CPU time record.

  • Return Value

    Value Description

    TDL_OK

    The function call succeeded.

    Smaller than 0

    The function call failed. See tdlerror.

5.22. tdlstat2

The tdlstat2 function displays TDL statistics.

If VERSION=3 is set in the TDL configuration file (tdl.cfg), set MONITOR=Y in the configuration file.

  • Prototype

    #include <tdlcall.h>
    int tdlstat2(char *libname, char *funcname, struct timeval svc_time, struct timeval cpu_usrtime, struct timeval cpu_systime)
  • Parameter

    Parameter Description

    libname

    The name of the library to collect statistics data.

    funcname

    The name of the function to collect statistics data.

    svc_time

    The service time record.

    cpu_usrtime

    The user CPU time record.

    cpu_systime

    The system CPU time record.

  • Return Value

    Value Description

    TDL_OK

    The function call succeeded.

    Smaller than 0

    The function call failed. See tdlerror.

5.23. tdlsuspend

The tdlsuspend function suspends version consistency maintenance and returns a suspend descriptor (sd). The maximum number of concurrent suspend descriptors is 8.

  • Prototype

    #include <tdlcall.h>
    int tdlsuspend(void)
  • Return Value

    Value Description

    Greater than or equal to 0

    The function call succeeded.

    TDL_TRAN_ERROR

    Version consistency maintenance is not currently active. See tdlcall for more information.

6.1. WinTmaxAcall

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

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

  • Prototype

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

    Parameter Description

    sinfo

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

    wHandle

    The Windows handle to receive messages.

    msgtype

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

    svc

    The service to request for.

    sndbuf

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

    len

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

    flags

    Same as the flags for tpacall().

    The following flags are available:

    • TPBLOCK

      If tpacall() is used without setting this flag, the call may appear to succeed even if the target service (svc) does not exist, and an incorrect result may be returned. In such cases, the error is reported only when tpgetrply() is called. When tpacall() is invoked with the TPBLOCK flag, the function checks whether the target service is currently running.

    • TPNOTRAN

      If a service does not support transactions in transaction mode, the TPNOTRAN flag must be set in order to call tpacall() in transaction mode.

      If the caller requests a service by setting this flag in transaction mode, the service will be excluded from transaction mode before being executed. When invoking tpacall() in transaction mode, it will still be affected by the transaction timeout even if TPNOTRAN was set.

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

    • TPNOREPLY

      A service call sent through tpacall() returns immediately without waiting for a response. Normally, the result can be retrieved later using tpgetrply() with the descriptor returned by tpacall().

      However, when the TPNOREPLY flag is set, no response is expected. In this case, tpacall() returns 0 if the service call is successfully issued.

      If the caller is in transaction mode, the TPNOTRAN flag must also be set for TPNOREPLY to take effect. To verify the service status, the TPBLOCK flag must be specified as well. Without TPBLOCK, no error is reported even if the target service is in the NRDY state.

    • TPNOBLOCK

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

      If tpacall() is called without setting the TPNOBLOCK flag and a blocking condition occurs, the caller must wait until it is unblocked or timeout (transaction or blocking timeout) occurs.

    • TPNOTIME

      The caller waits indefinitely until receiving the response, ignoring the blocking timeout. If tpacall() is invoked within the transaction timeout period, the timeout still applies.

    • TPSIGRSTRT

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

  • Return Value

    Value Description

    1

    The function call succeeded. The returned descriptor receives the response to the service request.

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

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

    [TPENOENT]

    The service (svc) is not available because it does not exist.

    [TPEITYPE]

    The type or subtype of the data is not supported by svc. For structures, this error occurs if the struct has not been declared in the SDLFILE.

    [TPELIMIT]

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

    [TPETRAN]

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

    [TPETIME]

    A timeout occurred. If the caller was in transaction mode, the transaction time limit expired and the transaction was rolled back. If the caller is not in transaction mode, and neither TPNOTIME nor TPNOBLOCK was set, a block timeout occurred. If a transaction timeout occurs, any new service requests and processes waiting for the response will fail due to a [TPETIME] error until the transaction is rolled back.

    [TPEBLOCK]

    A blocking condition occurred while TPNOBLOCK was set.

    [TPGOTSIG]

    A signal was received while TPSIGRSTRT was not set.

    [TPEPROTO]

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

    [TPESYSTEM]

    An error occurred in the Tmax system.

    [TPEOS]

    An error occurred in the operating system.

  • Example

    ...
    #include <usrinc/tmaxapi.h>
    #define WM_WINTMAX_RECV WM_USER + 1
    ...
    
    BEGIN_MESSAGE_MAP(CWinTmaxAcall2TestDlg, CDialog)
    ...
    ON_MESSAGE(WM_WINTMAX_RECV, OnWinTmaxAcall)
    ...
    END_MESSAGE_MAP()
    
    BOOL CWinTmaxAcall2TestDlg::OnInitDialog()
    {
        CDialog::OnInitDialog();
        ...
        ret = tmaxreadenv(“tmax.env”, “TMAX”);
        if (ret == -1){
            AfxMessageBox(“tmaxreadenv fail...”);
            return FALSE;
        }
        return TRUE;  // return TRUE  unless you set the focus to a control
    }
    
    void CWinTmaxAcall2TestDlg::OnOK()
    {
        ...
        GetDlgItemText(IDC_EDIT1, m_Input);
        lstrcpy((LPTSTR)buf, (LPCTSTR)m_Input.operator const char *());
        ...
    
        buf = tpalloc(“STRING”, NULL, 0);
        if (buf == NULL){
            AfxMessageBox(“buf alloc fail...”);
            return FALSE;
        }
    
        ret = WinTmaxAcall((TPSTART_T *)NULL, m_hWnd, WM_WINTMAX_RECV,
               “TOUPPER”, buf, 0, TPNOFLAGS);
        if (ret == -1){
            error processing
        }
    }
    
    LRESULT CWinTmaxAcall2TestDlg::OnWinTmaxAcall(WPARAM wp, LPARAM lp)
    {
        char msg[100];
        memset(msg, 0x00, 100);
        TPSVCINFO *get = (TPSVCINFO *)wp;
        if (lp < 0){
            error processing
        }
        ...
        SetDlgItemText(IDC_EDIT2, get->data);
        return 0;
    }
  • Related functions

    tpacall(), WinTmaxAcall2()

6.2. WinTmaxAcall2

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

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

  • Prototype

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

    Parameter Description

    sinfo

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

    fn

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

    svc

    The service name registered in the Tmax configuration file.

    sndbuf

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

    len

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

    flags

    Same as the flags for tpacall().

    The following flags are available:

    • TPBLOCK

      If tpacall() is used without setting this flag, the call may appear to succeed even if the target service (svc) does not exist, and an incorrect result may be returned. In such cases, the error is reported only when tpgetrply() is called. When tpacall() is invoked with the TPBLOCK flag, the function checks whether the target service is currently running.

    • TPNOTRAN

      If a service does not support transactions in transaction mode, the TPNOTRAN flag must be set in order to call tpacall() in transaction mode.

      If the caller requests a service by setting this flag in transaction mode, the service will be excluded from transaction mode before being executed. When invoking tpacall() in transaction mode, it will still be affected by the transaction timeout even if TPNOTRAN was set.

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

    • TPNOREPLY

      A service call sent through tpacall() returns immediately without waiting for a response. Normally, the result can be retrieved later using tpgetrply() with the descriptor returned by tpacall().

      However, when the TPNOREPLY flag is set, no response is expected. In this case, tpacall() returns 0 if the service call is successfully issued.

      If the caller is in transaction mode, the TPNOTRAN flag must also be set for TPNOREPLY to take effect. To verify the service status, the TPBLOCK flag must be specified as well. Without TPBLOCK, no error is reported even if the target service is in the NRDY state.

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

      If tpacall() is called without setting the TPNOBLOCK flag and a blocking condition occurs, the caller must wait until it is unblocked or timeout (transaction or blocking timeout) occurs.

    • TPNOTIME

      The caller waits indefinitely until receiving the response, ignoring the blocking timeout. If tpacall() is invoked within the transaction timeout period, the timeout still applies.

    • TPSIGRSTRT

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

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

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

    [TPENOENT]

    The service (svc) is not available because it does not exist.

    [TPEITYPE]

    The type or subtype of the data is not supported by svc. For structures, this error occurs if the struct has not been declared in the SDLFILE.

    [TPELIMIT]

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

    [TPETRAN]

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

    [TPETIME]

    A timeout occurred. If the caller was in transaction mode, the transaction time limit expired and the transaction was rolled back. If the caller is not in transaction mode, and neither TPNOTIME nor TPNOBLOCK was set, a block timeout occurred. If a transaction timeout occurs, any new service requests and processes waiting for the response will fail due to a [TPETIME] error until the transaction is rolled back.

    [TPEBLOCK]

    A blocking condition occurred while TPNOBLOCK was set.

    [TPGOTSIG]

    A signal was received while TPSIGRSTRT was not set.

    [TPEPROTO]

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

    [TPESYSTEM]

    An error occurred in the Tmax system.

    [TPEOS]

    An error occurred in the operating system.

  • Example

    #include <usrinc/tmaxapi.h>
    #define WM_WINTMAX_RECV WM_USER + 1
    int mycallfn(unsigned int, long);
    ...
    
    BEGIN_MESSAGE_MAP(CWinTmaxAcall2TestDlg, CDialog)
    ...
    END_MESSAGE_MAP()
    
    BOOL CWinTmaxAcall2TestDlg::OnInitDialog()
    {
        CDialog::OnInitDialog();
        ...
        ret = tmaxreadenv(“tmax.env”, “TMAX”);
        if (ret == -1){
            AfxMessageBox(“tmaxreadenv fail...”);
            return FALSE;
        }
        return TRUE;  // return TRUE  unless you set the focus to a control
    }
    
    void CWinTmaxAcall2TestDlg::OnOK()
    {
        ...
        GetDlgItemText(IDC_EDIT1, m_Input);
        lstrcpy((LPTSTR)buf, (LPCTSTR)m_Input.operator const char *());
        ...
        buf = tpalloc(“STRING”, NULL, 0);
        if (buf == NULL){
            AfxMessageBox(“buf alloc fail...”);
            return FALSE;
        }
        ret = WinTmaxAcall2((TPSTART_T *)NULL, (WinTmaxCallback)mycallfn,
                           “TOUPPER”, (char *)buf, 0, TPNOFLAGS);
        if (ret == -1){
            error processing
        }
    }
    
    int mycallfn(unsigned int msg, long retval)
    {
        TPSVCINFO *svcinfo;
        char infomsg[30];
        memset(infomsg, 0x00, sizeof(infomsg));
        svcinfo = (TPSVCINFO *)msg;
        strncpy(infomsg, svcinfo->data, svcinfo->len);
        if (retval != 0){
            strcpy(infomsg,tpstrerror(retval));
            AfxMessageBox(infomsg);
            return -1;
        } else {
            strncpy(infomsg, svcinfo->data, sizeof(infomsg) - 1);
            AfxMessageBox(infomsg);
            return 1;
        }
    }
  • Related functions

    tpacall(),WinTmaxAcall()

6.3. WinTmaxEnd

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

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

  • Prototype

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

    Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPETIME]

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

    [TPEPROTO]

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

    [TPESYSTEM]

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

    [TPEOS]

    An error occurred in the operating system.

  • Related functions

    tpend(), WinTmaxStart()

6.4. WinTmaxSend

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

  • Prototype

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

    Parameter Description

    recvContext

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

    svc

    The service name.

    data

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

    len

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

    flags

    Flags available for WinTmaxSend() are listed below.

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

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

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

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

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

    The following flags are available:

    Flag Description

    TPBLOCK

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

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

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

    TPNOREPLY

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

    TPNOTRAN

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

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

    TPNOBLOCK

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

    If WinTmaxSend() is called without setting the TPNOBLOCK flag and a blocking condition occurs, the caller must wait until it is unblocked or timeout (transaction or blocking timeout) occurs.

    TPNOTIME

    The caller waits indefinitely until receiving the response, ignoring the blocking timeout. If WinTmaxSend() is invoked within the transaction timeout period, the timeout still applies.

    TPSIGRSTRT

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

  • Return Value

    Value Description

    Descriptor

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

    -1

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

  • Error

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

    Error Code Description

    [TPENOENT]

    The service (svc) is not available because it does not exist.

    [TPEITYPE]

    The type or subtype of the data is not supported by svc. For structures, this error occurs if the struct has not been declared in the SDLFILE.

    [TPELIMIT]

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

    [TPETIME]

    A timeout occurred. While neither TPNOTIME nor TPNOBLOCK was set, a block timeout occurred.

    [TPEBLOCK]

    A blocking condition occurred while TPNOBLOCK was set.

    [TPGOTSIG]

    A signal was received while TPSIGRSTRT was not set.

    [TPEPROTO]

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

    [TPESYSTEM]

    An error occurred in the Tmax system.

    [TPECLOSE]

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

    [TPEOS]

    An error occurred in the operating system.

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

    Error Code Description

    [TPEBADDESC]

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

    [TPEOTYPE]

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

    [TPEPROTO]

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

    [TPESYSTEM]

    An error occurred in the Tmax system.

    [TPECLOSE]

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

    [TPEOS]

    An error occurred in the operating system.

  • Example

    ...
    int CTMaxGwView::SendData2(char *data, long nLen)
    {
        CString szTemp;
        m_send_length.Format(“%d”,nLen);
        UpdateData(FALSE);
    
        char *tpbuf = tpalloc(“STRING”, NULL, nLen);
        if (tpbuf == NULL) {
            szTemp.Format(“tpalloc Error [%s]”, tpstrerror(tperrno));
            LogDisplay2(2, (char *)(const char *)szTemp, szTemp.GetLength());
            return -1;
        }
    
       memcpy(tpbuf, data, nLen);
    
       CString strService;
       strService.Format(“TOUPPER_STRING”);
    
       int nSendResult=WinTmaxSend(2,(LPSTR)(LPCSTR)strService, (char*)tpbuf, nLen, 0);
       tpfree(tpbuf);
        …
    }
  • Related functions

    WinTmaxStart(),WinTmaxEnd()

6.5. WinTmaxSetContext

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

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

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

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

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

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

  • Prototype

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

    Parameter Description

    winhandle

    The Windows handle to process received messages.

    msgType

    The message type.

    slot

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

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

    The following values can be assigned to slot:

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

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

  • Return Value

    Value Description

    index

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

    -1

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

  • Error

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

    Error Code Description

    [TPESYSTEM]

    An error occurred in the Tmax system.

    [TPEOS]

    An error occurred in the operating system.

  • Example

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

    WinTmaxStart(),WinTmaxEnd(), WinTmaxSend()

6.6. WinTmaxStart

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

  • Prototype

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

    For TPSTART_T, see tpstart.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

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

  • Error

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

    Error Code Description

    [TPEINVAL]

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

    [TPEITYPE]

    tpinfo is not a pointer to the TPSTART_T structure.

    [TPEPROTO]

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

    [TPESYSTEM]

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

    [TPEOS]

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

  • Related functions

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

7. Other Functions

7.1. tlog_close

The tlog_close function closes a transaction log file. It is used for transaction log analysis and can be used independently of the Tmax engine. It can be used solely with the <usring/tlog.h> header file and the libtlog.so library.

  • Prototype

    #include <usring/tlog.h>
    int tlog_close (tlog_file_t *log);
  • Parameter

    Parameter Description

    log

    Internal information about the log file, populated when tlog_open() is called. Also a pointer to the structure used by tlog_find().

  • Return Value

    Value Description

    TLOG_OK

    The log was successfully closed.

    Negative value

    An error occurred while calling the function.

  • Example

    #include <stdio.h>
    #include <usrinc/tlog.h>
    
    int main(int argc, char *argv[])
    {
       int n;
       tlog_entry_t entry;
       tlog_file_t log;
    
       printf(“\n====== TXLOG =====\n”);
       n = tlog_open(NULL, &log, TLOG_LOCAL);
       printf(“n = %d\n”, n);
       if (n < 0) {
          printf(“tlog_open = %d, errno = %d\n”, n, errno);
          exit(1);
       }
       ...
       tlog_close(&log);
    }
  • Related functions

    tlog_close(), tlog_find(), tlog_nodeno()

7.2. tlog_find

The tlog_find function searches for an entry that matches the specified information in a transaction log file. The result is stored in an entry passed as a parameter and returned. The function can be used independently of the Tmax engine, and solely with the <usring/tlog.h> header file and the libtlog.so library.

  • Prototype

    #include <usring/tlog.h>
    int tlog_find (tlog_file_t *log, tlog_entry_t *entry, int flags);
  • Parameter

    Parameter Description

    log

    The tlog information structure created with tlog_open().

    entry

    The entry to retrieve.

    tlog_entry_t displays the data contained in the transaction log file.

    typedef struct {
       int decision;
       TXID xid;
       time_t ltime;
       /* following fields have meaning only for TLOG_REMOTE & TLOG_NONTMAX */
       TXID remote_xid;
       char gateway_name[GATEWAY_NAME_SIZE];
    } tlog_entry_t;

    The following describes each member:

    • decision : Records the behavior of the transaction.

      The following values can be set to decision.

      /* invalid entry */
      #define TXDEC_INVALID           -1
      /* commit */
      #define TXDEC_COMMIT            0
      /* rollback */
      #define TXDEC_ROLLBACK          1
      /* rollback due to svr/cli down or failure during the prepare phase */
      #define TXDEC_ABNORMAL_ROLLBACK 2
      /* tx initiated from a remote domain */
      #define TXDEC_REMOTE            3
      /* prepare phase */
      #define TXDEC_PREPARE           4
    • xid : The XID that generates the log. A transaction log created by a gateway contains two more fields ( remote_xid and gateway_name).

    • ltime : The time when the log is generated.

    flags

    The following are the available flags-six macros that can be combined using the bitwise OR (|) operator:

    /* get next log entry */
    #define TLOG_NEXT               0x0001
    /* find an entry logged later than or equal to the ltime field */
    #define TLOG_TIME               0x0002
    /* find an entry with matching xid */
    #define TLOG_XID                0x0004
    /* find an entry with matching remote_xid */
    #define TLOG_REMOTE_XID         0x0008
    /* find an entry from the matching gateway_name field */
    #define TLOG_GATEWAY            0x0010
    /* find an entry with same decision */
    #define TLOG_DECISION           0x0020
    • TLOG_NEXT : If this flag is set, the search starts from the current position in the log file. If not set, the search starts from the beginning of the file.

    • TLOG_TIME : If set, only entries with a timestamp later than entry→ltime are searched.

    • TLOG_XID : Searches only for entries matching entry→xid. When comparing XIDs, the branch qualifier is ignored, and only the global transaction ID is considered.

    • TLOG_REMOTE_XID : Searches for entries matching entry→remote_xid.

    • TLOG_GATEWAY : Searches for entries matching entry→gateway_name.

    • TLOG_DECISION : Searches for entries matching entry→decision.

  • Return Value

    Value Description

    TLOG_OK

    The function call succeeded.

    TLOG_INVAL

    The parameter is invalid.

    TLOG_NOTFOUND

    The search reached the end of the file without finding a match.

    TLOG_ESYSTEM

    An error occurred in the Tmax system. Refer to the errno for detailed information.

  • Example

    #include <stdio.h>
    #include <usrinc/tlog.h>
    
    int main(int argc, char *argv[])
    {
       int n;
       tlog_entry_t entry;
       tlog_file_t log;
    
       printf(“\n====== TXLOG =====\n”);
       n = tlog_open(NULL, &log, TLOG_LOCAL);
       printf(“n = %d\n”, n);
       if (n < 0) {
          printf(“tlog_open = %d, errno = %d\n”, n, errno);
          exit(1);
       }
       printf(“tlog_open success\n”);
       while(1) {
       n = tlog_find(&log, &entry, TLOG_NEXT);
       if (n == TLOG_NOTFOUND)
       {
          printf(“Not found any more\n”);
          break;
        }
    
       else if (n < 0) {
          printf(“tlog_find = %d, errno = %d\n”, n,errno);
          tlog_close(&log);
          exit(1);
       }
       tlog_close(&log);
    }
  • Related functions

    tlog_open(), tlog_close(), tlog_nodeno()

7.3. tlog_nodeno

The tlog_nodeno function retrieves the node number where a transaction started, using a given XID. In a multi-node configuration, transaction logs are stored on the node where the transaction originates, so this function identifies which node corresponds to a specific XID. It can be used independently of the Tmax engine, and solely with the <usring/tlog.h> header file and the libtlog.so library.

  • Prototype

    #include <usring/tlog.h>
    int tlog_nodeno (TXID *xid);
  • Parameter

    Parameter Description

    xid

    The XID to retrieve the node number.

  • Return Value

    Value Description

    Node number

    The function call succeeded and returns the number of the node that initiated the transaction.

    Negative value

    The function call failed.

  • Example

    #include <stdio.h>
    #include <usrinc/tlog.h>
    
    int main(int argc, char *argv[])
    {
       int n, nodeno;
       tlog_entry_t entry;
       tlog_file_t log;
    
       printf(“\n====== TXLOG =====\n”);
       n = tlog_open(NULL, &log, TLOG_LOCAL);
       printf(“n = %d\n”, n);
       if (n < 0) {
          printf(“tlog_open = %d, errno = %d\n”, n, errno);
          exit(1);
       }
       printf(“tlog_open success\n”);
       while(1) {
          n = tlog_find(&log, &entry, TLOG_NEXT);
          ...
       }
    
       nodeno = tlog_nodeno(&(entry.xid));
       printf(“nodeno of txlog = %d\n”, nodeno);
       tlog_close(&log);
    }
  • Related functions

    log_open(), tlog_close(), tlog_find()

7.4. tlog_open

The tlog_open opens a transaction log file. It is used for transaction log analysis and can be used independently of the Tmax engine. It can be used solely with the <usring/tlog.h> header file and the libtlog.so library.

  • Prototype

    #include <usring/tlog.h>
    int tlog_open (char *name, tlog_file_t *log, int flags);
  • Parameter

    Parameter Description

    name

    The name of the log file.

    log

    Internal information about the log file. Used for tlog_close() or tlog_find().

    flags

    Log settings.

    The following flags are available:

    • TLOG_LOCAL

      Retrieves transaction logs on the local node.

    • TLOG_REMOTE

      Retrieves transaction logs generated through the domain gateway.

    • TXLOG

      Records 2PC operations on the node.

    • GWTXLOG

      Records remote_xid and local_xid mapping data when transaction-related requests are received through a gateway running on the node.

    The following describes the behavior for each parameter setting.

    • Opens the (TMAXDIR)/log/tlog/TXLOG file by default.

      name = NULL, flags = TLOG_LOCAL
    • Opens the $(TMAXDIR)/log/tlog/GWTXLOG file.

      name = NULL, flags = TLOG_REMOTE
    • name != NULL

      name = specified name, flags = TLOG_LOCAL
  • Return Value

    Value Description

    TLOG_OK

    The log file was opened successfully.

    Negative value

    An error occurred while opening the log file.

  • Example

    #include <stdio.h>
    #include <usrinc/tlog.h>
    
    int main(int argc, char *argv[])
    {
       int n;
       tlog_entry_t entry;
       tlog_file_t log;
    
       printf(“\n====== TXLOG =====\n”);
       n = tlog_open(NULL, &log, TLOG_LOCAL);
       printf(“n = %d\n”, n);
    
       if (n < 0) {
          printf(“tlog_open = %d, errno = %d\n”, n, errno);
          exit(1);
       }
    
       printf(“tlog_open success\n”);
       ...
    }
  • Related functions

    tlog_close(), tlog_find(), tlog_nodeno()

7.5. Usiginit

The Usiginit function initializes the Tmax signal handler and configures macros for handling user-defined signals. It is not available in Windows environments.

  • Prototype

    # include <usignal.h>
    int  Usiginit(void)
  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. Even if an error occurs, no value is set in tperrno.

  • Example

    ...
    #include <signal.h>
    #include <usrinc/usignal.h>
    
    void sig_alrm(int);
    SERVICE(TPSVCINFO *msg)
    {
        int  i, ret;
    
        data process...
    
        ret=Usiginit();
        if (ret==-1) { error processing }
    
        Usignal(SIGALRM, &sig_alrm);
        alarm(1);
    
        tpreturn(TPSUCCESS,0,(char *)msg->data, 0,0);
    }
    
    void sig_alrm(int signo)
    {
        if (signo == SIGALRM) printf(“SIGALRM recieve\n”);
    }

7.6. Usignal

The Usignal function is used to set macros for user-defined signal handling. It is not available in Windows environments. The default Tmax signal handler processes SIGALRM, SIGPIPE, and SIGTERM for internal operations.

If a user attempts to handle these signals directly using signal() system calls, internal Tmax mechanisms that rely on this handling may fail. To avoid such conflicts, the Tmax library provides the Usignal() API. Usignal() manages an internal table that records user signal handlers. When a signal occurs, the Tmax signal handler checks the table. If a user-defined handler is registered, Tmax first invokes the user handler. After the user handler finishes, the Tmax signal handler is executed.

  • Prototype

    # include <usignal.h>
    Sigfunc *Usignal(int sig, Sigfunc *func)
  • Parameter

    Parameter Description

    sig

    A number or constant. (For example: 9 or SIGKILL)

    func

    The function to be called.

  • Return Value

    Value Description

    User-defined signal handler

    There is an existing user signal handler.

    SIG_DFL

    No user signal handler exists. Even if an error occurs, no value is set to tperrno.

  • Example

    ...
    #include <signal.h>
    #include <usrinc/usignal.h>
    
    void sig_alrm(int);
    SERVICE(TPSVCINFO *msg)
    {
        int             i, ret;
        data process...
        ret=Usiginit();
        if (ret==-1) { error processing }
        Usignal(SIGALRM, &sig_alrm);
        alarm(1);
        tpreturn(TPSUCCESS,0,(char *)msg->data, 0,0);
    }
    
    void sig_alrm(int signo)
    {
        if (signo == SIGALRM) printf(“SIGALRM recieve\n”);
    }

7.7. Uunixerr

Uunixerr is a variable to set an integrated error code when an error occurs while invoking a system call.

int Uunixerr

7.8. Uunix_err

The Uunix_err function prints a system error message to stderr when an ATMI API call fails and tperrno is set to TPEOS.

  • Prototype

    # include <Uunix.h>
    void Uunix_err (char *msg)
  • Parameter

    Parameter Description

    msg

    The message to prepend to the system error message. Typically, this is the program name.

    One of the following is printed:

    • UCLOSE, UCREAT, UEXEC, UFCTNL, UFORK, ULSEEK, UMSGCTL, UMSGGET, UMSGSND, UMSGRCV, UOPEN, UPLOCK, UREAD, USEMCTL, USEMGET, USEMOP, USHMCTL, USHMGET, USHMAT, USHMDT, USTAT, UWRITE, USBRK, USYSMUL, UWAIT, UKILL, UTIME, UMKDIR, ULINK, UUNLINK, UUNAME, UNLIST

  • Example

    ret=tmaxreadenv("NO THAT FILE", "TMAX");
    if (ret<0) {
       Uunix_err("myprog");
       exit(1);
    }

    The result is as follows:

    mypog: UOPEN

7.9. Ustrerror

The Ustrerror function returns the integrated error message corresponding to a system error code (errno).

  • Prototype

    # include <Uunix.h>
    char * Ustrerror(int err);
  • Parameter

    Parameter Description

    err

    The integrated error number for which the error message is to be retrieved.

  • Return Value

    If the function call is successful, the pointer address to the integrated error message corresponding to the errno is returned.

    One of the following is returned as a char * type pointer:

    • UCLOSE, UCREAT, UEXEC, UFCTNL, UFORK, ULSEEK, UMSGCTL, UMSGGET, UMSGSND, UMSGRCV, UOPEN, UPLOCK, UREAD, USEMCTL, USEMGET, USEMOP, USHMCTL, USHMGET, USHMAT, USHMDT, USTAT, UWRITE, USBRK, USYSMUL, UWAIT, UKILL, UTIME, UMKDIR, ULINK, UUNLINK, UUNAME, UNLIST

  • Example

    ret=tmaxreadenv("NO THAT FILE", "TMAX");
    if (ret<0)
    {
        printf("%d->%s\n", Uunixerr, Ustrerror(Uunixerr));
       exit(1);
    }

    The result is as follows:

    11->UOPEN

7.10. tmax_tencrypt

The tmax_tencrypt function provides a Tmax API for encryption and decryption. It requires linking against the libtencrypt library. Since tencerrno is a global variable and not thread-safe, users must take caution when using it.

  • Prototype

    #include <usrinc/tencrypt.h>
    int tmax_tencrypt(char *src, int srclen, char **dest, int *destlen, int mode)
  • Parameter

    Parameter Description

    src

    Address of the input data for encryption/decryption.

    srclen

    Length of the input data. If set to 0, strlen() is called internally to determine the length.

    dest

    Address of the output buffer that receives the encrypted or decrypted data. Memory for the buffer is allocated internally, and must be released using free() after use.

    destlen

    Length of the output data after encryption or decryption.

    mode

    Operation mode:

    • TENC_ENCRYPT – Encrypts the input data (supports up to 255 characters).

    • TENC_DECRYPT – Decrypts the input data.

  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

    The function call failed. An error code is set in tencerrno. The codes are the same as tperrno.

  • Error

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

    Error Code Description

    [TPEPROTO]

    The secret key file was not loaded during encryption/decryption.

    [TPEINVAL]

    The input data was invalid or NULL during encryption/decryption.

    [TPEOS]

    Memory allocation failed.

    [TPELIMIT]

    The encrypted text generated during encryption exceeded the allowable size.

  • Example

    #include <stdio.h>
    #include <string.h>
    #include <usrinc/tencrypt.h>
    
    int main(int argc, char **argv)
    {
        int n, len;
        char *cipher, *plain;
    
        if (argc < 2)
            return 1;
    
        cipher = plain = NULL;
    
        n = tmax_tencrypt(argv[1], strlen(argv[1]), &plain, &len, TENC_ENCRYPT);
        if (n < 0)
            printf("ENC failed. error = %d\n", tencerrno);
        else
            printf("ENC [%s] ==> [%s][%d]\n", argv[1], plain, len);
    
        n = tmax_tencrypt(plain, len, &cipher, &len, TENC_DECRYPT);
        if (n < 0)
            printf("DEC failed. error = %d\n", tencerrno);
        else
            printf("DEC [%s] ==> [%s][%d]\n", plain, cipher, len);
    
        free(cipher);
        free(plain);
        return 0;
    }
  • Build

    cc test.c -o test -I$TMAXDIR -L $TMAXDIR/lib64 -ltencrypt