tmax hms user guide...copyright notice copyright © 2009 tmaxsoft co., ltd. all rights reserved....

Tmax

HMS User Guide

Tmax v5.0 SP1

Copyright © 2009 TmaxSoft Co., Ltd. All Rights Reserved.

Copyright Notice

Copyright © 2009 TmaxSoft Co., Ltd. All Rights Reserved.

대한민국 경기도 성남시 분당구 서현동 263 분당스퀘어(AK프라자) 12층

Restricted Rights Legend

All TmaxSoft Software (Tmax®) and documents are protected by copyright laws and the Protection Act of Com

puter Programs, and international convention. TmaxSoft software and documents are made available under the

terms of the TmaxSoft License Agreement and may only be used or copied in accordance with the terms of this

agreement. No part of this document may be transmitted, copied, deployed, or reproduced in any form or by any

means, electronic, mechanical, or optical, without the prior written consent of TmaxSoft Co., Ltd.

이 소프트웨어(Tmax®) 사용설명서의 내용과 프로그램은 저작권법, 컴퓨터프로그램보호법 및 국제 조약에 의해

서 보호받고 있습니다. 사용설명서의 내용과 여기에 설명된 프로그램은 TmaxSoft Co., Ltd.와의 사용권 계약 하에

서만 사용이 가능하며, 사용권 계약을 준수하는 경우에만 사용 또는 복제할 수 있습니다. 이 사용설명서의 전부 또

는 일부분을 TmaxSoft의 사전 서면 동의 없이 전자, 기계, 녹음 등의 수단을 사용하여 전송, 복제, 배포, 2차적 저

작물작성 등의 행위를 하여서는 안 됩니다.

Trademarks

Tmax®, Tmax WebtoB® and JEUS® are registered trademark of TmaxSoft Co., Ltd. Other products, titles or

services may be registered trademarks of their respective companies.

Tmax®, Tmax WebtoB® 와 JEUS®는 TmaxSoft Co., Ltd.의 등록 상표입니다. 기타 모든 제품들과 회사 이름은 각

각 해당 소유주의 상표로서 참조용으로만 사용됩니다.

Open Source Software Notice

This product includes various open source software that has been developed and/or licensed by “OpenSSL”, “RSA

Data Security, Inc.”, “Apache Foundation”, or “Jean-loup Gailly and Mark Adler.” TmaxSoft fully respects the

aforementioned parties and the open source software used in this product. More details can be found within the

directory “${INSTALL_PATH}/license/oss_licenses”

본 제품은 “OpenSSL”, “RSA Data Security, Inc.”, “Apache Foundation” 및 “Jean-loup Gailly와 Mark Adler”에 의

해 개발 또는 라이선스된 오픈 소스 소프트웨어를 포함합니다. 오픈 소스 소프트웨어와 개발자에 대해 경의를 표

합니다. 관련 상세 정보는 제품의 디렉터리 “${INSTALL_PATH}/license/oss_licenses”에 기재된 사항을 참고해 주

십시오.

안내서 정보

안내서 제목: Tmax HMS User Guide

발행일: 2009-08-10

소프트웨어 버전: Tmax v5.0 SP1

안내서 버전: v2.1.1

내용 목차

안내서에 대하여 ........................................................................................................................... ix

제1장 소개 ................................................................................................................................. 1

1.1. 개요 ............................................................................................................................ 1

1.2. 구조 ............................................................................................................................ 1

1.3. JMS와 HMS 프로그래밍 ............................................................................................... 2

1.3.1. Connection ....................................................................................................... 3

1.3.2. 세션 .................................................................................................................. 3

1.3.3. 데스티네이션(Destination) ................................................................................. 4

1.3.4. 생산자(Producer) ............................................................................................... 4

1.3.5. 소비자(Consumer) ............................................................................................. 5

1.3.6. 메시지 .............................................................................................................. 5

1.3.7. 큐 브라우저(QueueBrowser) .............................................................................. 6

1.3.8. 복구(Recovery) ................................................................................................. 7

1.3.9. 클러스터링(Clustering) ...................................................................................... 7

제2장 HMS 설정 ......................................................................................................................... 9

2.1. 환경 파일 ..................................................................................................................... 9

2.1.1. DOMAIN 절 ....................................................................................................... 9

2.1.2. NODE 절 .......................................................................................................... 9

2.1.3. SVRGROUP 절 ............................................................................................... 10

2.1.4. HMS 절 ........................................................................................................... 13

2.2. 환경파일 예제 ............................................................................................................ 15

제3장 HMS API 함수 ................................................................................................................. 17

3.1. 세션 API .................................................................................................................... 17

3.1.1. hms_create_session ........................................................................................ 17

3.1.2. hms_create_xa_session .................................................................................. 20

3.1.3. hms_create_async_session ............................................................................. 22

3.1.4. hms_close_session ......................................................................................... 25

3.1.5. hms_unsubscribe_durable_subscriber .............................................................. 26

3.1.6. hms_commit .................................................................................................... 28

3.1.7. hms_rollback ................................................................................................... 30

3.1.8. hms_recover ................................................................................................... 31

3.2. 메시지 API ................................................................................................................. 33

3.2.1. hms_alloc ....................................................................................................... 33

3.2.2. hms_free ......................................................................................................... 35

3.2.3. hms_get_property ........................................................................................... 36

3.2.4. hms_set_property ............................................................................................ 39

3.2.5. hms_get_body ................................................................................................. 42

3.2.6. hms_set_body ................................................................................................. 44

3.2.7. hms_ack ......................................................................................................... 45

Tmax iii

3.3. 생산자(Producer) API ................................................................................................. 48

3.3.1. hms_create_producer ...................................................................................... 48

3.3.2. hms_create_sender ......................................................................................... 50

3.3.3. hms_create_publisher ...................................................................................... 52

3.3.4. hms_close_producer ....................................................................................... 54

3.3.5. hms_close_sender .......................................................................................... 55

3.3.6. hms_close_publisher ....................................................................................... 56

3.3.7. hms_sendex .................................................................................................... 57

3.3.8. hms_send ....................................................................................................... 60

3.4. 소비자(Consumer) API ............................................................................................... 62

3.4.1. hms_create_consumer ..................................................................................... 62

3.4.2. hms_create_receiver ....................................................................................... 64

3.4.3. hms_create_subscriber .................................................................................... 67

3.4.4. hms_create_durable_subscriber ....................................................................... 69

3.4.5. hms_close_consumer ...................................................................................... 71

3.4.6. hms_close_receiver ......................................................................................... 72

3.4.7. hms_close_subscriber ..................................................................................... 73

3.4.8. hms_close_durable_subscriber ........................................................................ 74

3.4.9. hms_recvex ..................................................................................................... 76

3.4.10. hms_recv ...................................................................................................... 78

3.5. 큐 브라우저 API ......................................................................................................... 80

3.5.1. hms_create_browser ....................................................................................... 80

3.5.2. hms_close_browser ......................................................................................... 82

3.5.3. hms_browser_nextmsg .................................................................................... 84

3.5.4. hms_browser_get_msgselector ........................................................................ 86

3.5.5. hms_browser_get_queue ................................................................................. 88

제4장 HMS 관리 ....................................................................................................................... 91

4.1. HMS 빌드 .................................................................................................................. 91

4.1.1. 사전 준비 ........................................................................................................ 91

4.1.2. HMS Makefile .................................................................................................. 92

4.1.3. HMS 빌드 및 확인 ............................................................................................ 92

4.2. HMS 기동 및 종료 ...................................................................................................... 93

4.3. HMS 상태 조회 ........................................................................................................... 93

4.3.1. tmadmin .......................................................................................................... 93

제5장 예제 ................................................................................................................................ 97

5.1. 기초 프로그램 1 .......................................................................................................... 97

5.1.1. HMS 환경설정 ................................................................................................. 97

5.1.2. 프로그램 예제 .................................................................................................. 98

5.1.3. 프로그램 컴파일 ............................................................................................ 103

5.2. 기초 프로그램 2 ........................................................................................................ 103

5.2.1. HMS 환경설정 ............................................................................................... 103

5.2.2. 프로그램 예제 ................................................................................................ 104

iv Tmax HMS User Guide

5.2.3. 프로그램 컴파일 ............................................................................................ 110

Appendix A. 메시지 셀렉터 사용하기 ...................................................................................... 111

색인 .......................................................................................................................................... 113

Tmax v

그림 목차

[그림 1.1] HMS의 구조 ................................................................................................................ 2

[그림 1.2] 프로그래밍 모델 .......................................................................................................... 2

[그림 5.1] 기초 프로그램 흐름 .................................................................................................... 97

[그림 5.2] 기초 프로그램 2 ....................................................................................................... 103

Tmax vii

안내서에 대하여

안내서의 대상

본 안내서는 Tmax®(이하 Tmax)에서 HMS를 사용하는 개발자나 운영자를 대상으로 작성되었다. HMS의

기본 개념과 환경설정 방법, API 사용법과 예제 등을 기술한다.

안내서의 전제 조건

본 안내서는 Tmax 시스템에 대한 전반적인 이해와 Tmax 시스템이 제공하는 각종 기능 및 특성에 대한 습

득을 위한 기본서이다.

본 안내서를 원활하게 이해하기 위해서는 다음과 같은 사항을 미리 알고 있어야 한다.

● 미들웨어(Middleware) 및 UNIX 시스템에 대한 이해

● Tmax의 기본 개념 이해

● Java , C 프로그래밍의 이해

● JMS(Java Messaging Service) Spec의 이해

안내서의 제한 조건

본 안내서 Tmax와 관련된 전반적인 부분은 포함하지 않고 HMS와 관련된 내용만 기술하였다. 실무에서

의 구체적인 사용방법이나 관리 및 운용에 관한 사항은 각 제품의 안내서를 참고한다.

참고

Tmax 시스템 개발에 대한 기본적인 내용은 "Tmax Administration Guide"나 "Tmax Application Devel

oment Guide"를 참고한다. Tmax에서 제공하는 명령어와 C API에 대한 설명은 “Tmax Reference

Guide”를 참고한다.

안내서에 대하여 ix

안내서 구성

Tmax HMS User Guide는 총 5개의 장과 Appendix로 구성되어 있다.

각 장의 주요 내용은 다음과 같다.

● 제1장: 소개

HMS에 관한 소개와 구조에 대해 설명한다.

● 제2장: HMS 설정

HMS 관련 설정에 대해 기술한다.

● 제3장: HMS API 함수

HMS에서 사용하는 API에 대해 기술한다.

● 제4장: HMS 관리

HMS를 사용하기 위해 HMS를 빌드하는 과정과 HMS의 기동과 종료 및 상태조회에 대해 기술한다.

● 제5장: 예제

애플리케이션 예제를 통한 기본적인 사용법을 기술한다.

● Appendix.A 메시지 셀렉터 사용하기

메시지 셀렉터의 구성에 대해 기술한다.

x Tmax HMS User Guide

안내서 규약

의미표기

프로그램 소스 코드의 파일명<AaBbCc123>

Ctrl과 C를 동시에 누름<Ctrl>+C

GUI의 버튼 또는 메뉴 이름[Button]

강조진하게

다른 관련 안내서 또는 안내서 내의 다른 장 및 절 언급" "(따옴표)

화면 UI에서 입력 항목에 대한 설명'입력항목'

메일계정, 웹 사이트하이퍼링크

메뉴의 진행 순서>

하위 디렉터리 또는 파일 있음+----

하위 디렉터리 또는 파일 없음|----

참고 또는 주의사항참고

그림 이름[그림 1.1]

표 이름[표 1.1]

명령어, 명령어 수행 후 화면에 출력된 결과물, 예제코드AaBbCc123

옵션 인수 값[ ]

선택 인수 값|

안내서에 대하여 xi

시스템 사용 환경

요구 사항

IBM AIX 5.xPlatform

HP-UX 11.xx

Solaris 7~9 (SunOS 5.7~5.9)

최소 120MB 하드디스크 공간Hardware

256MB 이상 메모리 공간

1GB 이상 하드디스크와 512MB 이상 메모리 공간 권장

Tibero 4.0Database

Oracle 9i 또는 10g

xii Tmax HMS User Guide

관련 안내서

설명안내서

Tmax 제품을 사용하는 도중 발생할 수 있는 에러 및 해당 에러에 대

한 대응 방법을 기술한 안내서이다.

Tmax

Error Message Reference Guide

Tmax FDL 함수 정의와 예제 프로그램을 통하여 FDL이 제공하는 기

능을 활용 하는 방법을 기술한 안내서이다.

Tmax

FDL Reference Guide

Tmax를 이용하기 위한 환경설정을 하는 방법과 시스템 운영방식을

기술한 안내서이다.

Tmax

Administration Guide

Tmax TDL(Tmax Dynamic Library )을 사용해서 프로그램을 개발하

려는 사용자를 위해 기술한 안내서이다.

Tmax

Programming Guide (Dynamic Li

brary)

Tmax 애플리케이션 프로그램 개발에 사용하는 API의 개념 및 사용

법과 예제를 기술한 안내서이다.

Tmax

Application Development Guide

Tmax 서비스를 특별한 변경 없이 웹서비스로 사용하기 위해서 제공

되는 게이트웨이 서버인 WebService Gateway를 기술한 안내서이

다.

Tmax

Gateway Guide (WebService)

Tmax의 SQ(Session Queue)에 대한 개념과 사용 방법을 기술한 안

내서이다.

Tmax

Programming Guide (SQ)

안내서에 대하여 xiii

연락처

Korea

TmaxSoft Co., Ltd

263 BundangSquare (AK Plaza) 12th floor, Seohyeon-dong, Bundang-gu,

Seongnam-si, Gyeonggi-do, 463-824

South Korea

Tel: +82-31-8018-1000

Fax: +82-31-8018-1115

Email: [email protected]

Web (Korean): http://www.tmax.co.kr

기술지원: http://technet.tmaxsoft.com

USA

TmaxSoft, Inc.

560 Sylvan Avenue Englewood Cliffs, NJ 07632

U.S.A

Tel: 1-201-567-8266

Fax: 1-201-567-7339


Web (English): http://www.tmaxsoft.com

Japan

TmaxSoft Japan Co., Ltd.

5F Sanko Bldg, 3-12-16 Mita, Minato-Ku, Tokyo, 108-0073

Japan

Tel: +81-3-5765-2550

Fax: +81-3-5765-2567


Web (Japanese): http://www.tmaxsoft.co.jp

xiv Tmax HMS User Guide

http://www.tmax.co.kr

http://technet.tmaxsoft.com

http://www.tmaxsoft.com

http://www.tmaxsoft.co.jp

China

TmaxSoft China Co., Ltd.

Beijing Silver Tower, RM 1508, 2# North Rd Dong San Huan,

Chaoyang District, Beijing, China, 100027

China

Tel: +86-10-6410-6145~8

Fax: +86-10-6410-6144


Web (Chinese): http://www.tmaxsoft.com.cn

ASEAN Office

TmaxSoft Pte. Ltd.

30 Cecil Street, Level 15 Unit 05 Prudential Tower, Singapore 049712

Singapore

Tel: +65-6232-2889

Fax: +65-6232-2919


Web (English): http://asean.tmaxsoft.com

안내서에 대하여 xv

http://www.tmaxchina.com.cn

http://www.tmaxchina.com.cn

제1장 소개

메시징 시스템(Messaging System)이란 송신자(Sender)와 수신자(Receiver) 사이의 느슨한 결합(loosely

coupled)을 가능케 하는 통신 매개체이다. 다시 말해 메시징 시스템을 사용하여 송신자와 수신자는 서로

에 관한 정보를 알 필요없이 가상적 채널, 즉 데스티네이션(Destination)에 관한 정보만 가지고 서로 통신

을 할 수 있다. 또한 송신하는 시점과 수신하는 시점을 분리할 수 있어 데이터에 대한 지연처리가 가능하

며, 이를 위해 메시징 시스템은 메시지의 송,수신에 대한 신뢰성(Reliability)을 보장한다.

이 장에서는 Hybird Messaging System(이하 HMS)에 관한 소개와 구조를 서술하고, 메시징 시스템에 관

한 기본적 개념과 용어를 설명한다.

1.1. 개요HMS는 엔터프라이즈 시스템 사이에 이루어지는 정보 교환의 양상을 메시지라는 형태의 데이터와 데스

티네이션이라는 가상적인 채널로 추상화한다. 사용자가 생성한 메시지는 관리자에 의해 생성된 가상 채

