API 함수

본 장에서는 HMS를 통해 메시지를 전달하기 위해 필요한 여러 가지 API들에 대해서 설명한다.

1. 개요

HMS API 함수들은 Tmax API와 함께 제공되는 서버 라이브러리와 클라이언트 라이브러리를 통해 제공된다. 따라서 Tmax API와 HMS API를 함께 사용하여 애플리케이션을 작성할 수 있다. UNIX 환경에서 서버 라이브러리는 libsvr.a, 클라이언트 라이브러리는 libcli.a, libclithr.a로 제공되며, 애플리케이션을 컴파일할 때 해당 라이브러리를 포함하여 컴파일해야 한다.

Tmax API는 기본적으로 hmsapi.h 헤더 파일을 사용하며, Tmax API를 함께 사용하기 위해서는 atmi.h, tmaxapi.h, tx.h 헤더 파일을 함께 사용한다. 클라이언트 애플리케이션을 작성할 경우 HMS를 이용하기 위해서는 반드시 Tmax로 tpstart()를 통해 연결되어야 한다. 따라서 이 경우에는 hmsapi.h와 더불어 atmi.h 헤더 파일을 사용해야 한다.

헤더 파일 설명

hmsapi.h

HMS를 사용하기 위한 세션 및 생산자(Producer), 소비자(Consumer), 메시지 등과 관련된 API들이 정의되어 있다.

atmi.h

버퍼 관리 및 통신과 관련된 API들이 정의되어 있다.

tmaxapi.h

비표준 API의 프로토타입이 정의되어 있다.

tx.h

트랜잭션 함수에 대한 프로토타입이 정의되어 있다.

HMS API는 크게 세션, 생산자, 소비자, 메시지, Queue Browser의 5 부분으로 나뉜다.

  • 세션 API

    API 설명

    hms_create_session

    HMS에 대한 세션을 생성하고 세션 핸들을 반환한다.

    hms_create_xa_session

    HMS에 대한 XA 세션을 생성하여 핸들을 반환한다.

    hms_create_async_session

    비동기 세션을 생성하여 핸들을 반환한다.

    hms_close_session

    세션을 종료한다.

    hms_unsubscribe_durable_subscriber

    영속적 구독자에 대한 등록을 해제한다.

    hms_commit

    세션을 통해 주고받았던 메시지에 대한 로컬 트랜잭션을 commit한다.

    hms_rollback

    세션을 통해 주고받았던 메시지에 대한 로컬 트랜잭션을 rollback한다.

    hms_recover

    세션을 통해 주고받았던 메시지 중 ACK를 받지 못한 메시지부터 전송을 다시 시작하도록 한다.

  • 메시지 API

    API 설명

    hms_alloc

    메시징 서비스에 사용할 메시지 버퍼를 할당하고 포인터를 반환한다.

    hms_free

    메시지 버퍼에 할당된 메모리를 해제한다.

    hms_get_property

    메시지에 설정된 해당하는 이름의 프로퍼티의 정보를 가져온다 .

    hms_set_property

    해당하는 이름으로 메시지에 프로퍼티를 설정한다.

    hms_get_body

    메시지의 데이터 부분을 가져온다.

    hms_set_body

    메시지의 데이터 부분을 설정한다.

    hms_ack

    수신받은 메시지에 200대한 ACK을 전송한다.

  • 생산자(Producer) API

    API 설명

    hms_create_producer

    Destination으로 메시지를 전송하기 위해 생산자를 생성하고 핸들을 반환한다.

    hms_create_sender

    Queue 타입의 Destination에 메시지를 전송할 송신자를 생성한다.

    hms_create_publisher

    Topic 타입의 Destination에 메시지를 전송할 발행자를 생성한다.

    hms_close_producer

    생산자를 닫고, 할당되었던 리소스를 반환한다.

    hms_close_sender

    Queue 타입의 송신자를 닫고, 할당되었던 리소스를 반환한다.

    hms_close_publisher

    Topic 타입의 발행자를 닫고, 할당되었던 리소스를 반환한다.

    hms_sendex

    생산자를 생성할 때 지정한 Destination으로 메시지를 전송한다.

    hms_send

    기본적인 설정만으로 메시지를 전송한다.

  • 소비자(Consumer) API

    API 설명

    hms_create_consumer

    Destination으로부터 메시지를 수신할 소비자를 생성하고 핸들을 반환한다.

    hms_create_receiver

    Queue 타입인 Destination으로부터의 수신자를 생성한다.

    hms_create_subscriber

    Topic 타입인 Destination으로부터의 구독자를 생성한다.

    hms_create_durable_subscriber

    Topic 타입인 Destination으로부터 수신할 영속적 구독자를 생성한다.

    hms_close_consumer

    소비자를 닫고, 할당되었던 리소스를 반환한다.

    hms_close_receiver

    Queue 타입인 수신자를 닫고, 할당되었던 리소스를 반환한다.

    hms_close_subscriber

    Topic 타입인 구독자를 닫고, 할당되었던 리소스를 반환한다.

    hms_close_durable_subscriber

    영속적 구독자를 닫고, 할당되었던 리소스를 반환한다.

    hms_recvex

    Destination으로부터 메시지를 수신한다.

    hms_recv

    Destination으로부터 메시지가 도착할 때까지 기다리는 함수이다.

  • Queue Browser API

    API 설명

    hms_create_browser

    Destination에 존재하는 메시지를 조회할 수 있는 Queue Browser를 생성하고 핸들을 반환한다.

    hms_close_browser

    Queue Browser를 닫고, 할당되었던 리소스를 반환한다.

    hms_browser_nextmsg

    가장 최근에 들어온 메시지부터 순서대로 메시지를 조회한다.

    hms_browser_get_msgselector

    Browser를 생성할 때 설정했던 Message Selector 문장을 가져온다.

    hms_browser_get_queue

    Browser를 생성할 때 설정했던 Destination의 이름을 버퍼에 복사하고 그 길이를 len에 설정한다.

2. 세션 API

세션 API는 세션을 생성하고 종료하기 위한 API 및 트랜잭션과 관련된 API들로 구성된다.

2.1. hms_create_session

HMS에 대한 세션을 생성하고 세션 핸들을 반환하는 함수이다. 세션 핸들을 이용하여 세션, 생산자, 소비자, 메시지, Queue Browser를 생성할 수 있다. 세션을 생성할 때 로컬 트랜잭션 여부와 ACK 모드를 함께 설정할 수 있다. 로컬 트랜잭션 모드에서는 hms_commit 또는 hms_rollback API를 호출해야만 트랜잭션이 완료된다.

클라이언트 애플리케이션에서 hms_create_session API를 사용하기 위해서는 우선 Tmax로의 연결이 필요하다. tpstart()를 통해서 Tmax와 연결을 맺은 뒤에 세션을 생성해야 한다. 서버 애플리케이션에서 사용할 경우에는 tpstart()를 통해 연결할 필요가 없다.

  • 프로토타입

    #include  <usrinc/hmsapi.h>
HMS_SHND * hms_create_session (char *hms, int transacted, int ackmode, int flags)

  • 파라미터

    파라미터 설명

    hms

    설정 파일의 SVRGROUP 절에서 지정한 HMS에 해당하는 서버 그룹명이다.

    transacted

    로컬 트랜잭션 여부이다.

    • 0 : 로컬 트랜잭션을 사용하지 않는다.

    • 1 : 로컬 트랜잭션을 사용한다.

    ackmode

    • HMS_AUTO_ACK : 내부적으로 각각의 메시지마다 ACK을 보낸다.

    • HMS_CLIENT_ACK : 클라이언트가 직접 ACK을 보낸다.

    • HMS_DUPS_OK_ACK : 다수의 메시지를 받고 한 번에 ACK을 보낸다. (현재 지원 안됨)

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    생성된 세션 핸들에 대한 포인터

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

    NULL

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

  • 오류

    다음과 같은 상황에서 hms_create_session()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. hms가 NULL이거나 지정된 문자열 길이를 초과했거나, ackmode가 유효하지 않은 값으로 설정되었다.

    [TPEOS]

    클라이언트에서 API를 사용할 때 발생 가능하다. HMS 운영 시스템에 에러가 발생했거나 환경변수 설정이 잘못된 경우이다.

    예를 들어 TMAX_HOST_ADDR나TMAX_HOST_PORT가 잘못 설정되어 연결이 실패한 경우에 발생한다.

    [TPESYSTEM]

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

    [TPELIMIT]

    HMS에 연결된 세션의 수가 설정 파일의 MAXSESSION에 도달하여 더 이상 세션을 생성할 수 없는 상태이다.

    [TPENOREADY]

    HMS로 지정한 이름의 HMS가 NOT READY 상태인 경우 발생한다.

    [TPENOENT]

    HMS로 지정한 이름의 HMS가 존재하지 않는 경우이다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_CHND *cons;
    hms_msg_t *msg;
    char *hms, *dest;
    char *buf;
    int ret;
    long size = 1024;
    ...
    if (argc != 3)
        return;
    hms = argv[1];
    dest = argv[2];
    /* 로컬 트랜잭션 모드의 세션을 생성함 */
    session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL,
                               NULL, 0);
    if (cons == NULL) { error processing }
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }
    ret = hms_recv(cons, &msg, 0);
    if (ret < 0) { error processing }
    buf = tpalloc("STRING", NULL, 0);
    if (buf == NULL) { error processing }
    ret = hms_get_body(msg, buf, &size);
    if (ret < 0) { error processing }
    ...
    ret = hms_commit(session, 0);
    if (ret < 0) { error processing }
    ...
    hms_free(msg);
    hms_close_consumer(cons, 0);
    /* 세션을 종료함 */
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_close_session(), hms_create_producer(), hms_create_consumer(), hms_create_browser(), hms_commit(), hms_rollback(), hms_recover()

2.2. hms_create_xa_session

HMS에 대한 XA 세션을 생성하여 핸들을 반환하는 함수이다. 이 세션으로 생성한 클라이언트(생산자 또는 소비자)의 모든 메시지는 트랜잭션으로 처리된다. 트랜잭션 범위는 tx_begin()을 호출해서 tx_commit() 또는 tx_rollback()이 호출되는 곳까지이다. tx_begin()과 tx_commit()의 범위 밖에서 메시지를 처리한다면 해당 메시지는 트랜잭션의 영향을 받지 않는다. hms_create_session으로 생성할 때 transacted = 0, ackmode = HMS_AUTO_ACK으로 설정했을 때와 동일하게 작동하게 되고, hms_send(), hms_recv() API를 호출하는 즉시 호출 결과가 반영된다.

클라이언트 애플리케이션에서 hms_create_xa_session API를 사용하기 위해서는 우선 Tmax로의 연결이 필요하다. tpstart()를 통해서 Tmax와 연결을 맺은 뒤에 세션을 생성해야 한다. 서버 애플리케이션에서 사용할 경우에는 tpstart()를 통해 연결할 필요가 없다.

  • 프로토타입

    #include <usrinc/hmsapi.h>
