tmax xa library and gateway guide · 2019. 4. 9. · *gateway xagw1 gwtype = xagw, portno = 10042,...

Tmax XA

Library and Gateway 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 XA Library and Gateway Guide

발행일: 2009-08-10

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

안내서 버전: v2.1.1

내용 목차

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

제1장 XA 라이브러리와 게이트웨이 ............................................................................................. 1

1.1. 개념 ............................................................................................................................ 1

1.1.1. XA 라이브러리 .................................................................................................. 1

1.1.2. XA 게이트웨이 .................................................................................................. 1

1.2. 환경설정 ...................................................................................................................... 2

1.2.1. XA 라이브러리 .................................................................................................. 2

1.2.2. XA 게이트웨이 .................................................................................................. 3

제2장 API ................................................................................................................................... 5

2.1. 동기형 call ................................................................................................................... 5

2.1.1. tpcall ................................................................................................................. 5

2.2. 비동기형 call .............................................................................................................. 10

2.2.1. tpacall ............................................................................................................. 10

2.2.2. tpgetrply .......................................................................................................... 14

제3장 예제 ................................................................................................................................ 19

Tmax XA iii

그림 목차

[그림 1.1] XA 게이트웨이 ............................................................................................................. 1

Tmax XA v

안내서에 대하여

안내서의 대상

본 안내서는 Tmax®(이하 Tmax) 시스템에서 XA 라이브러리와 XA 게이트웨이를 사용하여 프로그램을 개

발하는 사용자를 위해 기술되었다.

안내서의 전제 조건

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

득을 위한 기본서이다.

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

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

● Tmax의 기본 개념 이해

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

안내서의 제한 조건

본 안내서는 XA 라이브러리와 XA 게이트웨이에 대한 내용만 기술만 기술하기 때문에 읽기 전에 Tmax의

기본 개념을 숙지하고 있어야 한다. 실무에서의 구체적인 사용방법이나 관리 및 운용에 관한 사항은 각 제

품의 안내서를 참고한다.

참고

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

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

Guide”를 참고한다.

안내서에 대하여 vii

안내서 구성

Tmax XA Library and XA Gateway Guide는 총 3개의 장으로 구성되어 있다.

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

● 제1장: XA 라이브러리와 게이트웨이

XA 라이브러리와 XA 게이트웨이에 대해 기술한다.

● 제2장: API

실제 XA 라이브러리와 XA 게이트웨이를 사용하기 위해 기본적인 API 사용법과 환경을 설정하는 방법

을 기술한다.

● 제3장: 예제

Tmax XA 서비스를 호출하는 간단한 예제를 기술한다.

viii Tmax XA Library and Gateway Guide

안내서 규약

의미표기

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

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

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

강조진하게

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

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

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

메뉴의 진행 순서>

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

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

참고 또는 주의사항참고

그림 이름[그림 1.1]

표 이름[표 1.1]

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

옵션 인수 값[ ]

선택 인수 값|

안내서에 대하여 ix

시스템 사용 환경

요구 사항

IBM AIX 5.xPlatform

HP-UX 11.xx

Solaris 7~9 (SunOS 5.7~5.9)

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

256MB 이상 메모리 공간

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

Oracle 9i 또는 10gDatabase

x Tmax XA Library and Gateway Guide

관련 안내서

설명안내서

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

기술한 안내서이다.

Tmax

Administration Guide

Tmax 애플리케이션 프로그램 개발에 사용하는 클라이언트와 서버

의 연결, 통신에서 사용하는 함수에 대한 사용 방법과 예제를 기술한

안내서이다.

Tmax

Reference Guide

안내서에 대하여 xi

연락처

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

xii Tmax XA Library and Gateway 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

안내서에 대하여 xiii

http://www.tmaxchina.com.cn

http://www.tmaxchina.com.cn

제1장 XA 라이브러리와 게이트웨이

본 장에서는 XA 라이브러리와 XA 게이트웨이에 대한 개념과 환경설정에 대해서 설명한다.

1.1. 개념X/Open XA는 2PC(Phase Commit)를 통한 분산 트랜잭션 처리를 하기 위해 X/Open에서 명시한 표준이

다. XA는 DBMS 벤더별로 제공을 하고 있으며 이 표준 규약을 통해서 이기종 간의 트랜잭션이 보장된다.

Tmax에서는 이러한 XA 라이브러리와 XA 게이트웨이를 통해 XA를 제공함으로서 이기종과의 2PC를 보

장하도록 한다.

1.1.1. XA 라이브러리

Tmax의 XA를 사용하기 위해서는 XA 라이브러리를 사용하여 Tmax의 서비스를 처리하여야 한다. 라이브

러리는 Tmax의 클라이언트 라이브러리와는 조금 다른 형태로서 XA 게이트웨이와 통신한다. 기본 XA 인

터페이스는 Tmax의 xa-switch 이름인 tmaxxaosw를 사용하여 처리되며 이외에 Tmax의 서비스를 처리할

수 있도록 tpcall/tpacall/tpgetrply API를 추가적으로 지원한다. 라이브러리는 현재 멀티 스레드(multithread)

를 지원하지 않는다.

1.1.2. XA 게이트웨이