널, 데스티네이션에 전달되며 이 정보가 필요한 애플리케이션은 언제라도 이 데스티네이션에 자신을 등

록하여 메시지를 얻어올 수 있다. HMS는 썬 마이크로 시스템즈(Sun Microsystems)에서 재정한 Java 기

반의 메시징 시스템 표준, JMS(Java Messaging Service)의 개념과 동작방식을 반영하였다.

HMS는 TP-Monitor인 Tmax 시스템에서 동작하므로, 사용자는 TP-Monitor의 기능과 메시징 시스템의 기

능을 유연하게 결합하여 사용할 수 있다. 다시 말해 자원 관리자(Resource Manager)와의 2PC 기능, 백업

노드 설정으로 장애가 발생하면 유연한 대처 등이 가능하다.

1.2. 구조HMS는 Tmax 시스템 안에서 멀티 스레드 프로세스로 동작한다. HMS의 스레드는 메인 스레드(Main

Thread), 워커 스레드(Worker Thread) 2가지로 구분된다. 또한 워커 스레드는 일반 스레드와 스토리지 스

레드로 구분된다.

메인 스레드는 클라이언트, 서비스 등 Tmax와의 통신부분을 담당하며 해당 요청이나 메시지를 워커 스레

드로 전달하는 역할을 한다. 메시지나 요청의 종류에 따라 스토리지 관련 작업이 필요한 경우에는 스토리

지 스레드가, 그 외의 경우에는 일반 스레드가 해당 메시지나 요청을 처리한다. 각 워커 스레드의 개수는

환경파일에 사용자가 직접 설정할 수 있다. 설정하지 않으면 기본적으로 일반 스레드는 2개, 스토리지 스

레드는 4개로 동작한다. 스토리지 스레드의 개수는 무조건 많을수록 좋은 것은 아니며, 운영 시스템의 성

능과 스토리지의 성능에 따라 적절한 값을 설정해 주어야 한다.

제1장 소개 1

[그림 1.1] HMS의 구조

1.3. JMS와 HMS 프로그래밍HMS를 사용하기 위해서는 메시징 시스템에 대한 기본적 개념과 용어에 대한 이해가 필요하다. HMS는

JMS의 개념을 사용하므로 앞으로의 용어를 설명하는 데에 있어 JMS에서 사용하는 용어와 동일하다.

다음 그림은 JMS와 HMS에서 사용하는 프로그래밍 모델을 보여준다.

[그림 1.2] 프로그래밍 모델

2 Tmax HMS User Guide

1.3.1. Connection

HMS 기능을 사용하고자 하는 애플리케이션은 기본적으로 Tmax와의 연결을 맺어야 한다. 기동되면서 자

동으로 연결을 맺는 서버 애플리케이션과는 달리, 클라이언트 애플리케이션은 HMS 관련 API를 사용하기

전에 tpstart()를 이용해 Tmax와의 연결을 맺어야만 한다. 연결이 종료될 경우, 클라이언트가 tpend()를 수

행하거나 서버가 종료될 경우 애플리케이션에서 만든 세션과 클라이언트 정보가 HMS에서 모두 삭제된

다.

1.3.2. 세션

세션은 HMS 기능을 사용하는 데에 가장 기본이 되는 처리단위이다. Tmax와의 연결이 존재하는 상태에

서 생성해야 하며, 하나의 애플리케이션 안에서 다수의 세션을 생성할 수도 있다. 세션을 생성하기 위해서

는 대상 HMS의 이름이 필요하며, 생성될 경우 세션의 여러 가지 속성을 부여할 수 있다. 기본적인 속성은

다음과 같다.

설명속성

세션의 트랜잭티드 속성 사용여부를 결정한다.Transacted

메시지 수신에 대한 응답을 자동으로 전달할 것인지, 사용자가 직접 전달할

것이 응답 방법의 종류를 결정한다. 현재 자동으로 응답을 하는 AUTO_ACK,

사용자가 응답을 직접 보내는 CLIENT_ACK을 지원한다.

Acknowledge Mode

HMS에서 사용하는 세션은 일반 세션, 트랜잭티드 세션(Transacted Session), XA 세션, 비동기 세션(Async

Session) 4가지로 나뉜다.

트랜잭티드 세션(Transacted Session)

트랜잭티드 세션은 생성될 때 트랜잭티드 속성을 부여 받아 생성된 세션이다. 주로 로컬 트랜잭션을 사용

하기 위해 사용한다. 트랜잭티드 세션에서는 메시지의 송,수신의 결과가 HMS로 바로 반영되지 않는다.

hms_commit(), hms_rollback() API를 통해 반영여부를 결정한다. 예를 들어 트랜잭티드 세션으로 생성된

생산자가 다수의 메시지를 송신하고 hms_rollback()을 했다면 송신했던 메시지는 데스티네이션에 들어가

지 않고 무시된다. 메시지 수신 시 결과 반영여부를 hms_commit(), hms_rollback()으로 결정하게 되므로

트랜잭티드 세션에서는 AUTO_ACK만 허용한다.

XA 세션

XA 세션은 HMS와 다른 리소스 관리자(RM)와의 2PC를 수행하기 위해 존재한다. 트랜잭션으로 묶을 구

간 시작과 끝에 Tmax의 트랜잭션 관련 API(tx_beggin(), tx_commit(), tx_rollback())를 이용하여 명시한다.

트랜잭션이 시작되지 않은 상태에서는 일반 세션처럼 동작한다.

제1장 소개 3

비동기 세션(Async Session)

HMS는 메시지에 대한 요청 이후 메시지가 송신되는 동기적인 방법뿐만 아니라, 메시지에 대한 요청 없이

도 메시지를 수신할 수 있는 비동기 세션을 지원한다. 비동기 세션으로 소비자(Consumer)를 생성할 때 메

시지 도착 시 불릴 서비스 이름(Listener)을 넘겨주면, 메시지가 도착할 때 마다 지정한 Tmax 서비스가 호

출된다.

1.3.3. 데스티네이션(Destination)

데스티네이션(Destination)은 지연처리를 위해 송신된 메시지가 소비자가 메시지를 수신할 때까지 머무르

는 저장소이다. 각 데스티네이션은 고유한 이름을 가지며, 종류로는 토픽과 큐가 있다.

토픽(Topic)

발행자/구독자 메시징(Publish/Subscribe Messaging)에서 쓰이는 데스티네이션이다. 1개의 메시지는 송

신된 시점에 가입되어 있는 구독자(Subscriber)에게 모두 전달된다. 그 시점에 가입된 구독자가 존재하지

않을 경우에는 송신된 메시지는 버려진다.

큐(Queue)

Point-to-Point 메시징에서 쓰이는 데스티네이션이다. 하나의 메시지는 하나의 수신자(Receiver)에게 전달

된다. 송신자가 송신한 메시지는 수신자가 메시지를 꺼내갈 때까지 데스티네이션에 존재한다.

1.3.4. 생산자(Producer)

생산자(Producer)란 데스티네이션에 메시지를 송신하는 주체를 뜻한다. 대상 데스티네이션의 종류에 따

라 토픽에 대한 생산자는 발행자(Publisher), 큐에 대한 생산자는 송신자(Sender)라 지칭한다. 생산자를

생성하기 위해서는 Tmax 시스템과 연결이 된 상태에서 생성한 세션, 데스티네이션의 이름, 데스티네이션

의 종류가 필요하다. 그리고 필요에 따라 생산자의 이름을 설정할 수 있다.

생산자는 메시지를 송신할 때 해당 메시지 전달에 대한 속성을 부여할 수 있다.

설명속성

메시지에 영속적(Persistent) 혹은 비영속적(Non-Persistent) 속성을 부여해

서 송신한다. 영속적 메시지는 데스티네이션에 도착하는 동시에 스토리지에

Delivery Mode

도 저장되어 장애가 발생할 경우 복구가 가능하다. 비영속적 메시지는 HMS

의 메모리에서만 존재하며 HMS를 종료하거나 장애가 발생하면 소멸된다.

메시지가 데스티네이션 안에 큐잉될 때 우선순위를 지정한다. 현재 HMS에

서는 지원하지 않는다.

Priority


설명속성

메시지가 데스티네이션 안에서 유효한 시간을 지정한다. 지정한 시간이 지나

면 메시지는 더 이상 소비자에게 전달될 수 없다. HMS는 TTL을 초단위로 지

원한다.

Time to Live

메지시가 송신에 성공하게 되면 각 메시지는 고유한 메시지 ID를 발급 받는다. 메시지 ID는 프로퍼티로서

메시지에 존재하게 되며 사용자가 hms_get_property()를 이용하여 확인할 수 있다.

1.3.5. 소비자(Consumer)

소비자(Consumer)란 데스티네이션으로부터 메시지를 수신하는 주체를 뜻한다. 대상 데스티네이션의 종

류에 따라 토픽에 대한 소비자는 구독자(Subscriber), 큐에 대한 소비자는 수신자(Receiver)라 지칭한다.

소비자의 생성하기 위해서는 세션, 데스티네이션의 이름, 데스티네이션의 종류, 만들고자 하는 소비자의

이름이 필요하다. 또한 특정 프로퍼티를 갖는 메시지만 선택해 수신하고자 할 때는 메시지 셀렉터를 설정

할 수 있으며, 비동기적 메시지 수신을 하고자 할 경우 수신될 때 호출될 서비스 이름을 설정한다.

소비자가 메시지를 수신할 때 타임아웃 값을 지정할 수 있다. 지정하지 않을 경우 메시지가 도착할 때까지

블럭 된다. 타임아웃 값의 단위는 초이다.

영속적 구독자(Durable Subscriber)

소비자 중에 영속적인 속성을 갖는 구독자를 영속적 구독자(Durable Subscriber)라 한다. 영속적 구독자

는 생성된 이후에 구독해제(unsubscribe)할 때까지 데스티네이션으로 전달된 모든 메시지를 받을 수 있다.

이는 영속적 구독자가 Tmax와의 연결에서 해제되어도 추후에 재접속하면 이전 메시지에 이어서 수신이

가능하다는 의미이다. HMS가 영속적 구독자를 구분하는 기준은 구독자의 이름이다. 따라서 영속적 구독

자를 생성할 때에는 반드시 고유한 이름을 부여해야 한다.

1.3.6. 메시지

HMS에서 사용되는 메시지는 Tmax의 필드버퍼를 사용하기 때문에 필드버퍼의 장점을 그대로 이용할 수

있다. 하나의 메시지 안에는 다수의 프로퍼티와 한 개의 Body를 설정할 수 있다.

Body는 CARRAY 타입으로 설정하며, 프로퍼티는 필드버퍼에서 지원하는 8가지 데이터 타입으로 설정한

다. 그 8가지 데이터 타입은 HMS_CHAR, HMS_SHORT, HMS_INT, HMS_LONG, HMS_FLOAT,

HMS_DOUBLE, HMS_STRING, HMS_CARRAY이다.

프로퍼티는 이름과 함께 그 값을 설정하게 되며, 그 이름은 메시지 안에서 유일해야 한다. 같은 이름으로

프로퍼티를 재설정할 경우 이전 값이 수정된다.

메시지를 생성하기 위해서는 세션을 이용해야 하며, 각 프로퍼티는 데이터부분 뿐만 아니라 이름을 나타

내는 공간도 필요하므로 많은 프로퍼티를 설정할 경우 메시지의 크기를 고려하여 넉넉히 할당해야 한다.

제1장 소개 5

Reserved Property

다음은 HMS에서 기본적으로 정의한 프로퍼티이다. 사용자는 이와 같은 이름으로 프로퍼티를 재설정 할

수 없다.

설명프로퍼티

메시지의 고유한 ID이다. HMS가 발급하므로 송신에 성공한 이후에 확인할

수 있다. 12자의 16진수의 문자열로 확인할 수 있다.

HMSMessageID

("$MessageID")

생산자가 메시지를 송신하고 그 응답을 받을 때까지 걸린 시간(초)을 나타낸

다.

HMSTimeStamp

("$TimeStamp")

메시지가 송,수신된 데스티네이션의 이름을 나타낸다.HMSDestination

("$Destination")

메시지가 영속적(Persistent)인지 비영속적(Non-Persistent)인지 여부를 나타

낸다.

HMSDeliveryMode

("$DeliveryMode")

생산자가 메시지를 송신하면서 설정한 TTL 값을 의미한다.HMSExpiration

("$Expiration")

이외의 다른 예약된 프로퍼티가 있으나 현재 지원하지 않는다.

메시지 셀렉터(Message Selector)

수신자를 생성할 때에 메시지 셀렉터를 설정할 수 있다. 메시지 셀렉터는 사용자가 일정한 조건을 설정하

고 해당 조건을 충족하는 메시지만을 수신할 수 있도록 해준다. 메시지 셀렉터 구문은 SQL 조건문과 동일

하다.

예를 들어 메시지에 Type과 Month라는 프로퍼티가 존재한다면, 다음과 같은 메시지 셀렉터를 설정한 소

비자는 '4월 이후의 뉴스' 메시지만 수신하게 될 것이다.

"(Type = 'News') AND (Month > 4)"

1.3.7. 큐 브라우저(QueueBrowser)

큐 브라우저는 큐의 메시지를 조회할 수 있는 일종의 소비자이다. 큐로부터 확인 용도의 메시지를 수신하

지만 실제로는 메시지가 소비되지는 않는다. 기본적으로 가장 최신 메시지부터 오래된 순으로 열람하도

록 동작하나, 가장 오래된 메시지부터의 열람 또한 가능하다. 큐 브라우저의 이름에서처럼 대상 데스티네

이션은 큐만 허용한다.


1.3.8. 복구(Recovery)

영속적 메시지(Persistent Message)와 영속적 구독자(Durable Subscriber)의 정보는 스토리지에 저장된

다. HMS는 기동되자마자 스토리지에 남아있는 처리되지 않은 영속적 메시지와 영속적 구독자의 정보를

복구할 수 있다. 복구 여부는 부트 옵션으로 설정하며, 데스티네이션 별로 각각 설정할 수 있다. WARM은

기동될 때 복구를 의미하고, COLD는 기동될 때 스토리지의 정보를 클리어한다.

영속적 구독자가 복구 후 메시지를 이어서 수신하기 위해서는 이전에 만들어졌던 이름으로 다시 만들어

져야 한다. 따라서 영속적 구독자를 만들 때에는 고유한 이름을 부여하는 것이 중요하다. 또한 구독 해제

(unsubscribe)하지 않고 영속적 구독자를 제거한다면 해당 영속적 구독자에게 전달되지 않은 메시지와 그

이후에 도착하는 모든 메시지가 데스티네이션에 쌓여있게 되므로 주의해야 한다.

1.3.9. 클러스터링(Clustering)

Tmax 멀티노드 환경에서 다수의 HMS는 클러스터링 구성이 가능하다. 이를 이용해서 Failover와 부하분

산 효과를 얻을 수 있다. 이름이 동일하고, GLOBAL 속성을 준 데스티네이션은 논리적으로 하나의 데스티

네이션처럼 동작한다. HMS의 클러스터링을 구성하기 위해서는 SVRGROUP 절에 HMSPORT는 반드시

설정해주어야 하며, 큐를 클러스터링 하기 위해서는 추가적으로 GQINT를 설정해 주어야 한다. HMS 절

에는 클러스터링하고자 하는 데스티네이션의 이름은 같게 주고, GLOBAL=Y로 설정해야 한다. HMS에서

는 클러스터링이 설정된 토픽을 글로벌 토픽, 큐를 글로벌 큐라 지칭한다.

클러스터링 된 HMS는 서로에 대한 장애감지를 위해 Heartbeat 메시지를 주고 받는다. 사용자가 설정한

HMSHEARTBEAT 시간 내에 Heartbeat 메시지가 오지 않을 경우 장애 상황으로 판단한다.

글로벌 토픽(Global Topic)

글로벌 토픽으로 송신된 메시지는 나머지 다른 노드의 글로벌 토픽으로 전달된다. 예를 들어 노드 A, B, C

에 Topic01이라는 같은 이름을 같는 토픽에 모두 GLOBAL=Y 설정을 했다면, 노드 A의 Topic01에 도착한

메시지는 노드 B, C의 Topic01에도 전달된다.

글로벌 큐(Global Queue)

설정된 모든 노드에 복사본이 전달되는 글로벌 토픽과는 달리 글로벌 큐에 있어서는 메시지는 1개만이 존

재하고 소비될 수 있으므로 클러스터링에 있어서 다른 방법을 사용한다. 각 HMS는 글로벌 큐에 대한 정