HMS_SHND * hms_create_xa_session (char *hms, int flags)

  • 파라미터

    파라미터 설명

    hms

    설정 파일에서 지정한 HMS에 해당하는 서버 그룹명이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    생성된 세션 핸들에 대한 포인터

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

    NULL

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

  • 오류

    다음 상황에서 hms_create_xa_session()은 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. hms가 NULL이거나 지정된 문자열 길이를 초과했다.

    [TPEOS]

    클라이언트에서 API를 사용할 때 발생할 수 있다. HMS 운영 시스템에 에러가 발생했거나 환경변수 설정이 잘못된 경우이다.

    예를 들어 TMAX_HOST_ADDR나TMAX_HOST_PORT가 잘못 설정되어 연결이 실패한 경우에 발생한다.

    [TPESYSTEM]

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

    [TPELIMIT]

    HMS에 연결된 세션의 수가 설정 파일의 MAXSESSION에 도달하여 더 이상 세션을 생성할 수 없는 상태이다.

    [TPENOREADY]

    HMS로 지정한 이름의 HMS가 NOT READY 상태인 경우 발생한다.

    [TPENOENT]

    HMS로 이름의 HMS가 존재하지 않는 경우이다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_PHND *prod;
    hms_msg_t *msg;
    char *hms, *dest, *buf;
    int ret;
    long size = 1024;
    ...
    if (argc != 3)
        return;
    hms = argv[1];
    dest = argv[2];
    /* 글로벌 트랜잭션 모드의 세션을 생성함 */
    session = hms_create_xa_session(hms, 0);
    if (session == NULL) { error processing }

    ret = tx_begin();
    if (ret < 0) { error processing }

    prod = hms_create_producer(session, dest, HMS_QUEUE, "producer_1", 0);
    if (prod == NULL) { error processing }
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }
    ...
    ret = hms_set_body(msg, buf, size);
    if (ret < 0) { error processing }
    ret = hms_send(prod, msg, 0);
    if (ret < 0) { error processing }
    ...
    ret = tx_commit();
    if (ret < 0) { error processing }
    ...
    hms_free(msg);
    hms_close_producer(prod, 0);
    /* 세션을 종료함 */
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_close_session()

2.3. hms_create_async_session

비동기 세션을 생성하여 핸들을 반환하는 함수이다. 이 세션으로 메시지를 비동기적으로 처리할 수 있다.

비동기 세션으로 소비자를 생성하고 메시지를 수신하기 위해서는 hms_recv()를 호출하는 대신 메시지를 수신하고 이를 처리할 서비스를 지정해야 한다. 서비스명은 소비자를 생성할 때 지정할 수 있다. 비동기 세션을 통해 소비자를 생성할 때는 반드시 svcname을 지정하여 메시지를 처리할 서비스를 지정해야 한다. 해당 서비스는 새로운 메시지가 Destination으로 전송되면 즉시 해당 메시지를 수신하게 되며 이에 대한 처리를 수행하게 된다. 클라이언트나 서버 애플리케이션 어느 곳에서든지 비동기 세션을 통한 소비자를 생성할 수 있다.

비동기 세션이 종료되거나 HMS에서 장애가 발생하는 경우에는 Abendfunc Callback 함수가 실행된다. 사용자는 이 함수를 정의하여 장애가 발생할 경우를 대비할 수 있다.

  • 프로토타입

    #include <usrinc/hmsapi.h>
HMS_SHND * hms_create_async_session (char *hms, Abendfunc *func, int flags)

  • 파라미터

    파라미터 설명

    hms

    설정 파일에서 지정한 HMS에 해당하는 서버 그룹명이다.

    func

    HMS에 장애가 발생했을 경우 불리는 콜백함수이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    생성된 세션 핸들에 대한 포인터

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

    NULL

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

  • 오류

    다음 상황에서 hms_create_async_session()은 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. hms가 NULL이거나 지정된 문자열 길이를 초과했다.

    [TPEOS]

    클라이언트에서 API를 사용할 때 발생할 수 있다. HMS 운영 시스템에 에러가 발생했거나 환경변수 설정이 잘못된 경우이다.

    예를 들어 TMAX_HOST_ADDR나TMAX_HOST_PORT가 잘못 설정되어 연결이 실패한 경우에 발생한다.

    [TPESYSTEM]

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

    [TPELIMIT]

    HMS에 연결된 세션의 수가 설정 파일의 MAXSESSION에 도달하여 더 이상 세션을 생성할 수 없는 상태이다.

    [TPENOREADY]

    HMS로 지정한 이름의 HMS가 NOT READY 상태인 경우 발생한다.

    [TPENOENT]

    HMS로 지정한 이름의 HMS가 존재하지 않는 경우이다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

HMS_SHND *session;
HMS_PHND *cons;
HMS_PHND *prod;

void abend_callback(HMS_SHND *sess)
{
    hms_close_session(sess, 0);
    printf("hms_close_session success\n");
    while (1) {
        session = hms_create_async_session(hms, abend_callback, 0);
        if (session == NULL) {
            printf("hms_create_session() : FAIL [%d]\n\n", tperrno);
            if (tperrno == TPENOREADY) {
                sleep(2);
                continue;
            }
            return;
        }
        break;
    }
    printf("hms_create_session success\n");
    cons = hms_create_receiver(session, dest, "consumer_1", NULL, "MYSVC", 0);
    if (cons == NULL) {
        printf("hms_create_receiver() : FAIL tperrno = %d\n\n", tperrno);
        return;
    }
}

main(int argc, char* argv[])
{
   hms_msg_t *msg;
    char *hms, *dest, *buf;
    int ret;
    long size = 1024;
    ...
    if (argc != 3)
        return;
    hms = argv[1];
    dest = argv[2];
    /* 비동기 세션을 생성함 */
    session = hms_create_async_session(hms, 0);
    if (session == NULL) { error processing }

    cons = hms_create_receiver(session, dest, "consumer_1", NULL, "MYSVC", 0);
    if (cons == NULL) { error processing }

    prod = hms_create_producer(session, dest, HMS_QUEUE, "producer_1", 0);
    if (prod == NULL) { error processing }
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }
    ...
    ret = hms_set_body(msg, buf, size);
    if (ret < 0) { error processing }
    ret = hms_send(prod, msg, 0);
    if (ret < 0) { error processing }
    ...
    hms_free(msg);
    hms_close_producer(prod, 0);
    /* 세션을 종료함 */
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_close_session()

2.4. hms_close_session

생성했던 세션을 종료하고 HMS에 할당되었던 리소스를 반환하는 함수이다. hms_create_session() 또는 hms_create_xa_session(), hms_create_async_session()으로 생성했던 세션을 닫고, HMS 내에 할당되었던 리소스를 반환한다. 세션이 더 이상 필요하지 않을 경우 세션을 종료해야 한다. 세션이 종료될 경우 해당 세션으로 생성되었던 모든 클라이언트(생산자와 소비자)들도 함께 종료된다.

  • 프로토타입

    #include <usrinc/hmsapi.h>
int hms_close_session (HMS_SHND *sess, int flags)

  • 파라미터

    파라미터 설명

    sess

    닫을 세션 포인터이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_close_session()은 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. sess 세션 포인터가 NULL이거나 잘못된 포인터이다.

    [TPESYSTEM]

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

    [TPENOREADY]

    HMS로 지정한 이름의 HMS가 NOT READY 상태인 경우 발생한다.

  • 관련함수

    hms_create_session(), hms_create_xa_session(), hms_create_async_session()

2.5. hms_unsubscribe_durable_subscriber

영속적 구독자(Durable Subscriber)에 대한 등록을 해제하는 함수이다. Destination에 연결된 클라이언트 중에 영속적 구독자가 존재한다면 TOPIC 타입의 메시지는 모든 영속적 구독자들이 메시지를 수신할 때까지 그 정보가 유지된다.

또한 영속적 구독자가 hms_unsubscribe_durable_subscriber() API를 호출하지 않고 세션을 종료할지라도 클라이언트 정보(durable subscriber의 이름)가 Destination에 남아 있기 때문에, 다시 같은 이름의 영속적 구독자가 세션을 새로 생성하면, 소비자가 종료된 이후에 publish된 Topic 메시지들을 유실하지 않고 모두 수신할 수 있게 된다. 더 이상 영속적 구독자가 TOPIC 타입의 메시지를 수신할 필요가 없다면 API를 호출해주는 것이 좋다. 그렇게 되면 이후에 들어온 메시지가 해당 영속적 구독자가 수신할 때까지 대기하지 않고 메모리에서 제거된다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int hms_unsubscribe_durable_subscriber (HMS_SHND *sess, char *des, char *name,
                                        int flags)

  • 파라미터

    파라미터 설명

    sess

    세션 포인터이다.

    des

    등록했던 Destination의 이름이다.

    name

    등록했던 영속적 구독자의 이름이다.

    flags

    아직 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_unsubscribe_durable_subscriber()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. sess이나 des가 NULL이거나 des, name이 지정된 문자열 길이를 초과한 경우에 발생한다.

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPESYSTEM]

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

    [TPETIME]

    타임아웃이 발생하였다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    #include <stdio.h>...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_CHND *cons;
    hms_msg_t *msg;
    ...
    session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    /* durable_subscriber를 생성함 */
    cons = hms_create_durable_subscriber(session, dest, "consumer_1", NULL,
                                         NULL, 0);
    if (cons == NULL) { error processing }
    ...
    ret = hms_recv(cons, &msg, 0);
    if (ret < 0) { error processing }
    ...

    hms_free(msg);
    ret = hms_close_durable_subscriber(cons, 0);
    if (ret < 0) { error processing }
    ...

    /* durable_subscriber에 대한 등록을 해제함 */
    ret = hms_unsubscribe_durable_subscriber(session, dest, "consumer_1", 0);
    if (ret < 0) { error processing }
    ...

    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_create_durable_subscriber(), hms_close_durable_subscriber()

2.6. hms_commit

세션을 통해 주고받았던 메시지에 대한 로컬 트랜잭션을 commit하는 함수이다. 세션을 생성할 때 hms_create_session() API에서 'transacted = 1’로 설정하여 생성한 로컬 트랜잭션 모드의 세션에서만 사용가능하다. 트랜잭션이 ROLLBACK_ONLY 상태라면 rollback된다. XA 세션에서는 tx_commit() API를 사용해야 한다. XA 세션과는 달리 트랜잭션의 시작을 명시적으로 선언하기 위한 tx_begin()과 같은 API는 호출할 필요가 없다.

  • 프로토타입

    #include <usrinc/hmsapi.h>
