User API Function

This chapter describes the API functions that can be used in the client usrmain program.

1. Callback Function

1.1. user_thrmain

Thread’s main callback function that the user must create. TCPGWTHR executes the user program in a thread format.

  • Prototype

    int user_thrmain(WORKTHRINFO *wthrinfo, int server)

  • Parameter

    Parameter Description

    wthrinfo

    Pointer to WORKTHRINFO received from the thread.

    server

    Variable that displays whether the thread is in the server mode or client mode.

    • 0: Client mode

    • 1: Server mode

  • Return Value

    The macro used in the return value is defined in the tcphdr.h header file.

    Return Value Description

    WTHR_NORMAL_RETURN

    When the thread terminates successfully. Connection with the server or the client is terminated without an error log.

    WTHR_ABNORMAL_RETURN

    When the thread terminates abnormally. The error log is recorded in slog and the connection is terminated.

2. API Functions

The following table is a list of API functions. The function prototypes are defined in the tcphdr.h header file.

Function Name Description

tcpgw_tpcall

Synchronous Tmax service call function.

tcpgw_tpacall

Asynchronous Tmax service call function.

tcpgw_tpreply

Returns the result to Tmax.

tcpgw_get_svcdata

Receives data from Tmax.

tcpgw_select

Waits to receive a request from the thread until the timeout expires.

tcpgw_network_connect

Connects with the remote server when TCPGWTHR is running in the client mode.

tcpgw_read

Receives data from the remote server.

tcpgw_write

Sends data to the remote server.

tcpgw_portno_ipaddr

Gets the remote server’s address and port number.

tcpgw_client_id

Gets the client ID from the environment file of the gateway allocated to the thread.

tcpgw_getaddr_from_winfo

Gets the remote address and port number from the WORKTHRINFO struct received from the thread.

2.1. tcpgw_tpcall

Synchronous Tmax service call function.

  • Prototype

    int tcpgw_tpcall(WORKTHRINFO *wthrinfo, char *svc, char *ptr, long alen,
                 char *optr, long *olen)

  • Parameter

    Parameter Description

    wthrinfo

    Pointer to the WORKTHRINFO struct received from the thread.

    svc

    Tmax service name.

    ptr

    Buffer pointer to the data to send to the Tmax service.

    alen

    Length of the data to send to the Tmax service.

    optr

    Buffer pointer used to receive the result from the Tmax service.

    olen

    Long pointer to the data length of the result.

  • Return Value

    When an error occurs during Tmax service processing, the error code is returned as the return value. A value of -1 indicates an abnormal error, while other negative values indicate the actual error code (excluding '-') for an error during service processing.

2.2. tcpgw_tpacall

This function is used to send a request without receiving a reply (TPNOREPLY).

  • Prototype

    int tcpgw_tpacall(WORKTHRINFO *wthrinfo, char *svc, char *ptr, long alen)

  • Parameter

    Parameter Description

    wthrinfo

    Pointer to the WORKTHRINFO struct received from the thread.

    svc

    Tmax service name.

    ptr

    Buffer pointer to the data to send to the Tmax service.

    alen

    Length of the data to send to the Tmax service.

  • Return Value

    When an error occurs during Tmax service processing, the error code is returned as the return value. A value of -1 indicates an abnormal error, while other negative values indicate the actual error code (excluding '-') for an error during service processing.

2.3. tcpgw_tpreply

This function returns the result to Tmax. When Tmax initiates a service request first, the service is processed on the remote server and the result is returned to Tmax.

  • Prototype

    int tcpgw_tpreply(WORKTHRINFO *wthrinfo, char *ptr, long alen, int err)

  • Parameter

    Parameter Description

    wthrinfo

    Pointer to the WORKTHRINFO struct received from the thread.

    ptr

    Buffer pointer to the data to send to the Tmax service.

    alen

    Length of the data to send to the Tmax service.

    err

    Error code of an error that occurs during service processing.

  • Return Value

    When an error occurs during Tmax service processing, the error code is returned as the return value. A value of -1 indicates an abnormal error, while other negative values indicate the actual error code (excluding '-') for an error during service processing.

2.4. tcpgw_get_svcdata