보를 일정시간(HMSGQINT)을 주기로 계속 주고받는다. 이 정보에는 현재 노드의 각 큐에 존재하는 메시

지의 개수, 연결되어있는 클라이언트 수 등이 포함된다. 각 큐에는 원활한 메시지 전달을 위해 버퍼링을

하는데, 그 크기는 현재 큐에 연결되어 있는 소비자의 수에 사용자가 설정한 상수값(GQTHR)을 곱해서 구

해진다. 큐 안의 메시지 수가 계산된 버퍼의 크기보다 작을 경우에는 다른 노드의 큐로부터 메시지를 요청

한다. 한번의 요청으로 한꺼번에 가져올 수 있는 메시지의 수(GQMAXREQ) 또한 설정할 수 있다. 이 값이

클 경우 적은 요청으로 필요한 메시지를 채울 수 있으나, 너무 클 경우에는 노드 간의 불필요한 메시지의

이동이 발생 할 수 있다. 버퍼의 크기 말고도 큐의 길이가 불균형적으로 크게 차이 나는 현상을 방지하기

위하여 메시지가 일정 수 이상(GQFULL)이 되면 메시지의 요청이 없어도 큐의 길이를 균형적으로 맞춰주

는 기능도 제공한다.

제1장 소개 7

● Global Queue Information Interval (GQINT)

HMS의 글로벌 큐에 대한 상태정보를 교환하는 주기이다.

● Global Queue Threshold (GQTHR)

글로벌 큐의 버퍼의 크기를 구하는데 쓰이는 상수값이다.(버퍼크기 = 해당 큐의 소비자 수 X GQTHR)

● Global Queue Max Request (GQMAXREQ)

현재 큐의 길이가 버퍼량을 채우지 못할 때 다른 노드로 부터 한번의 요청으로 가져올 수 있는 최대 메

시지의 개수이다.

● Global Queue Full Length (GQFULL)

큐의 길이가 불균형이 되는 현상을 방지하기 위해 설정하는 큐의 임계길이이다. 이 길이 이상이 되면 더

짧은 길이를 갖는 큐로 메시지가 이동한다.


제2장 HMS 설정

HMS를 사용하기 위해서는 Tmax의 환경파일에 다음과 같은 HMS 관련 설정을 추가해주어야 한다.

2.1. 환경 파일HMS를 사용하기 위해서는 DOMAIN, NODE, SVRGROUP, HMS 절에 대한 설정이 필요하다. 아래는 각

환경 절에 대한 설명이다.

2.1.1. DOMAIN 절

DOMAIN 절의 기본 환경설정 형식은 다음과 같이 정의한다.

*DOMAIN

Domain1 [MAXSESSION=numeric]

DOMAIN 절에서는 HMS 사용을 위해 아래의 항목의 설정이 가능하다.

선택항목

● MAXSESSION = numeric (1024)

– 크기 : 1 ~ 65535

– 도메인 내의 HMS에서 생성할 수 있는 세션 수의 최대값을 설정한다. 기본값은 1024이다.

2.1.2. NODE 절

NODE 절의 기본 환경설정 형식은 다음과 같이 정의한다.

*NODE

Node1 [MAXSESSION=numeric]

NODE 절에서는 HMS 사용을 위해 아래의 항목의 설정이 가능하다.

선택항목

● MAXSESSION = numeric (1024)

– 크기 : 1 ~ 65535

제2장 HMS 설정 9

– Node내의 HMS에서 생성할 수 있는 세션의 수의 최대값을 설정한다. 기본값은 1024이다.

2.1.3. SVRGROUP 절

SVRGROUP 절의 기본 환경설정 형식은 다음과 같이 정의한다.

*SVRGROUP

SVRGROUP 이름 NODENAME=node-name,

SVGTYPE=HMS,

HMSNAME=string,

OPENINFO=literal,

HMSINDEX=numeric,

HMSMAXTHR=numeric,

HMSMAXDBTHR=numeric,

[HMSSUBSCFG=string,]

[HMSMSGLIVE=numeric,]

[HMSPORT=numeric,]

[HMSHEARTBEAT=numeric,]

[HMSGQINT=numeric]

SVRGROUP 절은 기본적인 SVRGROUP 절의 필수항목 외에 HMS와 관련하여 추가적인 항목의 설정이

필요하다.

필수항목

● SVRGROUP 이름 = string

– 크기: 15자 이내

– HMS 서버그룹에 대한 논리적인 이름으로서 SVRGROUP 절 내에서 유일한 이름이어야 한다.

● NODENAME = string


– HMS 서버그룹이 존재하는 노드를 정의한다. 사용되는 NODENAME은 NODE 절에서 정의한 노드 이

름이어야 한다.

● SVGTYPE = string

해당 서버그룹의 종류를 정의한다. HMS를 사용하기 위해서는 반드시 SVGTYPE=HMS로 설정해야만

한다.

● HMSNAME = string



– 사용자가 빌드한 HMS 프로세스 이름을 정의한다.

● OPENINFO = literal

– HMS는 기본적으로 데이터베이스를 스토리지로 사용한다. 따라서 HMS에서 연결을 할 DBMS의

OPENINFO를 설정해 주어야 한다.

– 데이터베이스로 연결을 초기화하고 각 데이터베이스에서 제공되는 문법으로 정의한다.

● HMSINDEX = numeric

– 크기 : 0 ~ 65535

– HMS의 메시지를 처리하는데 필요한 설정값으로서 도메인 안에서 유일한 값으로 반드시 설정해야

한다.

● HMSMAXTHR = numeric (2)

– 크기 : 0 ~ 65535

– 스토리지 처리를 하지 않는 스레드의 수를 설정한다.

– 비영속성 메시지만 송,수신하는 경우 이 항목의 값을 크게 늘려주어야 한다.

– 비영속적 메시지 이외에도 HMS의 기본적 동작을 위해 일정 수 이상 설정해야 한다.

● HMSMAXDBTHR = numeric (4)

– 크기 : 0 ~ 65535

– 스토리지 처리를 하는 스레드의 수를 설정한다.

– 영속적 메시지가 많은 경우 이 값을 늘려줄 필요가 있다.

– 영속적 메시지 처리 외에도 HMS의 기본적 동작을 위해 일정 수 이상 설정해야 한다.

선택항목

● HMSSUBSCFG = string

– 크기 : 255자 이내


– 영속적 구독자(Durable Subscriber)를 설정한 환경파일의 경로와 이름을 설정한다.

– 파일안의 내용은 Label을 [TopicName]으로 설정한 후, 각 라인마다 ClientName:Listener:Selector 의

순으로 콜론(:)을 구분자로 구분하여 넣어준다.

– 환경파일에 정의된 영속적 구독자는 HMS가 기동되면서 자동으로 등록된다.

● HMSMSGLIVE = numeric

– 크기 : 0 ~ 65535

– HMS는 영속적 메시지를 스토리지에 저장한다. 스토리지에 쌓인 메시지들을 주기적으로 삭제할 시

간을 설정한다. 설정 단위는 시간 단위이다.

– 모든 구독자가 수신한 토픽 메시지, 소비가 완료된 큐 메시지는 설정된 시간이 경과되면 스토리지에

서 삭제된다. 아직 받지 않은 영속적 수신자가 존재하는 메시지는 설정된 시간이 경과되어도 스토리

지에서 삭제되지 않는다.

● HMSPORT = numeric

– 다수의 HMS를 클러스터링하는 경우 각 HMS는 서로 통신하기 위해 직접 채널을 생성한다. 이때 사

용하는 포트번호를 설정한다.

– GLOBAL 속성을 설정한 데스티네이션이 존재하는 경우 HMS는 설정된 포트번호로 Listen한다. 따라

서 이미 사용하고 있는 포트를 설정하지 않도록 주의해야 한다.

● HMSHEARTBEAT = numeric

– 크기 : 0 ~ 65535

– 다수의 HMS를 클러스터링하는 경우 HMS 간의 네트워크 장애 감지를 위해 주기적으로 Heartbeat 메

시지를 주고 받는다. 이 메시지를 전송하는 주기를 초단위로 설정한다.

– 이 주기 안에 Hearbeat 메시지가 다른 HMS에서 오지 않은 경우 장애로 감지해 해당 HMS와의 연결

을 끊는다.

● HMSGQINT = numeric

– 크기 : 0 ~ 65535

– GLOBAL 속성을 설정한 큐 간의 메시지를 주고 받기 위해서는 각 큐의 상태정보를 주고 받아야 하는

데, 이 정보를 주고받는 주기를 밀리세컨드 단위로 설정한다.


– 클러스터링 된 큐를 사용하기위해서는 반드시 설정해야 한다. 주기가 짧을수록 정확한 분배가 가능

하지만 그만큼 네트워크의 부하는 크므로 적당한 크기의 값을 설정할 필요가 있다.

2.1.4. HMS 절

HMS 절의 기본 환경설정 형식은 다음과 같이 정의한다.

*HMS

데스티네이션 이름 SVGNAME=string,

TYPE=TOPIC | QUEUE,

[BOOT=WARM | (COLD),]

[GLOBAL=Y | (N),]

[GQTHR=numeric,]

[GQMAXREQ=numeric,]

[GQFULL=numeric]

HMS의 데스티네이션에 대한 설정은 HMS 절에서 한다.

필수항목

● 데스티네이션 이름 = string

– 크기 : 15자 이내

– 데스티네이션의 이름을 설정한다. 생산자와 소비자는 이 이름을 사용하여 생성된다.

● SVGNAME = string

– 크기 : 15자 이내

– 데스티네이션이 존재하게 될 HMS 서버그룹 이름을 정의한다. 사용되는 SVGNAME은 SVRGROUP

절에서 정의한 HMS 서버그룹 이름이어야 한다.

● TYPE = TOPIC | QUEUE

데스티네이션의 타입을 설정한다. 현재 TOPIC과 QUEUE만 지원한다.

선택항목

● BOOT = WARM | (COLD)

– 해당 데스티네이션에 대해 기동할 때 복구할 메시지가 있을 경우 복구 여부를 설정한다.


– WARM으로 설정할 스토리지에 있는 처리되지 않은 메시지가 복구되며, COLD로 설정될 경우 기동

할 때 해당 메시지를 모두 지우고 시작한다.

– RQ와 마찬가지로 WARM과 COLD만 설정할 수 있으며 기본값은 COLD이다.

● GLOBAL = Y | (N)

– 클러스터링된 HMS의 같은 이름을 갖는 데스티네이션들을 논리적으로 하나의 데스티네이션으로 동

작하도록 설정한다.

– GLOBAL 설정을 하기 위해서는 SVRGROUP 절의 HMS 설정에 HMSPORT가 설정되어 있어야 한다.

– 큐에 대한 GLOBAL 설정을 하기위해서는 아래의 추가적인 설정이 필요하다.

● GQTHR = numeric

– 크기 : 0 ~ 65535

– 클러스터링된 큐가 유지하고자 하는 버퍼 크기를 결정하는 계수값을 설정한다.

– 버퍼의 크기는 소비자의 수 X GQTHR 값이다. 현재 큐의 길이가 버퍼 크기보다 작을 때 나눠줄 메시

지가 있는 클러스터링된 다른 큐로 부터 메시지를 가져온다. 버퍼의 크기보다 적은 메시지를 가지고

있을 때 메시지 분배 요청을 받으면 메시지를 나누어주지 않는다.

● GQMAXREQ = numeric

– 크기 : 1 ~ 65535

– 클러스터링된 큐가 다른 큐에게 메시지를 요청할 경우 한번에 요청할 수 있는 메시지의 수를 설정한

다.

– 값이 클 경우 적은 횟수로 필요한 메시지를 채울 수 있지만, 너무 클 경우 노드 사이에 불필요한 메시

지의 이동이 발생할 수 있으므로 너무 크지 않은 것이 좋다.

● GQFULL = numeric

– 크기 : 0 ~ 65535

– 클러스터링된 큐의 메시지 소비가 이루어지지 않거나 메시지가 불균형적으로 너무 많이 쌓일 경우를

대비해 설정한 수 이상의 메시지가 쌓일 경우 그 초과분에 한해 다른 노드의 클러스터링 큐에게 메시

지를 균등하게 나누어 준다.


2.2. 환경파일 예제간단한 HMS를 사용하는 환경파일 예제이다.

*DOMAIN

Domain1 SHMKEY=0x11936,

TMMLOGLVL = "DEBUG1",

CLHLOGLVL = "DEBUG1",

MINCLH = 1,

MAXCLH = 1,

TPORTNO = 7783,

MAXSESSION = 1024

*NODE

Node1 TMAXDIR = "/data/tmax",

APPDIR = "/data/tmax/appbin/",

MAXSESSION = 1024

*SVRGROUP

svghms NODENAME = "node1", CPC=1, SVGTYPE="HMS", RESTART=N,

OPENINFO = "ORACLE_XA+Acc=P/scott/tiger+SesTm=60+Threads=true",

HMSSUBSCFG = "/data/tmax/config/hmssubsconfig",

HMSNAME = "hms_ora", HMSSINDEX = 1,

HMSMSGLIVE = 1, HMSMAXTHR = 4, HMSMAXDBTHR = 10

*SERVER

…

*SERVICE

…

*HMS

queue1 SVGNAME = svghms,

TYPE = "QUEUE",

BOOT = "WARM",

GLOBAL = N

topic1 SVGNAME = svghms,

TYPE = "TOPIC",

BOOT = "WARM",

GLOBAL = N

아래는 HMSSUBSCFG에 설정한 config의 간단한 예제이다.

[TOPIC1]

Durable0:listener:


Durable1:listener:

Durable2:listener:


제3장 HMS API 함수

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

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), 소비자(Con

sumer), 메시지 등과 관련된 API들이 정의되어 있고, atmi.h에는 버퍼 관리 및 통신과 관련된 API들이 정

의되어 있으며, tmaxapi.h는 비표준 API의 프로토타입이 정의되어 있다.

HMS API는 크게 세션, 생산자(Producer), 소비자(Consumer), 메시지, 큐 브라우저 부분으로 나뉜다.

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

3.1.1. hms_create_session

HMS에 대한 세션을 생성하고 세션 핸들을 반환하는 함수이다. 세션 핸들을 이용하여 세션, 생산자(Pro

ducer), 소비자(Consumer), 메시지, 큐 브라우저를 생성할 수 있다. 세션을 생성할 때 로컬 트랜잭션 여부

와 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)

● 파라미터

제3장 HMS API 함수 17

설명파라미터

설정파일의 SVRGROUP 절에서 지정한 HMS에 해당하는 SVG 이름이다.hms

로컬 트랜잭션 여부이다.transacted

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

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

- HMS_AUTO_ACK : 내부적으로 각각의 메시지마다 ACK을 보내는 방식이

다.

ackmode

- HMS_DUPS_OK_ACK : 다수의 메시지를 받고 한꺼번에 ACK을 보내는 방

식이다. (현재 지원 안됨)

- HMS_CLIENT_ACK : 클라이언트가 직접 ACK을 보내주는 방식이다.

현재 사용되지 않는다.flags

● 반환값

설명반환값

함수 호출에 성공한 경우이다.생성된 세션 핸들에 대한

포인터

함수 호출에 실패한 경우이다.NULL

(tperrno에 상황에 해당하는 값이 설정된다. )

● 오류

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

설명에러 코드

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

나, ackmode가 유효하지 않은 값으로 설정되었다.

[TPEINVAL]

클라이언트에서 API를 사용할 때 발생가능하며, HMS 운영 시스템에 에러가

발생했다. 또는 환경변수 설정이 잘못 된 경우이다.

[TPEOS]

예를 들어 TMAX_HOST_ADDR나TMAX_HOST_PORT가 잘못 설정되어 연

결이 실패한 경우에 발생한다.

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

HMS에 연결된 세션의 수가 설정파일의 MAXSESSION에 도달하여 더이상

세션을 만들 수 없는 상태이다.

[TPELIMIT]

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


설명에러 코드

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

● 예제

...

#include <stdio.h>

#include <usrinc/atmi.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);


...

ret = hms_commit(session, 0);


...

hms_free(msg);

hms_close_consumer(cons, 0);


/* 세션을 종료함 */

ret = hms_close_session(session, 0);


...

}

● 관련함수

hms_close_session(), hms_create_producer(), hms_create_consumer(), hms_create_browser(),

hms_commit(), hms_rollback(), hms_recover()