int hms_commit (HMS_SHND *sess, int flags)

  • 파라미터

    파라미터 설명

    sess

    해당하는 세션 포인터이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_commit()은 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. sess 세션 포인터가 NULL이거나 잘못된 포인터이다.

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPEPROTO]

    함수가 부적절한 곳에서 호출되었다. 예를 들어 hms_create_session()을 이용하여 세션을 생성할 때 transacted를 0으로 설정한 경우 발생한다.

    [TPESYSTEM]

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

    [TPETIME]

    타임아웃이 발생하였다.

    [TPENOENT]

    함수가 호출되기 전에 메시지를 전송했던 생산자나 소비자가 종료되었다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    #include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
   ...
    /* 로컬 트랜잭션 모드의 세션을 생성함 */
    session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    prod = hms_create_producer(session, dest, HMS_QUEUE, "producer_1", 0);
    if (prod == NULL) { error processing }
    ...
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }
    ret = hms_set_body(msg, buf, size);
    if (ret < 0) { error processing }
    ret = hms_send(prod, msg, 0);
    if (ret < 0) { error processing }
    ...

    /* 지금까지의 트랜잭션 작업을 처리함 */
    ret = hms_commit(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_create_session(), hms_rollback()

2.7. hms_rollback

세션을 통해 주고받았던 메시지에 대한 로컬 트랜잭션을 rollback하는 함수이다.

세션이 생성될 때 hms_create_session() API에서 'transacted = 1’로 설정하여 생성한 로컬 트랜잭션 모드의 세션에서만 사용가능하다. XA 세션에서는 tx_rollback() API를 사용해야 한다.

  • 프로토타입

    #include <usrinc/hmsapi.h>
int hms_rollback (HMS_SHND *sess, int flags)

  • 파라미터

    파라미터 설명

    sess

    해당하는 세션 포인터이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

2.8. hms_recover

세션을 통해 주고받았던 메시지 중 ACK를 받지 못한 메시지부터 전송을 다시 시작하도록 하는 함수이다.

세션이 생성될 때 hms_create_session() API에서 'transacted = 0’으로 설정해서 생성한 세션에서만 사용가능하다.

소비자가 메시지를 수신받는 도중 장애가 발생하거나, 수신받은 메시지에 대한 ACK을 HMS로 전달하지 않고 종료되었을 경우 다시 세션이 연결되었을 때 hms_recover() API를 호출함으로써 ACK를 받지 못한 메시지에 대해서 다시 수신할 수 있게 된다.

  • 프로토타입

    #include <usrinc/hmsapi.h>
int hms_recover (HMS_SHND *sess, int flags)

  • 파라미터

    파라미터 설명

    sess

    해당하는 세션 포인터이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_recover()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. sess 세션 포인터가 NULL이다.

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPEPROTO]

    함수가 부적절한 곳에서 호출되었다. 예를 들어 hms_create_session()을 이용하여 세션을 생성할 때 transacted를 0이 아닌 값으로 설정하여 생성한 세션일 경우 발생한다.

    [TPESYSTEM]

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

    [TPETIME]

    타임아웃이 발생하였다.

    [TPENOENT]

    함수가 호출되기 전에 메시지를 전송했던 생산자나 소비자가 종료되었다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
   ...
    /* 세션을 생성함 */
    session = hms_create_session(hms, 0, HMS_CLIENT_ACK, 0);

    if (session == NULL) { error processing }
    cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL,
                               NULL, 0);
    if (cons == NULL) { error processing }
    ...

    /* HMS로부터 메시지를 수신함 */
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }
    ret = hms_recv(cons, &msg, 0);
    if (ret < 0) { error processing }
    buf = tpalloc("STRING", NULL, 0);
    if (buf == NULL) { error processing }
    ret = hms_get_body(msg, buf, &size);
    if (ret < 0) { error processing }
    ...

    if ( condition ) {
        ret = hms_ack(msg, HMS_ACK_ONE);
        if (ret < 0) { error processing }
    } else {
        ret = hms_recover(session, 0);
        if (ret < 0) { error processing }
    }
    ...
}

  • 관련함수

    hms_create_session()

3. 메시지 API

메시지 API는 메시지 생성과 제거 및 메시지에 정보를 저장 및 조회하기 위한 API들로 구성된다.

3.1. hms_alloc

메시징 서비스에 사용할 메시지 버퍼를 할당하고, 버퍼의 포인터를 반환하는 함수이다.

사용되지 않는 메시지 버퍼를 해제하기 위해서는 반드시 hms_free() API를 사용해야 하며, free()를 사용해 메시지 버퍼를 해제해서는 안된다.

메시지 버퍼는 프로퍼티와 Body로 구성되어 있으며 hms_set_property(), hms_set_body() 등의 API를 사용하여 메시지 버퍼에 정보를 저장할 수 있다. 프로퍼티는 메시지에 대한 기본적인 정보와 클라이언트가 Message Selector를 통해 메시지를 선별하여 가져올 때 그 기준을 제공한다. 프로퍼티는 Name-Value 쌍의 정보로 구성되며 복수 개의 프로퍼티를 가질 수 있다. Body는 메시지의 주요 콘텐츠를 저장한다. 자세한 정보는 각 API 레퍼런스를 참고한다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
hms_msg_t * hms_alloc (HMS_SHND *sess, long size)

  • 파라미터

    파라미터 설명

    sess

    HMS와 연결된 세션 포인터이다.

    size

    할당할 메시지 버퍼의 크기이다.

  • 반환값

    반환값 설명

    할당된 메시지 버퍼의 포인터

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

    NULL

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

  • 오류

    다음 상황에서 hms_alloc()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    sess 포인터가 NULL이다.

    [TPESYSTEM]

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

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_CHND *cons;
    hms_msg_t *msg;
    long size;
    ...

    /* 일반 모드의 세션을 생성함 */
    session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }
    cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL,
                               NULL, 0);
    if (cons == NULL) { error processing }

    /* 메시지 버퍼를 할당함 */
    size = 1024;
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }

    ret = hms_recv(cons, &msg, 0);
    if (ret < 0) { error processing }
    buf = tpalloc("STRING", NULL, 0);
    if (buf == NULL) { error processing }
    ret = hms_get_body(msg, buf, &size);
    if (ret < 0) { error processing }
    ...
    ret = hms_ack(msg, HMS_ACK_ONE);
    if (ret < 0) { error processing }
    ...

    /* 메시지 버퍼를 해제함 */
    hms_free(msg);
    hms_close_consumer(cons, 0);
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_free()

3.2. hms_free

메시지 버퍼에 할당된 메모리를 해제하는 함수이다. hms_alloc()을 통해 할당받은 메시지 버퍼는 필요하지 않을 경우 반드시 API를 통해 해제해야 한다. 메시지 버퍼를 free()로 해제해서는 안되며, 이미 해제된 메시지 버퍼를 다시 해제할 경우 그 결과는 알 수 없다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
void  hms_free (hms_msg_t * msg)

  • 파라미터

    파라미터 설명

    msg

    해제할 메시지 버퍼 포인터이다.

  • 반환값

    반환값은 없다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_CHND *cons;
    hms_msg_t *msg;
    ...
    /* 일반 모드의 세션을 생성함 */
    session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL,
                               NULL, 0);
    if (cons == NULL) { error processing }

    /* 메시지 버퍼를 할당함 */
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }

    ret = hms_recv(cons, &msg, 0);
    if (ret < 0) { error processing }
    buf = tpalloc("STRING", NULL, 0);
    if (buf == NULL) { error processing }
    ret = hms_get_body(msg, buf, &size);
    if (ret < 0) { error processing }
    ...
    ret = hms_ack(msg, HMS_ACK_ONE);
    if (ret < 0) { error processing }
    ...
    /* 메시지 버퍼를 해제함 */
    hms_free(msg);
    hms_close_consumer(cons, 0);
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_alloc()

3.3. hms_get_property

메시지에 설정된 해당하는 이름의 프로퍼티의 정보를 가져오는 함수이다. 해당하는 이름의 프로퍼티가 있을 경우 타입(type), 값(value), 크기(len)를 가져온다. 존재하지 않을 경우에는 -1을 반환하고 tperrno는 TPENOENT로 설정된다. 데이터를 저장할 버퍼(value)는 미리 할당(또는 선언)되어 있어야 하며 버퍼의 크기가 함께 전달되어야 한다. 수신받은 데이터가 버퍼의 크기보다 클 경우 TPEINVAL 오류가 발생한다.

프로퍼티는 Name-Value 쌍으로 구성되며 하나의 메시지 버퍼에서 Name은 유일하다. 따라서 이미 존재하는 Name에 대해서 다시 hms_set_property()를 통해 Value를 저장하면 기존의 Value는 새로운 Value로 대체된다. 프로퍼티는 메시지를 hms_send()를 통해 Destination으로 전송하기 전과 hms_recv()를 통해 Destination에서 수신받은 후에도 설정할 수 있다. 이를 통해 수신된 메시지를 가공하여 다시 전달할 수 있다. 프로퍼티는 메시지를 수신받는 소비자가 Message Selector를 이용하여 메시지를 선택적으로 수신받고자 할 때 그 기준으로 사용된다. Message Selector는 소비자를 생성할 때 설정할 수 있으며 자세한 정보는 hms_create_consumer나 Message Selector 사용법을 참고한다.

내부적으로 사용되는 예약된 이름들에 대해서는 매크로가 제공되고 있으며, 다음과 같은 예약된 프로퍼티들은 hmsapi.h에 정의되어 있다. 예약된 이름의 프로퍼티를 사용자가 임의로 수정해서는 안된다. 예약 프로퍼티에 대한 설명은 메시지 API를 참고한다.

  • 프로토타입

    # include <usrinc/hmsapi.h>
int hms_get_property (hms_msg_t *msg, char *name, int *type, char *value,
                      long *len)

  • 파라미터

    파라미터 설명

    msg

    프로퍼티를 가져올 메시지 포인터이다.

    name

    가져올 프로퍼티의 이름이다.

    type

    프로퍼티의 타입을 나타낼 포인터이다.

    • HMS_CHAR

    • HMS_SHORT

    • HMS_INT

    • HMS_LONG

    • HMS_FLOAT

    • HMS_DOUBLE

    • HMS_STRING

    • HMS_CARRAY

    value

    프로퍼티를 받아올 포인터로 프로퍼티의 타입에 따라 적절한 변수 타입의 포인터를 전달한다.

    len

    프로퍼티를 담을 버퍼의 크기와 프로퍼티의 크기를 나타낼 포인터이다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_get_property()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. msg나 name, value가 NULL이거나 msg 포인터가 올바르지 않을 경우 또는 len이 가져올 프로퍼티의 길이보다 작을 경우에 발생한다.

    [TPESYSTEM]

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

    [TPENOENT]

    msg에 name에 해당하는 프로퍼티가 존재하지 않는다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_CHND *cons;
    hms_msg_t *msg;
    ...
    int type;
    long len = 256;
    char buf[256];     /* hms_get_property()에 사용 */
    int myval;         /* hms_get_property()에 사용 */

    /* 일반 모드의 세션을 생성함 */
    session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }
    cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL,
                               NULL, 0);
    if (cons == NULL) { error processing }

    /* 메시지 버퍼를 할당함 */
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }
    ret = hms_recv(cons, &msg, 0);
    if (ret < 0) { error processing }
    ret = hms_get_property(msg, HMSDestination, &type, buf, &len);
    if (ret < 0) { error processing }
    ret = hms_get_property(msg, HMSDestination, &type, &myval, sizeof(int));
    if (ret < 0) { error processing }
    ...

    ret = hms_ack(msg, HMS_ACK_ONE);
    if (ret < 0) { error processing }
    ...
    /* 메시지 버퍼를 해제함 */
    hms_free(msg);
    hms_close_consumer(cons, 0);
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_set_property(), hms_alloc(), hms_free()