XA 라이브러리에서 올라온 데이터를 처리하기 위한 모듈로서 Tmax 시스템에서는 XA 게이트웨이가 추가

적으로 기동된다.

다음 그림은 XA 게이트웨이가 Tmax 시스템에서 서비스를 처리하는 과정을 보여준다.

[그림 1.1] XA 게이트웨이

제1장 XA 라이브러리와 게이트웨이 1

XA 게이트웨이는 Tmax의 config에 설정한 listen 포트로 XA 라이브러리를 이용하여 애플리케이션의 요청

을 기다린다. 게이트웨이는 트랜잭션을 처리하며 Tmax 서비스를 호출할 수 있다.

1.2. 환경설정

1.2.1. XA 라이브러리

XA 라이브러리의 이름은 <libtxa.so>이다.

Tmax 시스템과 연동하여 트랜잭션을 처리하고자 하는 애플리케이션은 Tmax의 XA 라이브러리를 함께

연결하여 사용해야 한다.

실제 애플리케이션에서 이 라이브러리를 연동하는 makefile은 예제를 참조한다.

또한 애플리케이션이 Tmax의 버퍼형인 FIELD/STRUCT형 버퍼를 사용하고자 할 때는 환경변수로 SDLFILE

또는 FDLFILE을 아래와 같이 설정해야 한다.

export SDLFILE=/usr/home/tmax/tmax.sdl

export FDLFILE=/usr/home/tmax/tmax.fdl

Tmax에서 제공하는 XA 라이브러리를 이용하여 XA API를 사용하기 위해서는 xa-switch를 설정하여야 한

다. xa-swtch 이름은 tmaxxaosw로서 Tmax와 트랜잭션을 연동하고자 하는 애플리케이션에서 설정해 주

도록 한다.

항목 들은 구분자(+)로서 구별하여 각각 설정하여야 한다. 이때 설정해야 할 항목은 아래에 설명하도록 한

다.

필수 항목

아래의 field는 대소문자를 구별하므로 반드시 아래의 문자열로 설정하여야 한다.

● HOST = ip:port

XA 게이트웨이가 listen하고 있는 ip와 port 정보는 구분자인 콜론( : )으로 구별하여 설정한다.

선택 항목

● TIMEOUT = int_value

TIMEOUT 값은 XA API를 사용할 때 TMNOWAIT이 아닌 경우, 이 설정으로 타임아웃을 체크하게 되며

tpcall, tpacall, tpgetrply을 사용하는 경우도 마찬가지로 적용된다.

2 Tmax XA Library and Gateway Guide

1.2.2. XA 게이트웨이

XA 게이트웨이는 Tmax의 게이트웨이로 동작을 하며 다른 게이트웨이와 마찬가지로 Tmax의 환경파일에

등록을 해 주어야 한다.

XA 게이트웨이는 Tmax의 환경파일 중 GATEWAY 절에 아래와 같이 등록을 해 주어야 한다.

*GATEWAY

XAGW1 GWTYPE = XAGW,

PORTNO = 10042,

NODENAME = tmax1,

TIMEOUT = 30,

DIRECTION = IN,

CPC=5

필수 항목

아래의 항목은은 대소문자를 구별하므로 반드시 아래의 문자열로 설정하여야 한다.

● GWNAME = GW-name

GATEWAY 절에는 반드시 GWNAME이 들어가야 한다. 이름은 16자를 넘지 않아야 하며, 알파벳으로

시작하여야 한다.

● GWTYPE = XAGW

이 필드는 여러 Tmax의 게이트웨이 타입 중에 어떤 게이트웨이 타입인지를 설정하는 것으로 XA 게이

트웨이를 사용할 때는 XAGW로 설정해 주어야 한다.

● PORTNO =Listen_port

XA 게이트웨이가 listen할 포트를 설정하며, 이 포트는 xa_open string의 host 설정과 동일한 값이어야

한다.

● NODENAME = 노드 이름

XA 게이트웨이가 기동할 노드 이름을 설정하며, 노드의 ip는 xa_open string의 호스트 설정과 동일한

값이어야 한다.

● DIRECTION = IN

XA 게이트웨이는 IN 채널만 지원하는 게이트웨이이므로 반드시 설정값은 IN으로 설정해야 한다.

참고

기타 자세한 설정은 Tmax 안내서 중 "Tmax Application Development Guide"를 참고한다.

제1장 XA 라이브러리와 게이트웨이 3

제2장 API

본 장에서는 실제 XA 라이브러리와 XA 게이트웨이를 사용하기 위해 기본적인 API 사용법과 환경을 설정

하는 방법 등을 설명한다.

Tmax의 서비스를 요청하기 위한 API로 XA 라이브러리는 동기형 call과 비동기형 call을 제공한다.

참고

동기형 call, 비동기형 call API에 대한 자세한 정보 및 flags는 "Tmax Reference Guide"를 참고한다.

2.1. 동기형 call동기형 call로서는 tpcall을 제공한다.

tpcall은 tmax의 클라이언트 라이브러리및 서버 라이브러리에서 사용하는 API로서 동일한 구조로 XA 라

이브러리에서 사용할 수 있다.

