APIs and Error Messages

This chapter explains how to use APIs for actual application development and the error messages.

1. API

The following table is a list of RCA APIs.

API Description

tpsetfd

Registers a socket FD in an external socket scheduler of UCS process.

tpclrfd

Turns off the socket FD in an internal fdset of UCS-type process.

tpissetfd

Checks if data is received in a socket FD in a UCS process.

tpschedule

Waits for data to be received in UCS-type server process.

tpuschedule

Waits for data to be received for a specified time in UCS-type server process.

tpremoteconnect

Accesses a remote system through TCP.

tpgetrcahseqno

Returns a RCAH process number like Tmax tpgetsvrseqno API.

tpgetrcainfo

Retrieves RCAH thread information.

1.1. 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.2. 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()

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

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

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

1.6. 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.7. 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.8. 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.

2. Error Messages

RCA basically operates as a Tmax client, so refer to Tmax Application Develoment Guide for the error messages that occur while using the functions provided in Tmax system. The common error messages that apply to the entire Tmax system are not explained in this guide.

This chapter only explains the error messages that appear while using the RCA module. For other messages, refer to Tmax Error Message Reference Guide .

SVR0014 exec error: /user/tmax/appbin/rcah [No such file or directory]

Category

FATAL

Description

Failed to find the RCAH in the specified RCA_DIR.

Action

Check that the RCAH execution file exists in the specified RCA_DIR.
SVR0019: no available thread slot

Category

ERROR

Description

An error occurred while registering a new thread. This occurs when attempting to run more than the number of RCAs set in RCA_NTHR.
SVR0020: thread create error

Category

ERROR

Description

Failed to create a thread.

Action

Check the system resource.
SVR0100: RCA_PORT env is not set: set to default port (8899)

Category

ERROR

Description

RCA_PORT was not specified so the default value has been used.

Action

Specify a desired RCA_PORT to start the RCA. This error can be ignored when using the default value.
SVR2016: register to RCAL errror

Category

FATAL

Description

Failed to register to the RCAL.

Action

Check that the RCAL has started.
SVR3001: rcah is not ready yet

Category

WARN

Description

A client accessed but RCAH has not been started.

Action

This error occurs when a service has been received but the system or RCA has not started yet. The system or RCA must be started first to receive a service request.
SVR3003: rcah allocation error

Category

ERROR

Description

Rcah has not started yet but a client request has been received.

Action

1. Verify that the client module of the RCAH is valid when all RCAHs are shut down.

2. This error may be related to “send to rcah error” so check the system environment.
SVR3007: send to rcah error

Category

FATAL

Description

An error occurred while RCAL sends an fd to RCAH.

Action

This error occurred while using the basic system function so check the system environment.
SVR5103: unable to start RCAH

Category

FATAL

Description

An error occurred while starting an RCAH.

Action

1. Check that the RCAH executable file exists in the specified RCA_DIR.

2. Verify that the thrinit() routine of the RCAH client module is valid.
SVR5109: rcah shutdown

Category

ERROR

Description

The RCAH has been terminated.

Action

This error occurs when an RCAH has been terminated after the RCAL was forcibly shut down. Identify the reason whey the RCAL has been terminated.