This function receives data from Tmax.

  • Prototype

    int tcpgw_get_svcdata(WORKTHRINFO *wthrinfo, char *ptr, int *err, int *flags)

  • Parameter

    Parameter Description

    wthrinfo

    Pointer to the WORKTHRINFO struct received from the thread.

    ptr

    Pointer to the buffer where data will be stored.

    err

    Int pointer to where the error code will be stored.

    flags

    Sets whether to receive a reply or not when requesting a service from Tmax.

    0 indicates a waiting status for a reply from the Tmax service, 1 indicates a no waiting status.

  • Return Value

    Return Value Description

    Data Length

    When the function call was successful.

    –1

    When the function call failed.

2.5. tcpgw_select

This function waits to receive a request from the thread until the timeout expires.

  • Prototype

    int tcpgw_select(WORKTHRINFO *wthrinfo, int sec, int usec)

  • Parameter

    Parameter Description

    wthrinfo

    Pointer to the WORKTHRINFO struct received from the thread.

    sec

    Timeout. (unit: second)

    usec

    Timeout. (unit: microsecond)

  • Return Value

    Return Value Description

    WTHR_SELECT_TIMEOUT(1)

    Indicates a timeout.

    WTHR_TMAX_REQUEST(2)

    Indicates a Tmax request.

    WTHR_USER_REQUEST(3)

    Indicates a remote request.

    WTHR_SELECT_ERROR(-1)

    Indicates other errors.

2.6. tcpgw_network_connect

This function connects with the remote server when TCPGWTHR is running in the client mode.

  • Prototype

    int tcpgw_network_connect(char *host, int port, int sec)

  • Parameter

    Parameter Description

    host

    Remote address or hostname to connect to. IPv6 address is supported.

    port

    Remote port number to connect to.

    sec

    Timeout. (Unit: second)

  • Return Value

    Return Value Description

    Socket Number

    When the function call was successful.

    –1

    When the function call failed.

2.7. tcpgw_read

This function receives data from the remote server.

  • Prototype

    int tcpgw_read(int fd, char *ptr, int nbytes, int sec, int usec)

  • Parameter

    Parameter Description

    fd

    Remote socket number.

    ptr

    Buffer pointer to data.

    nbytes

    Length to data to receive from the remote server.

    sec

    Timeout. (Unit: second)

    usec

    Timeout. (Unit: microsecond)

  • Return Value

    Return Value Description

    Data Length

    When the function call was successful.

    –1

    When the function call failed.

2.8. tcpgw_write

This function sends data to the remote server.

  • Prototype

    int tcpgw_write(int fd, char *ptr, int nbytes)

  • Parameter

    Parameter Description

    fd

    Remote socket number.

    ptr

    Buffer pointer to data.

    nbytes

    Length of data to send to the remote server.

  • Return Value

    Return Value Description

    Data Length

    When the function call was successful.

    –1

    When the function call failed.

2.9. tcpgw_portno_ipaddr

This function gets the remote server’s address and port number.

  • Prototype

    int tcpgw_portno_ipaddr(char *ipaddr)

  • Parameter

    Parameter Description

    ipaddr

    Pointer to the buffer where the remote address will be stored.

  • Return Value

    The remote port number specified in the environment configuration is returned.

2.10. tcpgw_client_id

This function gets the client ID from the environment file of the gateway allocated to the thread.

  • Prototype

    int tcpgw_client_id (WORKTHRINFO *wthrinfo, char *id)

  • Parameter

    Parameter Description

    wthrinfo

    Pointer to WORKTHRINFO.

    id

    Pointer to the buffer where the ID will be stored.

  • Return Value

    The return value is not used for any purpose.

2.11. tcpgw_getaddr_from_winfo

This function gets the remote address and port number from the WORKTHRINFO struct received from the thread.

  • Prototype

    int tcpgw_getaddr_from_winfo(WORKTHRINFO *wthrinfo, char *ipaddr)

  • Parameter

    Parameter Description

    wthrinfo

    Pointer to the WORKTHRINFO struct received from the thread.

    ipaddr

    Pointer to the buffer where the remote address will be stored. If IPv6 address is configured, then enough buffer size must be allocated to accommodate IPv6 addresses.

  • Return Value

    The remote port number specified in the environment configuration is returned.