2.1.1. tpcall

서버/클라이언트의 동기형 서비스 요청 송수신 함수로 동기형 통신으로 svc로 명명된 서비스에게 서비스

요청을 송신하고 이에 대한 응답을 수신한다. tpacall() 호출 후 연속적으로 tpgetrply()를 호출하는 것과

동일하다.

● 프로토타입

# include <atmi.h>

int tpcall (char *svc, char *idata, long ilen, char **odata, long *olen,

long flags)

● 파라미터

설명파라미터

호출되는 서비스 이름을 의미한다. 이 서비스는 Tmax 응용 서버 프로그램에

서 제공되고 있는 것이어야 한다.

svc

서비스 요청의 데이터에 대한 포인터이다. 반드시 이전에 tpalloc()에 의해 할

당된 버퍼이어야 한다.

idata

idata의 유형(type)과 하위 유형(subtype)은 svc가 지원하는 유형이어야 한다.

제2장 API 5

설명파라미터

송신할 데이터의 길이를 지정한다.ilen

- idata가 가리키는 버퍼가 특별한 길이 명시가 필요 없는 버퍼 유형(STRING,

STRUCT, X_COMMON, X_C_TYPE)인 경우 ilen은 무시되고 기본으로 0을

사용한다.

- idata가 가리키는 버퍼가 길이 명시가 반드시 필요한 버퍼 유형( X_OCTET,

CARRAY, MULTI STRUCTURE)인 경우 ilen은 0이 될 수 없다.

- idata가 NULL인 경우 ilen은 무시된다.

*odata는 수신될 응답 버퍼에 대한 포인터로 버퍼는 *olen으로 반환된 길이

만큼의 응답이 수신된다.

*odata

*odata는 반드시 이전에 tpalloc()에 의해 할당된 버퍼이어야 한다. 동일한 버

퍼가 송신과 수신 역할을 모두 한다면, *odata는 idata의 주소로 설정되어야

한다.

응답 버퍼의 크기 변경 여부를 결정하기 위해서, tpcall()이 완료되기 전에

*odata로 할당된 응답 버퍼의 크기와 수신된 *olen을 비교한다. 수신된 *olen

이 더 크다면 할당된 응답 버퍼의 크기가 증가되며, 그렇지 않으면 크기는 변

경되지 않는다.

idata와 *odata로 동일한 버퍼가 사용되어 tpcall()이 호출된 경우, *odata가

변경되었다면 idata가 가리키는 주소는 더 이상 유효하지 않다. *odata는 수

신 데이터가 커서 변경 될 수도 있고, 이 외에 다른 이유에 의해서도 변경될

수 있다.

*olen이 0으로 반환되었다면, 어떤 데이터도 수신되지 않고 *odata와 *odata

가 가리키는 버퍼 모두 아무런 변화가 없다.

*odata나 olen이 NULL이 되는 것은 에러이다 .

*odata에 반환될 응답에 대한 길이이다.*olen

호출할 때 사용되는 옵션으로 어떤 방식으로 통신할 것인지를 지정한다.flags

flags로는 다음 값들을 사용할 수 있다.

설명설정값

tpcall() 함수 호출자가 트랜잭션 모드 상태에서 이 플래그를 설정하여 svc 서

비스를 요청하였다면, svc 서비스는 트랜잭션 모드에서 제외되어 수행된다.

TPNOTRAN

트랜잭션 모드에서 svc가 트랜잭션을 지원하지 않는 서비스라면, tpcall() 함

수가 트랜잭션 모드에서 호출되는 경우 플래그는 반드시 TPNOTRAN으로

설정해야 한다. 트랜잭션 모드 내에서의 tpcall() 함수 호출할 때, TPNOTRAN

으로 설정되었어도 여전히 트랜잭션 타임아웃(timeout)에 영향을 받는다.


설명설정값

TPNOTRAN으로 호출된 서비스가 실패하였을 경우, 호출자의 트랜잭션에는

영향을 미치지 않는다.

TPNOBLOCK 플래그를 설정한 상태에서, 내부 버퍼가 송신할 메시지들로

가득 찬 경우와 같은 블로킹(blocking) 상황을 만나면 서비스 요청은 실패한

다. TPNOCHANGE은 tpcall()의 Tx 부분에만 적용된다.

TPNOCHANGE

TPNOBLOCK 플래그 설정 없이 tpcall()호출할 때, 블로킹 상황이 발생하면

함수 호출자는 블로킹 상황이 풀리거나 타임아웃(트랜잭션 타임아웃 또는 블

로킹 타임아웃)이 발생할 때까지 대기한다.

함수 호출자가 블로킹 타임아웃을 무시하고 응답이 수신될 때까지 무한정 기

다리겠다는 것을 의미한다. 트랜잭션 타임아웃 내에서 tpcall()을 한 경우에는

여전히 트랜잭션 타임아웃이 적용된다.

TPNOTIME

시그널(signal) 인터럽트를 수용하고자 할 때 사용한다. 내부에서 시그널 인

터럽트가 발생하여 시스템 함수 호출이 방해될 때 시스템 함수 호출이 재실

행된다.

TPSIGRSTRT