3.4. hms_set_property

해당하는 이름으로 메시지에 프로퍼티를 설정하는 함수이다. 이미 해당하는 이름의 프로퍼티가 존재한다면 새로운 값으로 변경된다. 프로퍼티로 설정할 수 있는 타입은 필드 버퍼에서 지원하는 타입과 동일하다.

프로퍼티는 Name-Value 쌍으로 구성되며 하나의 메시지 버퍼에서 Name은 유일하다. 따라서 이미 존재하는 Name에 대해서 다시 hms_set_property()를 통해 Value를 저장하면 기존의 Value는 새로운 Value로 대체된다. 프로퍼티는 메시지를 hms_send()를 통해 Destination으로 전송하기 전과 hms_recv()를 통해 Destination에서 수신받은 후에도 설정할 수 있다. 이를 통해 수신된 메시지를 가공하여 다시 전달할 수 있다. 프로퍼티는 메시지를 수신받는 소비자가 Message Selector를 이용하여 메시지를 선택적으로 수신받고자 할 때 그 기준으로 사용된다. Message Selector에 대한 자세한 정보는 hms_create_consumer나 Message Selector 사용법을 참고한다.

내부적으로 쓰이는 예약된 이름들에 대해서는 매크로가 제공되고 있으며, 다음과 같은 예약된 프로퍼티들은 hmsapi.h에 정의되어 있다. 예약된 이름의 프로퍼티를 사용자가 임의로 수정해서는 안된다. 예약 프로퍼티에 대한 설명은 메시지 API를 참고한다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_set_property (hms_msg_t * msg, char *name, int type, char *value,
                       long len)

  • 파라미터

    파라미터 설명

    msg

    프로퍼티를 설정할 메시지 포인터이다.

    name

    설정할 프로퍼티의 이름으로 내부적으로 예약된 이름은 사용할 수 없다.

    type

    설정할 프로퍼티의 타입이다.

    • HMS_CHAR

    • HMS_SHORT

    • HMS_INT

    • HMS_LONG

    • HMS_FLOAT

    • HMS_DOUBLE

    • HMS_STRING

    • HMS_CARRAY

    value

    프로퍼티를 나타내는 포인터이다.

    len

    설정할 프로퍼티의 크기이다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_set_property()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다.

    msg나 name, value가 NULL이거나 msg 포인터가 올바르지 않을 경우에 발생한다. 또는 len이 음수일 경우, name이 예약된 프로퍼티일 경우, msg에 프로퍼티를 설정할만한 충분한 메모리 공간이 없는 경우 등에 발생한다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    char buf[256];
    ...
    if (argc != 2 ) return 1;
    strncpy(buf, argv[1], 255);

    /* 로컬 트랜잭션 모드의 세션을 생성함 */
    session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    prod = hms_create_producer(session, dest, HMS_QUEUE, "producer_1", 0);
    if (prod == NULL) { error processing }
    ...
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }
    ret = hms_set_property(msg, "NAME", HMS_STRING, buf, strlen(buf));
    if (ret < 0) { error processing }
    ret = hms_send(prod, msg, 0);
    if (ret < 0) { error processing }
    ...
    /* 지금까지의 트랜잭션 작업을 처리함 */
    ret = hms_commit(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_get_property(), hms_alloc(), hms_free()

3.5. hms_get_body

메시지의 데이터 부분을 가져오기 위한 함수이다. 내부적으로 "$DATA"라는 프로퍼티명을 사용한다.

데이터를 가져오는 버퍼는 tpalloc()으로 할당된 버퍼이어야 한다. 데이터를 저장할 버퍼는 미리 할당되어 있어야 하며 버퍼의 크기가 함께 전달되어야 한다. 수신받은 데이터가 버퍼의 크기보다 클 경우 TPEINVAL 오류가 발생한다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_get_body (hms_msg_t *msg, char *data, long *len)

  • 파라미터

    파라미터 설명

    msg

    메시지 포인터이다.

    data

    메시지의 데이터를 저장하기 위한 버퍼이다.

    len

    메시지의 데이터를 저장할 수 있는 데이터 버퍼의 최대 크기이다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_get_body()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. msg나 data, len 포인터가 NULL이거나 msg 포인터가 올바르지 않을 경우 또는 len이 메시지의 데이터 크기보다 작을 경우에 발생한다.

    [TPENOENT]

    메시지 데이터가 존재하지 않을 경우 발생한다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_CHND *cons;
    hms_msg_t *msg;
    char *buf;
    ...

    /* 일반 모드의 세션을 생성함 */
    session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }
    cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL,
                               NULL, 0);
    if (cons == NULL) { error processing }

    /* 메시지 버퍼를 할당함 */
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }
    ret = hms_recv(cons, &msg, 0);
    if (ret < 0) { error processing }

    /* 메시지 데이터를 가져온다. */
    buf = tpalloc("STRING", NULL, 0);
    if (buf == NULL) { error processing }
    ret = hms_get_body(msg, buf, &size);
    if (ret < 0) { error processing }
    ...

    ret = hms_ack(msg, HMS_ACK_ONE);
    if (ret < 0) { error processing }
    ...

    /* 메시지 버퍼를 해제함 */
    hms_free(msg);
    hms_close_consumer(cons, 0);
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_set_body()

3.6. hms_set_body

메시지의 데이터 부분을 설정하는 함수이다. 내부적으로 "$DATA"라는 프로퍼티명을 사용한다.

데이터의 버퍼는 tpalloc()으로 할당된 버퍼이어야 한다. Body는 프로퍼티와는 달리 Type을 가지고 있지 않으며 CARRAY 타입으로 len에 지정된 길이만큼 정보를 저장한다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_set_body (hms_msg_t *msg, char *data, long len)

  • 파라미터

    파라미터 설명

    msg

    메시지 포인터이다.

    data

    메시지의 데이터에 저장할 정보를 가지고 있는 버퍼이다.

    len

    메시지의 데이터의 길이이다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_set_body()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. msg나 data가 NULL이거나 msg 포인터가 올바르지 않을 경우, len이 음수일 경우, msg에 데이터를 설정할만한 충분한 메모리 공간이 없는 경우 등에 발생한다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_PHND *prod;
    hms_msg_t *msg;
    char *buf;
    ...
    if (argc !=2 )
        return 1;

    /* 로컬 트랜잭션 모드의 세션을 생성함 */
    session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }
    prod = hms_create_producer(session, dest, HMS_QUEUE, "producer_1", 0);
    if (prod == NULL) { error processing }
    ...
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }

    /* 메시지 데이터를 설정한다. */
    buf = tpalloc("STRING", NULL, 0);
    if (buf == NULL) { error processing }
    strcpy(buf, argv[1]);
    ret = hms_set_body(msg, buf, strlen(buf));
    if (ret < 0) { error processing }

    ret = hms_send(prod, msg, 0);
    if (ret < 0) { error processing }
    ...
    /* 지금까지의 트랜잭션 작업을 처리함 */
    ret = hms_commit(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_get_body()

3.7. hms_ack

수신받은 메시지에 대한 ACK을 전송한다. HMS로 메시지 수신 완료에 대한 ACK이 전송되면 HMS에서 해당 메시지에 대한 정보를 정리할 수 있다. ACK을 전송하지 않으면 해당 메시지는 계속해서 HMS에 남아있게 된다. 메시지 수신 후 ACK을 반드시 전송해야 하는 경우는 hms_create_session() API에서 ackmode가 HMS_DUPS_OK_ACK 또는 HMS_CLIENT_ACK으로 생성된 세션에서 메시지를 수신받은 경우이다.

ACK을 전송하지 않아도 자동으로 전송되는 경우가 있는데, 세션을 생성할 때 hms_create_session() API의 파라미터인 ackmode가 HMS_AUTO_ACK이면 hms_recv()를 통해 메시지를 수신받을 때 즉시 ACK가 전송되며, 트랜잭션을 지원하는 세션에서는 hms_commit() 또는 tx_commit() API를 호출할 때 자동으로 ACK가 전송되기 때문에 hms_ack()를 호출할 필요가 없다. ACK은 메시지를 수신했을 때 필요하므로 hms_send() API로 메시지를 전송할 때는 hms_ack()를 호출하지 않는다.

flags 설정이 HMS_ACK_ONE의 경우 해당 메시지에 대해서만 ACK이 전송되고, HMS_ACK_UPTHROUGH의 경우 그 이전에 수신된 메시지까지 모두 ACK 처리가 된다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_ack (hms_msg_t *msg, int flags)

  • 파라미터

    파라미터 설명

    msg

    ACK을 보낼 대상이 되는 메시지 포인터이다.

    flags

    다음 중에 하나를 설정한다.

    • HMS_ACK_ONE : 해당 메시지 하나만 ACK 처리한다.

    • HMS_ACK_UPTHROUGH : 그 이전 메시지까지 한 번에 ACK 처리한다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_ack()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. flags에 유효한 값이 설정되지 않거나 HMS_ACK_ONE와 HMS_ACK_UPTHROUGH를 같이 설정한 경우에 발생한다.

    [TPESYSTEM]

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

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPEPROTO]

    함수가 부적절한 상황에서 호출되었다.

    예를 들어 XA 세션이나 트랜젹션을 지원하는 세션에서 호출되었거나, ackmode가 HMS_DUPS_OK_ACK, HMS_CLIENT_ACK이 아닌 세션에서 호출되었다.

    [TPEITYPE]

    올바르지 않은 msg가 인수로 전달되었다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_CHND *cons;
    hms_msg_t *msg;
    ...

    /* 일반 모드의 세션을 생성함 */
    session = hms_create_session(hms, 0, HMS_CLIENT_ACK, 0);
    if (session == NULL) { error processing }
    cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL,
                               NULL, 0);
    if (cons == NULL) { error processing }
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }

    ret = hms_recv(cons, &msg, 0);
    if (ret < 0) { error processing }

    buf = tpalloc("STRING", NULL, 0);
    if (buf == NULL) { error processing }
    ret = hms_get_body(msg, buf, &size);
    if (ret < 0) { error processing }

    /* 수신받은 메시지에 대한 ACK을 전송함 */
    ret = hms_ack(msg, HMS_ACK_ONE)
    if (ret < 0) { error processing }
    ...

    hms_free(msg);
    hms_close_consumer(cons, 0);
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_recvex(), hms_recv()