3.1.2. hms_create_xa_session

HMS에 대한 XA 세션을 생성하여 핸들을 반환하는 함수이다. 이 세션으로 생성한 클라이언트(생산자

(Producer) 또는 소비자(Consumer))의 모든 메시지는 트랜잭션으로 처리된다. 트랜잭션 범위는 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()를 통해 연결을 할 필요가 없다.

● 프로토타입


HMS_SHND * hms_create_xa_session (char *hms, int flags)

● 파라미터

설명파라미터

설정파일에서 지정한 HMS에 해당하는 SVG 이름이다.hms


● 반환값

설명반환값


포인터



설명반환값


● 오류

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

설명에러 코드

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

클라이언트에서 API를 사용할 때 발생할 수 있다. HMS 운영 시스템에 에러

가 발생했다. 또는 환경변수 설정이 잘못 된 경우이다.

[TPEOS]






[TPELIMIT]



● 예제

...

#include <stdio.h>




{

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);



ret = tx_begin();


prod = hms_create_producer(session, dest, HMS_QUEUE, "producer_1", 0);

if (prod == NULL) { error processing }



...

ret = hms_set_body(msg, buf, size);


ret = hms_send(prod, msg, 0);


...

ret = tx_commit();


...

hms_free(msg);

hms_close_producer(prod, 0);




...

}

● 관련함수

hms_close_session()

3.1.3. hms_create_async_session

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

비동기 세션으로 소비자(Consumer)를 생성하고 메시지를 수신하기 위해서는 hms_recv()를 호출하는 대

신 메시지를 수신하고 이를 처리할 서비스를 지정해야 한다. 서비스명은 소비자(Consumer)를 생성할 때

지정할 수 있다. 비동기 세션을 통해 소비자(Consumer)를 생성할 때는 반드시 svcname을 지정하여 메시

지를 처리할 서비스를 지정해야 한다. 해당 서비스는 새로운 메시지가 데스티네이션으로 전송되면 즉시

해당 메시지를 수신하게 되며 이에 대한 처리를 수행하게 된다. 클라이언트나 서버 응용 프로그램 어느곳

에서든지 비동기 세션을 통한 소비자(Consumer)를 생성할 수 있다.

비동기 세션이 종료되거나 HMS에서 장애가 발생하는 경우에는 Abendfunc 콜백 함수가 실행된다. 사용

자는 이 함수를 정의하여 장애가 발생할 경우를 대비할 수 있다.

● 프로토타입



HMS_SHND * hms_create_async_session (char *hms, Abendfunc *func, int flags)

● 파라미터

설명파라미터

설정파일에서 지정한 HMS에 해당하는 SVG 이름이다.hms

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


● 반환값

설명반환값


포인터



● 오류

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

설명에러 코드

인수가 유효하지 않다.[TPEINVAL]

hms가 NULL이거나 지정된 문자열 길이를 초과했다.

클라이언트에서 API를 사용할 때 발생할 수 있다. HMS 운영 시스템에 에러

가 발생했다. 또는 환경변수 설정이 잘못 된 경우이다.

[TPEOS]






[TPELIMIT]



● 예제


...

#include <stdio.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;

}

}


{

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);



cons = hms_create_receiver(session, dest, "consumer_1", NULL, "MYSVC", 0);






...





...

hms_free(msg);





...

}

● 관련함수

hms_close_session()

3.1.4. hms_close_session

hms_create_session() 또는 hms_create_xa_session(), hms_create_async_session()으로 생성했던 세션

을 닫고, HMS 내에 할당되었던 자원을 반환한다. 세션이 더이상 필요하지 않을 경우 세션을 종료해야 한

다. 세션이 종료될 경우 해당 세션으로 생성되었던 모든 클라이언트(생산자와 소비자)들도 함께 종료된다.

● 프로토타입


int hms_close_session (HMS_SHND *sess, int flags)

● 파라미터

설명파라미터

닫고자 하는 세션 포인터이다.sess


● 반환값


설명반환값

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

함수 호출에 실패한 경우이다.-1


● 오류

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

설명에러 코드


sess 세션 포인터가 NULL이거나 올바르지 않는 포인터이다.



● 관련함수

hms_create_session(), hms_create_xa_session(), hms_create_async_session()

3.1.5. hms_unsubscribe_durable_subscriber

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

데스티네이션에 연결된 클라이언트 중에 영속적 구독자가 존재한다면 TOPIC 타입의 메시지는 모든 영속

적 구독자들이 메시지를 수신할 때까지 그 정보가 유지된다. 또한 영속적 구독자가 hms_unsub

scribe_durable_subscriber() API를 호출하지 않고 세션을 종료할지라도 클라이언트 정보(durable subscriber

의 이름)가 데스티네이션에 남아 있기 때문에, 다시 같은 이름의 영속적 구독자가 새로 세션을 생성하면,

소비자(Consumer)가 종료된 이후에 publish된 토픽 메시지들을 유실하지 않고 모두 수신할 수 있게 된다.

더이상 영속적 구독자가 토픽 타입의 메시지를 수신 할 필요가 없다면 API를 호출해주는 것이 좋다. 그렇

게 되면 이후에 들어온 메시지가 해당 영속적 구독자가 수신할 때까지 대기하지 않고 메모리에서 제거된

다.

● 프로토타입

# include <usrinc/hmsapi.h>

int hms_unsubscribe_durable_subscriber (HMS_SHND *sess, char *des, char *name,

int flags)

● 파라미터


설명파라미터

세션 포인터이다.sess

등록했던 데스티네이션의 이름이다.des

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

아직 사용되지 않는다.flags

● 반환값

설명반환값




● 오류

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

다.

설명에러 코드

인수가 유효하지 않다. sess이나 des가 NULL 이거나 des, name이 지정된

문자열 길이를 초과한 경우에 발생한다.

[TPEINVAL]

HMS와의 세션 연결이 종료되었다. 현재 세션을 hms_close_session()을 통

해 종료하고 새로운 세션으로 생성해서 다시 시도해야 한다.

[TPECLOSE]


타임아웃이 발생하였다.[TPETIME]

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

● 예제

#include <stdio.h>...

#include <stdio.h>




{

HMS_SHND *session;

HMS_CHND *cons;

hms_msg_t *msg;

...




/* durable_subscriber를 생성함 */

cons = hms_create_durable_subscriber(session, dest, "consumer_1", NULL, NULL,

0);


...



...

hms_free(msg);

ret = hms_close_durable_subscriber(cons, 0);


...

/* durable_subscriber에 대한 등록을 해제함 */

ret = hms_unsubscribe_durable_subscriber(session, dest, "consumer_1", 0);


...



...

}

● 관련함수

hms_create_durable_subscriber(), hms_close_durable_subscriber()

3.1.6. hms_commit

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

hms_create_session() API에서 transacted = 1로 설정하여 생성한 로컬 트랜잭션 모드의 세션에서만 사

용가능하다. 트랜잭션이 ROLLBACK_ONLY 상태라면 rollback된다. XA 세션에서는 tx_commit() API를

사용해야 한다. XA 세션과는 달리 트랜잭션의 시작을 명시적으로 선언하기 위한 tx_begin()과 같은 API는

호출할 필요가 없다.

● 프로토타입


int hms_commit (HMS_SHND *sess, int flags)

● 파라미터


설명파라미터

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


● 반환값

설명반환값




● 오류

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

설명에러 코드

인수가 유효하지 않다. sess 세션 포인터가 NULL이거나 올바르지 않는 포인

터이다.

[TPEINVAL]



[TPECLOSE]

hms_commit()이 부적절한 곳에서 호출되었다. 예를 들어, hms_create_ses

sion() 을 이용하여 세션을 생성할 때 transacted를 0으로 설정했을 경우 발생

한다.

[TPEPROTO]



hms_commit()이 호출되기 전에 메시지를 전송했던 생산자(Producer)나 소

비자(Consumer)가 종료되었다.

[TPENOENT]


● 예제

...

#include <stdio.h>




{

...







...







...

/* 지금까지의 트랜잭션 작업을 처리함 */



...

}

● 관련함수

hms_create_session(), hms_rollback()

3.1.7. hms_rollback

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

sion() API에서 transacted = 1로 설정하여 생성한 로컬 트랜잭션 모드의 세션에서만 사용가능하다. XA 세

션에서는 tx_rollback() API를 사용해야 한다.

● 프로토타입


int hms_rollback (HMS_SHND *sess, int flags)

● 파라미터

설명파라미터



● 반환값

설명반환값



설명반환값



3.1.8. hms_recover

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

세션이 생성될 때 hms_create_session() API에서 transacted = 0으로 설정해서 생성한 세션에서만 사용

가능하다.

소비자(Consumer)가 메시지를 수신받는 도중 장애가 발생하거나, 수신받은 메시지에 대한 ACK을 HMS

로 전달하지 않고 종료되었을 경우 다시 세션이 연결되었을 때 hms_recover() API를 호출함으로써 ACK

을 받지 못한 메시지에 대해서 다시 수신할 수 있게 된다.

● 프로토타입


int hms_recover (HMS_SHND *sess, int flags)

● 파라미터

설명파라미터



● 반환값

설명반환값




● 오류

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

설명에러 코드

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


설명에러 코드



[TPECLOSE]

hms_recover()가 부적절한 곳에서 호출되었다. 예를 들어, hms_create_ses

sion()을 이용하여 세션을 생성할 때 transacted 를 0이 아닌 값으로 설정하여

생성한 세션일 경우 발생한다.

[TPEPROTO]



hms_recover()가 호출되기 전에 메시지를 전송했던 생산자(Producer)나 소

비자(Consumer)가 종료되었다.

[TPENOENT]


● 예제

...

#include <stdio.h>




{

...

/* 세션을 생성함 */

session = hms_create_session(hms, 0, HMS_CLIENT_ACK, 0);



0);


...

/* HMS로부터 메시지를 수신함 */









...

if ( condition ) {

ret = hms_ack(msg, HMS_ACK_ONE);


} else {


ret = hms_recover(session, 0);


}

...

}

● 관련함수

hms_create_session()

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

3.2.1. hms_alloc

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

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

지 버퍼를 해제해서는 안된다.

메시지 버퍼는 프로퍼티와 Body로 구성되어 있으며 hms_set_property(), hms_set_body()등의 API를 사

용하여 메시지 버퍼에 정보를 저장할 수 있다. 프로퍼티는 메시지에 대한 기본적인 정보와 클라이언트가

메시지 셀렉터를 통해 메시지를 선별하여 가져오고자 할 때 그 기준을 제공한다. 프로퍼티는 Name-Value

쌍의 정보로 구성되며 복수 개의 프로퍼티를 가질 수 있다. Body는 메시지의 주요 컨텐츠를 저장한다. 자

세한 정보는 각 API 레퍼런스를 참고한다.

● 프로토타입


hms_msg_t * hms_alloc (HMS_SHND *sess, long size)

● 파라미터

설명파라미터

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

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

● 반환값

설명반환값

함수 호출에 성공한 경우이다.할당된 메시지 버퍼의 포인터



설명반환값


● 오류

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

설명에러 코드

sess 포인터가 NULL이다.[TPEINVAL]

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

● 예제

...

#include <stdio.h>




{

HMS_SHND *session;

HMS_CHND *cons;

hms_msg_t *msg;

long size;

...

/* 일반 모드의 세션을 생성함 */




0);


/* 메시지 버퍼를 할당함 */

size = 1024;









...




...

/* 메시지 버퍼를 해제함 */

hms_free(msg);




...

}

● 관련함수

hms_free()

3.2.2. hms_free

메시지 버퍼에 할당된 메모리를 해제하는 함수이다. hms_alloc()을 통해 할당받은 메시지 버퍼는 필요하

지 않을 경우 반드시 API를 통해 해제해야 한다. 메시지 버퍼를 free()로 해제해서는 안되며, 이미 해제된

메시지 버퍼를 다시 해제할 경우 그 결과는 알 수 없다.

● 프로토타입


void hms_free (hms_msg_t * msg)

● 파라미터

설명파라미터

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

● 반환값

반환값은 없다.

● 예제

...

#include <stdio.h>




{

HMS_SHND *session;


HMS_CHND *cons;

hms_msg_t *msg;

...





0);











...



...


hms_free(msg);




...

}

● 관련함수

hms_alloc()

3.2.3. hms_get_property

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

있을 경우 타입(type), 값(value), 크기(len)를 가져온다. 존재하지 않을 경우에는 -1을 반환하고 tperrno는

TPENOENT로 설정된다. 데이터를 저장할 버퍼(value)는 미리 할당(또는 선언)되어 있어야 하며 버퍼의

크기가 함께 전달되어야 한다. 수신받은 데이터가 버퍼의 크기보다 클 경우 TPEINVAL 오류가 발생한다.


프로퍼티는 Name-Value 쌍으로 구성되며 하나의 메시지 버퍼에서 Name은 유일하다. 따라서 이미 존재

하는 Name에 대해서 다시 hms_set_property()를 통해 Value를 저장하면 기존의 Value는 새로운 Value로

대체된다. 프로퍼티는 메시지를 hms_send()를 통해 데스티네이션으로 전송하기 전과 hms_recv()를 통해

데스티네이션에서 수신받은 후에도 설정할 수 있다. 이를 통해 수신된 메시지를 가공하여 다시 전달할 수

있다.

프로퍼티는 메시지를 수신받는 소비자(Consumer)가 메시지 셀렉터를 이용하여 메시지를 선택적으로 수

신받고자 할 때 그 기준으로 사용된다. 메시지 셀렉터는 소비자(Consumer)를 생성할 때 설정할 수 있으며

자세한 정보는 hms_create_consumer() API를 참조한다.

내부적으로 쓰이는 reserved된 이름들에 대해서는 매크로가 제공되고 있으며, 다음과 같은 예약된 프로퍼

티들은 hmsapi.h에 정의되어 있다. 예약된 이름의 프로퍼티를 사용자가 임의로 수정해서는 안된다.

● Reserved Property

설명프로퍼티

데스티네이션의 이름이다.HMSDestination

("$Destination")

Non-persistent 또는 Persistent이다.HMSDeliveryMode

("$DeliveryMode")

데스티네이션으로 수신 성공한 경우 HMS가 발급한 MSGID이다.HMSMessageID

("$MessageID")

데스티네이션으로 enqueue된 시간이다.HMSTimeStamp

("$TimeStamp")

장애 발생 후 메시지가 재전송 되었을 가능성 여부이다.HMSRedelivered

("$Redelivered")

● 프로토타입


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

● 반환값

설명반환값




● 오류

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

설명에러 코드

인수가 유효하지 않다. msg나 name, value가 NULL이거나 msg 포인터가 올

바르지 않을 경우, 또는 len이 가져올 프로퍼티의 길이보다 작을 경우에 발생

한다.

[TPEINVAL]


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

● 예제

...

#include <stdio.h>




{

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()에 사용 */





0);







ret = hms_get_property(msg, HMSDestination, &type, buf, &len);


ret = hms_get_property(msg, HMSDestination, &type, &myval, sizeof(int));


...



...


hms_free(msg);




...

}

● 관련함수

hms_set_property(), hms_alloc(), hms_free()

3.2.4. hms_set_property

해당하는 이름으로 메시지에 프로퍼티를 설정하기 위한 함수이다. 이미 해당하는 이름의 프로퍼티가 존

재한다면 새로운 값으로 변경된다. 프로퍼티로 설정할 수 있는 타입은 필드버퍼에서 지원하는 타입과 동

일하다.

프로퍼티는 Name-Value 쌍으로 구성되며 하나의 메시지 버퍼에서 Name은 유일하다. 따라서 이미 존재

하는 Name에 대해서 다시 hms_set_property()를 통해 Value를 저장하면 기존의 Value는 새로운 Value로


대체된다. 프로퍼티는 메시지를 hms_send()를 통해 데스티네이션으로 전송하기 전과 hms_recv()를 통해

데스티네이션에서 수신받은 후에도 설정할 수 있다. 이를 통해 수신된 메시지를 가공하여 다시 전달할 수

있다.

프로퍼티는 메시지를 수신받는 소비자(Consumer)가 메시지 셀렉터를 이용하여 메시지를 선택적으로 수

신받고자 할 때 그 기준으로 사용된다. 메시지 셀렉터에 대한 자세한 정보는 hms_create_consumer() API

를 참고한다.

사용자는 내부적으로 쓰이는 reserved된 이름의 프로퍼티에는 값을 설정할 수 없다.