TPSIGRSTRT 플래그가 설정되지 않은 경우 시그널 인터럽트가 발생하였다

면, 함수는 실패하고 tperrno에 TPGOTSIG가 설정된다.

● 반환값

설명반환값

함수 호출에 성공한 경우1

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

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

● 오류

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

설명에러 코드

인수가 유효하지 않거나 플래그가 유효하지 않다.[TPEINVAL]

예를 들어, svc가 NULL이거나 data가 tpalloc()으로 할당되지 않은 버퍼를 가

리킨다.

svc라는 서비스가 존재하지 않아서 서비스를 요청할 수 없다.[TPENOENT]

data의 유형 및 하위 유형이 svc가 지원하지 않는 유형이다.[TPEITYPE]

- 수신된 응답버퍼의 유형이나 하위 유형이 호출자가 알지 못하는 유형이다.[TPEOTYPE]

제2장 API 7

설명에러 코드

- 플래그가 TPNOCHANGE로 설정되었는데 *odata가 가리키는 버퍼의 유형

및 하위 유형이 수신된 응답 버퍼의 유형 및 하위 유형과 맞지 않은 경우

*odata의 내용과 *olen은 모두 변경되지 않는다.

- 호출자가 트랜잭션 모드에서 서비스를 요청하였다면, 그 트랜잭션은 응답

이 무시되었기 때문에 Rollback된다.

트랜잭션 서비스를 호출할 때 데이터 베이스에 문제가 발생하여 xa_start가

실패하였다.

[TPETRAN]

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

함수 호출자가 트랜잭션 모드에 있다면, 트랜잭션 타임아웃이 발생하였고 그

트랜잭션은 Rollback된다. 트랜잭션 모드가 아니고 TPNOTIME과 TP

NOBLOCK 어느 것도 지정되지 않았다면, 블로킹 타임아웃이 발생한다. 이

두 경우에, *odata의 내용과 *olen은 변경되지 않는다.

트랜잭션 타임아웃이 발생하였다면, 새로운 서비스 요청을 송신한다거나 응

답을 대기하는 일은 트랜잭션이 Rollback될 때까지 [TPETIME] 에러로 실패

하게 된다.

서비스 요청에 대한 응답을 송신하는 서비스 루틴이 애플리케이션에서 에러

가 발생하여 TPFAIL로 tpreturn()을 호출하였다. 서비스 응답이 수신 되었다

면, 그 내용들은 *odata가 가리키는 버퍼를 통하여 사용될 수 있다.

[TPESVCFAIL]

트랜잭션 타임아웃이 발생해서 트랜잭션이 Rollback되기 전에 다른 통신들

이 시도될 수 있다. 그러한 통신들은 정상적으로 처리될 수도 있고, 또는 실패

할 수도 있다. 통신이 정상적으로 수행되기 위해서는 TPNOTRAN이 설정되

어야 한다. 호출자의 트랜잭션 모드에서 수행된 작업들은 트랜잭션을 완료할

때에 모두 Rollback된다.

- 서비스 루틴 수행중이나 tpreturn()(예를 들어, 잘못된 인수가 전달된 경우)

수행 중에 에러가 발생하였다. 에러가 발생하면 어떠한 응답 데이터도 반환

되지 않고 *odata의 내용 또는 *olen 모두 변경되지 않는다.

[TPESVCERR]

- tpalloc로 생성되지 않은 버퍼를 사용하였거나 할당된 버퍼의 Tmax 헤더가

잘못된 포인터(memcpy 등)의 영향을 받았거나, tpacall이나 tpconnect의 cd

로 반환하였을 경우, Recv모드에서 서비스가 유효하지 않은 대화형 내용일

경우에 발생한다. 단, tpreturn을 시도하면 클라이언트는 TPESVCERR를 받

게 된다.

- 클라이언트가 강제로 대화를 해제하여 서비스 프로그램이 TPEV_DISCOMN

을 받는 것과 같은 TPEV_DISCOMN 이벤트가 발생하였을 경우, 클라이언트

는 서비스의 tpreturn에 TPESVCERR tperrno를 전송 받게 된다.


설명에러 코드

- 함수 호출자가 트랜잭션 모드에 있을 경우, 트랜잭션 타임아웃이 발생하기

전까지는, 트랜잭션이 Rollback되기 전에 다른 통신들이 시도될 수 있다. 그

러한 통신들은 정상적으로 처리될 수도 있고, 또는 실패할 수도 있다. 이들이

제대로 수행되기 위해서는 TPNOTRAN이 설정되어야 한다. 호출자의 트랜

잭션 모드에서 수행된 작업들은 트랜잭션 완료 시에 모두 Rollback된다.

- Tmax 환경파일에 서비스별로 SVCTIMEOUT을 설정할 수 있는데 서비스의

수행 시간이 이 시간을 초과하게 되면 서비스는 수행을 멈추고 TPESVCERR

를 반환한다. SVCTIMEOUT이 발생하면 tpsvctimeout()을 불러주는데 이 함

수내에서 버퍼 해제, 로깅 작업 등 업무별로 적당한 작업을 할 수 있다.

TPNOBLOCK이 설정된 상태에서, 블로킹 상황이 발생하였다.[TPEBLOCK]