4. 생산자(Producer) API

생산자 API는 Topic, Queue 타입의 생산자를 생성하고 종료하기 위한 API들로 구성된다.

4.1. hms_create_producer

Destination으로 메시지를 전송하기 위해 생산자를 생성하고, 그 생산자에 대한 핸들을 반환하는 함수이다. Destination은 관리자에 의해 생성된 가상 채널로 메시지를 생성하고 전송할 때 목적지이며, 또한 메시지를 수신받을 때 메시지를 제공해주는 소스를 지칭한다.

Destination은 Point-to-Point 방식의 메시지를 지원하는 Queue 방식과 Publish-and-Subscribe 방식으로 메시지 전달을 지원해주는 Topic 방식으로 구분된다. 한 애플리케이션 내에서 이 2가지 방식의 메시지를 모두 처리할 수 있다.

생산자를 생성하기 위해서는 먼저 세션이 생성되어 있어야 한다. 생산자가 생성되면 hms_send() API를 사용하여 Destination으로 메시지를 전송할 수 있다. 생산자는 Queue 타입 또는 Topic 타입의 Destination에 메시지를 전송함으로써 해당 Destination에 접근한 다른 소비자들이 해당 메시지를 수신할 수 있게 된다.

  • 프로토타입

    #include <usrinc/hmsapi.h>
HMS_PHND * hms_create_producer (HMS_SHND *sess, char *des, int destype,
                                char *name, int flags)

  • 파라미터

    파라미터 설명

    sess

    메시지 전달에 사용할 세션 포인터이다.

    des

    메시지를 전달할 Destination의 이름이다.

    destype

    Destination의 타입으로 반드시 메시지를 전달할 Destination의 타입과 일치해야 한다.

    • HMS_QUEUE

    • HMS_TOPIC

    name

    생성할 생산자의 이름이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    해당 생산자의 핸들

    함수 호출에 성공한 경우(성공적으로 생산자가 생성된 경우)이다.

    NULL

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

  • 오류

    다음 상황에서 hms_create_producer()은 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. sess 세션 포인터가 NULL이거나 des 이름이 지정되지 않은 경우, 또는 des나 name이 각각 지정된 길이를 초과한 경우, 또는 destype이 유효하지 않은 값으로 설정된 경우 발생한다.

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPESYSTEM]

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

    [TPENOENT]

    메시지를 전송할 Destination이 존재하지 않거나 활성화되지 않은 Destination일 경우에 발생한다.

    [TPEITYPE]

    Destination의 타입과 생성할 생산자의 Destination의 타입이 일치하지 않다.

    [TPEOS]

    HMS 또는 운영 시스템에 에러가 발생하였다. 예를 들어 내부적으로 사용하는 버퍼의 메모리 할당이 실패한 경우이다.

    [TPEMATCH]

    인수로 전달한 생산자 name이 이미 HMS에 등록되어 있다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    #include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_PHND *prod;
    hms_msg_t *msg;
    ...
    session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }
    /* QUEUE 타입의 생산자(Producer)를 생성함 */
    prod = hms_create_producer(session, dest, HMS_QUEUE, "producer_1", 0);
    if (prod == NULL) { error processing }
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }
    ...

    ret = hms_set_body(msg, buf, size);
    if (ret < 0) { error processing }
    ret = hms_send(prod, msg, 0);
    if (ret < 0) { error processing }
    ...

    hms_free(msg);
    hms_close_producer(prod, 0);
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_close_producer()

4.2. hms_create_sender

Queue 타입의 Destination에 메시지를 전송할 송신자(Sender)를 생성하기 위한 함수로 동작 방식은 hms_create_producer()와 동일하다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
HMS_PHND * hms_create_sender (HMS_SHND *sess, char *des, char *name, int flags)

  • 파라미터

    파라미터 설명

    sess

    메시지 전달에 사용할 세션 포인터이다.

    des

    메시지를 전달할 Destination의 이름이다.

    name

    생성할 생산자의 이름이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    생산자 핸들

    함수 호출에 성공한 경우(성공적으로 생산자가 생성된 경우)이다.

    NULL

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

  • 오류

    다음 상황에서 hms_create_sender()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. sess 세션 포인터가 NULL이거나 des 이름이 지정되지 않은 경우 또는 des나 name이 각각 지정된 길이를 초과한 경우에 발생한다.

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPESYSTEM]

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

    [TPENOENT]

    메시지를 전송할 Destination이 존재하지 않거나 활성화되지 않은 Destination일 경우에 발생한다.

    [TPEITYPE]

    Destination의 타입과 생성할 생산자의 Destination의 타입이 일치하지 않다.

    [TPEOS]

    HMS 또는 운영 시스템에 에러가 발생하였다. 예를 들어 내부적으로 사용하는 버퍼의 메모리 할당이 실패한 경우이다.

    [TPEMATCH]

    인수로 전달한 sender name이 이미 HMS에 등록되어 있다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    #include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_PHND *prod;
    hms_msg_t *msg;
    ...
    session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    /* QUEUE 타입의 생산자(Producer)를 생성함 */
    prod = hms_create_sender(session, dest, "producer_1", 0);
    if (prod == NULL) { error processing }
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }
    ...
    ret = hms_set_body(msg, buf, size);
    if (ret < 0) { error processing }
    ret = hms_send(prod, msg, 0);
    if (ret < 0) { error processing }
    ...
    hms_free(msg);
    hms_close_sender(prod, 0);

    /* 세션을 종료함 */
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_close_sender()

4.3. hms_create_publisher

Topic 타입의 Destination에 메시지를 전송할 발행자를 생성하는 함수이다. 동작 방식은 hms_create_producer()와 동일하다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
HMS_PHND * hms_create_publisher (HMS_SHND *sess, char *des, char *name, int flags)

  • 파라미터

    파라미터 설명

    sess

    메시지 전달에 사용할 세션 포인터이다.

    des

    메시지를 전달할 Destination의 이름이다.

    name

    생성할 생산자의 이름이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    생산자 핸들

    함수 호출에 성공한 경우(성공적으로 생산자가 생성될 경우)이다.

    NULL

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

  • 오류

    다음 상황에서 hms_create_publisher()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. sess 세션 포인터가 NULL이거나 des 이름이 지정되지 않은 경우 또는 des나 name이 각각 지정된 길이를 초과한 경우에 발생한다.

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPESYSTEM]

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

    [TPENOENT]

    메시지를 전송할 Destination이 존재하지 않거나 활성화되지 않은 Destination일 경우에 발생한다.

    [TPEITYPE]

    Destination의 타입과 생성할 생산자의 Destination의 타입이 일치하지 않다.

    [TPEOS]

    HMS 또는 운영 시스템에 에러가 발생하였다. 예를 들어 내부적으로 사용하는 버퍼의 메모리 할당이 실패한 경우이다.

    [TPEMATCH]

    인수로 전달한 publisher name이 이미 HMS에 등록되어 있다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    #include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_PHND *prod;
    hms_msg_t *msg;
    ...
    session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    /* TOPIC 타입의 생산자(Producer)를 생성함 */
    prod = hms_create_publisher(session, dest, "producer_1", 0);
    if (prod == NULL) { error processing }
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }
    ...
    ret = hms_set_body(msg, buf, size);
    if (ret < 0) { error processing }
    ret = hms_send(prod, msg, 0);
    if (ret < 0) { error processing }
    ...
    hms_free(msg);
    hms_close_publisher(prod, 0);

    /* 세션을 종료함 */
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_close_publisher()

4.4. hms_close_producer

생산자를 닫고, 할당되었던 리소스를 반환하는 함수이다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_close_producer (HMS_PHND *prod, int flags)

  • 파라미터

    파라미터 설명

    prod

    닫고자 하는 생산자의 핸들 포인터이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_close_producer()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. prod 포인터가 NULL이거나 잘못된 포인터이다.

    [TPESYSTEM]

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

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 관련함수

    hms_create_producer()

4.5. hms_close_sender

Queue 타입의 송신자를 닫고, 할당되었던 리소스를 반환하는 함수이다. 동작 방식은 hms_close_producer()와 동일하다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_close_sender (HMS_PHND *prod, int flags)

  • 파라미터

    파라미터 설명

    prod

    닫고자 하는 생산자의 핸들 포인터이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_close_sender()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. prod가 NULL이다.

    [TPESYSTEM]

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

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 관련함수

    hms_create_sender()

4.6. hms_close_publisher

Topic 타입의 발행자를 닫고, 할당되었던 리소스를 반환하는 함수이다. 동작은 hms_close_producer()와 동일하다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_close_publisher (HMS_PHND *prod, int flags)

  • 파라미터

    파라미터 설명

    prod

    닫고자 하는 생산자의 핸들 포인터이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_close_publisher()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. prod가 NULL이다.

    [TPESYSTEM]

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

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 관련함수

    hms_create_publisher()

4.7. hms_sendex

생산자를 생성할 때 지정한 Destination으로 메시지를 전송한다.

전송 방식에는 Persistent mode와 Non-persistent mode가 존재한다. Persistent mode의 경우 전송된 메시지는 데이터베이스에 저장된다. HMS에 장애가 발생할 경우 Destination에 전송되었던 메시지들을 온전하게 복구할 수 있다. 해당 메시지를 소비자가 수신해 간다면 데이터베이스에 저장되었던 Persistent mode의 메시지는 이후 일정 시간이 지나면 데이터베이스에서 삭제된다. 수신된 메시지가 데이터베이스에서 삭제되는 시간은 설정 파일에서 지정할 수 있다.

