ALTIBASE HDB Application Development Application Program Interface User s Manual Release 6.3.1 (April 16, 2015)
----------------------------------------------------------- ALTIBASE Application Development Application Program Interface User s Manual Release 6.3.1 Copyright c 2001~2015 ALTIBASE Corp. All Rights Reserved. 본문서의저작권은 알티베이스에있습니다. 이문서에대하여당사의동의없이무단으로복제또는전용할수없습니다. 알티베이스 152-790 서울시구로구구로동 182-13 대륭포스트타워 Ⅱ 10 층전화 : 02-2082-1114 팩스 : 02-2082-1099 고객서비스포털 : http://support.altibase.com homepage: http://www.altibase.com -----------------------------------------------------------
목차 서문... 5 이매뉴얼에대하여... 6 1. PHP Interface... 11 ALTIBASE HDB PHP 모듈참고사항... 12 PHP 연동을위한 ODBC 매니저설치... 13 ODBC 연결을위한 PHP 함수... 15 2. PERL DBD DBI... 17 Perl DBD와 DBI 개요... 18 Perl 패키지설치... 19 ALTIBASE HDB DBD 설치... 20 3..NET Data Provider... 23.NET Data Provider의개요... 24.NET Data Provider 사용방법... 26.NET Data Provider 인터페이스... 36.NET Data Provider 예제... 40 4. XA Interface... 45 XA 개요... 46 XA 인터페이스... 51 XA 사용... 56 XA 사용시제약사항... 63 JDBC 분산트랜잭션... 66 XA를사용한애플리케이션의문제해결... 79 5. iloader API... 83 iloader API 개요... 84 iloader API 사용... 85 iloader API 데이터구조체... 86 목차 3
iloader API... 92 6. CheckServer API... 107 CheckServer API 개요... 108 CheckServer API 사용... 109 CheckServer API 데이터구조체... 110 CheckServer API... 111 찾아보기... 116 4 API User s Manual
서문 서문 5
이매뉴얼에대하여 이매뉴얼은 API 사용법에대해설명한다. 대상사용자 이매뉴얼은다음과같은 ALTIBASE HDB 사용자를대상으로작성되었다. 데이터베이스관리자 성능관리자 데이터베이스사용자 응용프로그램개발자 기술지원부다음과같은배경지식을가지고이매뉴얼을읽는것이좋다. 컴퓨터, 운영체제및운영체제유틸리티운용에필요한기본지식 관계형데이터베이스사용경험또는데이터베이스개념에대한이해 컴퓨터프로그래밍경험 데이터베이스서버관리, 운영체제관리또는네트워크관리경험 소프트웨어환경 이매뉴얼은데이터베이스서버로 ALTIBASE HDB 버전 6.3.1 을 사용한다는가정하에작성되었다. 이매뉴얼의구성 이매뉴얼은다음과같이구성되어있다. 제 1 장 PHP Interface 이장은 PHP 에서 ODBC 함수를이용하여 ALTIBASE HDB 와연동하는방법을설명한다. 제 2 장 PERL DBD DBI 이장은 PerL DBD (Database Driver) 와 DBI (Database 6 API User s Manual
Interface) 가무엇인지살펴보고, 이를사용하기위해 Perl 패키지설치및 ALTIBASE HDB DBD 설치를어떻게하는지, ALTIBASE HDB DBD 검증등은어떻게이뤄지는지에대해설명한다. 제 3 장.NET Data Provider 이장은마이크로소프트의 ADO.NET 인터페이스를 ALTIBASE HDB 와함께사용하기위한방법을설명한다. 제 4 장 XA Interface 이장은 XA 표준을소개하고, 분산트랜잭션의기본개념과 XA 인터페이스를설명한다. 그리고 ODBC, Embedded SQL, JDBC 프로그램에서글로벌트랜잭션을사용하여 ALTIBASE HDB 에접근하는방법에대해설명한다. 제 5 장 iloader API 이장은 ALTIBASE HDB 서버로부터데이터를다운로드또는서버로데이터를업로드하는응용프로그램을작성할수있는인터페이스인 ALTIBASE HDB iloader API 를소개한다. 제 6 장 CheckServer API 이장은 ALTIBASE HDB 서버가비정상종료했는지를감시하는응용프로그램을작성하기위해사용하는인터페이스인 ALTIBASE HDB CheckServer API 를소개한다. 문서화규칙 이절에서는이매뉴얼에서사용하는규칙에대해설명한다. 이규칙을이해하면이매뉴얼과설명서세트의다른매뉴얼에서정보를쉽게찾을수있다. 여기서설명하는규칙은다음과같다. 구문다이어그램 샘플코드규칙 구문다이어그램 이매뉴얼에서는다음구성요소로구축된다이어그램을사용하여, 명령문의구문을설명한다. 구성요소 예약어 의미명령문이시작한다. 완전한명령문이아닌구문요소는화살표로시작한다. 명령문이다음라인에계속된다. 완전한명령문이아닌구문요소는이기호로종료한다. 서문 7
명령문이이전라인으로부터계속된다. 완전한 명령문이아닌구문요소는이기호로시작한다. ; 명령문이종료한다. SELECT 필수항목 선택적항목 NOT ADD 선택사항이있는필수항목. 한항목만제공해야한다. DROP 선택사항이있는선택적항목 ASC DESC ASC 선택적항목. 여러항목이허용된다. 각반복앞부분에 콤마가와야한다. DESC, 샘플코드규칙 코드예제는 SQL, Stored Procedure, isql 또는다른명령라인 구문들을예를들어설명한다. 아래테이블은코드예제에서사용된인쇄규칙에대해설명한다. 규칙 의미 예제 [ ] 선택항목을표시 VARCHAR [(size)] [[FIXED ] VARIABLE] 필수항목표시. 반드시하나이상을선택해야되는표시 ENABLE DISABLE COMPILE 선택또는필수항목표시의인자구분표시. 그이전인자의반복표시. 예제코드들의생략되는것을. 표시 ENABLE DISABLE COMPILE [ ENABLE DISABLE COMPILE ] SQL> SELECT ename FROM employee; ENAME ----------------------- 8 API User s Manual
그밖에기호기울임꼴소문자대문자 위에서보여진기호이외에기호들구문요소에서사용자가지정해야하는변수, 특수한값을제공해야만하는위치지정자사용자가제공하는프로그램의요소들, 예를들어테이블이름, 칼럼이름, 파일이름등시스템에서제공하는요소들또는구문에나타나는키워드 SWNO HJNO HSCHOI... 20 rows selected. EXEC :p1 := 1; acc NUMBER(11,2); SELECT * FROM table_name; CONNECT userid/password; SELECT ename FROM employee; DESC SYSTEM_.SYS_INDICES_; 관련자료 자세한정보를위하여다음문서목록을참조하기바란다. Installation Guide Administrator s Manual Replication Manual CLI User's Manual Precompiler User s Manual ODBC User's Manual isql User s Manual Utilities Manual Error Message Reference 온라인매뉴얼 Altibase 고객서비스포털 (http://support.altibase.com) 에서국문 및영문매뉴얼 (PDF, HTML) 을받을수있다. 서문 9
Altibase 는여러분의의견을환영합니다. 이매뉴얼에대한여러분의의견을보내주시기바랍니다. 사용자의의견은다음버전의매뉴얼을작성하는데많은도움이됩니다. 보내실때에는아래내용과함께고객서비스포털 (http://support.altibase.com/kr/) 로보내주시기바랍니다. 사용중인매뉴얼의이름과버전 매뉴얼에대한의견 사용자의성함, 주소, 전화번호이외에도 Altibase 기술지원설명서의오류와누락된부분및기타기술적인문제들에대해서이주소로보내주시면정성껏처리하겠습니다. 또한, 기술적인부분과관련하여즉각적인도움이필요한경우에도고객서비스포털을통해서비스를요청하시기바랍니다. 여러분의의견에항상감사드립니다. 10 API User s Manual
1. PHP Interface 이장에서는 PHP 에서 ODBC 함수를이용하여 ALTIBASE HDB 와 연동하는방법을설명한다. PHP Interface 11
ALTIBASE HDB PHP 모듈참고사항 PHP 에서지원하는데이터타입은다음과같다. resource, int, bool, double, float, string, array, HashTable ALTIBASE HDB 서버의포트번호와 ALTIBASE HDB 에서제공한샘플프로그램의 db.php 에서포트번호를맞춰야한다. 12 API User s Manual
PHP 연동을위한 ODBC 매니저설치 유닉스또는윈도우환경에서 PHP 로 ALTIBASE HDB 에연동을하기위해서는먼저 ODBC 매니저를설치해야한다. 이절에서는유닉스, 리눅스와윈도우에서 ODBC 매니저를설치하고사용환경을설정하는방법을설명한다. 유닉스와리눅스 리눅스또는유닉스환경에서다음절차대로 ODBC 매니저를 설치한다. 1. unixodbc 다운로드한다. unixodbc 홈페이지 (http://www.unixodbc.org) 에서 다운로드할수있다. 2. unixodbc 설치한다. 다운로드한 unixodbc 소스파일을컴파일해야한다. 컴파일된라이브러리를특정위치에설치하려면, configure 할 때 prefix 옵션으로경로를입력한다../configure -prefix= 설치경로 -enable-gui=no - enabledrivers=no make make install 3. unixodbc 환경을설정한다. ODBCSYSINI 환경변수의값을 ALTIBASE HDB 설치계정의홈디렉터리경로로설정한다. export ODBCSYSINI=~ 4. unixodbc Driver Manager 가설치된경로를다음과같이 환경변수에추가한다. 라이브러리경로를설정하는환경변수는 플랫폼과운영체제의 bit 에따라서 LD_LIBRARY_PATH, LD_LIBRARY_PATH_64, SHLIB_PATH 중의하나일수있다. 다음은 unixodbc 를 /usr/local/odbcdrivermanager32 또는 /usr/local/odbcdrivermanager64 에설치한예이다. export LD_LIBRARY_PATH= /usr/local/odbcdrivermanager32/lib:$ld_library_path export LD_LIBRARY_PATH_64= /usr/local/odbcdrivermanager64/lib:$ld_library_path_64 PHP Interface 13
5. ODBCSYSINI 환경변수의경로에다음 2 개의파일을생성한다. odbc.ini odbcinst.ini 6. odbcinst.ini 는실제내용이없는 0 byte 파일이다. 7. odbc.ini 에는 DSN 이름및 ALTIBASE HDB ODBC 드라이버 파일의위치, 서버의 IP 주소, 접속포트번호를아래처럼 설정한다. [Altibase] Driver = /home/altibase/altibase_home/lib/libaltibase_odbc.so Server = 127.0.0.1 Port = 20300 윈도우 윈도우환경은 ODBC 매니저가기본으로설치되어있어, ALTIBASE HDB 를설치할때 ODBC 매니저에 ALTIBASE HDB ODBC 드라이버를자동으로등록한다. 14 API User s Manual
ODBC 연결을위한 PHP 함수 ALTIBASE HDB 는표준 ODBC 를지원함으로써 PHP 에서이 ODBC 함수들을사용하여 ALTIBASE HDB 서버와연동할수있다. PHP 에서사용하는 ODBC 함수들에대한자세한설명은아래의 PHP 공식매뉴얼사이트를참조한다 : http://php.morva.net/manual/kr/index.php Sample Test <? // SYSTEM DSN, USER_ID, USER_PASSWORD $conn = odbc_connect("altibase", "SYS", "MANAGER"); if ($conn) // direct-execution echo "now, i create table t1 (id integer, name char(20)<br>"; odbc_exec($conn, "drop table t1"); odbc_exec($conn, "create table t1 (id integer, name char(20))"); // prepare-execution echo "now, i insert into t1 value (100, Lee)<br>"; $stmt = odbc_prepare ($conn, "insert into t1 values (?,?)"); $Insert = array (100, "Lee"); if (!odbc_execute($stmt, &$Insert)) echo ("error"); // single-selection $res = odbc_do ($conn, "select id, name, sysdate from T1"); odbc_fetch_row ($res); $ID = odbc_result($res, 1); $NAME = odbc_result($res, 2); $DATE = odbc_result($res, 3); echo ("id = $ID, name = $NAME datetime = $DATE <br>"); odbc_close($conn);?> PHP Interface 15
2. PERL DBD DBI 이장에서는 PerL DBD (Database Driver) 와 DBI (Database Interface) 가무엇인지살펴보고, 이를사용하기위해 Perl 패키지설치및 ALTIBASE HDB DBD 설치를어떻게하는지, ALTIBASE HDB DBD 검증등은어떻게이뤄지는지에대해설명한다. PERL DBD DBI 17
Perl DBD 와 DBI 개요 DBI 는 Perl 을위한표준데이터베이스인터페이스모듈이다. 이는일련의메소드 (methods) 와속성 (attributes) 을정의한것으로, 실제사용하는데이터베이스에독립적인일관된인터페이스를제공한다. DBI 는애플리케이션에서동일한인터페이스를사용하여여러다른데이터베이스에서제공하는 DBD 에접근하는것을가능하게한다. 실제로데이터베이스와통신을하는것은 DBD 이다. ALTIBASE HDB 에서제공하는드라이버 (DBD) 를 DBD::altibase 라고부른다. 이들메소드와속성들은 database 메소드와속성, 그리고 statement 메소드와속성으로나뉘어져있다. DBI Altibase DBD Oracle DBD DB2 DBD mysql DBD Altibase Oracle DB2 mysql [ 그림 2-1] PERL DBD 와 DBI 구조도 18 API User s Manual
Perl 패키지설치 Perl 패키지설치절차 1. 사용하는장비의운영체제의버전에맞게 Perl 패키지를 다운로드받는다. ( 예를들어 SunOS 의 Perl 패키지는 http://www.sunfreeware.com 에서다운로드받을수있다.) 2. 임의의디렉터리에서패키지 (ex. perl-5.8.5.tar.gz) 의압축을 푼다. gzip -cd perl-5.8.5.tar.gz tar xvf 3. Perl 패키지의압축을푼디렉터리에서 configure 를수행한다../configure 4. Perl 패키지의압축을푼디렉터리에서 make 를수행한다. make 5. Perl 패키지의압축을푼디렉터리에서 root 계정으로 컴파일한모듈을설치한다. make install 6. Event 모듈설치를위해서 event 패키지 (ex. Event-1.00.tar.gz) 를다운로드받는다. 7. 임의의디렉터리에서 Event-1.00.tar.gz 의압축을푼다. gzip -cd Event-1.00.tar.gz tar xvf 8. Event 패키지의압축을푼디렉터리에서 configure 를 수행한다../configure 9. Event 패키지의압축을푼디렉터리에서 make 를수행한다. make 10. Event 패키지의압축을푼디렉터리에서 root 계정으로 컴파일한모듈을설치한다. make install PERL DBD DBI 19
ALTIBASE HDB DBD 설치 ALTIBASE HDB PERL DBD 설치절차 1. perl V 를실행하여 dlext 설정이올바른지확인한다. 이때 HP 는 sl, 다른플랫폼은 so 이어야한다. 이값이 잘못되었으면다시 Perl 을설치한다. 2. Perl DBI 설치 Perl DBD 컴파일하기위한선행절차로 Perl DBI 패키지를 설치한다. 방법 1) root 계정으로 # perl -MCPAN -e shell prompt> install DBI 방법 2) 상기방법으로안될경우, 아래 ftp 사이트에서 DBI 패키지를다운받아컴파일한후에설치한다. ftp://ftp.nuri.net/pub/cpan/modules/by-module/dbi 2-1) perl Makefile.PL 2-2) make 2-3) make install 3. 아래위치에서 ALTIBASE HDB Perl DBD 를다운로드하고설치한다. ALTIBASE HDB Perl DBD 는 32bit 이기때문에 ALTIBASE HDB 32bit 클라이언트패키지또는 32bit 서버패키지가이미설치되어있어야하고, ALTIBASE_HOME 환경변수도올바르게설정되어있어야한다. http://data.altibase.com/download_back/altibase/p ERL-DBD/altibase-perlDBD.tar.gz gzip cd altibase-perldbd.tar.gz tar xvf - 4. 다운로드한패키지내의 install.mk 를사용해서 ALTIBASE HDB DBD 를생성하는데필요한 Makefile 을생성한다. make -f install.mk 5. 컴파일한다. make ALTIBASE HDB Perl DBD 는 shared library 형태로생성된다. HP 플랫폼에서는 altibase.sl 의이름으로생성된다. HP 이외의플랫폼에서는 altibase.so 의이름으로생성되며, 생성되는위치는 blib/arch/auto/dbd/altibase 이다. 20 API User s Manual
6. root 계정으로 make install 을실행한다. ALTIBASE HDB Perl DBD 가 Perl 에설치된다. 이예제에서는 ALTIBASE HDB DBD 는아래위치에설치된다. /opt/perl_5.8.8/bin/lib/site_perl/5.8.8/ia64.arch REV_0/auto/DBD/altibase 7. LD_PRELOAD 환경변수를설정한다. HP 또는일부플랫폼은이단계를수행해야한다. 이작업을 수행하지않을경우오류메시지가나타난다. 8. perl test.pl 을수행해서테스트한다. ALTIBASE HDB 서버를구동한후, test.pl 파일의소스코드를 아래와같이수정한후에 perl test.pl 을수행한다. my $dbh = DBI- >connect("dbi:altibase:dsn=127.0.0.1;uid=sys;pwd =MANAGER;CONNTYPE=1;NLS_USE=US7ASCII;PORT_NO=209 99", "", "", 'RaiseError' => 1); PERL DBD DBI 21
3..NET Data Provider 이장에서는마이크로소프트의 ADO.NET 인터페이스를 ALTIBASE HDB 와함께사용하기위한방법을설명한다..NET Data Provider 23
.NET Data Provider 의개요 개요 ALTIBASE HDB.NET Data Provider 는마이크로소프트의 ADO.NET 인터페이스를 ALTIBASE HDB 에서사용하기위해구현한것이다. 즉, 닷넷프레임워크 (.NET Framework) 기반의애플리케이션에서 ALTIBASE HDB 를사용하기위해서는 ALTIBASE HDB.NET Data Provider 를사용해야한다. ADO.NET 인터페이스는닷넷프레임워크를사용하여 DBMS 와같은데이터소스에접근하게되며, 닷넷프레임워크는 ODBC 와 OLEDB 인터페이스를지원하며, SQLServer 와 ORACLE 에접근하는방법을기본으로제공한다. 닷넷프레임워크에기반한 Data Provider 의역할은데이타소스에접근하여명령어를수행하고결과값을추출해오는것이다. 이렇게가져온결과값을 ADO.NET DataSet 클래스를이용하여개발자가가공하고다시데이타소스에반영하게된다. ADO.NET 인터페이스가장큰장점은 ALTIBASE HDB 버전을업그레이드하더라도, 새로운 ALTIBASE HDB 와일치하도록 CLI 라이브러리만업그레이드하면 Data Provider 나애플리케이션을변경하지않고계속사용할수있다는것이다. 기타 ADO.NET 의자세한내용은마이크로소프트의홈페이지 (http://www.msdn.com) 를참고한다. 요구사항.NET Framework 사용할 ADO.NET 버전에호환하는.NET Framework 을설치해야한다. 예를들어, ADO.NET 1.0 을사용하는경우에는.NET Framework 1.1 이상을, ADO.NET 2.0 을사용할때에는.NET Framework 2.0 SP1 이상을설치해야한다. ADO.NET 버전에따라서다른.NET Data Provide 라이브러리파일을제공하므로, 사용하려는 ADO.NET 버전에적합한라이브러리를사용해야한다. Altibase CLI 24 API User s Manual
ALTIBASE HDB.NET Data Provider 는 Altibase CLI 라이브러리를이용하여데이터베이스서버에접속하므로 Altibase CLI 라이브러리를설치해야한다. 주의사항및제약사항.NET Data Provider 는 CLI 라이브러리를사용하므로해당시스템에맞는 odbccli_sl.dll 과함께사용해야한다..NET Framework 버전에따라일부구현이다르므로, 해당하는.NET Framework 버전을위해빌드된.NET Data Provider 를사용해야한다. ColumnName 속성은 DataReader, CommandBuilder 등에서대소문자를구별한다. 테이블을생성할때큰따옴표를이용해칼럼이름을감싸지않은경우, 컬럼이름은대문자로변환된다. 이경우대문자로된칼럼이름을사용해야올바른값을가져올수있다. NUMBER, NUMERIC, FLOAT, DECIMAL 타입컬럼으로부터 DataReader.GetValue() 를사용해서데이터를가져올때, 데이터손실이발생할수있다. 이는이함수가숫자데이터를.NET System.Decimal 타입으로변환하는데, 이때가져온데이터의범위가 System.Decimal 로표현할수있는범위를넘는경우이다. ALTIBASE HDB.NET Data Provider 는다중쿼리문의실행을지원하지않는다. 여러개의 SQL 문을한번에실행하려면저장프로시저를사용하도록한다..NET Data Provider 25
.NET Data Provider 사용방법 ALTIBASE HDB 가설치된디렉터리 ( 환경변수 %ALTIBASE_HOME%) 내의 lib 디렉터리에.NET Data Provider 가존재한다. 파일의이름은다음과같다. %ALTIBASE_HOME%\lib\Altibase.Data.AltibaseClient.dll.NET 응용프로그램컴파일 ALTIBASE HDB.NET Data Provider 를사용한애플리케이션은아래 2 가지방법으로컴파일할수있다. 커맨드라인에서컴파일하는방법 커맨드라인에서소스파일을컴파일을할때에는아래와같이 DLL 를참조합니다. csc /r:%altibase_home%\lib\altibase.data.altibaseclient.dll 프로그램명.cs IDE 환경에서컴파일하는방법 IDE (Integrated Development Environment) 환경에서.NET Data Provider 등록하는방법이다. ( 예 MS Viaual Studio) 1. 새프로젝트를연다. 26 API User s Manual
[ 그림 3-1] 새프로젝트열기 2..NET Data Provider 를등록하기위해, References 에마우스 오른쪽버튼을클릭하여 참조추가 메뉴를클릭한다. [ 그림 3-2] 프로젝트의참조추가설정 3. ALTIBASE HDB 설치디렉터리내의 lib 디렉터리에서 Altibase.Data.AltibaseClient.dll 를찾아등록한다. ALTIBASE.NET Data Provider 27
HDB 설치디렉터리는환경변수 %ALTIBASE_HOME% 으로 확인한다. [ 그림 3-3].NET Data Provider 를프로젝트에등록 4. 프로젝트를빌드하고생성된실행파일을실행한다. 배열바인딩 (Array Binding) ALTIBASE HDB.NET Data Provider 는배열바인딩을지원하는데, 즉배열형태의데이터에대하여파라미터바인딩이가능하다. 이는일반적인바인딩방법보다적은네트워크비용으로여러개의열을처리하므로속도향상을기대할수있다. 현재는입력 (Input) 파라미터로만배열바인딩을지원하며, 출력 (Output) 이나입출력공용파라미터의배열바인딩은지원하지않는다. 배열바인딩순서는다음과같다. 1. 바인드하려는변수들을모두배열로잡는다. 이때배열 크기는 AltibaseCommand 클래스의 ArrayBindCount 값보다 크거나같아야한다. 2. 배열변수들을파라미터에바인드한다. 만약바인드하려는 칼럼이 CHAR, VARCHAR, BLOB 타입인경우에는, 파라미터 28 API User s Manual
설정시 AltibaseParameter 클래스의 ArrayBindSize 를배열 요소중최대큰것과같은크기로설정해야한다. 3. AltibaseCommand 클래스의 ArrayBindCount 값을세팅한다. 예 : 한번에 100 개씩입력하는경우 ArrayBindCount = 100; 4. SQL 구문을실행한다. 주의사항 배열바인딩할때다음사항을주의해야한다. ArrayBindCount 의유효범위는 1 부터 65535 까지이다. 배열 크기를무조건크게잡는다고속도가빨라지는것은아니므로 적당한크기로바인딩한다. CHAR, VARCHAR, BLOB 타입의경우배열단일요소의데이터 길이가 ArrayBindSize 를넘을경우에러가발생한다. NCHAR, NVARCHAR 타입의경우, ArrayBindSize 값은 byte 가 아닌문자수로세팅해야한다. BLOB 타입의경우, 소스프로그램에서배열타입으로 Object 를 사용하고, 배열원소는 byte[] 를사용한다. 예 : byte[] var1; byte[] var2; Object[] var = new Object[2] var1, var2; CLOB, BYTE, NIBBLE, BIT, VARBIT, GEOMETRY 타입의배열 바인딩은지원하지않는다. 예제 using System; using System.Data; using Altibase.Data.AltibaseClient; class ArrayBind static void Main() AltibaseConnection con = new AltibaseConnection(); con.connectionstring = "DSN=127.0.0.1;UID=sys;PWD=manager;NLS_USE=KO16KSC5601"; con.open(); Console.WriteLine("Connected successfully"); // table: create table t1 (c1 int, c2 varchar(12)); // 3 records const int arraybindcount = 3; int[] c1 = new int[arraybindcount] 100, 200, 300; String[] c2 = new String[arrayBindCount] "APPLE", "ORANGE", "GRAPE" ;.NET Data Provider 29
AltibaseCommand cmd = new AltibaseCommand(); cmd.connection = con; //===================================================== // bind parameters //===================================================== cmd.commandtext = "insert into t1 values (?,?)"; AltibaseParameter prm1 = new AltibaseParameter("c1", DbType.Int32); prm1.direction = ParameterDirection.Input; prm1.value = c1; AltibaseParameter prm2 = new AltibaseParameter("c2", DbType.AnsiString); prm2.direction = ParameterDirection.Input; prm2.value = c2; prm2.arraybindsize = 12; // max element size in bytes cmd.parameters.add(prm1); cmd.parameters.add(prm2); //===================================================== // execute INSERT //===================================================== cmd.arraybindcount = arraybindcount; cmd.executenonquery(); //===================================================== // SELECT //===================================================== IDataReader sdatareader = null; cmd.parameters.clear(); cmd.commandtext = "select * from t1"; sdatareader = cmd.executereader(); while (sdatareader.read()) for (int i = 0; i < sdatareader.fieldcount; i++) Console.Write("[" + sdatareader.getvalue(i) + "] "); Console.WriteLine(); sdatareader.close(); con.close(); con.dispose(); ALTIBASE HDB.NET Data Provider 사용선언 ALTIBASE HDB.NET Data Provider 클래스들을사용려면, 먼저아래와같이선언하여야있다. 30 API User s Manual
using Altibase.Data.AltibaseClient;.NET Data Provider 31
트랜잭션처리 ADO.NET 에서제공하는트랜잭션처리인터페이스를이용하여 트랜잭션을처리할수있다. ADO.NET 인터페이스를이용한트랜잭션처리는 AltibaseConnection.BeginTransaction() 와 AltibaseTransaction 객체를사용한다. AltibaseConnection sconn = new AltibaseConnection(sConnStr); sconn.open(); // 트랜잭션시작 AltibaseTransaction strans = sconn.begintransaction(); AltibaseCommand scmd = sconn.createcommand(); // 트랜잭션작업... // TODO // 트랜잭션끝 strans.commit(); 스키마 ALTIBASE HDB 는 GetSchema() 메소드를사용해서 MetadataCollections, DataSourceInformation, DataTypes, Restrictions, ReservedWords 와같은공통스키마이외에도 ALTIBASE HDB 에서지원하는다음과같은메타정보스키마를조회해볼수있도록지원한다. 스키마메타테이블설명 Users Tables Views SYS_USERS_ SYS_TABLES_ SYS_VIEWS_ 사용자관련정보를저장하는메타테이블테이블관련정보를저장하는메타테이블뷰관련정보를저장하는메타테이블 32 API User s Manual
Sequences V$SEQ Synonyms SYS_SYNONYMS_ Indexes SYS_INDICES_ Columns SYS_COLUMNS_ Constraints SYS_CONSTRAINTS_ Procedures SYS_PROCEDURES_ ProcedureParameters SYS_PROC_PARAS_ [ 표 3-1] ALTIBASE에서지원하는메타정보스키마 시퀀스관련정보를저장하는성능뷰시노님관련정보를저장하는메타테이블인덱스정보를기록하고있는메타테이블칼럼관련정보를저장하는메타테이블제약조건관련정보를저장하는메타테이블저장프로시저및함수관련정보를저장하는메타테이블저장프로시저및함수의파라미터관련정보를저장하는메타테이블 ALTIBASE HDB 에서지원하는각각의스키마에대한자세한 설명은 General Reference 의데이터딕셔너리를참조한다. ALTIBASE HDB.NET Data Provider 클래스 ALTIBASE HDB 의.NET Data Provider 는데이타베이스와의연결, 질의실행및결과검색을위한기능을제공한다. 이기능들은아래표에서보여주는 4 개의클래스에기반하고있다. 각클래스들의하위메소드기능은마이크로소프트의 ADO.NET 문서을참조한다. 클래스 AltibaseConnection 설명 데이터베이스와의연결을설정하고 트랜잭션을시작할수있다..NET Data Provider 33
데이터베이스에서질의문을실행하고 AltibaseCommand 매개변수를표시할수있다. 데이터베이스에서명령수행에대한 AltibaseDataReader 결과를가져와출력할수있다. DataSet에데이터를채우고 AltibaseDataAdapter 데이터베이스로저장된데이터를갱신할수있다. [ 표 3-2] 연결및질의실행, 결과검색을위한 ALTIBASE HDB.NET Data Provider 클래스 ALTIBASE HDB.Net Data Provider 는예외처리, 저장프로시저실행과트랜잭션처리등을위해다음클래스들을제공한다. 클래스설명데이터베이스오류나,.Net Framework을 AltibaseException 통해받은클라이언트오류를받아표시할수있다. SQL 명령및저장프로시저에대한 AltibaseParameter 입력, 출력파라미터를정의한다. 데이터베이스에서트랜잭션관련명령을 AltibaseTransaction 수행할수있도록한다. [ 표 3-3] 예외처리, 트랜잭션처리를위한 ALTIBASE HDB.NET Data Provider 클래스 ALTIBASE HDB.NET Data Provider 데이터타입 테이블칼럼이나파라미터의데이터타입을선언하기위해서 AltibaseType 클래스가사용된다. 아래표를통해 ALTIBASE HDB 가제공하는데이터타입과.NET Framework 의데이터타입간의관계를확인할수있다. ALTIBASE HDB AltibaseType 데이터베이스칼럼.NET Framework 타입 BigInt BIGINT Int64 Bit BIT Byte[] Blob BLOB Byte[] Byte BYTE Byte[] Char CHAR String 34 API User s Manual
Clob CLOB String DateTime DATE DateTime Decimal DECIMAL Decimal Double DOUBLE Double Float FLOAT Decimal Geometry GEOMETRY Byte[] Integer INT Int32 NChar NCHAR String Nibble NIBBLE Byte[] Number NUMBER Decimal Numeric NUMERIC Decimal NVarChar NVARCHAR String Real REAL Float SmallInt SMALLINT Int16 VarBit VARBIT Byte[] VarChar VARCHAR String [ 표 3-4] 데이터타입간의관계 SQL 구문내에내셔널캐릭터를포함하는상수문자열을 사용하려면, 해당문자열바로앞에 N 을붙이면된다..NET Data Provider 35
.NET Data Provider 인터페이스 인터페이스설정 ADO.NET 2.0 부터프로바이더에독립적인프로그래밍이가능하다. DbProviderFactories 클래스는사용자가요구하는프로바이더의 DbProviderFactory 클래스의인스턴스를얻게해준다. 따라서사용자는 DbProviderFactory 인스턴스로부터 DbConnection 이나 DbCommand 객체를생성하여사용할수있다. 그러나 DbProviderFactories 를사용하기위해서는.NET Framework 의설정파일에해당.NET Data Provider 의팩토리정보가등록되어야있어야한다. 팩토리정보를등록하기위한다음두가지방법이있다..NET Framework 설정파일에등록하는방법 애플리케이션환경설정파일을사용하는방법환경설정파일은 xml 파일로되어있으며, 프로바이더정보는 system.data - DbProviderFactories 의하위항목에있다. 여기에 ALTIBASE HDB.NET Data Provider 에대한정보를추가하면된다..NET Framework 설정파일에등록하는방법.NET Framework 의설정파일은설치된폴더하위에있는 CONFIG 폴더에 machine.config 라고저장되어있다. 일반적으로.NET Framework 는 %windir%\microsoft.net\framework 에 버전별로설치된다..NET Framework 2.0 의경우설정파일의위치는보통다음과 같다. c:\windows\microsoft.net\framework\v2.0.50727\config\ machine.config machine.config 파일을열어서 system.data - DbProviderFactories 의하위아이템으로 ALTIBASE HDB.NET Data Provider 에대한정보를다음과같이추가한다. <add name="altibase Data Provider" invariant="altibase.data.altibaseclient" description="altibase Data Provider" 36 API User s Manual
애플리케이션환경설정파일을사용하는방법 type="altibase.data.altibaseclient.altibasefactory, Altibase.Data.AltibaseClient" /> 애플리케이션환경설정파일은 " 실행파일이름.config" 라는이름으로, 실행파일이있는디렉터리에저장된다. 예를들어실행파일의이름이 AltiTest.exe 일경우애플리케이션환경설정파일은 AltiTest.exe.config 가된다. 아래는환경설정파일의예이다. <?xml version="1.0" encoding="utf-8"?> <configuration> <system.data> <DbProviderFactories> <remove invariant="altibase.data.altibaseclient" /> <add name="altibase Data Provider" invariant="altibase.data.altibaseclient" description="altibase Data Provider" type="altibase.data.altibaseclient.altibasefactory, Altibase.Data.AltibaseClient" /> </DbProviderFactories> </system.data> </configuration> 지원하지않는인터페이스 ALTIBASE HDB 는 ADO.NET 버전에따라다음과같이지원하지 않는인터페이스가있다. 각버전별로지원하지않는구성요소들은 모두 NotImplementedException 을발생시킨다. ADO.NET 1.X 에서지원하지않는인터페이스 클래스 구분 구성요소 AltibaseConnection M ChangeDatabase M Clone P Database AltibaseCommand M Cancel M Clone P CommandTimeout P CommandType AltibaseDataReader M GetData.NET Data Provider 37
P Depth AltibaseParameter M Clone AltibaseParameterCollection M AddRange M: Method P: Property A: 클래스전체 AltibaseDataReader.Depth 는언제나 0 을반환한다. ADO.NET 2.0 에서지원하지않는인터페이스 ADO.NET 1.X 에서지원하지않는인터페이스는 ADO.NET 2.0 에서도지원하지않는다. 클래스 구분 구성요소 AltibaseFactory M CreateDataSourceEnumerator M CreatePermission AltibaseConnection M EnlistTransaction(Transaction transcation) P DataSource P ServerVersion AltibaseDataReader M GetDbDataReader M GetProviderSpecificFieldType M GetProviderSpecificValue M GetProviderSpecificValues P HasRows P VisibleFieldCount AltibaseDataAdapter M AddToBatch(IDbCommand command) M CrearBatch M ExecuteBatch M GetBatchedParameter M GetBatchedRecordsAffected(int commandidentifier, out int recordsaffected, out Exception error) M InitializeBatching M TerminateBatching AltibaseParameter M ResetDbType 38 API User s Manual
AltibaseDataSourceEnumerator AltibasePermission AltibasePermissionAttribute A A A 상속받는추상클래스에기본구현이있는메소드는해당하는기본메소드를사용한다. 기본구현을제공하는멤버는다음과같다. CreateCommandBuilder CreateConnectionStringBuilder CreateDataSourceEnumerator CreatePermission GetProviderSpecificFieldType GetProviderSpecificValue GetProviderSpecificValues VisibleFieldCount GetBatchedRecordsAffected(int commandidentifier, out int recordsaffected, out Exception error) 기본구현이없는멤버는모두 NotImplementedException 을발생시킨다..NET Data Provider 39
.NET Data Provider 예제 연결문자열 (Connection String).NET 응용프로그램에서 ALTIBASE HDB 에접속하기위한연결 문자열은다음과같다. Server=127.0.0.1;PORT=20091;User=sys;Password=manage r DDL 과 DML 단순예제 AltibaseConnection 클래스를사용하여 ALTIBASE HDB 에 접근하여 test_goods 테이블을생성하고데이터를삽입한후 검색한다. using Altibase.Data.AltibaseClient; class ConnectionTest static void Main(string[] args) string sconnectionstring = "Server=127.0.0.1;PORT=20091;User=sys;Password=manager"; AltibaseConnection conn = new AltibaseConnection(sConnectionString); try conn.open(); // This connects to the database AltibaseCommand command = new AltibaseCommand("drop table test_goods", conn); query query try command.executenonquery(); // This executes a catch (Exception ex) command.commandtext = "create table test_goods ( gno char(10), gname char(20), location char(9), stock integer, price numeric(10, 2))"; command.executenonquery(); // This executes a command.commandtext = "insert into test_goods values ('A111100001','IM-300','AC0001',1000,78000)"; command.executenonquery();//this executes a query 40 API User s Manual
command.commandtext = "insert into test_goods values ('A111100002','IM-310','DD0001',100,98000)"; command.executenonquery();//this executes a query command.commandtext = "insert into test_goods values ('B111100001','NT-H5000','AC0002',780,35800)"; command.executenonquery();//this executes a query command.commandtext = "select * from test_goods"; AltibaseDataReader dr = command.executereader(); Console.WriteLine(" GNO GNAME LOCATION STOCK PRICE "); Console.WriteLine( "=========================================================== ========================"); while (dr.read()) for (int i = 0; i < dr.fieldcount; i++) Console.Write("\t0", dr[i]); // This outputs the retrieved data Console.WriteLine(); catch (Exception ex) Console.WriteLine(ex.ToString()); conn.close(); // This closes the connection to the database using Altibase.Data.AltibaseClient; class ConnectionTest static void Main(string[] args) string sconnectionstring = "DSN=127.0.0.1;PORT_NO=20091;UID=sys;PWD=manager;"; // This is the host IP address and port number of the database server used as the DSN AltibaseConnection conn = new AltibaseConnection(sConnectionString); try conn.open(); // This connects to the database AltibaseCommand command = new AltibaseCommand("drop table test_goods", conn); query try command.executenonquery(); // This executes a catch (Exception ex) command.commandtext = "create table test_goods ( gno char(10), gname char(20), location char(9),.net Data Provider 41
query stock integer, price numeric(10, 2))"; command.executenonquery(); // This executes a command.commandtext = "insert into test_goods values ('A111100001','IM-300','AC0001',1000,78000)"; command.executenonquery();//this executes a query command.commandtext = "insert into test_goods values ('A111100002','IM-310','DD0001',100,98000)"; command.executenonquery();//this executes a query command.commandtext = "insert into test_goods values ('B111100001','NT-H5000','AC0002',780,35800)"; command.executenonquery();//this executes a query command.commandtext = "select * from test_goods"; AltibaseDataReader dr = command.executereader(); Console.WriteLine(" GNO GNAME LOCATION STOCK PRICE "); Console.WriteLine( "=========================================================== ========================"); while (dr.read()) for (int i = 0; i < dr.fieldcount; i++) Console.Write("\t0", dr[i]); // This outputs the retrieved data Console.WriteLine(); catch (Exception ex) Console.WriteLine(ex.ToString()); conn.close(); // This closes the connection to the database 실행결과 GNO GNAME LOCATION STOCK PRICE ================================================== A111100001 IM-300 AC0001 1000 78000 A111100002 IM-310 DD0001 100 98000 B111100001 NT-H5000 AC0002 780 35800 벌크복사 AltibaseBulkCopy 를이용해서 bulkcopy_source 테이블에서 bulkcopy_destination 테이블로데이터를복사한다. 42 API User s Manual
using System; using System.Data; using Altibase.Data.AltibaseClient; class Program static void Main(string[] args) if (args.length!= 2) Console.WriteLine("\t[NOT PASSED]: Invalid argument"); return; string connectionstring = GetConnectionString(args); using (AltibaseConnection sourceconnection = new AltibaseConnection(connectionString)) sourceconnection.open(); // Perform an initial count on the destination table. AltibaseCommand commandrowcount = new AltibaseCommand( "SELECT COUNT(*) FROM BULKCOPY_DESTINATION;", sourceconnection); long countstart = System.Convert.ToInt32( commandrowcount.executescalar()); Console.WriteLine("Starting row count = 0", countstart); // Get data from the source table as a AltibaseDataReader. AltibaseCommand commandsourcedata = new AltibaseCommand( "SELECT A1, A2, A3, A4 FROM BULKCOPY_SOURCE;", sourceconnection); AltibaseDataReader reader = commandsourcedata.executereader(); // Open the destination connection. In the real world you would // not use AltibaseBulkCopy to move data from one table to the other // in the same database. This is for demonstration purposes only. using (AltibaseConnection destinationconnection = new AltibaseConnection(connectionString)) destinationconnection.open(); // Set up the bulk copy object. // Note that the column positions in the source // data reader match the column positions in // the destination table so there is no need to // map columns. using (AltibaseBulkCopy bulkcopy = new AltibaseBulkCopy(destinationConnection)) bulkcopy.destinationtablename = "BULKCOPY_DESTINATION"; try.net Data Provider 43
// Write from the source to the destination. bulkcopy.writetoserver(reader); catch (Exception ex) Console.WriteLine(ex.Message); finally // Close the AltibaseDataReader. The AltibaseBulkCopy // object is automatically closed at the end // of the using block. reader.close(); // Perform a final count on the destination // table to see how many rows were added. long countend = System.Convert.ToInt32( commandrowcount.executescalar()); Console.WriteLine("Ending row count = 0", countend); Console.WriteLine("0 rows were added.", countend - countstart); private static string GetConnectionString(string[] args) // To avoid storing the sourceconnection string in your code, // you can retrieve it from a configuration file. return "Server=" + args[0] + ";" + "PORT=" + args[1] + ";" + "User=sys;Password=manager"; 44 API User s Manual
4. XA Interface 이장은 XA 표준을소개하고, 분산트랜잭션의기본개념과 XA 인터페이스를설명한다. ODBC, Embedded SQL, JDBC 프로그램에서글로벌트랜잭션을사용하여 ALTIBASE HDB 에접근하는방법에대해설명한다. 또한 XA 의제약사항및애플리케이션에서발생할수있는문제를다루는법을살펴본다. XA Interface 45
XA 개요 XA 구조는 X/Open 에서정한분산트랜잭션 ( 또는글로벌트랜잭션 ) 처리를위한표준모델이다. 분산트랜잭션이란 2 개또는그이상의네트워크상에서의데이터베이스시스템간의트랜잭션으로서글로벌트랜잭션 (Global Transaction) 이라고도한다. 데이터베이스시스템은트랜잭션의자원역할을하고, 트랜잭션매니져 (Transaction Manager, TM) 는이러한자원에관련된모든동작에대하여트랜잭션을생성하고관리한다. 즉다수의데이터베이스서버들이제공하는자원을분산애플리케이션이공유할수있도록해주거나또는글로벌트랜잭션으로처리할수있도록한다. XA 는하나이상의데이터베이스에서트랜잭션을처리하는애플리케이션에유용한구조이다. XA 관련용어 Application (AP) 애플리케이션은필요한트랜잭션과트랜잭션으로구성된작업을정의한다. 애플리케이션은 Embedded SQL 또는 ODBC CLI 로작성할수있다. 글로벌트랜잭션 (Global Transaction) TM 에의해관리되는트랜잭션전체를의미하며, 분산트랜잭션이라고도한다. 휴리스틱완료 (Heuristic Completion) in-doubt 트랜잭션에서어떤원인으로커밋등의다음명령을받지못해서 RM 스스로커밋또는롤백을수행한경우휴리스틱커밋 (Heuristic Commit) 이나휴리스틱롤백 (Heuristic Rollback) 이라고한다. 이러한상태를휴리스틱완료 (Heuristic Completion) 가되었다고한다. 일반적으로네트워크실패또는트랜잭션타임아웃에의해발생한다. In-doubt 트랜잭션 RM 즉 DBMS 에 prepare 된후커밋또는롤백메시지를받기전까지의트랜잭션브랜치을의미한다. 또는 Pending 트랜잭션이라고도한다. Resource Manager (RM) Resource Manager 는 XA 트랜잭션에의해접근되는자원을관리한다. 예를들어관계형데이터베이스, 트랜잭션큐, 또는 46 API User s Manual
파일시스템이있을수있다. 트랜잭션브랜치 (Transaction Branch) 이는하위트랜잭션으로글로벌트랜잭션의일부이다. 이는글로벌트랜잭션에참여하는 RM 들중하나에서실행된다. 하나의트랜잭션브랜치는하나의 XID (XA 의트랜잭션아이디 ) 와일대일로대응한다. Transaction Manager (TM) 이는트랜잭션을정의하는 API 를제공한다. 트랜잭션의커밋과롤백을책임지고, 복구를수행한다. TM 은모든 RM 이서로일관성을가지도록 2 단계커밋엔진을가지고있다. Transaction Processing Monitor (TPM) 이는하나이상의 AP 가하나이상의 RM 으로요청하는트랜잭션의흐름을조정한다. RM 은이기종이가능하며네트워크를통해서분산될수있다. TPM 은커밋과롤백작업을조정함으로써분산트랜잭션을완료한다. TPM 에속하는 TM 부분은분산된커밋과롤백작업의타이밍을결정할책임이있다. 즉 TPM 은 2 단계커밋을제어할책임이있다. TM 은분산된커밋과롤백작업을관리하기때문에, 모든 RM 에대해알수있어야하며직접통신할수있어야한다. 이를위해 TM 은 XA 인터페이스를사용한다. ALTIBASE HDB 의경우, TM 은 ALTIBASE HDB 에서제공하는 XA 라이브러리를사용할수있다. TX 인터페이스 AP 는 TX 인터페이스를사용하여 TM 을통해서트랜잭션을제어한다. AP 가직접 XA 인터페이스를사용하지는않는다. AP 는개별트랜잭션브랜치의작업을알지못하고, 애플리케이션쓰레드가직접트랜잭션브랜치작업에참여하지도않는다. 글로벌트랜잭션의브랜치들은 AP 를대신하여 TM 에의해서관리된다. AP 는다만 TM 에게글로벌트랜잭션을커밋또는롤백할것을요청할뿐이다. XA 의구조 아래그림에서보는것처럼, 하나이상의 AP (Application Program), TM (Transaction Manager) 과하나이상의 RM (Resource Manager) 이분산트랜잭션에관여한다. XA Interface 47
[ 그림 4-1] XA 구조 AP 가 TX 인터페이스를사용하여 TM 에게분산트랜잭션이시작됐다고알리면, TM 은어떤 RM ( 데이터베이스시스템 ) 이분산트랜잭션의대상인지확인한다. TM 은내부적으로 RM 에서수행할트랜잭션브랜치를위한 XID 를생성하여 XA 인터페이스를호출하여 RM 에게 XID 를전달한다. 각각의 RM (DB 노드 ) 은전송된 XID 에대응하는트랜잭션브랜치를처리하기시작한다. 그리고 TM 으로부터그트랜잭션의종료요청이올때까지는 AP 로부터요청된작업을그 XID 에해당하는글로벌트랜잭션내의작업으로인지하고트랜잭션브랜치에서작업을진행한다. 트랜잭션을종료하려면, AP 는 TX 인터페이스를사용하여 TM 에게분산트랜잭션이종료됐다고알린다. 그러면 TM 은 XA 인터페이스를사용하여분산트랜잭션을진행한 RM 에게커밋또는롤백을명령한다. XA 와 2 단계커밋 ALTIBASE HDB XA Interface 는 2 단계커밋 (2-Phase Commit, 2PC) 을따른다. 2PC 는 Prepare 단계와 Commit 단계로구성된다. 1 단계인 Prepare 에서 TM 은분산트랜잭션에참여하는모든데이터베이스노드들즉 RM 에게커밋의가능성을확인한다. 48 API User s Manual
RM 은커밋이가능하다면 Prepare 상태를 TM 에게전달한다. 그러나가능하지않다면 RM 은이를롤백시키기위한상태값을반환한다. 2 단계인 Commit 에서 TM 은 Prepare 의상태를전달받을때까지대기한다. 그리고 Prepare 가정상적으로진행되었다면, 모든 RM 에게커밋명령을보낸다. 그러나하나의 RM 이라도 Prepare 가되지않았다면, 롤백명령을보낸다. xa_switch_t 구조체 XA 인터페이스를지원하는모든 RM 은 RM 에대한정보와각인터페이스의 entry point 를가지는 xa_switch_t 구조체를제공한다. ALTIBASE HDB 는 altibase_xa_switch 라는이름으로제공한다. struct xa_switch_t char name[rmnamesz]; manager */ long flags; specific options */ long version; /* name of resource /* resource manager int (*xa_open_entry)(/*_ char *, int, long _*/); /*xa_open fn pointer*/ int (*xa_close_entry)(/*_ char *, int, long _*/); /*xa_close fn pointer*/ int (*xa_start_entry)(/*_ XID *, int, long _*/); /*xa_start fn pointer*/ int (*xa_end_entry)(/*_ XID *, int, long _*/); /*xa_end fn pointer*/ int (*xa_rollback_entry)(/*_ XID *, int, long _*/); /*xa_rollback fn pointer*/ int (*xa_prepare_entry)(/*_ XID *, int, long _*/); /*xa_prepare fn pointer*/ int (*xa_commit_entry)(/*_ XID *, int, long _*/); /*xa_commit fn pointer*/ int (*xa_recover_entry)(/*_ XID *, long, int, long _*/); /*xa_recover fn pointer*/ int (*xa_forget_entry)(/*_ XID *, int, long _*/); /*xa_forget fn pointer*/ int (*xa_complete_entry)(/*_ int *, int *, int, long _*/); /*xa_complete fn pointer*/ ; XA 라이브러리 ALTIBASE HDB XA 인터페이스를사용하는애플리케이션을연결하기위해서는별도의라이브러리가필요하지않다. ODBC XA Interface 49
프로그램을위한 odbccli 라이브러리에포함되어제공하기때문에, 사용자가 XA 관련기능을사용하기위해서는 XA 를사용하는 애플리케이션에 libodbccli.a 라이브러리만링크하면된다. 50 API User s Manual
XA 인터페이스 XA 인터페이스는 RM 과 TM 간의상호인터페이스이다. TM 은글로벌트랜잭션을수행하기위해 RM 을제어하는 XA 루틴과 RM 이동적으로 TM 에게요청하는 AX 루틴으로구성된다. Note: ALTIBASE HDB 는동적인등록을지원하지않기때문에, 트랜잭션을시작하기전에 TM 이 RM 으로 xa_start 를호출해야한다. XA 함수 ALTIBASE HDB 는 xa_switch_t 의 ALTIBASE HDB 구현인 altibase_xa_switch 구조체에 XA 관련함수들을제공한다. XA 인터페이스 설명 xa_open Resource Manager 에연결한다. xa_close Resource Manager로부터연결을해제한다. xa_start 새로운트랜잭션브랜치또는기존의트랜잭션브랜치를다시시작하고, 주어진트랜잭션식별자 (XID) 와연계시킨다. xa_end 트랜잭션브랜치로부터분리한다. xa_rollback 주어진 XID와연계된트랜잭션브랜치를롤백한다. xa_prepare 트랜잭션브랜치의커밋을준비한다. xa_commit 트랜잭션브랜치를커밋한다. xa_recover prepare, 휴리스틱커밋또는휴리스틱롤백된트랜잭션의 XID 리스트를보여준다. xa_forget 휴리스틱하게완료된트랜잭션브랜치에대한정보를 RM에서폐기하도록한다. [ 표 4-1] XA 인터페이스 xa_open RM 에접속한다. int xa_open(char *xa_info, int rmid, long flags); xa_info 는 null-terminated 문자열로, 서버정보를포함하며최대길이는 256byte 이다. SQLDriverConnect 의인자와동일한포맷을가지며, 추가적으로 XA_NAME, XA_LOG_DIR 필드가존재한다. 다른필드에대한자세한설명한 CLI User's Manual 의 XA Interface 51
SQLDriverConnect 함수를참조하기바란다. NAME=value;NAME=value;NAME=value; 예 ) DSN=127.0.0.1;UID=SYS;PWD=MANAGER ;XA_NAME=conn1 XA 파라미터 XA_NAME XA_LOG_DIR 설명 ALTIBASE HDB Embedded SQL 프로그램에서연결의식별자로사용되는이름이다. ALTIBASE HDB Embedded SQL로애플리케이션을작성할때이값을생략하면, 기본연결을사용하게된다. 만약 XA_NAME 속성에이름을명시했다면, SQL문수행시 AT 절에이이름을사용하면된다. ALTIBASE HDB XA 라이브러리에서발생한에러정보를로깅하는디렉터리를명시한다. 기본값은 ALTIBASE_HOME 환경변수가설정되었을경우 $ALTIBASE_HOME/trc이고, 그렇지않다면현재디렉터리다. [ 표 4-2] XA 인터페이스에추가된필드 rmid 는접속할서버의 ID 를기록하며, 아무값이나쓸수있다. 플래그 (flags) 는다음의값을사용할수있다. TMNOFLAGS xa_close 지정된 RM 과연결을종료한다. int xa_close(char *xa_info, int rmid, long flags); xa_info 는서버에대한정보를기록하는문자열로, 최대길이는 256byte 이다. Note: 연결이이미종료된것에대해 xa_close 가수행되어도, XA_OK 값이반환된다. 플래그 (flags) 는다음의값을쓸수있다. TMNOFLAGS xa_start 트랜잭션브랜치를시작한다. xid 는글로벌트랜잭션에대한식별자이다. int xa_start(xid *xid, int rmid, long flags); 플래그 (flags) 는다음의값을쓸수있다. 52 API User s Manual
TMRESUME 이전에 suspend 된트랜잭션브랜치를계속한다. TMNOWAIT xa_start 가차단될경우, 기다리지않고 XA_RETRY 값을반환한다. TMASYNC 비동기모드로트랜잭션브랜치를시작한다 (ALTIBASE HDB 는지원하지않음 ). TMNOFLAGS 다른플래그를지정하지않을경우반드시이값을지정해야한다. TMJOIN 존재하는트랜잭션브랜치에연결한다. xa_end 트랜잭션브랜치를끝낸다. int xa_end(xid *xid, int rmid, long flags); 플래그 (flags) 는다음의값을쓸수있다. TMSUSPEND 해당트랜잭션브랜치를 suspend 상태로변경하고종료한다. 이트랜잭션브랜치는 xa_start 에의해서다시계속될수있다. TMSUCCESS 성공적으로종료했다는것을나타내는것으로 TMSUSPEND 또는 TMFAIL 과같이사용될수없다. TMFAIL 비정상적으로종료했다는것을나타낸다. 이트랜잭션브랜치의상태는 roll-back only 로지정된다. TMSUCCES 또는 TMSUSPEND 와같이사용될수없다. xa_rollback 지정된트랜잭션브랜치에대해서수행한연산을롤백한다. int xa_rollback(xid *xid, int rmid, long flags); 플래그 (flags) 는다음의값을쓸수있다. TMASYNC xa_rollback 이비동기모드로동작하도록한다 (ALTIBASE HDB 는지원하지않음 ). TMNOFLAGS XA Interface 53
다른플래그를지정하지않을경우반드시이값을지정해야 한다. xa_prepare 2 단계커밋프로토콜에서트랜잭션을커밋하거나롤백하기이전에수행한다. int xa_prepare(xid *xid, int rmid, long flags); 플래그 (flags) 는다음의값을쓸수있다. TMASYNC (ALTIBASE HDB 는지원하지않음 ) TMNOFLAGS 다른플래그를지정하지않을경우반드시이값을지정해야한다. 다음의값이리턴될수있다. XA_RDONLY 트랜잭션이 RM (DBMS) 의어떤데이터도변경하지않았을경우에반환된다. RM 에서수행된트랜잭션은커밋이나롤백이필요하지않다. XA_OK 정상적으로수행되었을경우에이값을반환한다. xa_commit 특정트랜잭션브랜치를커밋한다. int xa_commit(xid *xid, int rmid, long flags); 플래그 (flags) 는다음의값을쓸수있다. TMONEPHASE one phase commit 을수행할경우설정한다. TMNOFLAGS 다른플래그를지정하지않을경우반드시이값을지정해야한다. xa_recover RM 에서 prepare 상태로있는트랜잭션브랜치에해당하는 xid 의 목록을얻는다. int xa_recover(xid *xids, long count, int rmid, long flags); 54 API User s Manual
리턴값은 xids 에반환되는 xid 의갯수이다. count 매개변수에는 xids 의사이즈를지정한다. 플래그 (flags) 는다음의값을쓸수있다. TMSTARTRSCAN 자세한설명은 XA Specification 문서를참고한다. TMENDRSCAN 자세한설명은 XA Specification 문서를참고한다. TMNOFLAGS 현재커서위치에서시작하여 XID 목록을반환한다. xa_forget 휴리스틱하게 (heuristically) 완료된트랜잭션을 ALTIBASE HDB 서버가관리하지않도록한다. int xa_forget(xid * xid, int rmid, long flags); 플래그 (flags) 는다음의값을쓸수있다. TMNOFLAGS 항상이값을지정한다. xa_complete 비동기모드의연산을수행할때해당연산이종료될때까지 대기한다. ALTIBASE HDB 에서는지원하지않으며, 항상오류 메시지를리턴한다. XA Interface 55
XA 사용 이절에서는 XA 환경에서 ODBC, Embedded SQL, JDBC 등을 사용하기위한기본적인절차를살펴본다. ODBC/XA 수행순서 1. xa_open 지정한서버에접속한다. 2. SQLAllocHandle ODBC 에연결하기위해서 connection 과 environment 핸들을생성한다. 3. SQLSetConnectAttr XA connection 을 connection 핸들에연결한다. 4. SQLConnect 실제연결은 xa_open 으로연결되었으므로, 이호출에서새로운접속을수행하지는않는다. 다만 SQLConnect 는 ODBC 에서 connection 의내부상태값을변경한다. 이과정을생략하면 DML 연산을수행할수없다. 5. xa_start 특정 XID 에대응하는트랜잭션브랜치를시작한다. 6. SQL 구문실행 SQLPrepare, SQLExecute 등의연산을수행한다. 만일여기에서 commit 문을실행한다면서버는에러메시지를반환한다. 7. xa_end 트랜잭션브랜치를종료한다. 8. xa_prepare 커밋을위해 prepare 를수행한다. 9. xa_commit 트랜잭션을커밋한다. 56 API User s Manual
10. SQLDisconnect ODBC 에서 connection 의내부상태를연결되지않은상태로변경한다. 그러나실제 XA 에의해서생성된연결은그대로유지된다. 11. xa_close xa 의연결을종료한다. SQLSetConnectAttr ODBC 애플리케이션이분산트랜잭션을사용할수있도록, SQLSetConnectAttr 을호출하여 XA connection 을 ODBC connection 에연결시킨다. XA 연결하기위해서는 SQLSetConnectAttr 에다음과같은매개변수를준다. SQLRETURN SQLSetConnectAttr (SQLHDBC SQLINTEGER SQLPOINTER SQLINTEGER hdbc, fattr, vparam, slen); fattr = ALTIBASE_XA_RMID hdbc 로지정한연결을 XA 연결로서사용하도록한다. XA 연결에대한자세한정보는 vparam 에다음의구조체포인터를지정하여설정한다. vparam xa_open 으로연결할때사용한 rmid 값을갖는다. rmid 를지정하지않고서버에 XA 연결을하려면다음의매개변수를사용한다. fattr = SQL_ATTR_ENLIST_IN_DTC 또는 SQL_ATTR_ENLIST_IN_XA 지정한 hdbc 연결을마지막 XA 연결과맺는다. Embedded SQL XA_NAME 설정에따른프로그램작성방법 XA 프로그램을작성할때, 커서는한트랜잭션내에서만유효하다. 즉트랜잭션이시작한후에커서를열어야하고, 트랜잭션이커밋또는롤백되기전에커서를닫아야한다. 기본연결을사용한프로그램작성방법 XA Interface 57
기본연결을사용려면다음과같이 xa_open 의연결정보를가지는 xa_info 인자에 XA_NAME 필드를지정하지않은문자열을사용해야한다. DSN=127.0.0.1;UID=SYS;PWD=MANAGER 그리고 SQL 구문에서는다음예제처럼 AT 절을사용하지않아도된다. EXEC SQL UPDATE emp SET empno = 5; 한개이상의연결을사용하기위해 XA_NAME 을사용한프로그 램작성방법 Embedded SQL 프로그램에서명시적으로연결의이름을 사용하려면, xa_open 의연결정보를가지는 xa_info 인자에 XA_NAME=conn1 필드가포함된문자열을사용해야한다. 기본연결과한개이상의이름이명시된연결이있는프로그램을 작성하려면, 다음과같이한다. 연결이름이 conn1, conn2 로존재한다면 TM 의환경설정에서 open_string 은다음과같이 XA_NAME 을사용해서연결이름을 명시한다. DSN=127.0.0.1;UID=SYS;PWD=MANAGER;XA_NAME=conn1 DSN=127.0.0.1;UID=SYS;PWD=MANAGER;XA_NAME=conn2 DSN=127.0.0.1;UID=SYS;PWD=MANAGER 애플리케이션서버의서비스함수프로그램에서는아래처럼 AT 절을포함한 Embedded SQL 구문을작성한다. EXEC SQL AT conn1 UPDATE emp SET empno = 5; EXEC SQL AT conn2 UPDATE emp SET empno = 5; EXEC SQL UPDATE emp SET empno = 5; JDBC/XA 수행순서 ALTIBASE HDB 의 JDBC 드라이버가정의하는 XA 관련클래스는다음과같다. Altibase.jdbc.driver.ABXADataSource Altibase.jdbc.driver.ABXAResource Altibase.jdbc.driver.XID 사용자가직접사용하는클래스는 ABXADataSource 이다. 나머지는 JTA 인터페이스클래스를구현한클래스로사용자가직접사용할필요는없다. 58 API User s Manual
1. ABXADataSource 객체생성 ABXADataSource xadatasource = new ABXADataSource(); xadatasource.seturl(args[0]); xadatasource.setuser("sys"); xadatasource.setpassword("manager"); 2. XAConnection 객체생성 XAConnection 을 XADataSource 클래스의 getxaconnection 매소드를호출하여생성한다. XAConnection xaconnection = xadatasource.getxaconnection( SYS, MANAGER: ); 3. XAResource 객체생성 XAResource 를 XAConnection 클래스의 getxaresource 매소드를호출하여생성한다. XAResource xaresource = xaconnection.getxaresource(); 4. Connection 객체생성 SQL 을수행할커넥션을 XAConnection 클래스의 getconnection 매소드를호출하여생성한다. Connection conn1 = xaconnection.getconnection(); 5. XAResource 객체를이용하여 XA 함수실행 xa_start, xa_end 등의 XA 함수들은 XAResource 클래스의매소드를사용하여실행된다. xaresource.start(xid, XAResource.TMNOFLAGS); 6. Connection 객체를이용하여 SQL 구문수행 Statement stmt = conn.createstatement(); int cnt = stmt.executeupdate("insert into t1 values (4321)"); XA 트랜잭션제어 ALTIBASE HDB XA 환경에서트랜잭션을제어하는방법에대해설명한다. XA 라이브러리를사용할때는 commit 이나 rollback 구문을사용하여트랜잭션을처리하면안된다. 대신에 AP 는아래표의 TX 인터페이스를사용하여 TM 이트랜잭션을시작하거나종료하도록해야한다.. XA Interface 59
TM 은일반적으로 XA 인터페이스를사용해서트랜잭션을제어한다. TX 인터페이스 설명 tx_open RM에 logon한다. tx_close RM에서 logout한다. tx_begin 새로운트랜잭션을시작한다. tx_commit 트랜잭션을커밋한다. tx_rollback 트랜잭션을롤백한다. [ 표 4-3] TX 인터페이스 TX 인터페이스와 XA 인터페이스의호출흐름을살펴보면, 다음 그림과같다. AP tx_open tx_begin TM XA Interface xa_open xa_start tx_commit tx_close xa_end xa_prepare xa_commit xa_close xa_recover xa_commit (xa_rollback, xa_forget) ALTIBASE Native Calls [ 그림 4-2] TX 인터페이스와 XA 인터페이스의호출흐름도 TPM 애플리케이션은애플리케이션클라이언트가애플리케이션서버에서제공하는서비스를요청하는 client/server 구조로되어있다. 서비스란논리적인일의단위로써, ALTIBASE HDB 를 RM 으로사용하는경우에는 SQL 구문의집합으로구성된다고볼수있다. 예제 다음예제들은애플리케이션서버가 TPM 시스템에이미로그온 되었다고가정한예제이다. 애플리케이션서버에서트랜잭션시작하기 60 API User s Manual
애플리케이션서버에의해서트랜잭션이시작되는예제이다. Client: tpm_service( SERVICE1 ); Server: SERVICE1() <get service specific data> tx_begin(); EXEC SQL UPDATE...; tpm_service( SERVICE2 ); tx_commit(); <return service status back to the client> 애플리케이션클라이언트에서트랜잭션시작하기 애플리케이션클라이언트에의해서트랜잭션이시작되는예제이다. Client: tx_begin(); tpm_service( SERVICE1 ); tmp_service( SERVICE2 ); tx_commit(); Server: SERVICE1() <get service specific data> EXEC SQL UPDATE...; <return service status back to the client> SERVICE2() <get service specific data> EXEC SQL UPDATE...; <return service status back to the client> 기존애플리케이션을 TPM 애플리케이션으로변경 기존에작성되어있던애플리케이션 (Precompiler 또는 ODBCCLI) 을 ALTIBASE HDB XA 라이브러리를이용한 TPM (Transaction Performance Monitoring) 애플리케이션으로변경하기위해서는다음의절차를따라야한다. 1. 애플리케이션을 서비스 라는프레임워크 (framework) 구조로전환한다. 여기서프레임워크란애플리케이션클라이언트가애플리케이션서버에게 서비스 를요청하는구조를의미한다. 어떤 TPM 은 tx_open, tx_close 함수를사용할것을요구하고, 어떤 TPM 은묵시적으로 logon, logoff 를하기도한다. 2. 일반적인 connect 구문을 TPM 호환성이있는형태로 XA Interface 61
변경한다. 예를들어, Embedded SQL 프로그램의경우에는 EXEC SQL CONNECT 구문을 tx_open() 으로변경하고, ODBCCLI 에서는 SQLDriverConnect 구문을 tx_open 과 SQLConnect 로변경한다. 실제연결은 tx_open 으로연결되었으나, ODBC 내부에서 XA 연결과맺어주는 SQLConnect 과정을생략하면 DML 연산을수행할수없다. 자세한설명은 ODBC/XA 수행순서를참조한다. 3. 일반적인 disconnect 구문을 TPM 호환성이있는형태로변경한다. Embedded SQL 프로그램의 EXEC SQL DISCONNECT 또는 ODBCCLI 의 SQLDisconnect 구문을 tx_close() 로변경한다. 4. Commit, rollback 구문을 TPM 호환성이있는형태로변경한다. 예를들어 EXEC SQL COMMIT/ROLLBACK (Embedded SQL 프로그램 ), SQLEndTran(ODBCCLI) 을 tx_commit/tx_rollback 으로변경하고, tx_begin() 을호출하여트랜잭션을시작하도록한다. 5. 애플리케이션은트랜잭션을종료 (end) 하기전에 fetch 상태를리셋해야한다. 커서를사용해서 fetch 를했으면트랜잭션을종료하기전에 CLOSE RELEASE 를사용해서커서를닫고자원을해제해야한다. ALTIBASE HDB 구문 CONNECT 암묵적인트랜잭션시작 SQL COMMIT ROLLBACK DISCONNECT SET TRANSACTION READ ONLY TPM 함수 tx_open tx_begin SERVICE에서 SQL구문수행 tx_commit tx_rollback tx_close 허용하지않음 62 API User s Manual
XA 사용시제약사항 XA 를사용할때다음과같은몇가지제약사항이존재한다. SQL 사용시제약사항 트랜잭션브랜치관련제약사항 연계이주비지원 비동기호출비지원 동적등록비지원 서버종료 SQL 사용시제약사항 롤백과커밋 TM 이글로벌트랜잭션을관리하기때문에 XA 애플리케이션에서는 COMMIT 또는 ROLLBACK 구문같은트랜잭션제어구문을사용해서글로벌트랜잭션을제어해서는안된다. 글로벌트랜잭션을종료하기위해서는 tx_commit 이나 tx_rollback 을사용해야한다. Precompiler 애플리케이션에서 EXEC SQL ROLLBACK 이나 EXEC SQL COMMIT 구문을사용할수없다. ODBCCLI 애플리케이션에서도 SQLEndTran 을사용해서커밋이나롤백을수행하면안된다. DDL 구문 AUTOCOMMIT 세션프로퍼티 DDL SQL 구문은 ALTIBASE HDB 서버내부적으로커밋을하기 때문에 ALTIBASE HDB XA 애플리케이션에서사용할수없다. 글로벌트랜잭션은 non-autocommit 모드에서수행되기때문에, ALTER SESSION SET AUTOCOMMIT = TRUE 구문을사용하여 AUTOCOMMIT 프로퍼티를변경할수없다. SET TRANSACTION XA 애플리케이션에서 SET TRANSACTION READ ONLY READ WRITE ISOLATION LEVEL... 구문을사용하면안된다. XA Interface 63
EXEC SQL 구문으로연결또는해제 Embedded SQL 프로그램에서연결또는연결해제를위해서 EXEC SQL CONNECT, EXEC SQL DISCONNECT 구문을 사용해서는안된다. 트랜잭션브랜치관련제약사항 하나의글로벌트랜잭션에는다수의애플리케이션쓰레드들이참여하는데, 이들쓰레드는서로 tightly-coupled 또는 looselycoupled 관계일수있다. Tightly-coupled 관계는자원을공유하는쓰레드의관계이다. 이들쓰레드들은하나의개체로처리된다. Tightly-coupled 쓰레드에서 RM 은트랜잭션브랜치가자원의데드락이발생하지않도록해야한다. 그러나 Loosely-coupled 관계에서는이런보장을하지않는다. RM 에서는 loosely-coupled 관계의트랜잭션브랜치를서로다른글로벌트랜잭션처럼다룬다. XID 와쓰레드의관계 TM 이 XID 의 branch qualifier 를새로운값으로생성하여 RM 에전달한다면, 이쓰레드는같은브랜치안의다른쓰레드들과 loosely-coupled 관계가된다. RM 은이쓰레드를별도의글로벌트랜잭션처럼처리한다. 그리고만약 TM 이 XID 의 branch qualifier 를재사용한다면, 이쓰레드는해당브랜치를공유하는다른쓰레드들과 tightly-coupled 한관계가된다. RM 은이러한 tightly-coupled 쓰레드들을하나의개체처럼다뤄야하고, 이들 tightly-coupled 쓰레드간에자원데드락이발생하지않도록보장해야한다. 연계이주비지원 ALTIBASE HDB 는연계이주 (Association Migration, TM 이 suspended 브랜치를다른브랜치에서연계하여다시시작하는것 ) 를지원하지않는다. 64 API User s Manual
비동기호출비지원 ALTIBASE HDB 는비동기 XA 호출을지원하지않는다. 동적인등록비지원 ALTIBASE HDB 서버는동적등록을지원하지않고, 정적등록만지원한다. 동적등록 (Dynamic Registration) 이란 RM 이글로벌트랜잭션을시작하기전에자신이 TM 에등록하는것을말한다. 정적등록에서는 TM 이 xa_start 를꼭호출하여트랜잭션시작을 RM 에알려야한다. 서버종료 Shutdown abort 를사용한 ALTIBASE HDB 종료또는비정상종료시 prepared 트랜잭션이존재하였다면, 종료후서버재구동시이들트랜잭션이 recovery 과정을거치게되므로구동후에 xa_recover 를통해서이들트랜잭션을처리할수있다. Shutdown immediate 또는 shutdown normal 로서버를종료할때 prepared 트랜잭션이존재하면, 정상종료를명령했더라도 ALTIBASE HDB 는 abort 로종료시킬때와같은방식으로서버를종료한다. 따라서재구동시 recovery 과정을거쳐이들트랜잭션이그대로유지되며 xa_recover 를통해서이들트랜잭션을처리할수있다. 그러나 prepared 트랜잭션이존재하지않을경우에는정상종료하며, 다음구동시 recovery 과정을거치지않게된다. XA Interface 65
JDBC 분산트랜잭션 분산트랜잭션을구현한 ALTIBASE HDB JDBC 는 JDBC 2.0 extension API 에서 Connection Pooling 기능과분산트랜잭션을위한 Open XA 표준을준수한다. XA 표준에부합하는분산트랜잭션기능을구현한모든클래스는 ALTIBASE HDB JDBC 드라이버패키지에기본으로포함되어제공된다. JTA(Java Transaction API) 와애플리케이션서버 분산트랜잭션에서애플리케이션이애플리케이션서버를통해서 트랜잭션을수행하는과정을그림과같이설명한다. Application Application Server Transaction Manager Resource Adapter [ 그림 4-3] 분산트랜잭션과정 애플리케이션서버는각각의자원들과연결될수있는 XAConnection 을지원한다. 애플리케이션은애플리케이션서버에접속해서 Connection 을얻어쿼리를수행한다. 그리고애플리케이션서버는 TM (Transaction Manager) 을통해트랜잭션을관리한다. 이때 TM 은 DBMS 벤더에서제공하는 Resource Adapter 를이용해서자원에접근할수있다. Resource 가 DBMS 일경우, Resource Adapter 는 JDBC 드라이버패키지가될수있다. Resource Adapter 는 ResourceFactory, Transactional Resource(XAConnection), Connection, XAResource 등 4 가지종류의클래스로구성된다. ResourceFactory 는 XAConnection 을생성하며, JDBC 스펙에서 XADataSource 가여기에해당한다. 애플리케이션서버는 XADataSource 에서가져온 XAConnection(DBMS 로연결 ) 을얻는다. 그리고 XAConnection 은애플리케이션에서사용할 connection(java.sql.connection) 인스턴스와 TM 에서사용할 XAResource 인스턴스를얻어온다. 66 API User s Manual
XA 컴포넌트 XADataSource Interface JDBC 2.0 Optional 패키지의표준 XA 인터페이스들과이를 구현한 ALTIBASE 클래스를설명한다. javax.sql.xadatasource 는 XA Connection 의 factory 기능을 갖는인터페이스이다. 이인터페이스의 getxaconnection 메소드가 XA Connection 인스턴스를반환한다. public interface XADataSource XAConnection getxaconnection() throws SQLException; XAConnection getxaconnection(string user, String password) throws SQLException;... Altibase.jdbc.driver.ABXADataSource 는 ALTIBASE HDB 에서제공한 JDBC 드라이버에존재하는 XADataSource 인터페이스를구현한클래스이다. 동시에 Altibase.jdbc.driver.ABConnectionPoolDataSource 를상속한클래스이다. ABConnectionPoolDataSource 클래스는 Altibase.jdbc.driver.DataSource 를상속한다. 따라서, ABXADataSource 클래스는 DataSource 와 ABConnectionPoolDataSource 의 connection properties 를모두포함한다. DataSource <Interface> XADataSource ABConnectionPoolDataSource ABXADataSource [ 그림 4-4] ABXADataSource 클래스 ABXADataSource 클래스의 getxaconnection 메소드는 XAConnection 타입의인스턴스를반환한다. 이인스턴스는실제로 ABPooledConnection 클래스의인스턴스로서 XA Interface 67
ABPooledConnection 클래스는 XAConnection 인터페이스를구현하고있다. XA data source 는 Java Naming Directory 와 Interface(JNDI) 에등록및사용할수있다. XAConnection Interface XAConnection 인터페이스는 PooledConnection 인터페이스의 하위인터페이스이다. getconnection, close, addconnectioneventlistener, removeconnectioneventlistener 메소드를포함한다. public interface XAConnection extends PooledConnection javax.jta.xa.xaresource getxaresource() throws SQLException; XAConnection 의인스턴스는데이터베이스와물리적으로연결하고있다. 또한 XAConnection 인스턴스를통해분산트랜잭션을관리하는데사용되는 XAResource 를얻을수있다. ALTIBASE HDB JDBC driver 에서는 Altibase.jdbc.driver.ABPooledConnection 클래스의인스턴스가실질적인 XAConnection 타입의인스턴스가된다. ABPooledConnection 클래스의 getxaresource 메소드는 ABXAResource 인스턴스를반환하고, getconnection 메소드는 ABConnection 인스턴스를반환한다. <Interface> PooledConnection <Interface> XAConnection ABPooled Connection [ 그림 4-5] ABPooledConnection 클래스 68 API User s Manual
getconnection 메소드를통해반환되는 ABConnection 인스턴스는데이터베이스와의물리적인연결에대한임시핸들이고, 이 Connection 은글로벌트랜잭션에참여되기까지는일반적인 Connection 처럼동작한다. 글로벌트랜잭션에참여되는순간에 auto-commit 상태는 false 가되며, 글로벌트랜잭션이끝난후에 auto-commit 상태는글로벌트랜잭션이시작되기이전상태로돌아간다. XAConnection 의 getconnection 메소드가호출될때마다새로운 Connection 인스턴스를반환하는데, 동일한 XAConnection 인스턴스에의해반환되어이전에존재하던 Connection 인스턴스는 close 된다. 그럼에도불구하고, 새로운 Connection 이오픈되기전에이전의 Connection 은명시적으로 close 하기를권장한다. XAConnection 인스턴스의 close 메소드가호출되면데이터베이스로의물리적인연결이끊어진다. XAResource Interface TM 은모든트랜잭션브랜치들을조정하기위해서 ABXAResource 인스턴스를사용한다. Altibse.jdbc.driver.ABXAResource 타입의인스턴스는 javax.transaction.xa.xaresource 인터페이스를구현하는클래스의인스턴스이다. <Interface> javax.transaction.xa.xaresource ABXAResource [ 그림 4-6] ABXAResource 클래스 Altibase JDBC driver 는 ABPooledConnection 클래스의 getxaresource 메소드를호출할때마다 ABXAResource 인스턴스를생성하여반환하고, Altibase JDBC driver ABXAResource 인스턴스와 connection 인스턴스를연결시킨다. 트랜잭션브랜치는이 connection 으로동작한다. ABXAResource 클래스는분산된트랜잭션의트랜잭션브랜치를조정하기위해몇개의메소드를갖고있다. XA Interface 69
TM 은애플리케이션서버와같은중간층의컴포넌트로부터 ABXAResource 인스턴스를받으며, 아래의메소드를갖고있다. void start(xid xid, int flags) void end(xid xid, int flags) int prepare(xid xid) void commit(xid xid, boolean onephase) void rollback(xid xid) public void forget(xid xid) public Xid[] recover(int flag) 자세한내용은 java API Spec. 의 javax.transaction.xa.xaresource 를참조하기바란다. Xid interface TM 은트랜잭션 ID 인스턴스를생성하고, 분산트랜잭션의브랜치를관리하는데이를사용한다. 각각의트랜잭션브랜치는유일한트랜잭션 ID 를부여받으며, 다음의정보를포함한다. Format identifier Global transaction identifier Branch qualifier Altibase 는 javax.transaction.xa.xid 인터페이스를구현한클래스가 Altibase.jdbc.driver 패키지에 XID 클래스로존재한다. Note: ABXAResource 호출에는 Altibase.jdbc.driver.XID 를반드시사용할필요는없다. 여기에는 javax.transaction.xa.xid 인터페이스를구현한어떤클래스도사용될수있다. 에러처리 XA 관련메소드는에러가발생할때, ABXAException 을 throw 한다. ABXAException 클래스는 javax.transaction.xa.xaexception 클래스의하위클래스이다. 애플리케이션서버에서 XA 설정 WebLogic 에서 XA 설정 1. 웹로직콘솔에서 Services -> JDBC -> Connection Pools 에서 Configure a new JDBC Connection Pool 을선택한후 JDBC 연결정보를입력한다. ([ 그림 6-6]JDBC 연결정보입력참조 ) 70 API User s Manual
구분 NON-XA XA URL jdbc:altibase://[ip]:[port]/dbnam e jdbc:altibase://[ip]:[port]/dbnam e Driver Classname Altibase.jdbc.driver.AltibaseDriv er Altibase.jdbc.driver.ABXADataS ource Properties User=[username] User=[username] [ 표 4-4] NON-XA와 XA의연결정보비교 [ 그림 4-7] JDBC 연결정보입력 2. 생성된 Connection Pool 을이용해서 DataSource 를만든다. Services->JDBC->Data Sources 에서 Configure a new JDBC Data Source 를선택한다. Name 과 JNDI Name 을입력하고 Honor Global Transactions 에체크한다. 다음페이지에서 PoolName 에앞서만든 Pool 의이름을입력한다. (weblogic 8.1) ([ 그림 6-7] 데이터소스생성참조 ) Note: weblogic8.1 이전버전에서는 Services->JDBC->XA Data Sources 에서새로운 DataSource 를생성한다. XA Interface 71
[ 그림 4-8] 데이터소스생성 Weblogic 애플리케이션예제 JEUS 에서 XA 설정 // step 1. JNDI Lookup and get UserTransaction Object Context ctx = null; Hashtable env = new Hashtable(); // Parameter for weblogic env.put(context.initial_context_factory, "weblogic.jndi.wlinitialcontextfactory"); env.put(context.provider_url,"t3://localhost:7001"); env.put(context.security_principal,"weblogic"); env.put(context.security_credentials,"weblogic"); ctx = new InitialContext(env); System.out.println("Context Created :"+ctx); // step 2. get User Transaction Object UserTransaction tx = (UserTransaction)ctx.lookup("javax.transaction.UserTransa ction"); // step 3 start Transaction System.out.println("Start Transaction :"+tx); tx.begin(); try // step 4. doing query // step 4-1. get Datasource DataSource xads1 = (DataSource)ctx.lookup("altiTXDS"); 제우스에서 JDBC 데이터소스를생성하기위한기본설정을한다. 72 API User s Manual
1. JEUS 매니저리소스 ->JDBC 에서새 JDBC 데이터소스생성을 선택한다. 2. 기본설정창이나타나면다음의정보를입력한다. DBMS : Other 가능한데이터소스들 : Other DataSource Data Source Class Name: Altibase.jdbc.driver.ABXADataSource Data Source Type : XADataSource 3. Database Name, Port Number, Server Name, User, Password 에는해당하는값을입력한다. [ 그림 4-9] 제우스에서데이터소스설정하기 JEUS 애플리케이션예제 // step 1. JNDI Lookup and get UserTransaction Object Context ctx = null; Hashtable env = new Hashtable(); // Parameter for weblogic XA Interface 73
env.put(context.initial_context_factory, "jeus.jndi.jnscontextfactory"); env.put(context.url_pkg_prefixes, "jeus.jndi.jns.url"); env.put(context.provider_url, "127.0.0.1"); env.put(context.security_principal,"jeus"); env.put(context.security_credentials,"jeus"); ctx = new InitialContext(env); System.out.println("Context Created :"+ctx); // step 2. get User Transaction Object UserTransaction tx = (UserTransaction)ctx.lookup("java:comp/UserTransaction"); // step 3 start Transaction System.out.println("Start Transaction :"+tx); tx.begin(); try // step 4. doing query // step 4-1. get Datasource DataSource xads1 = (DataSource)ctx.lookup("altiTXDS"); 예제 ALTIBASE HDB XA 기능을사용해서분산트랜잭션을어떻게구현하는지예제를통해살펴본다. 이예제는아래의순서대로실행한다. 1. Start transaction branch #1. 2. Start transaction branch #2. 3. Execute DML operations on branch #1. 4. Execute DML operations on branch #2. 5. End transaction branch #1. 6. End transaction branch #2. 7. Prepare branch #1. 8. Prepare branch #2. 9. Commit branch #1. 10. Commit branch #2. import java.sql.*; import javax.sql.*; 74 API User s Manual