TPSIGRSTRT가 설정되지 않은 상태에서, 시그널이 수신되었다.[TPGOTSIG]

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

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

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

● 예제

#include <stdio.h>

#include <usrinc/atmi.h>

void main(int argc, char *argv[])

{

int ret;

char *sndbuf, *rcvbuf;

long sndlen, rcvlen;

ret=tpstart((TPSTART_T *)NULL);

if (ret==-1) { error processing }

sndbuf = (char *)tpalloc(“CARRAY”, NULL, 20);

if (sndbuf==NULL) {error processing };

rcvbuf = (char *)tpalloc(“CARRAY”, NULL, 20);

if (rcvbuf==NULL) {error processing };

data process....

sndbuf=strlen(sndbuf);

ret=tpcall(”SERVICE”, sndbuf, sndlen, &rcvbuf, &rcvlen, TPNOCHANGE);


data process....

tpfree((char *)sndbuf);

tpfree((char *)rcvbuf);

tpend();

}

제2장 API 9

● 관련 함수

tpalloc(), tpacall(), tpgetrply(), tpreturn()

2.2. 비동기형 call비동기형 call로서는 tpacll과 응답을 받기위한 tpgetrply를 제공한다.

tpacall, tpgetrply는 tmax의 클라이언트 라이브러리및 서버 라이브러리에서 사용하는 API로서 동일한 구

조로 XA 라이브러리에서 사용할 수 있다.

2.2.1. tpacall

서버/클라이언트에서 비동기 서비스 요청을 송신하는 함수니다.

tpacall() 함수는 svc로 명명된 서비스에게 서비스 요청 메시지를 송신한다. 비동기 통신으로 메시지를 송

신한 후에 결과를 받을 때까지 기다리지 않고 바로 반환된다. 결과는 tpgetrply() 함수를 이용하여 응답을

받을 수도 있고, 또는 tpcancel() 함수를 이용하여 응답을 취소할 수 있다.

● 프로토타입

# include <atmi.h>

int tpacall (char *svc, char *data, long len, long flags)

● 파라미터

설명파라미터

호출되는 서비스 이름을 의미한다. 이 서비스는 Tmax 응용 서버 프로그램에

서 제공되고 있는 것이어야 한다.

svc

NULL 값인 경우를 제외하고, 반드시 tpalloc()으로 할당된 버퍼에 대한 포인

터이어야 한다.

data

송신되는 데이터 길이다.len

- data가 가리키는 버퍼가 특별한 길이 명시가 필요 없는 버퍼 유형(STRING,

STRUCT, X_COMMON, X_C_TYPE)이라면 len은 무시되고 보통 0이 사용

된다.

- data가 가리키는 버퍼가 길이 명시가 반드시 필요한 버퍼 유형( X_OCTET,

CARRAY, MULTI STRUCTURE)이라면 len은 0이 될 수 없다.

- data가 NULL이라면 len은 무시되고 데이터 없이 서비스 요청이 송신된다.

data의 유형(type)과 하위 유형(subtype)은 svc가 지원하는 유형이어야 한다.

서비스 요청이 트랜잭션 모드에서 송신되었다면, 해당 응답들은 결과적으로

반드시 수신되어야 한다.


설명파라미터

호출할 때 사용되는 옵션으로 호출 모드를 결정한다.flags

flags로 사용 가능한 값은 다음과 같다.

설명설정값

플래그없이 tpacall() 함수가 사용되었다면, svc에 호출된 서비스가 없거나 잘

못된 결과가 반환되었어도 정상적인 결과가 반환된다.

TPBLOCK

tpgetrply() 함수를 호출할 때 에러가 반환 된다. TPBLOCK 플래그를 이용해

tpacall() 함수 호출할 경우 서비스 상태의 정상 여부를 확인 할 수 있다.

트랜잭션 모드에서 svc가 트랜잭션을 지원하지 않는 서비스라면, tpacall()함

수가 트랜잭션 모드에서 호출되는 경우 플래그는 반드시 TPNOTRAN으로

설정해야 한다.

TPNOTRAN

tpacall() 함수 호출자가 트랜잭션 모드 상태에서 TPNOTRAN을 설정하여 svc

서비스를 요청하였다면, svc 서비스는 트랜잭션 모드에서 제외되어 수행된

다. 트랜잭션 모드 내에서의 tpacall()함수를 호출할 때, TPNOTRAN로 설정

되었어도 여전히 트랜잭션 타임아웃(timeout)에 영향을 받는다.

TPNOTRAN으로 호출된 서비스가 실패하였을 경우, 호출자의 트랜잭션에는

영향을 미치지 않는다.

tpacall()로 송신한 서비스 요청은 응답을 기다리지 않고 즉시 반환한다. 결과

는 나중에 tpacall() 함수에서 반환한 구별자를 이용하여 tpgetrply() 함수로 결

TPNOREPLY

과를 수신한다. flags가 TPNOREPLY로 설정하면 서비스에 대한 응답을 받

지 않겠다고 설정된다. TPNOREPLY로 설정하면 tpacall() 함수는 서비스가

정상적으로 호출되면 0을 반환한다.