메시지가 Destination 내에서 스케줄링되는 우선순위나 유효시간을 지정해서 전송할 수도 있다. 유효시간이 지나도 소비자에 의해 메시지가 수신되지 않으면 해당 메시지는 폐기되며, 이후 메시지 수신 요청이 들어와도 해당 메시지를 수신할 수 없게 된다. 성공적으로 전송이 되면 해당 메시지에 메시지 ID와 전송/응답 시간의 차가 각각 HMSMessageID, HMSTimeStamp의 이름의 프로퍼티가 설정된다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_sendex (HMS_PHND *prod, hms_msg_t *msg, int dlvmode, int priority,
                 int ttl, int flags)

  • 파라미터

    파라미터 설명

    prod

    메시지를 전송할 생산자의 핸들 포인터이다.

    msg

    전송할 메시지의 포인터이다.

    dlvmode

    전송 방식을 설정한다.

    • HMS_DLV_NON_PERSISTENT

    • HMS_DLV_PERSISTENT

    priority

    메시지 우선순위로 현재는 지원되지 않는다.

    ttl

    time to live로 메시지의 유효시간이다. (기본값: 0, 단위: 초)

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_sendex()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. prod 또는 msg가 NULL이거나 ttl이 0보다 작은 경우, dlvmode가 유효하지 않은 값으로 설정된 경우, 성공적으로 전송된 이후 해당 msg의 사이즈가 작아서 추가적인 프로퍼티를 설정할 수 없을 경우에 발생한다.

    [TPESYSTEM]

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

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPEOS]

    HMS 또는 운영 시스템에 에러가 발생하였다. 예를 들어 내부적으로 사용하는 버퍼의 메모리 할당이 실패한 경우이다.

    [TPETIME]

    타임아웃이 발생하였다.

    [TPEPROTO]

    함수가 부적절한 곳에서 호출되었다.

    [TPENOENT]

    이미 종료된 생산자를 사용해 메시지를 전송하였다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    #include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_PHND *prod;
    hms_msg_t *msg;
    ...
    session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    /* TOPIC 타입의 생산자(Producer)를 생성함 */
    prod = hms_create_publisher(session, dest, "producer_1", 0);
    if (prod == NULL) { error processing }
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }
    ...
    ret = hms_set_body(msg, buf, size);
    if (ret < 0) { error processing }

    /* PERSISTENT 메시지를 destination으로 전송함 */
    ret = hms_sendex(prod, msg, HMS_DLV_PERSISTENT, 0, 60, 0);
    if (ret < 0) { error processing }
    ...
    hms_free(msg);
    hms_close_publisher(prod, 0);
    /* 세션을 종료함 */
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_send()

4.8. hms_send

기본적인 설정만으로 메시지를 전송한다. 전송모드는 Non-persistent이며, 우선순위와 유효시간은 설정하지 않고 전송한다. 그외 동작 방식은 hms_sendex()와 동일하다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_send (HMS_PHND *prod, hms_msg_t *msg, int flags)

  • 파라미터

    파라미터 설명

    prod

    메시지를 전송할 생산자의 핸들 포인터이다.

    msg

    전송할 메시지의 포인터이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

    메시지 전송이 성공할 경우이다.

    -1

    메시지 전송이 실패한 경우이다. tperrno에 에러 코드가 설정된다.

  • 오류

    다음 상황에서 hms_send()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. prod 또는 msg가 NULL이거나 ttl이 0보다 작은 경우, dlvmode가 유효하지 않은 값으로 설정된 경우, 성공적으로 전송된 이후 해당 msg의 사이즈가 작아서 추가적인 프로퍼티를 설정할 수 없는 경우에 발생한다.

    [TPESYSTEM]

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

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPEOS]

    HMS 또는 운영 시스템에 에러가 발생하였다. 예를 들어 내부적으로 사용하는 버퍼의 메모리 할당이 실패한 경우이다.

    [TPETIME]

    타임아웃이 발생하였다.

    [TPEPROTO]

    함수가 부적절한 곳에서 호출되었다.

    [TPENOENT]

    이미 종료된 생산자를 사용해 메시지를 전송하였다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    #include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_PHND *prod;
    hms_msg_t *msg;
    ...
    session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    /* TOPIC 타입의 생산자(Producer)를 생성함 */
    prod = hms_create_publisher(session, dest, "producer_1", 0);
    if (prod == NULL) { error processing }
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }
    ret = hms_set_body(msg, buf, size);
    if (ret < 0) { error processing }

    /* 메시지를 destination으로 전송함 */
    ret = hms_send(prod, msg, 0);
    if (ret < 0) { error processing }
    ...
    hms_free(msg);
    hms_close_publisher(prod, 0);

    /* 세션을 종료함 */
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_sendex()

5. 소비자(Consumer) API

소비자 API는 Topic, Queue 타입의 소비자를 생성하고 종료하기 위한 API들로 구성된다.

5.1. hms_create_consumer

Destination으로부터 메시지를 수신할 소비자를 생성하고, 그 소비자에 대한 핸들을 반환하는 함수이다. Message Selector를 설정하면 조건에 맞는 메시지를 필터링하여 수신할 수 있다.

비동기 세션에서는 생산자로부터 메시지가 전송될 때 즉시 해당 메시지를 수신받아 처리할 서비스를 지정할 수 있다. 비동기 세션에서 소비자를 생성할 때는 반드시 svcname을 지정해야 한다. 반대로 비동기 세션이 아닌 세션에서 소비자를 생성할 때는 svcname을 지정하면 안된다. 또한 클라이언트는 Message Selector를 설정함으로써 해당 조건을 충족하는 메시지만을 수신할 수 있다. Message Selector에 관한 보다 자세한 설명은 Message Selector 사용법을 참고한다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
HMS_CHND * hms_create_consumer (HMS_SHND *sess, char *des, int destype,
               char *name, char *msgselector, char *svcname, int flags)

  • 파라미터

    파라미터 설명

    sess

    메시지 수신에 사용할 세션 포인터이다.

    des

    메시지를 수신할 Destination의 이름이다.

    destype

    Destination의 타입이다.

    • MS_QUEUE

    • HMS_TOPIC

    name

    생성할 소비자의 이름이다.

    msgselector

    Message Selector 문장이다.

    svcname

    비동기 세션에서 메시지를 수신할 서비스명으로 비동기 세션에서 생성할 경우 반드시 설정해야 한다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    소비자의 핸들

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

    NULL

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

  • 오류

    다음 상황에서 hms_create_consumer()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. sess이나 des가 NULL일 경우, des나 name, msgselector, svcname이 지정된 길이를 초과할 경우, 비동기 세션에서 svcname이 지정되지 않은 경우, destype에 유효하지 않은 값이 설정된 경우에 발생한다.

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPEPROTO]

    함수가 부적절한 곳에서 호출되었다. 예를 들어 비동기 세션에서 이미 svcname을 사용하는 다른 소비자가 생성되어 있는 경우, 비동기 세션이 아님에도 불구하고 svcname이 설정되어 있는 경우, durable subscriber를 생성하면서 소비자 이름을 지정하지 않을 경우에 발생한다.

    [TPESYSTEM]

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

    [TPENOENT]

    메시지를 수신할 Destination이 존재하지 않거나 활성화 되지 않은 Destination일 경우에 발생한다.

    [TPEITYPE]

    Destination의 타입과 생성할 소비자의 Destination의 타입이 일치하지 않다.

    [TPEOS]

    HMS 또는 운영 시스템에 에러가 발생하였다. 예를 들어 내부적으로 사용하는 버퍼의 메모리 할당이 실패한 경우이다.

    [TPEMATCH]

    인수로 전달한 소비자 name이 이미 HMS에 등록되어 있다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_CHND *cons;
    hms_msg_t *msg;
    ...
    session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    /* QUEUE 타입의 소비자(Consumer)를 생성함 */
    cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL,
                               NULL, 0);
    if (cons == NULL) { error processing }
    ...
    ret = hms_recv(cons, &msg, 0);
    if (ret < 0) { error processing }
    ...
    hms_free(msg);

    /* 소비자(Consumer)를 종료함 */
    hms_close_consumer(cons, 0);
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_close_consumer()

5.2. hms_create_receiver

Queue 타입인 Destination으로부터의 수신자를 생성하는 함수로 동작 방식은 hms_create_consumer()와 동일하다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
HMS_CHND * hms_create_receiver (HMS_SHND *sess, char *des, char *name,
                                char *msgselector, char *svcname, int flags)

  • 파라미터

    파라미터 설명

    sess

    메시지 전달에 사용할 세션 포인터이다.

    des

    메시지를 전달할 Destination의 이름이다.

    name

    생성할 생산자의 이름이다.

    msgselector

    Message Selector 문장이다.

    svcname

    비동기 세션에서 메시지를 수신할 서비스명으로 비동기 세션에서 생성하는 경우 반드시 설정해야 한다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    소비자의 핸들러

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

    NULL

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

  • 오류

    다음 상황에서 hms_create_receiver()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. sess이나 des가 NULL일 경우, des나 name, msgselector, svcname이 지정된 길이를 초과할 경우, 비동기 세션에서 svcname이 지정되지 않은 경우에 발생한다.

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPEPROTO]

    비동기 세션에서 이미 svcname을 사용하는 다른 소비자가 생성되어 있다.

    [TPESYSTEM]

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

    [TPENOENT]

    메시지를 수신할 Destination이 존재하지 않거나 활성화되지 않은 Destination일 경우에 발생한다.

    [TPEITYPE]

    Destination의 타입과 생성할 수신자의 Destination의 타입이 일치하지 않다.

    [TPEOS]

    HMS 또는 운영 시스템에 에러가 발생하였다. 예를 들어 내부적으로 사용하는 버퍼의 메모리 할당이 실패한 경우이다.

    [TPEMATCH]

    인수로 전달한 receiver name이 이미 HMS에 등록되어 있다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_CHND *cons;
    hms_msg_t *msg;
    ...
    session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    /* QUEUE 타입의 receiver를 생성함 */
    cons = hms_create_receiver(session, dest, "consumer_1", NULL, NULL, 0);
    if (cons == NULL) { error processing }
    ...

    ret = hms_recv(cons, &msg, 0);
    if (ret < 0) { error processing }
    ...
    hms_free(msg);

    /* receiver를 종료함 */
    hms_close_receiver(cons, 0);
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_close_receiver()

5.3. hms_create_subscriber

Topic 타입인 Destination으로부터의 구독자를 생성하는 함수로, 동작 방식은 hms_create_consumer()와 동일하다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
HMS_CHND * hms_create_subscriber (HMS_SHND *sess, char *des, char *name,
                                  char *msgselector, char *svcname, int flags)

  • 파라미터

    파라미터 설명

    sess

    메시지 전달에 사용할 세션 포인터이다.

    des

    메시지를 전달할 Destination의 이름이다.

    name

    생성할 생산자의 이름이다.

    msgselector

    Message Selector 문장이다.

    svcname

    비동기 세션에서 메시지를 수신할 서비스명으로 비동기 세션에서 생성하는 경우 반드시 설정해야 한다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    소비자의 핸들러

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

    NULL

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

  • 오류

    다음 상황에서 hms_create_subscriber()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. sess이나 des가 NULL일 경우, des나 name, msgselector, svcname이 지정된 길이를 초과할 경우, 비동기 세션에서 svcname이 지정되지 않은 경우 발생한다.

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPEPROTO]

    비동기 세션에서 이미 svcname을 사용하는 다른 소비자가 생성되어 있다.

    [TPESYSTEM]

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

    [TPENOENT]

    메시지를 수신할 Destination이 존재하지 않거나 활성화 되지 않은 Destination일 경우에 발생한다.

    [TPEITYPE]

    Destination의 타입과 생성할 소비자의 Destination의 타입이 일치하지 않다.

    [TPEOS]

    HMS 또는 운영 시스템에 에러가 발생하였다. 예를 들어 내부적으로 사용하는 버퍼의 메모리 할당이 실패한 경우이다.

    [TPEMATCH]

    인수로 전달한 subscriber name이 이미 HMS에 등록되어 있다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_CHND *cons;
    hms_msg_t *msg;
    ...
    session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    /* TOPIC 타입의 subscriber를 생성함 */
    cons = hms_create_subscriber(session, dest, "consumer_1", NULL, NULL, 0);
    if (cons == NULL) { error processing }
    ...
    ret = hms_recv(cons, &msg, 0);
    if (ret < 0) { error processing }
    ...
    hms_free(msg);

    /* subscriber를 종료함 */
    hms_close_subscriber(cons, 0);
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_close_subscriber()

