API와 에러 메시지

본 장에서는 실제 애플리케이션 개발을 위한 API 사용법과 에러 메시지에 대해서 소개한다.

1. API

다음은 RCA API 목록이다.

API 설명

tpsetfd

소켓 FD를 UCS 프로세스의 scheduler에 등록하는 함수이다.

tpclrfd

UCS 프로세스 내부의 fdset의 소켓 FD를 off시키는 데 사용되는 함수이다.

tpissetfd

UCS 서버 프로세스에서 소켓 FD로 데이터가 도착했는지를 검사하는 함수이다.

tpschedule

UCS 서버 프로세스에서 데이터의 도착을 기다리는 함수이다.

tpuschedule

UCS 서버 프로세스에서 데이터의 도착을 입력한 시간 동안 기다리는 함수이다.

tpremoteconnect

리모트와 TCP/IP로 연결하는 함수로, 특정 시간 동안 연결을 시도한다.

tpgetrcahseqno

tpgetsvrseqno API와 동일하게 RCAH 프로세스 번호를 반환하는 함수이다.

tpgetrcainfo

RCAH의 스레드 정보를 조회하는 함수이다.

1.1. tpsetfd

소켓 FD를 UCS 프로세스의 외부 소켓 스케줄러에 등록하는 함수로 UCS 방식 프로세스를 사용한 소켓 FD를 켤 때 사용된다. UCS 스케줄러는 TMM, CLH뿐만 아니라 해당 소켓 FD에 도착한 메시지도 같이 검사한다. 사용자가 지정한 소켓에 메시지가 도착했을 경우 tpschedule()은 별도의 처리없이 정상 결과(UCS_USER_MSG)를 반환하며 어떤 소켓에 메시지가 도착했는지를 알기 위해서는 아래에 설명된 tpisetfd()를 사용해야 한다.

  • 프로토타입

    #include <ucs.h>
int  tpsetfd (int  fd)

  • 파라미터

    파라미터 설명

    fd

    등록할 소켓 FD를 설정한다.

  • 반환값

    반환값 설명

    1

    함수 호출에 성공한 경우이다.

    -1

    함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

  • 오류

    tpsetfd()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

    에러 코드 설명

    [TPESYSTEM]

    Tmax 시스템 에러가 발생한 경우로 자세한 정보는 로그 파일에 기록된다.

    [TPEOS]

    운영 시스템에 에러가 발생하였다.

  • 예제

    #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)){
            /* 소켓으로부터 버퍼를 읽는다 */
            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;
}

  • 관련 함수

    tpclrfd(), tpissetfd()

1.2. tpclrfd

UCS 방식 프로세스 내부의 fdset의 소켓 FD를 off시키는 데 사용되는 함수로 UCS 방식 서버 프로세스의 외부 소켓을 스케줄링하는 경우에 사용한다.

  • 프로토타입

    #include <ucs.h>
int  tpclrfd (int fd)

  • 파라미터

    파라미터 설명

    fd

    off할 내부 fdset의 소켓이다.

  • 반환값

    반환값 설명

    1

    함수 호출에 성공한 경우이다.

    -1

    함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

  • 오류

    tpclrfd()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

    에러 코드 설명

    [TPESYSTEM]

    Tmax 시스템 에러가 발생한 경우로 자세한 정보는 로그 파일에 기록된다.

    [TPEOS]

    운영 시스템에 에러가 발생하였다.

  • 예제

    #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)){
            /* 소켓으로부터 버퍼를 읽는다 */
            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;
}

  • 관련 함수

    tpissetfd()

1.3. tpissetfd

서버에서 UCS 프로세스에서 소켓 FD로 데이터가 도착했는지를 검사하는 함수로 UCS 방식 서버 프로세스의 외부 소켓을 스케줄링하는 데 사용한다.

  • 프로토타입

    #include <ucs.h>
int  tpissetfd (int fd)

  • 파라미터

    파라미터 설명

    fd

    테스트할 fdset 내부의 FD를 설정한다.

  • 반환값

    반환값 설명

    양수

    메시지가 도착했을 경우이다.

    0

    메시지가 도착하지 않은 경우이다.

    -1

    함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

  • 오류

    tpissetfd()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

    에러 코드 설명

    [TPESYSTEM]

    Tmax 시스템 에러가 발생하였다. 자세한 정보는 로그 파일에 기록된다.

    [TPEOS]

    운영 시스템에 에러가 발생하였다.

  • 예제

    #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)){
                /* 소켓으로부터 버퍼를 읽는다 */
                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;
}

  • 관련함수

    tpissetfd(), tpsetfd()

1.4. tpschedule

UCS 형태의 서버 프로세스에서만 사용 가능한 함수로 UCS 서버 프로세스에서 데이터의 도착을 기다린다. 최대 타임아웃 시간 동안 sleep하다가 그 안에 데이터가 도착하면 즉시 반환한다.