함수 호출자가 트랜잭션 모드에 있을 경우에는 반드시 TPNOTRAN 플래그

와 함께 설정해야만 TPNOREPLY 플래그를 사용할 수 있다.

TPNOREPLY 플래그인 경우 서비스 상태의 정상 여부를 체크하기 위해서는

TPBLOCK 플래그를 함께 설정해야 한다. TPBLOCK 플래그를 설정하지 않

으면 서비스가 NRDY인 경우에도 에러를 반환하지 않는다.

내부 버퍼가 송신할 메시지들로 가득 찬 경우와 같은 블로킹(blocking) 상황

을 만나면 서비스 요청은 실패하도록 설정하는 플래그이다.

TPNOBLOCK

TPNOBLOCK 플래그 설정 없이 tpacall() 함수가 호출된 경우 블로킹 상황이

발생하면 함수 호출자는 블로킹 상황이 풀리거나 타임아웃(트랜잭션 타임아

웃 또는 블로킹 타임아웃)이 발생할 때까지 대기한다.

제2장 API 11

설명설정값

함수 호출자가 블로킹 타임아웃을 무시하고 응답이 수신될 때까지 무한정 대

기하도록 설정하는 플래그이다. 트랜잭션 타임아웃 내에서 tpacall()을 한 경

우에는 여전히 트랜잭션 타임아웃이 적용된다.

TPNOTIME

시그널(signal) 인터럽트를 수용하고자 할 때 사용하는 플래그이다.TPSIGRSTRT

시스템 함수 호출이 방해될 때 시스템 함수 호출이 재실행된다. TPSIGRSTRT

가 설정되지 않은 상태에서 신호 인터럽트가 발생하였다면, 함수는 실패하고

tperrno에 TPGOTSIG가 설정된다

● 반환값

설명반환값

함수 호출에 성공한 경우구별자(descriptor)

(반환된 구별자는 송신된 서비스 요청에 대한 응답을 수신하는데 사용된다.)

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


● 오류

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

설명에러 코드

인수가 유효하지 않은 경우 발생한다.[TPEINVAL]

예를 들어, svc가 NULL이거나 data가 tpalloc()으로 할당되지 않은 버퍼를 가

리키거나, 또는 플래그가 유효하지 않다.

svc라는 서비스가 존재하지 않아서 서비스를 요청할 수 없다.[TPENOENT]

data의 유형 및 하위 유형이 svc가 지원하지 않는 유형이다. 구조체 인 경우

사용된 구조체가 SDLFILE 파일에 선언되어 있지 않은 경우 발생한다.

[TPEITYPE]

처리되지 않은 비동기성 서비스 요청 수가 최대 한계에 도달했기 때문에, 호

출자의 서비스 요청이 송신되지 않은 경우 발생한다.

[TPELIMIT]

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

-함수 호출자가 트랜잭션 모드인 경우 : 트랜잭션 타임아웃이 발생한 것이며

트랜잭션은 Rollback된다.

- 함수 호출자가 트랜잭션 모드가 아닌 경우 : TPNOTIME이나 TPNOBLOCK

이 모두 설정되지 않은 상황에서 블로킹 타임아웃이 발생한다.


설명에러 코드

트랜잭션 타임아웃이 발생하는 경우 트랜잭션이 Rollback될 때까지 새로운

서비스 요청을 송신한다거나 아직 수신되지 않은 응답을 기다리는 일은 모두

[TPETIME] 에러로 실패한다.

TPNOBLOCK이 설정된 상태에서, 블로킹 상황이 발생하였다.[TPEBLOCK]

TPSIGRSTRT가 설정되지 않은 상태에서, 시그널이 수신되었다.[TPGOTSIG]

트랜잭션 모드에서의 TPNOREPLY 서비스 호출할 때 TPNOTRAN 플래그를

설정하지 않는 경우 등 부적절한 상황에서 발생한다.

[TPEPROTO]

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


● 예제

#include <stdio.h>



{

char *buf;

int ret,cd;

long len;


if (ret<0) { error processing }

buf = (char *)tpalloc(“CARRAY”, NULL, 20);

if (buf==NULL) {error processing }

data process…

cd = tpacall(“SERVICE”, sndbuf, 20, TPNOTIME);

if (cd<0) {error processing }

data process…

ret=tpgetrply(&cd, (char **)&buf, &len, TPNOTIME);

if (ret<0) { error processing }

data process....

tpfree((char *)buf);

tpend();

}

● 관련 함수

tpalloc(), tpcall(), tpcancel(), tpgetrply()

제2장 API 13

2.2.2. tpgetrply

서버/클라이언트에서 비동기적으로 요청한 서비스에 대한 응답을 수신하는 함수로 tpacall()로 요청한 서

비스에 대한 응답을 수신한다.

● 프로토타입

# include <atmi.h>

int tpgetrply(int *cd, char **data, long *len, long flags)

● 파라미터

설명파라미터

tpacall()에 의해 반환된 호출 구별자를 가리킨다. 보통 cd와 일치하는 응답이

수신되거나 또는 타임아웃이 발생할 때까지 기다린다. 일반적으로 cd는 응답

이 수신된 후에는 더 이상 유효하지 않다.