5.4. hms_create_durable_subscriber

Topic 타입인 Destination으로부터 수신할 영속적 구독자를 생성하는 함수이다.

영속적 구독자는 메시지 수신에 대한 신뢰성을 보장하여 영속적 구독자가 메시지를 정상적으로 수신할 때까지 HMS는 해당 메시지를 유지한다. HMS는 영속적 구독자을 이름으로 구별하므로 각 영속적 구독자는 반드시 유일한 이름을 사용해야 한다.

hms_close_durable_subscriber와는 별도로 등록을 해제하는 unsubscribe 과정이 반드시 필요하다. unsubscribe를 하지 않으면 영속적 구독자가 close된 이후에도 메시지는 다음에 해당 subscriber에 의해 수신될 때까지 정보를 유지하기 때문에 더 이상 subscribe를 할 필요가 없다면 unsubscribe를 해야 한다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
HMS_CHND * hms_create_durable_subscriber (HMS_SHND *sess, char *des, char *name,
                                    char *msgselector, char *svcname, int flags)

  • 파라미터

    파라미터 설명

    sess

    메시지 전달에 사용할 세션 포인터이다.

    des

    메시지를 전달할 Destination의 이름이다.

    name

    생성할 생산자의 이름이다.

    msgselector

    Message Selector 문장이다.

    svcname

    비동기 세션에서 메시지를 수신할 서비스명으로 비동기 세션에서 생성하는 경우 반드시 설정해야 한다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    소비자의 핸들

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

    NULL

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

  • 오류

    다음 상황에서 hms_create_durable_subscriber()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. sess이나 des가 NULL일 경우, des나 name, msgselector, svcname이 지정된 길이를 초과할 경우, 비동기 세션에서 svcname이 지정되지 않은 경우 발생한다.

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPEPROTO]

    비동기 세션에서 이미 svcname을 사용하는 다른 소비자가 생성되어 있다.

    [TPESYSTEM]

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

    [TPENOENT]

    메시지를 수신할 Destination이 존재하지 않거나 활성화되지 않은 Destination일 경우에 발생한다.

    [TPEITYPE]

    Destination의 타입과 생성할 subscriber의 Destination의 타입이 일치하지 않다.

    [TPEOS]

    HMS 또는 운영 시스템에 에러가 발생하였다. 예를 들어 내부적으로 사용하는 버퍼의 메모리 할당이 실패한 경우이다.

    [TPEMATCH]

    인수로 전달한 durable subscriber name이 이미 HMS에 등록되어 있다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_CHND *cons;
    hms_msg_t *msg;
    ...
    session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    /* durable_subscriber를 생성함 */
    cons = hms_create_durable_subscriber(session, dest, "consumer_1", NULL,
                                         NULL, 0);
    if (cons == NULL) { error processing }
    ...
    ret = hms_recv(cons, &msg, 0);
    if (ret < 0) { error processing }
    ...
    hms_free(msg);

    /* durable_subscriber를 종료함 */
    ret = hms_unsubscribe_durable_subscriber(session, dest, "consumer_1", 0);
    if (ret < 0) { error processing }
    ret = hms_close_consumer(cons, 0);
    if (ret < 0) { error processing }

    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_close_durable_subscriber()

5.5. hms_close_consumer

소비자를 닫고, 할당되었던 리소스를 반환하는 함수이다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_close_consumer (HMS_CHND *cons, int flags)

  • 파라미터

    파라미터 설명

    cons

    닫고자 하는 소비자 핸들 포인터이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_close_consumer()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. cons가 NULL이다.

    [TPESYSTEM]

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

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 관련함수

    hms_create_consumer()

5.6. hms_close_receiver

Queue 타입인 수신자를 닫고, 할당되었던 리소스를 반환하는 함수로 동작방식은 hms_close_consumer()와 동일하다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_close_receiver (HMS_CHND *cons, int flags)

  • 파라미터

    파라미터 설명

    cons

    닫고자 하는 소비자 핸들 포인터이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_close_receiver()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. cons가 NULL이다.

    [TPESYSTEM]

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

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 관련함수

    hms_create_receiver()

5.7. hms_close_subscriber

Topic 타입인 구독자를 닫고 할당되었던 리소스를 반환하는 함수로, 동작 방식은 hms_close_consumer()와 동일하다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_close_subscriber (HMS_CHND *cons, int flags)

  • 파라미터

    파라미터 설명

    cons

    닫고자 하는 소비자 핸들 포인터이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_close_subscriber()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. cons가 NULL이다.

    [TPESYSTEM]

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

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 관련함수

    hms_create_subscriber()

5.8. hms_close_durable_subscriber

영속적 구독자를 닫고, 할당되었던 리소스를 반환하는 함수로 동작 방식은 hms_close_consumer()와 동일하다. 사용 후에 hms_unsubscribe_durable_subscriber()를 통해 unsubscribe 과정이 필요하다. 만일 unsubscribe를 하지 않는다면 해당 영속적 구독자가 수신하지 않은 모든 메시지들은 해당 subscriber가 수신할 때까지 또는 unsubscribe를 수행할 때까지 메모리에서 제거되지 않고 수신을 기다린다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_close_durable_subscriber (HMS_CHND *cons, int flags)

  • 파라미터

    파라미터 설명

    cons

    닫을 소비자 핸들 포인터이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_close_durable_subscriber()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. cons가 NULL이다.

    [TPESYSTEM]

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

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    #include <stdio.h>...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>


main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_CHND *cons;
    hms_msg_t *msg;
    ...
    session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    /* durable_subscriber를 생성함 */
    cons = hms_create_durable_subscriber(session, dest, "consumer_1", NULL,
                                         NULL, 0);
    if (cons == NULL) { error processing }
    ...
    ret = hms_recv(cons, &msg, 0);
    if (ret < 0) { error processing }
    ...
    hms_free(msg);
    /* durable_subscriber를 종료함 */
    ret = hms_close_consumer(cons, 0);
    if (ret < 0) { error processing }
    ...
    ret = hms_unsubscribe_durable_subscriber(session, dest, "consumer_1", 0);
    if (ret < 0) { error processing }
    ...
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_create_durable_subscriber()

5.9. hms_recvex

Destination으로부터 메시지를 수신하는 함수이다. 타임아웃을 설정할 수 있으며 0으로 설정하면 메시지가 도착할 때까지 기다린다. 소비자를 생성할 때 Message Selector를 설정했다면, 그 기준에 부합되는 메시지들만 선택적으로 수신할 수 있다. 메시지를 수신받기 위해서는 hms_alloc() API를 통해 메시지 버퍼를 미리 생성해야 한다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_recvex (HMS_CHND * cons, hms_msg_t **msg, long timeout, int flags)

  • 파라미터

    파라미터 설명

    cons

    메시지를 수신할 소비자 핸들 포인터이다.

    msg

    hms_alloc()으로 할당된 메시지 버퍼이다.

    timeout

    타임아웃이다. (기본값: 0, 단위: 초)

    flags

    아직 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_recvex()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. cons나 msg가 NULL이거나 timeout 값이 음수이다.

    [TPESYSTEM]

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

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPEOTYPE]

    올바르지 않은 msg가 인수로 전달되었다.

    [TPEITYPE]

    올바르지 않은 msg를 수신받았다.

    [TPETIME]

    타임아웃이 발생하였다.

    [TPENOENT]

    이미 종료된 소비자를 사용해 메시지를 전송하였다. 세션이 종료되면서 세션으로 생성되었던 생산자와 소비자가 종료되었을 수 있다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_CHND *cons;
    hms_msg_t *msg;
    ...
    /* 일반 모드의 세션을 생성함 */
    session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }
    cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL,
                               NULL, 0);
    if (cons == NULL) { error processing }
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }

    /* 메시지 수신 (timeout 20초 설정) */
    ret = hms_recvex(cons, &msg, 20, 0);
    if (ret < 0) { error processing }
    ret = hms_ack(msg, HMS_ACK_ONE);
    if (ret < 0) { error processing }
    ...
    /* 메시지 버퍼를 해제함 */
    hms_free(msg);

    hms_close_consumer(cons, 0);
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_recv(), hms_create_consumer(), hms_create_receiver(),hms_create_subscriber(),

    hms_create_durable_subscriber(), hms_ack(), hms_commit(), hms_rollback()

5.10. hms_recv

Destination으로부터 메시지가 도착할 때까지 기다리는 함수로 동작방식은 hms_recvex()와 동일하다. (timeout = 0)

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_recvex (HMS_CHND * cons, hms_msg_t **msg, int flags)

  • 파라미터

    파라미터 설명

    cons

    메시지를 수신할 소비자 핸들 포인터이다.

    msg

    hms_alloc()으로 할당된 메시지 버퍼이다.

    flags

    아직 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_recv()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. cons나 msg가 NULL이다.

    [TPESYSTEM]

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

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPEOTYPE]

    올바르지 않은 msg가 인수로 전달되었다.

    [TPEITYPE]

    올바르지 않은 msg를 수신받았다.

    [TPETIME]

    타임아웃이 발생하였다.

    [TPENOENT]

    이미 종료된 소비자를 사용해 메시지를 전송하였다. 세션이 종료되면서 세션으로 생성되었던 생산자와 소비자가 종료되었을 수 있다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_CHND *cons;
    hms_msg_t *msg;
    ...
    /* 일반 모드의 세션을 생성함 */
    session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }
    cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL,
                               NULL, 0);
    if (cons == NULL) { error processing }
    msg = hms_alloc(session, size);
    if (msg == NULL) { error processing }

    /* 메시지 수신 */
    ret = hms_recv(cons, &msg, 0);
    if (ret < 0) { error processing }
    ret = hms_ack(msg, HMS_ACK_ONE);
    if (ret < 0) { error processing }
    ...
    /* 메시지 버퍼를 해제함 */
    hms_free(msg);
    hms_close_consumer(cons, 0);
    ret = hms_close_session(session, 0);
    if (ret < 0) { error processing }
    ...
}

  • 관련함수

    hms_recv(), hms_create_consumer(), hms_create_receiver(), hms_create_subscriber(), hms_create_durable_subscriber(), hms_ack(), hms_commit(), hms_rollback()