다음에 명시된 이름 이외에 다른 reserved 이름은 hmsapi.h에 정의되어 있다.

$Destination", "$DeliveryMode", "$MessageID", "$TimeStamp", "$CorrelationID", "$ReplyTo", "$Redeliv

ered", "$Type", "$Expiration", "$Priority"

● 프로토타입


int hms_set_property (hms_msg_t * msg, char *name, int type, char *value,

long len)

● 파라미터

설명파라미터

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

설정할 프로퍼티의 이름이다.name

(내부적으로 쓰이는 reserved된 이름은 사용 불가)

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

HMS_CHAR, HMS_SHORT, HMS_INT, HMS_LONG, HMS_FLOAT,

HMS_DOUBLE, HMS_STRING, HMS_CARRAY

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

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

● 반환값

설명반환값





● 오류

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

설명에러 코드


msg나 name, value가 NULL이거나 msg 포인터가 올바르지 않을 경우, 또는

len이 음수일 경우, name이 예약된 프로퍼티일 경우, msg에 프로퍼티를 설

정할만한 충분한 메모리 공간이 없는 경우 등에 발생한다.

● 예제

...

#include <stdio.h>




{

char buf[256];

...

if (argc != 2 ) return 1;

strncpy(buf, argv[1], 255);






...



ret = hms_set_property(msg, "NAME", HMS_STRING, buf, strlen(buf));




...




...

}

● 관련함수


hms_get_property(), hms_alloc(), hms_free()

3.2.5. hms_get_body

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

데이터를 가져오는 버퍼는 tpalloc()으로 할당된 버퍼이어야 한다. 데이터를 저장할 버퍼는 미리 할당되어

있어야 하며 버퍼의 크기가 함께 전달되어야 한다. 수신받은 데이터가 버퍼의 크기보다 클 경우 TPEINVAL

오류가 발생한다.

● 프로토타입


int hms_get_body (hms_msg_t *msg, char *data, long *len)

● 파라미터

설명파라미터

메시지 포인터이다.msg

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

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

● 반환값

설명반환값




● 오류

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

설명에러 코드

인수가 유효하지 않다. msg나 data, len 포인터가 NULL이거나 msg 포인터

가 올바르지 않을 경우, 또는 len이 메시지의 데이터 크기보다 작을 경우에

발생한다.

[TPEINVAL]

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

● 예제


...

#include <stdio.h>




{

HMS_SHND *session;

HMS_CHND *cons;

hms_msg_t *msg;

char *buf;

...





0);







/* 메시지 데이터를 가져온다. */





...



...


hms_free(msg);




...

}

● 관련함수

hms_set_body()


3.2.6. hms_set_body

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

의 버퍼는 tpalloc()으로 할당된 버퍼이어야 한다. Body는 프로퍼티와는 달리 Type을 가지고 있지 않으며

CARRAY 타입으로 len에 지정된 길이만큼 정보를 저장하게 된다.

● 프로토타입


int hms_set_body (hms_msg_t *msg, char *data, long len)

● 파라미터

설명파라미터

메시지 포인터이다.msg

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

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

● 반환값

설명반환값




● 오류

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

설명에러 코드


msg나 data가 NULL이거나 msg 포인터가 올바르지 않을 경우, 또는 len이

음수일 경우, msg에 데이터를 설정할만한 충분한 메모리 공간이 없는 경우

등에 발생한다.

● 예제

...

#include <stdio.h>





{

HMS_SHND *session;

HMS_PHND *prod;

hms_msg_t *msg;

char *buf;

...

if (argc !=2 )

return 1;






...



/* 메시지 데이터를 설정한다. */



strcpy(buf, argv[1]);

ret = hms_set_body(msg, buf, strlen(buf));




...




...

}

● 관련함수

hms_get_body()

3.2.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처리가 된다.

● 프로토타입


int hms_ack (hms_msg_t *msg, int flags)

● 파라미터

설명파라미터

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

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

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

● 반환값

설명반환값




● 오류

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

설명에러 코드


flags에 유효한 값이 설정되지 않거나 HMS_ACK_ONE와 HMS_ACK_UP

THROUGH를 같이 설정한 경우에 발생한다.


설명에러 코드




[TPECLOSE]

hms_ack()가 부적절한 상황에서 호출되었다.[TPEPROTO]

예를 들어, XA세션이나 트랜젹션을 지원하는 세션에서 호출되었거나, ack

mode가 HMS_DUPS_OK_ACK, HMS_CLIENT_ACK이 아닌 세션에서 호출

되었다.

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

● 예제

...

#include <stdio.h>




{

HMS_SHND *session;

HMS_CHND *cons;

hms_msg_t *msg;

...


session = hms_create_session(hms, 0, HMS_CLIENT_ACK, 0);



0);










/* 수신받은 메시지에 대한 ACK을 전송함 */

ret = hms_ack(msg, HMS_ACK_ONE)



...

hms_free(msg);




...

}

● 관련함수

hms_recvex(), hms_recv()

3.3. 생산자(Producer) API생산자 API는 토픽, 큐 타입의 생산자를 생성하고 종료하기 위한 API들로 구성된다.

3.3.1. hms_create_producer

데스티네이션으로 메시지를 전송하기 위해 생산자를 생성하고, 그 생산자에 대한 핸들을 반환하는 함수

이다.

데스티네이션은 관리자에 의해 생성된 가상 채널로, 메시지를 생성하고 전송할 때 목적지이며, 또한 메시

지를 수신받고자 할 때 메시지를 제공해주는 소스를 지칭한다. 데스티네이션은 2가지 종류로 구분된다.

point-to-point 방식의 메시지를 지원하는 큐 방식과 publish-and-subscribe 방식으로 메시지 전달을 지원

해주는 토픽 방식이 있다. 한 응용 프로그램 내에서 이 2가지 방식의 메시지를 모두 처리할 수 있다.

생산자를 생성하기 위해서는 먼저 세션이 생성되어 있어야 한다. 생산자가 생성되면 hms_send() API를

사용하여 데스티네이션으로 메시지를 전송할 수 있다. 생산자는 큐 타입 또는 토픽 타입의 데스티네이션

에 메시지를 전송함으로써 해당 데스티네이션에 접근한 다른 소비자(Consumer)들이 해당 메시지를 수신

할 수 있게 된다.

● 프로토타입


HMS_PHND * hms_create_producer (HMS_SHND *sess, char *des, int destype,

char *name, int flags)

● 파라미터

설명파라미터

메시지 전달에 사용하고자 하는 세션 포인터이다.sess

메시지를 전달할 데스티네이션의 이름이다.des

데스티네이션의 타입, 반드시 데스티네이션의 타입과 일치해야 한다.destype


설명파라미터

- HMS_QUEUE

- HMS_TOPIC

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


● 반환값

설명반환값

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



● 오류

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

설명에러 코드


sess 세션 포인터가 NULL이거나 des 이름이 지정되지 않은 경우, 또는 des

나 name이 각각 지정된 길이를 초과한 경우, 또는 destype이 유효하지 않은

값으로 설정된 경우 발생한다.



[TPECLOSE]


메시지를 전송할 데스티네이션이 존재하지 않거나 활성화 되지 않은 데스티

네이션일 경우에 발생한다.

[TPENOENT]

데스티네이션의 타입과 생성하고자 하는 생산자의 데스티네이션의 타입이

일치하지 않는다.

[TPEITYPE]

HMS 또는 운영 시스템에 에러가 발생하였다.[TPEOS]

예를 들어, 내부적으로 사용하는 버퍼의 메모리 할당이 실패한 경우이다.

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


● 예제




{

HMS_SHND *session;

HMS_PHND *prod;

hms_msg_t *msg;

...



/* QUEUE 타입의 생산자(Producer)를 생성함 */





...





...

hms_free(msg);




...

}

● 관련함수

hms_close_producer()

3.3.2. hms_create_sender

큐 타입의 데스티네이션에 메시지를 전송할 sender를 생성하기 위한 함수이다. 동작방식은 hms_create_pro

ducer()와 동일하다.

● 프로토타입


HMS_PHND * hms_create_sender (HMS_SHND *sess, char *des, char *name, int flags)

● 파라미터


설명파라미터





● 반환값

설명반환값

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



● 오류

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

설명에러 코드



나 name이 각각 지정된 길이를 초과한 경우에 발생한다.



[TPECLOSE]




[TPENOENT]



[TPEITYPE]



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


● 예제




{

HMS_SHND *session;

HMS_PHND *prod;

hms_msg_t *msg;

...



/* QUEUE 타입의 생산자(Producer)를 생성함 */

prod = hms_create_sender(session, dest, "producer_1", 0);




...





...

hms_free(msg);

hms_close_sender(prod, 0);




...

}

● 관련함수

hms_close_sender()

3.3.3. hms_create_publisher

토픽 타입의 데스티네이션에 메시지를 전송할 publisher를 생성하는 함수이다. 동작방식은 hms_create_pro

ducer()와 동일하다.

● 프로토타입


HMS_PHND * hms_create_publisher (HMS_SHND *sess, char *des, char *name, int flags)

● 파라미터


설명파라미터





● 반환값

설명반환값

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



● 오류

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

설명에러 코드



나 name이 각각 지정된 길이를 초과한 경우에 발생한다.



[TPECLOSE]




[TPENOENT]



[TPEITYPE]



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


● 예제




{

HMS_SHND *session;

HMS_PHND *prod;

hms_msg_t *msg;

...



/* TOPIC 타입의 생산자(Producer)를 생성함 */

prod = hms_create_publisher(session, dest, "producer_1", 0);




...





...

hms_free(msg);

hms_close_publisher(prod, 0);




...

}

● 관련함수

hms_close_publisher()

3.3.4. hms_close_producer

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

● 프로토타입


int hms_close_producer (HMS_PHND *prod, int flags)

● 파라미터


설명파라미터

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


● 반환값

설명반환값




● 오류

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

설명에러 코드

인수가 유효하지 않다. prod 포인터가 NULL이거나 올바르지 않는 포인터이

다.

[TPEINVAL]




[TPECLOSE]


● 관련함수

hms_create_producer()

3.3.5. hms_close_sender

QUEUE 타입의 sender를 닫고, 할당되었던 자원을 반환하는 함수이다. 동작은 hms_close_producer()와

동일하다.

● 프로토타입


int hms_close_sender (HMS_PHND *prod, int flags)

● 파라미터


설명파라미터



● 반환값

설명반환값




● 오류

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

설명에러 코드

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




[TPECLOSE]


● 관련함수

hms_create_sender()

3.3.6. hms_close_publisher

토픽 타입의 publisher를 닫고, 할당되었던 자원을 반환하는 함수이다. 동작은 hms_close_producer()와

동일하다.

● 프로토타입


int hms_close_publisher (HMS_PHND *prod, int flags)

● 파라미터

설명파라미터



설명파라미터


● 반환값

설명반환값




● 오류

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

설명에러 코드

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




[TPECLOSE]


● 관련함수

hms_create_publisher()

3.3.7. hms_sendex

생산자(Producer)를 생성할 때 지정한 데스티네이션으로 메시지를 전송한다.

전송방식에는 persistent mode와 non-persistent mode가 존재한다.

persistent mode의 경우 전송된 메시지는 데이터베이스에 저장된다. HMS에 장애가 발생할 경우 데스티

네이션에 전송되었던 메시지들을 온전하게 복구 할 수 있다. 해당 메시지를 소비자(Consumer)가 수신해

간다면 데이터베이스에 저장되었던 persistent mode의 메시지는 이후 일정시간이 지나면 데이터베이스

에서 삭제된다. 수신된 메시지가 데이터베이스에서 삭제되는 시간은 설정파일에서 지정할 수 있다.

메시지가 데스티네이션내에서 스케쥴링되는 우선순위나 유효시간을 지정해서 전송할 수도 있다. 유효시

간이 지나도 소비자(Consumer)에 의해 메시지가 수신되지 않으면 해당 메시지는 폐기되며, 이후 메시지

수신 요청이 들어와도 해당 메시지를 수신할 수 없게 된다.


성공적으로 전송이 되면 해당 메시지에 메시지 ID와 전송/응답시간의 차가 각각 HMSMessageID, HM

STimeStamp의 이름의 프로퍼티가 설정된다.

● 프로토타입


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

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


● 반환값

설명반환값




● 오류

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

설명에러 코드


prod 또는 msg가 NULL이거나 ttl이 0보다 작은 경우, dlvmode가 유효하지 않

은 값으로 설정된 경우 또는 성공적으로 전송된 이후 해당 msg의 size가 작

아서 추가적인 프로퍼티를 설정할 수 없을 경우에 발생한다.



설명에러 코드



[TPECLOSE]




hms_sendex()가 부적절한 곳에서 호출되었다.[TPEPROTO]

이미 종료된 생산자(Producer)를 사용해 메시지를 전송하였다.[TPENOENT]


● 예제



{

HMS_SHND *session;

HMS_PHND *prod;

hms_msg_t *msg;

...








...



/* PERSISTENT 메시지를 destination으로 전송함 */

ret = hms_sendex(prod, msg, HMS_DLV_PERSISTENT, 0, 60, 0);


...

hms_free(msg);





...

}


● 관련함수

hms_send()

3.3.8. hms_send

기본적인 설정만으로 메시지를 전송한다. 전송모드는 non-persistent 이며, 우선순위와 유효시간은 설정

하지 않고 전송한다. 그외 동작방식은 hms_sendex()와 동일하다.

● 프로토타입


int hms_send (HMS_PHND *prod, hms_msg_t *msg, int flags)

● 파라미터

설명파라미터

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

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


● 반환값

설명반환값

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

메시지 전송이 실패한 경우이다.-1


● 오류

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

설명에러 코드


prod 또는 msg가 NULL이거나 ttl이 0보다 작은 경우, dlvmode가 유효하지 않

은 값으로 설정된 경우 또는 성공적으로 전송된 이후 해당 msg의 size가 작

아서 추가적인 프로퍼티를 설정할 수 없을 경우에 발생한다.



설명에러 코드



[TPECLOSE]




hms_sendex()가 부적절한 곳에서 호출되었다.[TPEPROTO]

이미 종료된 생산자(Producer)를 사용해 메시지를 전송하였다.[TPENOENT]


● 예제



{

HMS_SHND *session;

HMS_PHND *prod;

hms_msg_t *msg;

...










/* 메시지를 destination으로 전송함 */



...

hms_free(msg);





...

}


● 관련함수

hms_sendex()

3.4. 소비자(Consumer) API소비자 API는 토픽, 큐 타입의 소비자를 생성하고 종료하기 위한 API들로 구성된다.

3.4.1. hms_create_consumer

데스티네이션으로부터 메시지를 수신할 소비자를 생성하고, 그 소비자에 대한 핸들을 반환하는 함수이다.

메시지 셀렉터를 설정하면 조건에 맞는 메시지를 필터링하여 수신할 수 있다.

비동기 세션에서는 생산자로부터 메시지가 전송될 때 즉시 해당 메시지를 수신 받아 처리할 서비스를 지

정할 수 있다. 비동기 세션에서 소비자를 생성할 때는 반드시 svcname을 지정해야 한다. 반대로 비동기

세션이 아닌 세션에서 소비자를 생성할 때는 svcname을 지정하면 안된다.

또한 클라이언트는 메시지 셀렉터를 설정함으로써 해당 조건을 충족하는 메시지만을 수신할 수 있다. 메

시지 셀렉터에 관한 보다 자세한 설명은 “Appendix A. 메시지 셀렉터 사용하기”를 참고한다.

● 프로토타입


HMS_CHND * hms_create_consumer (HMS_SHND *sess, char *des, int destype,

char *name, char *msgselector, char *svcname, int flags)

● 파라미터

설명파라미터

메시지 수신에 사용하고자 하는 세션 포인터이다.sess

메시지를 수신할 데스티네이션의 이름이다.des

데스티네이션의 타입이다.destype

- HMS_QUEUE

- HMS_TOPIC

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

메시지 셀렉터 문장이다.msgselector

비동기 세션에서 메시지를 수신할 서비스명이다. (비동기 세션에서 생성시

반드시 설정해야 함)

svcname



● 반환값

설명반환값

함수 호출에 성공한 경우이다.소비자(Consumer)의 핸

들



● 오류

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

설명에러 코드


sess이나 des가 NULL일 경우, 또는 des나 name, msgselector, svcname 등

이 지정된 길이를 초과할 경우, 또는 비동기 세션에서 svcname이 지정되지

않은 경우, 또는 destype에 유효하지 않은 값이 설정된 경우에 발생한다.