cd

반드시 이전에 tpalloc()에 의해 할당된 버퍼에 대한 포인터이어야 한다.*data

tpgetrply()가 성공적으로 수신한 데이터의 길이이다. 필요하다면 응답 내용

이 지정된 버퍼에 수신될 수 있도록 버퍼 크기를 증가시킨다. *data는 수신

len

데이터가 커서 변경 될 수도 있고, 이 외에 다른 이유에 의해서도 변경될 수

있다. len이 호출 전 버퍼의 총 크기보다 크다면, len이 그 버퍼의 새로운 크기

가 된다.

len이 0으로 반환되는 경우 어떤 응답도 수신되지 않고 *data와 len이 지시하

는 버퍼 모두 아무런 변화가 없다. *data나 len이 NULL이 되는 것은 에러이

다.

flags로 사용 가능한 값은 다음과 같다:

설명설정값

입력 값으로 준 cd를 무시하고, 이에 상관없이 수신 가능한 응답을 반환하도

록 한다.

TPGETANY

cd는 반환된 응답에 대한 호출 구별자가 된다. 아무런 응답이 없으면, 일반적

으로 tpgetrply()는 응답이 도착할 때까지 대기한다.

*data가 가리키는 버퍼의 유형은 변경되지 못한다.TPNOCHANGE

수신된 응답버퍼와 *data가 가리키는 버퍼의 유형이 다른 경우 *data의 버퍼

유형은 수신자가 인식할 수 있는 한도 내에서 수신된 응답버퍼의 유형으로

변경되는데 TPNOCHANGE 플래그가 설정되는 경우 변경이 안된다 . 수신된

응답 버퍼의 유형 및 하위 유형은 *data가 가리키는 버퍼의 유형 및 하위 유

형과 반드시 일치해야 한다.


설명설정값

응답이 도착할 때까지 대기하지 않는다. 수신 가능한 응답이 있는 경우는 반

환을 한다.

TPNOBLOCK

TPNOBLOCK 플래그가 지정되지 않았고 수신 가능한 응답이 없다면, 함수

호출자는 응답이 도착하거나 또는 타임아웃(트랜잭션 타임아웃이나 블로킹

타임아웃)이 발생할 때까지 대기한다.

함수 호출자가 블로킹 타임아웃을 무시하고 응답이 수신될 때까지 무한정 대

기한다. 트랜잭션 모드에서 tpgetrply()를 한 경우에는 트랜잭션 타임아웃이

적용된다.

TPNOTIME

시그널(signal) 인터럽트를 수용하고자 할 때 사용한다. 시스템 함수 호출이

방해될 때 시스템 함수 호출이 재실행된다. TPSIGRSTRT 플래그가 설정되

TPSIGRSTRT

지 않은 경우 시그널 인터럽트가 발생하였다면, 함수는 실패하고 tperrno에

TPGOTSIG가 설정된다.

● 반환값

설명반환값

함수 호출에 성공한 경우1

(tpreturn()으로 전달되는 tpurcode 전역 변수는 tpgetrply()가 성공적으로 반

환되었거나 tperrno가 [TPESVCFAIL]인 경우, 응용 프로그램(application)에

서 정의한 값을 갖게 된다. )

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


● 오류

TPGETANY가 설정되지 않은 경우, 특별한 언급이 없는 한 *cd는 무효화됨에 유의해야 한다. TPGETANY

가 설정되었다면, cd는 에러가 발생한 응답에 대한 구별자가 된다. 응답이 반환되기 전에 에러가 발생했

다면, cd는 0이 된다. 특별한 언급이 없다면, 호출자의 트랜잭션에 영향을 미치지 않는다.

설명에러 코드

인수가 유효하지 않다. 예를 들어, cd나 data, *data, len 등이 NULL이거나 또

는 flags가 유효하지 않다.

[TPEINVAL]

cd가 NULL이 아니면, 에러 발생 후에도 cd는 유효하며, 그에 대한 응답을 계

속 기다리게 된다.

cd가 유효하지 않은 구별자이다[TPEBADDESC]

- 수신된 응답의 유형 또는 하위 유형이 호출자가 알지 못하는 유형이다.[TPEOTYPE]

제2장 API 15

설명에러 코드

- flags가 TPNOCHANGE로 설정되었는데, *data의 유형 및 하위 유형이 서비

스가 송신한 응답의 것과 맞지 않는 경우로 *data의 내용과 *len은 모두 변경

되지 않는다.

- 응답이 호출자의 트랜잭션 모드에서 수신되었다면, 그 트랜잭션은 응답이

무시되었기 때문에 Rollback된다.

- 타임아웃이 발생한 경우이다.[TPETIME]

- 함수 호출자가 트랜잭션 모드에 있다면, 트랜잭션 타임아웃이 발생하였고

그 트랜잭션은 Rollback된다.

- 트랜잭션 모드가 아니고 TPNOTIME과 TPNOBLOCK 어느 것도 지정되지

않았다면, 블로킹 타임아웃이 발생하였다. 이 두 경우에, *data의 내용과 *len

은 변경되지 않는다. 트랜잭션 타임아웃이 발생하였다면, 새로운 서비스 요