tpschedule() 함수는 데이터가 도착했을 때 해당되는 서비스가 자동적으로 수행되고 난 후에 반환된다. 그러므로 데이터가 도착한 후에 사용자가 임의로 서비스를 수행하면 안 된다.

서비스는 무조건 시스템에 의해서 항상 수행되므로 UCS 형태의 서비스 프로그램이라도 이점을 주의해야 한다.

  • 프로토타입

    #include <ucs.h>
int  tpschedule(int timeout)

  • 파라미터

    파라미터 설명

    timeout

    기다릴 시간을 초 단위로 입력해야 한다.

    • -1 : 데이터가 도착했는지 체크만 한 후 즉시 반환한다.

    • 0 : 데이터가 도착할 때까지 무한 대기한다.

  • 반환값

    반환값 설명

    양의 정수

    함수가 수행에 성공해서 데이터가 도착한 경우이다.

    -1

    타임아웃 시간까지 데이터가 도착하지 않은 경우 또는 함수가 수행에 실패해서 에러가 발생한 경우이다. 타임아웃 시간까지 데이터가 도착하지 않으면 -1을 반환하고, tperrno에13번(TPETIME)이 설정된다. 그 외의 경우 tperrno에 에러 코드가 설정된다.

  • 오류

    tpschedule()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

    에러 코드 설명

    [TPESYSTEM]

    Tmax 시스템 에러가 발생한 경우로 자세한 정보는 로그 파일에 기록된다.

    [TPEOS]

    운영 시스템에 에러가 발생하였다.

    [TPETIME]

    타임아웃 시간까지 데이터가 도착하지 않았다.

    [TPEPROTO]

    함수가 부적절한 상황에서 호출되었을 경우이다. 예를 들어 서비스 내에서 호출하는 경우 발생한다.

  • 예제

    #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}
        ...
    }
}

  • 관련 함수

    tpsleep(), tp_sleep(), tp_usleep()

1.5. tpuschedule

UCS 서버 프로세스에서 데이터의 도착을 microsecond 단위로 입력한 시간 동안 기다리는 함수이다. tpuschedule()은 UCS 형태의 서버 프로세스에서만 사용 가능한 함수로 최대 타임아웃(timeout) 시간 동안 대기하다가 정해진 시간 안에 데이터가 도착하면 즉시 반환한다.

  • 프로토타입

    #include <ucs.h>
int tpuschedule (int timeout)

  • 파라미터

    파라미터 설명

    timeout

    대기할 시간을 시간을 microsecond 단위로 입력해야 한다.

    • –1 : 데이터가 도착했는지 체크만 하고 즉시 종료한다.

    • 0 : 데이터가 도착할 때까지 대기한다.

  • 반환값

    반환값 설명

    0

    타임아웃 시간까지 데이터가 도착하지 않는 경우이다.

    양의 정수

    타임아웃 시간까지 데이터가 도착한 경우이다.

    -1

    함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

  • 오류

    tpuschedule()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

    에러 코드 설명

    [TPESYSTEM]

    Tmax 시스템 에러가 발생한 경우로 자세한 정보는 로그 파일에 기록된다.

    [TPEOS]

    운영 시스템에 에러가 발생하였다.

  • 예제

    ...
#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 }
        ...
     }
}

  • 관련 함수

    tpschedule()

1.6. tpremoteconnect

리모트와 TCP로 연결하는 함수로서 sec가 주어지면 해당 시간 동안 연결을 시도한다. 시간 초과의 경우 연결 오류가 발생한다.

  • 프로토타입

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

  • 반환값

    반환값 설명

    0

    소켓 번호이다.

    -1

    함수 호출에 실패한 경우이다. tperrno에 에러 상황에 해당되는 값이 설정된다.

1.7. tpgetrcahseqno

Tmax API인 tpgetsvrseqno API와 동일하게 RCAH 프로세스 번호를 반환하는 함수이다. 이 번호는 RCAL에서 순차적으로 부여한 번호이다.

  • 프로토타입

    #include <ucs.h>
int tpgetrcahseqno()

  • 반환값

    반환값 설명

    0

    RCAH 프로세스 순서 번호이다.

1.8. tpgetrcainfo

RCAH의 Thread 정보를 알려주는 함수이다.

  • 프로토타입

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

  • 반환값

    RCA 헤더 파일의 RCAINFO에 대한 포인터를 반환한다.

2. 에러 메시지

RCA는 기본적으로 Tmax 클라이언트로 동작하기 때문에 Tmax 시스템에서 제공하는 함수를 사용하는 경우에 발생하는 에러 메시지는 Tmax Application Development Guide를 참고하며, 에러 메시지에 대해서는 Tmax Error Message Reference Guide를 참고한다.