[TPECLOSE]

hms_create_consumer()가 부적절한 곳에서 호출되었다.[TPEPROTO]

예를 들어, 비동기 세션에서 이미 svcname을 사용하는 다른 소비자가 생성

되어 있는 경우, 또는 비동기 세션이 아님에도 불구하고 svcname이 설정되

어 있는 경우, 또는 durable subscriber를 생성하면서 소비자 이름을 지정하

지 않을 경우에 발생한다.


메시지를 수신할 데스티네이션이 존재하지 않거나 활성화 되지 않은 데스티


[TPENOENT]

데스티네이션의 타입과 생성하고자 하는 소비자의 데스티네이션의 타입이


[TPEITYPE]



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


● 예제


...

#include <stdio.h>




{

HMS_SHND *session;

HMS_CHND *cons;

hms_msg_t *msg;

...



/* QUEUE 타입의 소비자(Consumer)를 생성함 */


0);


...



...

hms_free(msg);

/* 소비자(Consumer)를 종료함 */




...

}

● 관련함수

hms_close_consumer()

3.4.2. hms_create_receiver

타입이 Queue인 데스티네이션으로부터 수신할 receiver를 생성한다. 동작방식은 hms_create_consumer()

와 동일하다.

● 프로토타입



HMS_CHND * hms_create_receiver (HMS_SHND *sess, char *des, char *name,

char *msgselector, char *svcname, int flags)

● 파라미터

설명파라미터







svcname


● 반환값

설명반환값


들러



● 오류

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

설명에러 코드




않은 경우 발생한다.



[TPECLOSE]

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




[TPENOENT]


설명에러 코드

데스티네이션의 타입과 생성하고자 하는 receiver의 데스티네이션의 타입이


[TPEITYPE]



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


● 예제

...

#include <stdio.h>




{

HMS_SHND *session;

HMS_CHND *cons;

hms_msg_t *msg;

...



/* QUEUE 타입의 receiver를 생성함 */

cons = hms_create_receiver(session, dest, "consumer_1", NULL, NULL, 0);


...



...

hms_free(msg);

/* receiver를 종료함 */

hms_close_receiver(cons, 0);



...

}

● 관련함수

hms_close_receiver()


3.4.3. hms_create_subscriber

타입이 토픽인 데스티네이션으로부터 수신할 subscriber를 생성한다. 동작방식은 hms_create_consumer()

와 동일하다.

● 프로토타입


HMS_CHND * hms_create_subscriber (HMS_SHND *sess, char *des, char *name,


● 파라미터

설명파라미터







svcname


● 반환값

설명반환값


들러



● 오류

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

설명에러 코드






설명에러 코드



[TPECLOSE]





[TPENOENT]

데스티네이션의 타입과 생성하고자 하는 소비자의 데스티네이션의 타입이


[TPEITYPE]



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


● 예제

...

#include <stdio.h>




{

HMS_SHND *session;

HMS_CHND *cons;

hms_msg_t *msg;

...



/* TOPIC 타입의 subscriber를 생성함 */

cons = hms_create_subscriber(session, dest, "consumer_1", NULL, NULL, 0);


...



...

hms_free(msg);

/* subscriber를 종료함 */

hms_close_subscriber(cons, 0);




...

}

● 관련함수

hms_close_subscriber()

3.4.4. hms_create_durable_subscriber

타입이 토픽인 데스티네이션으로부터 수신할 영속적 구독자를 생성한다. 영속적 구독자는 메시지 수신에

대한 신뢰성을 보장하여, 영속적 구독자가 메시지를 정상적으로 수신할 때까지 HMS는 해당 메시지를 유

지한다. HMS는 영속적 구독자을 이름으로 구별하므로 각 영속적 구독자는 반드시 유일한 이름을 사용해

야 한다.

또한 hms_close_durable_subscriber와는 별도로 등록을 해제하는 unsubscribe 과정이 반드시 필요하다.

unsubscribe를 하지 않으면 영속적 구독자가 close된 이후에도 메시지는 다음에 해당 subscriber에 의해

수신될 때까지 정보를 유지하기 때문에 더이상 subscribe를 할 필요가 없다면 unsubscribe를 해야 한다.

● 프로토타입


HMS_CHND * hms_create_durable_subscriber (HMS_SHND *sess, char *des, char *name,


● 파라미터

설명파라미터







svcname


● 반환값

설명반환값

함수 호출에 성공한 경우이다.소비자의 핸들



설명반환값


● 오류

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

설명에러 코드







[TPECLOSE]





[TPENOENT]

데스티네이션의 타입과 생성하고자 하는 subscriber의 데스티네이션의 타입

이 일치하지 않는다.

[TPEITYPE]



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


● 예제

...

#include <stdio.h>




{

HMS_SHND *session;

HMS_CHND *cons;

hms_msg_t *msg;

...






0);


...



...

hms_free(msg);

/* durable_subscriber를 종료함 */



ret = hms_close_consumer(cons, 0);




...

}

● 관련함수

hms_close_durable_subscriber()

3.4.5. hms_close_consumer

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

● 프로토타입


int hms_close_consumer (HMS_CHND *cons, int flags)

● 파라미터

설명파라미터

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


● 반환값


설명반환값




● 오류

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

설명에러 코드


cons가 NULL이다.




[TPECLOSE]


● 관련함수

hms_create_consumer()

3.4.6. hms_close_receiver

큐 타입의 수신기를 닫고, 할당되었던 자원을 반환하는 함수이다. 동작방식은 hms_close_consumer()와

동일하다.

● 프로토타입


int hms_close_receiver (HMS_CHND *cons, int flags)

● 파라미터

설명파라미터



● 반환값


설명반환값




● 오류

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

설명에러 코드

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




[TPECLOSE]


● 관련함수

hms_create_receiver()

3.4.7. hms_close_subscriber

토픽 타입의 subscriber를 닫고, 할당되었던 자원을 반환한다. 동작방식은 hms_close_consumer()와 동일

하다.

● 프로토타입


int hms_close_subscriber (HMS_CHND *cons, int flags)

● 파라미터

설명파라미터



● 반환값

설명반환값



설명반환값



● 오류

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

설명에러 코드





[TPECLOSE]


● 관련함수

hms_create_subscriber()

3.4.8. hms_close_durable_subscriber

영속적 구독자를 닫고, 할당되었던 자원을 반환한다. 동작방식은 hms_close_consumer()와 동일하다.

추후에 hms_unsubscribe_durable_subscriber()를 통해 unsubscribe과정이 필요하다. 만일 unsubscribe

를 하지 않는다면 해당 영속적 구독자가 수신하지 않은 모든 메시지들은 해당 subscriber가 수신할 때까지

또는 unsubscribe를 수행할 때까지 메모리에서 제거되지 않고 수신을 기다린다.

● 프로토타입


int hms_close_durable_subscriber (HMS_CHND *cons, int flags)

● 파라미터

설명파라미터



● 반환값


설명반환값




● 오류

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

설명에러 코드





[TPECLOSE]


● 예제

#include <stdio.h>...

#include <stdio.h>




{

HMS_SHND *session;

HMS_CHND *cons;

hms_msg_t *msg;

...





0);


...



...

hms_free(msg);


/* durable_subscriber를 종료함 */

ret = hms_close_consumer(cons, 0);


...



...



...

}

● 관련함수

hms_create_durable_subscriber()

3.4.9. hms_recvex

데스티네이션으로부터 메시지를 수신한다. 타임아웃을 설정할 수 있으며 0으로 설정하면 메시지가 도착

할때까지 기다린다. 소비자를 생성할 때 메시지 셀렉터를 설정했다면, 그 기준에 부합되는 메시지들만 선

택적으로 수신할 수 있다. 메시지를 수신받기 위해서는 hms_alloc() API를 통해 메시지 버퍼를 미리 생성

해야 한다.

● 프로토타입


int hms_recvex (HMS_CHND * cons, hms_msg_t **msg, long timeout, int flags)

● 파라미터

설명파라미터

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

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

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


● 반환값

설명반환값





● 오류

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

설명에러 코드

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




[TPECLOSE]

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

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


이미 종료된 소비자를 사용해 메시지를 전송하였다. 세션이 종료되면서 세션

으로 생성되었던 생산자와 소비자가 종료되었을 수 있다.

[TPENOENT]


● 예제

...

#include <stdio.h>




{

HMS_SHND *session;

HMS_CHND *cons;

hms_msg_t *msg;

...





0);




/* 메시지 수신 (timeout 20초 설정) */

ret = hms_recvex(cons, &msg, 20, 0);





...


hms_free(msg);




...

}

● 관련함수

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

ate_durable_subscriber(), hms_ack(), hms_commit(), hms_rollback()

3.4.10. hms_recv

데스티네이션으로부터 메시지가 도착할 때까지 기다린다.(timeout = 0) 동작방식은 hms_recvex()와 동일

하다.

● 프로토타입


int hms_recvex (HMS_CHND * cons, hms_msg_t **msg, int flags)

● 파라미터

설명파라미터

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

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


● 반환값

설명반환값




● 오류

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


설명에러 코드

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




[TPECLOSE]

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

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


이미 종료된 소비자를 사용해 메시지를 전송하였다. 세션이 종료되면서 세션

으로 생성되었던 생산자와 소비자가 종료되었을 수 있다.

[TPENOENT]


● 예제

...

#include <stdio.h>




{

HMS_SHND *session;

HMS_CHND *cons;

hms_msg_t *msg;

...





0);




/* 메시지 수신 */





...


hms_free(msg);





...

}

● 관련함수

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

ate_durable_subscriber(), hms_ack(), hms_commit(), hms_rollback()

3.5. 큐 브라우저 API큐 브라우저 API는 큐 브라우저의 생성과 종료, 메시지 조회 등을 위한 API들로 구성된다.

3.5.1. hms_create_browser

현재 데스티네이션에 존재하는 메시지를 조회할 수 있는 큐 브라우저를 생성하고, 해당 브라우저의 핸들

을 반환한다. 큐 타입의 데스티네이션에 대해서만 생성이 가능하다. 브라우저를 생성할 때 메시지 셀렉터

를 설정하여 조건에 맞는 메시지만을 조회할 수 있다.

● 프로토타입


HMS_BHND * hms_create_browser (HMS_SHND *sess, char *queue, char *msgselector,

int flags)

● 파라미터

설명파라미터

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

조회할 큐의 이름이다.queue


- HMS_QB_FIRST : 데스티네이션에 있는 수신 가능한 메시지를 전송된 순

서대로 조회한다.

flags

- 0(기본값) : 데스티네이션에 있는 메시지 중 가장 최근에 전송된 메시지부터

조회한다.

● 반환값


설명반환값

함수 호출에 성공한 경우이다.브라우저에 대한 핸들 포

인터



● 오류

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

설명에러 코드

인수가 유효하지 않다. sess이나 queue가 NULL일 경우, 또는 queue나 msgs

elector가 지정된 길이를 초과할 경우에 발생한다.

[TPEINVAL]



[TPECLOSE]




[TPENOENT]

queue로 전달한 데스티네이션이 큐 타입이 아니다.[TPEITYPE]

HMS 또는 운영 시스템에 에러가 발생하였다. 예를 들어, 내부적으로 사용하

는 버퍼의 메모리 할당이 실패한 경우이다.

[TPEOS]


● 예제

...

#include <stdio.h>




{

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);



/* Queue Browser 생성하기 */

browser = hms_create_browser(session, "queue1",

"HMSType = 'cat' AND weight < 3"), 0);

if (brow == NULL) { error processing }

...

msg = hms_alloc(session, 1024);




/* Queue browser를 통해 메시지 데이터를 가져온다. */

hms_browser_nextmsg(browser, &msg, 0);

if (ret == -1) { error processing }

ret = hms_get_body(msg, buf, strlen(buf));


else

printf("message : %s\n", buf);

...

/* Queue Browser 종료하기 */

ret = hms_close_browser(browser, 0);




...

}

● 관련함수

hms_close_browser()

3.5.2. hms_close_browser

큐 브라우저를 닫고, 할당되었던 자원을 반환하는 함수이다.

● 프로토타입


int hms_close_browser (HMS_BHND *browser, int flags)

● 파라미터

설명파라미터

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



● 반환값

설명반환값




● 오류

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

설명에러 코드

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




[TPECLOSE]


● 예제

...

#include <stdio.h>




{

HMS_SHND *session;

HMS_BHND *browser;

hms_msg_t *msg;

char buf[100];

long len = 100;

...






...



...

/* Queue browser 종료하기 */






...

}

● 관련함수

hms_create_browser()

3.5.3. hms_browser_nextmsg

가장 최근에 들어온 메시지부터 순서대로 메시지를 조회하기 위한 함수이다. 내부적인 동작은 hms_recv()

와 비슷하나 차이점은 조회만 가능하고 메시지는 큐에서 소비되지 않는다는 점이다. hms_create_browser()

로 생성할 때 설정한 flags 값에 따라서 HMS_QB_FIRST이면 데스티네이션으로 전송된 순서대로 조회하

며, 기본값이면 가장 최근에 들어온 메시지(큐의 끝)부터 순서대로 메시지를 조회한다.

● 프로토타입


int hms_browser_nextmsg (HMS_BHND *browser, hms_msg_t **msg, int flags)

● 파라미터

설명파라미터


메시지 버퍼 포인터이다.msg


● 반환값

설명반환값




● 오류

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


설명에러 코드

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




[TPECLOSE]

HMS 또는 운영 시스템에 에러가 발생하였다. 예를 들어, 내부적으로 사용하

는 버퍼의 메모리 할당이 실패한 경우이다.

[TPEOS]

해당 데스티네이션에 조회가능한 메시지가 존재하지 않는다.[TPEMATCH]


● 예제

...

#include <stdio.h>




{

HMS_SHND *session;

HMS_BHND *browser;

hms_msg_t *msg;

char buf[100];

long len = 100;

...






...

msg = hms_alloc(session, 1024);




/* Queue browser를 통해 메시지 데이터를 가져온다. */



ret = hms_get_body(msg, buf, strlen(buf));


else

printf("message : %s\n", buf);

...






...

}

● 관련함수

hms_create_browser(), hms_browser_get_queue(), hms_browser_get_msgselector()

3.5.4. hms_browser_get_msgselector

브라우저를 생성할 때 설정했던 메시지 셀렉터 문장을 가져오기 위한 함수이다.

브라우저를 생성할 때 설정했던 메시지 셀렉터 문장을 버퍼에 복사하고 그 길이를 len에 설정한다. 버퍼는

메시지 셀렉터 문장의 길이를 충분히 수용할 만큼 커야 하며, API를 호출하기 전에 버퍼의 크기를 len에

설정해야 한다. 복사할 버퍼의 크기가 메시지 셀렉터 문장의 길이보다 작거나, 메시지 셀렉터가 설정되지

않았다면 -1을 반환한다.

● 프로토타입


int hms_browser_get_msgselector(HMS_BHND *browser, char *buf, long *len,

int flags)

● 파라미터

설명파라미터


메시지 셀렉터 문장을 복사할 버퍼이다.buf

버퍼의 크기를 입력받고 메시지 셀렉터 문장의 길이를 반환한다.len


● 반환값

설명반환값





● 오류

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

설명에러 코드

인수가 유효하지 않다. browser나 buf가 NULL이거나 len(버퍼의 크기)이 메

시지 셀렉터 문장의 길이보다 작을 경우 발생한다.

[TPEINVAL]

메시지 셀렉터가 설정되지 않았다.[TPENOENT]

● 예제

...

#include <stdio.h>




{

HMS_SHND *session;

HMS_BHND *browser;

hms_msg_t *msg;

char buf[100];

long len = 100;

...






...

/* 메시지 셀렉터 문장 가져오기 */

ret = hms_browser_get_msgselector(browser, buf, &len);


else

printf("Message Selector : %s\n", buf);

...





...

}

● 관련함수

hms_create_browser(), hms_browser_nextmsg(), hms_browser_get_queue()


3.5.5. hms_browser_get_queue

브라우저를 생성할 때 설정했던 데스티네이션의 이름을 버퍼에 복사하고 그 길이를 len에 설정하는 함수

이다. 버퍼는 데스티네이션의 이름을 충분히 수용할 만큼 커야 하고, API를 호출하기 전에 버퍼의 크기를

len에 설정해야 한다. 복사할 버퍼의 크기가 데스티네이션의 이름보다 작다면 -1을 반환한다.

● 프로토타입