청을 송신한다거나 응답을 기다리는 일은 트랜잭션이 Rollback될 때까지

[TPETIME] 에러로 실패하게 된다.

서비스 요청에 대한 응답을 송신하는 서비스 루틴이 애플리케이션상의 에러

가 발생하여 TPFAIL로 tpreturn()을 호출하였다. 서비스 응답이 수신 되었다

[TPESVCFAIL]

면, 그 내용들은 *data가 가리키는 버퍼를 통하여 사용될 수 있다. 함수 호출

자가 트랜잭션 모드에 있다면, 그 트랜잭션은 Rollback된다.

트랜잭션 타임아웃이 발생하기 전까지는, 트랜잭션이 Rollback 되기 전에 다

른 통신들이 시도될 수 있다. 그러한 통신들은 정상적으로 처리될 수도 있고,

또는 실패할 수도 있다. 이들이 제대로 수행되기 위해서는 TPNOTRAN이 설

정되어야 한다. 호출자의 트랜잭션 모드에서 수행된 작업들은 트랜잭션 완료

시에 모두 Rollback된다.

TPNOBLOCK이 설정된 상태에서, 블로킹 상황이 발생하였다. 구별자(cd)는

유효하다.

[TPEBLOCK]

TPSIGRSTRT가 설정되지 않은 상태에서 시그널이 수신되었다.[TPGOTSIG]

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

트랜잭션 서비스를 호출할 때 데이터베이스에 문제가 발생하여 xa_start가

실패하였다.

[TPETRAN]

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


● 예제

#include <stdio.h>




{

int ret;

long len;

char *buf;



buf = (char *)tpalloc(“STRING”, NULL, 0);

if (buf==NULL) { error processing }

data process …

cd = tpacall(“SERVICE”, buf, 0, TPNOFLAGS);

if (cd==-1) { error procesing }

data process....

ret=tpgetrply(&cd, &buf, &len, TPNOTIME);


data process....

tpfree(buf);

tpend();

}

● 관련함수

tpacall(), tpalloc(), tpreturn()

제2장 API 17

제3장 예제

본 장에서는 Tmax XA 서비스를 호출하는 간단한 예제를 기술한다.

/* Tmax의 xa switch openinfo */

#define OPENINFO

"host=192.168.1.43:7000+dbglvl=1+timeout=10"

/* Tmax의 xa switch closeinfo */

#define CLOSEINFO ""

extern struct xa_switch_t tmaxxaosw;

struct xa_switch_t _xasw;

int _xa_load(int xaoption)

{

_xasw.name[0] = 0;

_xasw = tmaxxaosw;

if (_xasw.name[0] == 0)

return -1;

return 1;

}

int main(int argc, char **argv)

{

….

XID xid;

// XA 정보 로드

ret = _xa_load(0);

if (ret < 0) {

error processing…

}

// xa open

ret = xa_open(OPENINFO, rmid, TMNOFLAGS);

if (ret < 0) {

error processing…

}

….

// xa start

ret = xa_start(&xid, rmid, TMNOFLAGS);

if (ret < 0) {

error processing…

}

제3장 예제 19

// Tmax xa 서비스 호출

ret = call_tmax(“SVCA”, sndbuf, rcvbuf);

if (ret < 0) {

error processing…

}

// xa end

ret = xa_end(&xid, rmid, TMSUSPEND);

if (ret < 0) {

error processing…

}

// xa start

ret = xa_start(&xid2, rmid, TMRESUME | TMJOIN);

if (ret < 0) {

error processing…

}

/* tpcall을 포함하는 function */

// Tmax xa 서비스 호출

ret = call_tmax(svcname, sndbuf, rcvbuf);

if (ret < 0) {

error processing…

}

// xa end

ret = xa_end(&xid2, rmid, TMSUCCESS);

if (ret < 0) {

error processing…

}

// xa prepare

ret = xa_prepare(&xid, rmid, TMNOFLAGS);

if (ret < 0) {

error processing…

}

// xa prepare

ret = xa_prepare(&xid2, rmid, TMNOFLAGS);

if (ret < 0) {

error processing…

}

else if (ret == XA_RDONLY) {

// xa commit

ret = xa_commit(&xid, rmid, TMNOFLAGS);

if (ret < 0) {

error processing…

}


}

else {

ret = xa_commit(&xid, rmid, TMNOFLAGS);

if (ret < 0) {

error processing…

}

ret = xa_commit(&xid2, rmid, TMNOFlAGS);

if (ret < 0) {

error processing…

}

}

// xa close

ret = xa_close(CLOSEINFO, rmid, TMNOFLAGS);

if (ret < 0) {

error processing…

}

…

}

// Tmax 서비스 호출 루틴

int call_tmax(char *svcname, char * sndbuf, char * rcvbuf)

{

…

ret = tpcall(svcname, (char *)sndbuf, strlen(sndbuf), (char **)&rcvbuf,

(long *)&rcvlen, TPNOFLAGS);

if(ret < 0) {

error processing…

}

…

}

제3장 예제 21

tmax xa library and gateway guide · 2019. 4. 9. · *gateway xagw1 gwtype = xagw, portno = 10042,...

Documents