6. Queue Browser API

Queue Browser API는 Queue Browser의 생성과 종료, 메시지 조회 등을 위한 API들로 구성된다.

6.1. hms_create_browser

현재 Destination에 존재하는 메시지를 조회할 수 있는 Queue Browser를 생성하고, 해당 Browser의 핸들을 반환하는 함수이다. Queue 타입의 Destination에 대해서만 생성이 가능하다. 브라우저를 생성할 때 Message Selector를 설정하여 조건에 맞는 메시지만을 조회할 수 있다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
HMS_BHND * hms_create_browser (HMS_SHND *sess, char *queue, char *msgselector,
                               int flags)

  • 파라미터

    파라미터 설명

    sess

    브라우저를 사용하는 세션 포인터이다.

    queue

    조회할 Queue의 이름이다.

    msgselector

    Message Selector 문장이다.

    flags

    다음 중에 하나를 설정한다.

    • HMS_QB_FIRST : Destination에 있는 수신 가능한 메시지를 전송된 순서대로 조회한다.

    • 0 : Destination에 있는 메시지 중 가장 최근에 전송된 메시지부터 조회한다. (기본값)

  • 반환값

    반환값 설명

    브라우저에 대한 핸들 포인터

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

    NULL

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

  • 오류

    다음 상황에서 hms_create_browser()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. sess이나 queue가 NULL일 경우, queue나 msgselector가 지정된 길이를 초과할 경우에 발생한다.

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPESYSTEM]

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

    [TPENOENT]

    메시지를 수신할 Destination이 존재하지 않거나 활성화 되지 않은 Destination일 경우에 발생한다.

    [TPEITYPE]

    queue로 전달한 Destination의 타입이 Queue 타입이 아니다.

    [TPEOS]

    HMS 또는 운영 시스템에 에러가 발생하였다. 예를 들어 내부적으로 사용하는 버퍼의 메모리 할당이 실패한 경우이다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_BHND *browser;
    hms_msg_t *msg;
    char buf[100];
    long len = 100;
    ...
    session = hms_create_session("svghms", 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    /* Queue Browser 생성하기 */
    browser = hms_create_browser(session, "queue1",
                                 "HMSType = 'cat' AND weight < 3"), 0);
    if (brow == NULL) { error processing }
    ...
    msg = hms_alloc(session, 1024);
    if (msg == NULL) { error processing }
    buf = tpalloc("STRING", NULL, 0);
    if (buf == NULL) { error processing }

    /* Queue browser를 통해 메시지 데이터를 가져온다. */
    hms_browser_nextmsg(browser, &msg, 0);
    if (ret == -1) { error processing }
    ret = hms_get_body(msg, buf, strlen(buf));
    if (ret == -1)
       { error processing }
    else
        printf("message : %s\n", buf);
    ...

    /* Queue Browser 종료하기 */
    ret = hms_close_browser(browser, 0);
    if (ret == -1) { error processing }
    ret = hms_close_session(session, 0);
    if (ret == -1) { error processing }
    ...
}

  • 관련함수

    hms_close_browser()

6.2. hms_close_browser

Queue Browser를 닫고, 할당되었던 리소스를 반환하는 함수이다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int hms_close_browser (HMS_BHND *browser, int flags)

  • 파라미터

    파라미터 설명

    browser

    브라우저 핸들 포인터이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_close_browser()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. 브라우저가 NULL이다.

    [TPESYSTEM]

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

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_BHND *browser;
    hms_msg_t *msg;
    char buf[100];
    long len = 100;
    ...

    session = hms_create_session("svghms", 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }
    browser = hms_create_browser(session, "queue1",
                                 "HMSType = 'cat' AND weight < 3"), 0);
    if (brow == NULL) { error processing }
    ...
    hms_browser_nextmsg(browser, &msg, 0);
    if (ret == -1) { error processing }
    ...

    /* Queue browser 종료하기 */
    ret = hms_close_browser(browser, 0);
    if (ret == -1) { error processing }
    ret = hms_close_session(session, 0);
    if (ret == -1) { error processing }
    ...
}

  • 관련함수

    hms_create_browser()

6.3. hms_browser_nextmsg

가장 최근에 들어온 메시지부터 순서대로 메시지를 조회하기 위한 함수이다. 내부적인 동작은 hms_recv()와 비슷하나 조회만 가능하고 메시지는 Queue에서 소비되지 않는다는 점이 다르다.

hms_create_browser()로 생성할 때 설정한 flags 값에 따라서 HMS_QB_FIRST이면 Destination으로 전송된 순서대로 조회하며, 기본값이면 가장 최근에 들어온 메시지(Queue의 끝)부터 순서대로 메시지를 조회한다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_browser_nextmsg (HMS_BHND *browser, hms_msg_t **msg, int flags)

  • 파라미터

    파라미터 설명

    browser

    브라우저 핸들 포인터이다.

    msg

    메시지 버퍼 포인터이다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_browser_nextmsg()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. browser나 msg가 NULL이다.

    [TPESYSTEM]

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

    [TPECLOSE]

    HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

    [TPEOS]

    HMS 또는 운영 시스템에 에러가 발생하였다. 예를 들어 내부적으로 사용하는 버퍼의 메모리 할당이 실패한 경우이다.

    [TPEMATCH]

    해당 Destination에 조회 가능한 메시지가 존재하지 않는다.

    [TPENOREADY]

    HMS가 NOT READY 상태인 경우 발생한다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_BHND *browser;
    hms_msg_t *msg;
    char buf[100];
    long len = 100;
    ...
    session = hms_create_session("svghms", 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }
    browser = hms_create_browser(session, "queue1",
                                 "HMSType = 'cat' AND weight < 3"), 0);
    if (brow == NULL) { error processing }
    ...
    msg = hms_alloc(session, 1024);
    if (msg == NULL) { error processing }
    buf = tpalloc("STRING", NULL, 0);
    if (buf == NULL) { error processing }

    /* Queue browser를 통해 메시지 데이터를 가져온다. */
    hms_browser_nextmsg(browser, &msg, 0);
    if (ret == -1) { error processing }

    ret = hms_get_body(msg, buf, strlen(buf));
    if (ret == -1)
       { error processing }
    else
        printf("message : %s\n", buf);
    ...
    ret = hms_close_browser(browser, 0);
    if (ret == -1) { error processing }
    ret = hms_close_session(session, 0);
    if (ret == -1) { error processing }
    ...
}

  • 관련함수

    hms_create_browser(), hms_browser_get_queue(), hms_browser_get_msgselector()

6.4. hms_browser_get_msgselector

브라우저를 생성할 때 설정했던 Message Selector 문장을 가져오기 위한 함수이다.

브라우저를 생성할 때 설정했던 Message Selector 문장을 버퍼에 복사하고 그 길이를 len에 설정한다. 버퍼는 Message Selector 문장의 길이를 충분히 수용할 만큼 커야 하며, API를 호출하기 전에 버퍼의 크기를 len에 설정해야 한다. 복사할 버퍼의 크기가 Message Selector 문장의 길이보다 작거나, Message Selector가 설정되지 않았다면 -1을 반환한다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_browser_get_msgselector(HMS_BHND *browser, char *buf, long *len,
                                 int flags)

  • 파라미터

    파라미터 설명

    browser

    브라우저 핸들 포인터이다.

    buf

    Message Selector 문장을 복사할 버퍼이다.

    len

    버퍼의 크기를 입력받고 Message Selector 문장의 길이를 반환한다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

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

  • 오류

    다음 상황에서 hms_browser_get_msgselector()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다. browser나 buf가 NULL이거나 len(버퍼의 크기)이 Message Selector 문장의 길이보다 작을 경우 발생한다.

    [TPENOENT]

    Message Selector가 설정되지 않았다.

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_BHND *browser;
    hms_msg_t *msg;
    char buf[100];
    long len = 100;
    ...

    session = hms_create_session("svghms", 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }

    browser = hms_create_browser(session, "queue1",
                                 "HMSType = 'cat' AND weight < 3"), 0);
    if (brow == NULL) { error processing }
    ...

    /* Message Selector 문장 가져오기 */
    ret = hms_browser_get_msgselector(browser, buf, &len);
    if (ret == -1)
       { error processing }
    else
        printf("Message Selector : %s\n", buf);
    ...

    ret = hms_close_browser(browser, 0);
    if (ret == -1) { error processing }
    ret = hms_close_session(session, 0);
    if (ret == -1) { error processing }
    ...
}

  • 관련함수

    hms_create_browser(), hms_browser_nextmsg(), hms_browser_get_queue()

6.5. hms_browser_get_queue

브라우저를 생성할 때 설정했던 Destination의 이름을 버퍼에 복사하고 그 길이를 len에 설정하는 함수이다. 버퍼는 Destination의 이름을 충분히 수용할 만큼 커야 하고, API를 호출하기 전에 버퍼의 크기를 len에 설정해야 한다.

  • 프로토타입

    # include  <usrinc/hmsapi.h>
int  hms_browser_get_queue (HMS_BHND * browser, char *buf, long *len, int flags)

  • 파라미터

    파라미터 설명

    browser

    브라우저 핸들 포인터이다.

    buf

    Destination의 이름을 복사할 버퍼이다.

    len

    버퍼의 크기를 입력받고 Destination의 이름의 길이를 반환한다.

    flags

    현재 사용되지 않는다.

  • 반환값

    반환값 설명

    1

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

    -1

    복사할 버퍼의 크기가 Destination의 이름보다 작은 경우로 함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

  • 오류

    다음 상황에서 hms_browser_get_queue()는 실패하고 tperrno에 아래 값 중 하나가 설정된다.

    에러 코드 설명

    [TPEINVAL]

    인수가 유효하지 않다.

    browser나 buf가 NULL이거나 len(버퍼의 크기)이 Destination의 이름 길이보다 작을 경우 발생한다.

    [TPESYSTEM]

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

  • 예제

    ...
#include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/hmsapi.h>

main(int argc, char* argv[])
{
    HMS_SHND *session;
    HMS_BHND *browser;
    hms_msg_t *msg;
    char buf[100];
    long len = 100;
    ...
    session = hms_create_session("svghms", 0, HMS_AUTO_ACK, 0);
    if (session == NULL) { error processing }
    browser = hms_create_browser(session, "queue1",
                                 "HMSType = 'cat' AND weight < 3"), 0);
    if (brow == NULL) { error processing }
    ...
    /* Destination 이름 가져오기 */
    ret = hms_browser_get_queue(browser, buf, &len, 0);
    if (ret == -1) { error processing }
    else
        printf("Destination : %s\n", buf);
    ...
    ret = hms_close_browser(browser, 0);
    if (ret == -1) { error processing }
    ret = hms_close_session(session, 0);
    if (ret == -1) { error processing }
    ...
}

  • 관련함수

    hms_create_browser(), hms_browser_nextmsg(), hms_browser_get_msgselector()