int hms_browser_get_queue (HMS_BHND * browser, char *buf, long *len, int flags)

● 파라미터

설명파라미터


데스티네이션의 이름을 복사할 버퍼이다.buf

버퍼의 크기를 입력받고 데스티네이션의 이름의 길이를 반환한다.len


● 반환값

설명반환값




● 오류

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

설명에러 코드

인수가 유효하지 않다. browser나 buf가 NULL이거나 len(버퍼의 크기)이 데

스티네이션의 이름 길이보다 작을 경우 발생한다.

[TPEINVAL]


● 예제

...

#include <stdio.h>





{

HMS_SHND *session;

HMS_BHND *browser;

hms_msg_t *msg;

char buf[100];

long len = 100;

...






...

/* Destination 이름 가져오기 */

ret = hms_browser_get_queue(browser, buf, &len, 0);


else

printf("Destination : %s\n", buf);

...





...

}

● 관련함수

hms_create_browser(), hms_browser_nextmsg(), hms_browser_get_msgselector()


제4장 HMS 관리

본 장에서는 HMS를 사용하기 위해서 HMS를 빌드하는 과정과 HMS의 기동과 종료 및 HMS 상태조회에

대해 설명한다.

4.1. HMS 빌드HMS는 신뢰성을 제공하기 위한 목적으로 일부 중요한 정보들을 스토리지를 이용하여 관리할 수 있다. 이

러한 기능을 지원하기 위해서 HMS는 스토리지 기능이 구현된 라이브러리를 사용한다. 기본적으로 지원

되는 스토리지 이외에 사용자의 운영 환경에 설치된 외부 스토리지도 확장하여 사용할 수 있도록 지원되

며, 이러한 경우에는 사용하고자 하는 스토리지의 종류에 따라 지원되는 라이브러리가 달라지기 때문에

해당 스토리지의 라이브러리를 이용하여 HMS를 다시 빌드해 주어야 한다.

4.1.1. 사전 준비

기본 스토리지가 아닌 외부 스토리지를 사용하고자 하는 경우, HMS를 해당 스토리지 라이브러리에 맞추

어 새롭게 빌드해 주어야 한다. HMS를 빌드하기 위해서는 운영 시스템에 스토리지가 설치되어 있고 해당

스토리지를 지원하는 라이브러리가 있어야 한다. 또한 운영 시스템에 설치된 스토리지를 올바르게 사용

하기 위한 환경변수 설정을 확인해야 한다. 예를 들어, UNIX 시스템에서 외부 스토리지를 Oracle로 사용

할 경우 다음 환경변수 값들을 설정하거나 올바르게 설정되었는지 확인한다.

● ORACLE_HOME=/data/home/oracle

● PATH=$PATH:$ORACLE_HOME/bin

● LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib

HMS가 사용하게 될 스토리지의 라이브러리 이외에 Tmax에서 각 스토리지 종류에 맞추어 제공하는 HMS

라이브러리도 준비가 되어 있어야 한다. HMS 라이브러리는 기본 스토리지를 사용할 경우에는 libhms.a

이름으로 제공되고, 외부 스토리지를 사용할 경우에는 libhms_<STORAGE>.a 형태의 이름으로 제공된다.

예를 들어 외부 스토리지로 Oracle을 사용 할 경우 HMS 라이브러리는 libhms_ora.a 의 이름으로 제공된

다. 사용하고자 하는 외부 스토리지에 대한 HMS 라이브러리가 존재하지 않는다면 Tmax 제품 담당자에

게 문의하기 바란다.

제4장 HMS 관리 91

4.1.2. HMS Makefile

외부 스토리지를 사용하여 HMS를 새로 빌드하고자 하는 경우, Makefile을 이용한다. Makefile은 사용자

의 플랫폼 및 개발환경에 맞추어 적절히 수정해서 사용한다.

다음은 Linux 환경에서 외부스토리지로 Oracle을 사용하기 위해서 HMS를 빌드하기 위한 HMS Makefile

의 예제이다.

# HMS Makefile for Oracle

# Linux

TARGET = hms_ora

APOBJ = dumy.o

APPDIR = $(TMAXDIR)/appbin

TMAXLIBD= $(TMAXDIR)/lib

TMAXLIBS= -lhms_ora -lpthread

CFLAGS =

all: $(TARGET)

include $(ORACLE_HOME)/precomp/lib/env_precomp.mk

ORALIBDIR = $(LIBHOME)

ORALIB = $(PROLDLIBS)

$(TARGET): $(APOBJ)

$(CC) $(CFLAGS) -o $(TARGET) -L$(TMAXLIBD) -L$(ORALIBDIR) $(ORALIB) $(APOBJ)

$(TMAXLIBS)

mv $(TARGET) $(APPDIR)/.

$(APOBJ):

$(CC) $(CFLAGS) -c dumy.c

clean:

-rm -f core $(TARGET) $(APPDIR)/$(TARGET)

~

~

4.1.3. HMS 빌드 및 확인

HMS Makefile을 이용할 경우 빌드된 HMS는 $TMAXDIR 아래 appbin 디렉터리로 옮겨진다. appbin 디렉

터리로 옮겨지지 않았다면 빌드된 HMS를 appbin으로 복사해준다. HMS의 파일 이름은 사용자가 지정할


수 있다. 이 경우 지정한 HMS의 이름은 Tmax 환경설정 파일에서 SVRGROUP 절의 HMSNAME 항목에

대한 값이 된다.

4.2. HMS 기동 및 종료HMS는 Tmax가 운영중인 상황에서 동작한다. Tmax가 종료되어 있다면 HMS를 기동하기 위해서는 Tmax

를 먼저 기동시켜야 한다. 옵션없이 tmboot 명령을 통해 기동시키면 HMS도 함께 부팅되지만, Tmax 시스

템 프로세스만 기동시켰다면 다음과 같은 명령을 통해 HMS를 기동 할 수 있다.

tmboot -q <SVGNAME>

SVGNAME은 Tmax 환경설정 파일에서 정의한 SVRGROUP 절의 이름이 된다.

HMS를 종료하기 위해서는 다음 명령을 이용한다.

tmdown -q <SVGNAME>

4.3. HMS 상태 조회HMS가 운영중인 상황에서 현재 환경설정에 대한 정보를 확인해보고 시스템에 대한 상태, HMS 시스템에

접속되어 있는 클라이언트의 정보, 전송된 메시지 또는 처리된 메시지, 실패한 메시지 등의 현황 정보를

관리할 필요가 있다. 이를 위해서는 Tmax에서 제공하는 tmadmin 프로그램을 이용한다.

참고

tmadmin에 대한 자세한 정보는 "Tmax Administration Guide"를 참고한다.

4.3.1. tmadmin

tmadmin을 통해서 로컬 및 글로벌 HMS의 정보를 확인 할 수 있다.

tmadmin st -q

환경설정 파일에서 설정한 데스티네이션의 목록과 각 데스티네이션에서 처리중인 메시지와 클라이언트

의 정보를 확인할 수 있다.

아래는 해당 명령을 수행했을 때의 로컬 HMS 환경에서의 결과이다.

$$2 Locke2 (tmadm): st -q

----------------------------------------------------------------------------------

G dest cqcount type apqcnt acqcnt f_dscrd t_dscrd cons_cnt prod_cnt

----------------------------------------------------------------------------------

- queue01 58 QUEUE 169 111 0 0 30 5

- topic01 32 TOPIC 42 283 0 0 28 3


각 필드에 대한 설명은 다음과 같다.

설명필드

해당 데스티네이션이 GLOBAL로 설정된 경우 'O'로 표시되고, GLOBAL이

아닐 경우 '하이픈(-)'으로 표시된다.

G

데스티네이션의 이름으로 환경설정 파일에서 HMS 절에 설정된 이름이 표시

된다.

dest

해당 데스티네이션에서 아직 처리되지 않은 메시지 건수이다.cqcount

해당 데스티네이션의 타입을 표시한다. QUEUE와 TOPIC으로 표시된다.type

현재까지 전송되어 누적된 총 메시지 건수이다.apqcnt

소비자에 의해 처리된 메시지의 총 건수로 토픽 타입은 하나의 메시지에 대

해서 모든 소비자가 수신받아야 처리완료가 되므로 apqcnt보다 acqcnt가 커

질 수 있다.

acqcnt

수신 받은 메시지에 대해서 failed 처리를 함으로써 수신이 실패된 메시지 건

수이다.

f_dscrd

메시지를 전송할 때 TTL이 설정된 경우, 유효시간이 지남으로써 실패된 메시

지 건수이다.

t_dscrd

해당 데스티네이션에 접속한 소비자(consumer)의 수이다.cons_cnt

해당 데스티네이션에 접속한 생산자(producer)의 수이다.prod_cnt

tmadmin st -q <DESTNAME> -c

특정 데스티네이션에 대한 각 클라이언트의 상세한 정보를 조회할 수 있다. 현재 데스티네이션에 접속되

어 있는 클라이언트의 정보를 표시한다.

아래는 해당 명령을 수행했을 때 나타나는 결과이다.

$$3 Locke2 (tmadm): st -q queue01 -c

------------------------------------------------------------------------------

sesi clid cname clitype qcnt cnt f_dscrd t_dscrd listener

------------------------------------------------------------------------------

0 0x39d prodasync ARCV 49 0 0 0 ASYNCSVC

0x1 0 prod41 SND 0 32 0 0

0x1 0 prod42 SND 0 11 0 0

0x1 0 cons51 RCV 3 0 0 0

0x1 0 cons52 RCV 9 0 0 0

$$4 Locke2 (tmadm): st -q topic01 -c

------------------------------------------------------------------------------

sesi clid cname clitype qcnt cnt f_dscrd t_dscrd listener

------------------------------------------------------------------------------


0x1 0 prod11 PUB 0 2 0 0

0x1 0 prod12 PUB 0 1 0 0

0x1 0 cons11 SUB 30 0 0 0

0x2 0x2 prod21 PUB 0 16 0 0

0x2 0x2 prod22 PUB 0 8 0 0

0x2 0x2 cons21 SUB 23 0 0 0

0x3 0 prod31 PUB 0 3 0 0

0x4 0x4 cons41 ADSUB 32 0 0 0 ASYNCSVC2

각 필드에 대한 설명은 다음과 같다.

설명필드

해당 클라이언트를 생성한 세션의 번호이다.sesi

클라이언트 ID이다.clid

해당 데스티네이션에 연결된 클라이언트의 종류이다.cname

– SND : QUEUE 타입의 sender (hms_create_sender() 에 의해 생성)

– PUB : TOPIC 타입의 publisher (hms_create_publisher() 에 의해 생성)

– RCV : QUEUE 타입의 receiver (hms_create_receiver() 에 의해 생성)

– SUB : TOPIC 타입의 subscriber (hms_create_subscriber() 에 의해 생성)

– DSUB : TOPIC 타입의 durable subscriber (hms_create_durable_sub

scriber() 에 의해 생성)

– ARCV : Async 세션에서 생성된 QUEUE 타입의 receiver

– ASUB : Async 세션에서 생성된 TOPIC 타입의 subscriber

– ADSUB : Async 세션에서 생성된 TOPIC 타입의 durable subscriber

각 Subscriber들이 실제로 가지고 있는 메시지 건수이다.qcnt

각 클라이언트가 전송하거나 수신한 메시지 건수이다.cnt

수신 후 메시지를 failed로 처리함으로써 실패된 메시지 건수이다.f_dscrd

전송할 때 설정한 TTL (유효시간)이 지남으로써 실패된 메시지 건수이다.t_dscrd

ASYNC 세션으로 생성한 소비자(consumer)의 경우, 메시지를 수신할 서비

스 명이다.

listener


제5장 예제

본 장에서는 앞서 설명한 API들을 사용하여 개발된 애플리케이션 예제를 보여준다. 간단한 예를 제시하여

사용자는 기본적인 사용법과 전체적인 흐름을 익히게 될 것이다.

5.1. 기초 프로그램 1기초 프로그램은 클라이언트와 서버에서 HMS API를 사용하여 메시지를 주고 받는 간단한 흐름의 예제이

다.

클라이언트는 string 타입의 버퍼에 입력된 문자열을 복사해서 서비스를 호출하고, 서버의 서비스 루틴에

서는 이 문자열을 받아서 소문자를 대문자로 변경한 뒤 HMS로 메시지를 전송한다. 그리고 나서 클라이언

트는 일정 시간이 지난 뒤 HMS로부터 메시지를 수신받는다.

[그림 5.1] 기초 프로그램 흐름

5.1.1. HMS 환경설정

다음은 HMS 환경설정 파일 예제이다.

*DOMAIN

hms SHMKEY=74347,

TPORTNO=8808

*NODE

Locke2 TMAXDIR ="/home/tmax5/tmax",

APPDIR ="/home/tmax5/tmax/appbin/",

제5장 예제 97

MAXSESSION = 100

*SVRGROUP

hms01 NODENAME="Locke2", CPC=1, SVGTYPE="HMS", RESTART=Y,

OPENINFO="ORACLE_XA+Acc=P/scott/tiger+SesTm=60",

HMSINDEX=2, HMSMSGLIVE=1, HMSMAXTHR=2, HMSMAXDBTHR=5,

HMSNAME=hms_ora

svg1 NODENAME="Locke2"

*HMS

queue01 SVGNAME=hms01, BOOT="WARM", TYPE="QUEUE"

topic01 SVGNAME=hms01, BOOT="WARM", TYPE="TOPIC"

*SERVER

svr SVGNAME=svg1

*SERVICE

SVC SVRNAME=svr

5.1.2. 프로그램 예제

클라이언트 프로그램

다음은 클라이언트 프로그램 예제이다.

#include <stdio.h>

#include <stdlib.h>

#include <unistd.h>

#include <string.h>



int main(int argc, char **argv)

{

char *sndbuf, *rcvbuf;

long rcvlen, sndlen;

HMS_SHND *sess;

HMS_CHND *cons;

hms_msg_t *msg;

if (argc != 2) {

printf("Usage : %s <message>\n\n", argv[0]);

exit(1);


}

if (tmaxreadenv("tmax.env", "TMAX") == -1) {

printf("error: tmaxreadenv() failed - %d\n", tperrno);

exit(1);

}

if (tpstart((TPSTART_T *) NULL) == -1) {

printf("error: tpstart() fail - %d\n", tperrno);

exit(1);

}

if ((sndbuf = (char *)tpalloc("STRING", NULL, 0)) == NULL) {

printf("error: sendbuf alloc failed !\n");

tpend();

exit(1);

}

if ((rcvbuf = (char *)tpalloc("STRING", NULL, 0)) == NULL) {

printf("error: recvbuf alloc failed !\n");

tpfree((char *)sndbuf);

tpend();

exit(1);

}

strcpy(sndbuf, argv[1]);

if(tpcall("SVC", sndbuf, 0, &rcvbuf, &rcvlen, 0)==-1){

printf("error: Can't send request to service SVC\n");

tpfree((char *)sndbuf);

tpfree((char *)rcvbuf);

tpend();

exit(1);

}

sleep(5);

/* RECV MESSAGE FROM HMS */

if ((sess = hms_create_session("hms01", 0, HMS_AUTO_ACK, 0)) == NULL) {

printf("error: hms_create_session() failed tperrno = %d\n", tperrno);

tpend();

exit(1);

}

if ((cons = hms_create_receiver(sess, "queue01", "cons01", NULL, NULL, 0))

== NULL) {

printf("error: hms_create_receiver() failed tperrno = %d\n", tperrno);

제5장 예제 99

tpend();

exit(1);

}

/* ALLOCATION */

if ((msg = hms_alloc(sess, 1024)) == NULL) {

printf("error: hms_alloc() failed tperrno = %d\n", tperrno);

tpend();

exit(1);

}

/* RECV MESSAGE */

if (hms_recvex(cons, &msg, 5, 0) == -1) {

printf("error: hms_recvex() failed tperrno = %d\n", tperrno);

hms_free(msg);

tpend();

exit(1);

}

/* GET BODY */

rcvlen = 1024;

if (hms_get_body(msg, rcvbuf, &rcvlen) == -1) {

printf("error: hms_get_body() failed tperrno = %d\n", tperrno);

hms_free(msg);

tpend();

exit(1);

}

printf("HMS MESSAGE : %s\n", rcvbuf);

/* CLOSE RECEIVER */

if (hms_close_receiver(cons, 0) == -1) {

printf("error: hms_close_receiver() failed tperrno = %d\n", tperrno);

hms_free(msg);

tpend();

exit(1);

}

/* CLOSE SESSION */

if (hms_close_session(sess, 0) == -1) {

printf("error: hms_close_session() failed tperrno = %d\n", tperrno);

hms_free(msg);

tpend();

exit(1);

}

hms_free(msg);


tpend();

return 0;

}

서버 프로그램 (svr.c)

다음은 서버 프로그램의 예제이다.

#include <stdio.h>

#include <stdlib.h>



HMS_SHND *sess = NULL;

HMS_CHND *prod = NULL;

int tpsvrinit(int argc, char **argv)

{

while(1) {

sess = hms_create_session("hms01", 0, HMS_AUTO_ACK, 0);

if (sess != NULL) {

break;

}

if (tperrno != TPENOREADY) {

printf("hms_create_session(hms01) : FAIL tperrno = %d\n", tperrno);

return -1;

}

}

prod = hms_create_sender(sess, "queue01", "prod_svc", 0);

if (prod == NULL) {

printf("hms_create_sender() : FAIL tperrno = %d\n", tperrno);

return -1;

}

return 1;

}

int tpsvrdone()

{

hms_close_sender(prod, 0);


return 1;

제5장 예제 101

}

SVC(TPSVCINFO *msg)

{

int n, i;

hms_msg_t *hmsmsg = NULL;

char *data = msg->data;

int len = msg->len, asize;

printf("SVC STARTED!\n");

/* TOUPPER */

for (i = 0; i < len; i++)

data[i] = toupper(data[i]);

/* ALLOCATION */

asize = len +1024;

hmsmsg = hms_alloc(sess, asize);

if (hmsmsg == NULL) {

printf("hms_alloc : fail tperrno = %d\n", tperrno);

tpreturn(TPFAIL, 0, NULL, 0, 0);

}

/* SET BODY */

n = hms_set_body(hmsmsg, data, len);

if (n < 0) {

hms_free(hmsmsg);

printf("hms_set_body : fail tperrno = %d\n", tperrno);


}

/* SEND : hms01, persistent */

n = hms_sendex(prod, hmsmsg, HMS_DLV_PERSISTENT, 0, 0, 0);

if (n < 0) {

hms_free(hmsmsg);

printf("hms_sendex(prod) : fail tperrno = %d\n", tperrno);


}

/* FREE */

hms_free(hmsmsg);

printf("SVC SUCCESS!\n");

tpreturn(TPSUCCESS, 0, NULL, 0, 0);

}


5.1.3. 프로그램 컴파일

두 프로그램은 Tmax 응용 프로그램을 컴파일하는 과정과 동일하게 컴파일하면 된다.

참고

프로그램 컴파일에 대한 자세한 내용은 Tmax 안내서 중 "Tmax Application Development Guide"를

참고한다.

5.2. 기초 프로그램 2클라이언트는 사용자의 입력을 받아서 HMS로 QUEUE 타입의 메시지를 전송한다. 서버측에서는 비동기

세션을 통해 소비자(Consumer)를 생성하고 메시지가 전송될 경우 ASYNC 서비스가 이 메시지를 수신하

여 해당 내용을 데이터베이스에 Insert한다.

[그림 5.2] 기초 프로그램 2

5.2.1. HMS 환경설정

다음은 HMS 환경설정에 대한 예제이다.

*DOMAIN

hms SHMKEY=74347,

TPORTNO=8808

*NODE

Locke2 TMAXDIR ="/home/tmax5/tmax",

APPDIR ="/home/tmax5/tmax/appbin/",

MAXSESSION = 100

*SVRGROUP

제5장 예제 103

hms01 NODENAME="Locke2", CPC=1, SVGTYPE="HMS", RESTART=Y,


HMSINDEX=2, HMSMSGLIVE=1, HMSMAXTHR=2, HMSMAXDBTHR=5,

HMSNAME=hms_ora

svg1 NODENAME="Locke2", RESTART=N,


DBNAME="ORACLE", TMSNAME=tms_ora, MINTMS=1

*HMS

queue01 SVGNAME=hms01, BOOT="WARM", TYPE="QUEUE"

topic01 SVGNAME=hms01, BOOT="WARM", TYPE="TOPIC"

*SERVER

async SVGNAME=svg1, CLOPT="-- -i"

*SERVICE

ASYNCSVC SVRNAME=async

5.2.2. 프로그램 예제

클라이언트 프로그램

다음은 클라이언트 프로그램 예제이다.

#include <stdio.h>

#include <stdlib.h>

#include <unistd.h>

#include <string.h>



int main(int argc, char **argv)

{

long len;

HMS_SHND *sess;

HMS_PHND *prod;

hms_msg_t *msg;

char *data;

int no;

if (argc != 3) {

printf("Usage : %s <no> <message>\n\n", argv[0]);

exit(1);

}


if (tmaxreadenv("tmax.env", "TMAX") == -1) {

printf("error: tmaxreadenv() failed - %d\n", tperrno);

exit(1);

}

if (tpstart((TPSTART_T *) NULL) == -1) {

printf("error: tpstart() fail - %d\n", tperrno);

exit(1);

}

len = strlen(argv[2]);

data = argv[2];

no = atoi(argv[1]);

/* SEND MESSAGE TO HMS */

if ((sess = hms_create_session("hms01", 0, HMS_AUTO_ACK, 0)) == NULL) {

printf("error: hms_create_session() failed tperrno = %d\n", tperrno);

tpend();

exit(1);

}

if ((prod = hms_create_sender(sess, "queue01", "prod01", 0)) == NULL) {

printf("error: hms_create_sender() failed tperrno = %d\n", tperrno);

tpend();

exit(1);

}

/* ALLOCATION */

if ((msg = hms_alloc(sess, len + 1024)) == NULL) {

printf("error: hms_alloc() failed tperrno = %d\n", tperrno);

tpend();

exit(1);

}

/* SET BODY */

if (hms_set_body(msg, data, len) == -1) {

printf("error: hms_set_body() failed tperrno = %d\n", tperrno);

hms_free(msg);

tpend();

exit(1);

}

/* SET PROPERTY */

if (hms_set_property(msg, "NO", HMS_INT, (char *)&no, sizeof(int)) == -1) {

printf("error: hms_set_property() failed tperrno = %d\n", tperrno);

hms_free(msg);

제5장 예제 105

tpend();

exit(1);

}

/* SEND MESSAGE */

if (hms_sendex(prod, msg, HMS_DLV_PERSISTENT, 0, 0, 0) == -1) {

printf("error: hms_sendex() failed tperrno = %d\n", tperrno);

hms_free(msg);

tpend();

exit(1);

}

if (hms_close_sender(prod, 0) == -1) {

printf("error: hms_close_sender() failed tperrno = %d\n", tperrno);

hms_free(msg);

tpend();

exit(1);

}

if (hms_close_session(sess, 0) == -1) {

printf("error: hms_close_session() failed tperrno = %d\n", tperrno);

hms_free(msg);

tpend();

exit(1);

}

hms_free(msg);

tpend();

return 0;

}

서버 프로그램 (async.pc)

다음은 서버 프로그램 예제이다.

#include <stdio.h>

#include <stdlib.h>

#include <unistd.h>

#include <string.h>



HMS_SHND *sess;

HMS_CHND *cons;

int svrinit_start = 0;


void abend_callback(HMS_SHND *session)

{

printf("START ABEND_CALLBACK FUNCTION\n");

hms_close_session(session, 0);

printf("hms_close_session success\n");

while (1) {

sess = (HMS_SHND *) hms_create_async_session("hms01", abend_callback, 0);

if (sess == NULL) {


usleep(500000);

continue;

}

printf("hms_create_session() : FAIL [%d]\n\n", tperrno);

return;

}

break;

}

cons = (HMS_CHND *) hms_create_receiver(sess, "queue01", "consasync", NULL,

"ASYNCSVC", 0);

if (cons == NULL) {

printf("hms_create_receiver() : FAIL tperrno = %d\n\n", tperrno);

return;

}

printf("END ABEND_CALLBACK FUNCTION\n");

}

int tpsvrinit(int argc, char **argv)

{

int c;

while ((c = getopt(argc, argv, "i")) != EOF) {

switch (c) {

case 'i':

svrinit_start = 1;

break;

}

}

if (svrinit_start == 1) {

printf("ASYNC SERVICE svrinit()\n");

while(1) {

sess = (HMS_SHND *) hms_create_async_session("hms01", abend_callback,

0);

if (sess == NULL) {


usleep(500000);

continue;

}

제5장 예제 107

printf("ASYNC SERVICE hms_create_async_session() failed,

tperrno[%d]\n", tperrno);

return;

}

break;

}

cons = (HMS_CHND *) hms_create_consumer(sess, "queue01", HMS_QUEUE,

"consasync", "", "ASYNCSVC", 0);

if (cons == NULL)

printf("ASYNC SERVICE hms_create_consumer() failed, tperrno[%d]\n",

tperrno);

return -1;

}

printf("ASYNC SERVICE svrinit() success\n");

}

return 1;

}

int tpsvrdone()

{

if (svrinit_start == 1) {

printf("ASYNC SERVICE svrdone()\n");



}

return 1;

}

/* DB INSERT */

EXEC SQL include sqlca.h;

EXEC SQL begin declare section;

int no;

char message[128];

EXEC SQL end declare section;

int DBInsert( int n, char *data )

{

printf("UPDATE START!!!\n");

memset( message, 0x00, sizeof(message) );

no = n;

strcpy(message, data);

EXEC SQL insert into hmstest(no, message) values(:no, :message);

if ( sqlca.sqlcode != 0 ){

printf( "insert failed sqlcode = %d\n",sqlca.sqlcode );


return -1;

}

return 1;

}

ASYNCSVC(TPSVCINFO *svc)

{

hms_msg_t *msg;

char *data;

long llen = 4096;

int prop = 0;

int type;

printf("ASYNC SERVICE CALLED\n");

msg = (hms_msg_t *)svc->data;

if ((data = (char *)tpalloc("CARRAY", NULL, 4096)) == NULL) {

printf("ASYNC SERVICE tpalloc return failed. tperrno[%d]\n",

tperrno);

tpreturn(TPFAIL, TPFAIL_ACK, svc->data, svc->len, 0);

}

if (hms_get_body(msg, data, &llen) < 0) {

printf("ASYNC SERVICE hms_get_body() return failed. tperrno[%d]\n",

tperrno);


}

data[llen] = '\0';

llen = sizeof(int);

if (hms_get_property(msg, "NO", &type, (char *)&prop, &llen) < 0) {

printf("ASYNC SERVICE hms_get_property() return failed. tperrno[%d]\n",

tperrno);

}

printf("ASYNC SERVICE RECV MESSAGE, BODY[%s], PROPERTY[NO:%d]\n", data, prop);

if (DBInsert(prop, data) == -1)


tpreturn(TPSUCCESS, 0, svc->data, svc->len, 0);

}

제5장 예제 109

Oracle 테이블 작성 스크립트

다음은 Oracle 테이블 작성 스크립트이다.

sqlplus scott/tiger << EOF

create table hmstest (

no number(7),

message char(128)

);

EOF

Oracle 테이블 및 데이터 출력 스크립트

다음은 Oracle 테이블 및 데이터 출력 스크립트이다.

sqlplus scott/tiger << EOF

desc hmstest;

select * from hmstest;

select count(*) from hmstest;

EOF

5.2.3. 프로그램 컴파일

두 프로그램은 Tmax 애플리케이션을 컴파일하는 과정과 동일하게 컴파일하면 된다.

참고

자세한 정보는 Tmax 안내서 중 "Tmax Application Development Guide"를 참고한다.


Appendix A. 메시지 셀렉터 사용하기

클라이언트는 메시지 셀렉터를 설정함으로써 일정한 조건을 충족하는 메시지만을 수신받을 수 있다. 메

시지 셀렉터는 데스티네이션에 있는 메시지들 중에서 기준에 부합되는 메시지를 선별하여 수신 할 수 있

도록 필터링 역할을 한다. 메시지의 프로퍼티에 설정된 값과 메시지 셀렉터에서 설정한 조건을 비교한다.

비교 대상은 프로퍼티만 가능하며 주요 컨텐츠를 저장하는 Body의 값은 비교하지 않는다.

메시지 셀렉터의 문법은 SQL92의 표현식 중 일부분을 준수한다. 메시지 셀렉터를 평가하는 순서는 왼쪽

에서 오른쪽으로 진행하며 괄호를 사용하여 순서를 변경할 수 있다. 메시지 셀렉터는 리터럴과 식별자, 그

리고 표현식으로 구성된다.

● 리터럴

– 따옴표로 둘러싸인 문자열 (예: 'cat' )

– long 또는 double 범위 이내의 수치 문자열 (예: 50, 1.414)

● 식별자

– 프로퍼티의 Name에 해당한다. 뒤따르는 리터럴은 프로퍼티의 타입과 일치해야 한다. 일치하지 않을

경우 해당 프로퍼티의 평가는 False가 될 것이다. 또한 메시지에 해당 프로퍼티가 존재하지 않는다면

값은 NULL로 평가된다.

– 식별자는 표현식 또는 리터럴을 사용해서는 안된다. 또한 대소문자를 구별한다.

– 식별자로 일부 예약된 프로퍼티는 사용할 수 없다. 예약된 프로퍼티의 종류는 hms_set_property()

API를 참고한다.

– 식별자로 메시지 셀렉터에서 사용하는 문법의 키워드는 사용할 수 없다.

● 표현식

– 조건 표현식, 비교 연산자, 논리 연산자, 수치 연산자 등을 사용할 수 있다.

– 비교 연산자 : =, >, >=, <, <=, <>

– 논리 연산자 : NOT, AND, OR

– 수치 연산자 : +, - (단항연산), *, /, +, - (우선순위는 +, - (단항연산) > *, / > +, - 순)

Appendix A. 메시지 셀렉터 사용하기 111

– 조건 표현식

• 표현식1 [NOT] BETWEEN 표현식2 AND 표현식3

"weight BETWEEN 50 AND 70"는 "weight >= 50 AND weight <= 70" 과 같다.

"weight NOT BETWEEN 50 AND 70"는 "weight < 50 OR weight > 70" 과 같다.

• 식별자 [NOT] IN (리터럴1, 리터럴2, …)

"type IN ('cat', 'tiger', 'puma')"는

"type = 'cat' OR type = 'tiger' OR type = 'puma'" 와 같다.

"type NOT IN (20, 30, 40)"은

"type <> 20 AND type <> 30 AND type <> 40" 과 같다.

• 식별자 [NOT] LIKE 패턴

패턴은 물음표(?), 별표(*) 문자를 사용할 수 있으며, 물음표(?) 문자는 해당 위치에 어떤 문자든지

반드시 한 문자가 있어야 참이 되며, 별표(*) 문자는 해당 위치에 0개 이상의 어떤 문자열이든지 올

수 있음을 뜻한다.

"year LIKE '200?' "는 '2009'는 참이지만 '200' 이나 '20001'은 거짓이 된다.

"year LIKE '200*' "는 '200' 으로 시작하는 모든 문자열들이 참이 된다.

예제

"Type = 'cat' AND Weight BETWEEN 5 AND 15"

>>>

Type 프로퍼티의 값은 'cat' 문자열이며 동시에 Weight 프로퍼티의 값은 5와 15 사이의 수와

일치하는 메시지를 뜻한다.

"Type = 'cat'"이 참이고 "Weight BETWEEN 5 AND 15"( "weight >= 5 그리고 weight <= 15" )가 참이면 해

당 메시지 셀렉터문은 참이 된다.


색인

HHMS, 1

Hybird Messaging System, 1

TTmax, ix

XXA 세션, 3

ㄱ

글로벌 큐(Global Queue), 7

글로벌 토픽(Global Topic), 7

ㄷ

데스티네이션(Destination), 4

ㅁ

메시지 셀렉터(Message Selector), 6

메시징 시스템(Messaging System), 1

메인 스레드, 1

ㅂ

비동기 세션(Async Session), 4

ㅅ

생산자(Producer), 4

세션, 3

소비자(Consumer), 5

ㅇ

영속적 구독자(Durable Subscriber), 5

ㅋ

큐 브라우저(QueueBrowser), 6

큐(Queue), 4

클러스터링(Clustering), 7

ㅌ

토픽(Topic), 4

트랜잭티드 세션, 3

색인 113

tmax hms user guide...copyright notice copyright © 2009 tmaxsoft co., ltd. all rights reserved....

Documents