Altibase Starting User's Manual

Transcription

1 ALTIBASE HDB Application Development Altibase C Interface Manual Release (April 16, 2015)

2 Altibase Application Development ACI Manual Release Copyright c 2001~2015 Altibase Corp. All Rights Reserved. 본문서의저작권은 알티베이스에있습니다. 이문서에대하여당사의동의없이무단으로복제또는전용할수없습니다. 알티베이스 서울시구로구구로동 대륭포스트타워 Ⅱ 10 층전화 : 팩스 : 고객서비스포털 : homepage:

3 목차 서문... 7 이매뉴얼에대하여 Altibase C 인터페이스소개 Altibase C 인터페이스란? ACI 사용방법 클라이언트응용프로그램빌드 데이터타입 ACI 자료구조 ACI 함수 altibase_affected_rows() altibase_client_version() altibase_client_verstr() altibase_close() altibase_commit() altibase_connect() altibase_data_seek() altibase_errno() altibase_error() altibase_fetch_lengths() altibase_fetch_row() altibase_field() altibase_field_count() altibase_free_result() altibase_get_charset() altibase_get_charset_info() altibase_host_info() altibase_init() 목차 3

4 altibase_list_fields() altibase_list_tables() altibase_next_result() altibase_num_fields() altibase_num_rows() altibase_proto_version() altibase_proto_verstr() altibase_query() altibase_rollback() altibase_server_version() altibase_server_verstr() altibase_set_charset() altibase_set_autocommit() altibase_set_failover_callback() altibase_set_option() altibase_sqlstate() altibase_store_result() altibase_use_result() Prepared Statement 관련 ACI 함수 altibase_stmt_affected_rows() altibase_stmt_bind_param() altibase_stmt_bind_result() altibase_stmt_close() altibase_stmt_data_seek() altibase_stmt_errno() altibase_stmt_error() altibase_stmt_execute() altibase_stmt_fetch() altibase_stmt_fetch_column() altibase_stmt_fetched() altibase_stmt_field_count() altibase_stmt_free_result() altibase_stmt_get_attr() altibase_stmt_init() Altibase C Interface Manual

5 altibase_stmt_num_rows() altibase_stmt_param_count() altibase_stmt_prepare() altibase_stmt_processed() altibase_stmt_reset() altibase_stmt_result_metadata() altibase_stmt_send_long_data() altibase_stmt_set_array_bind() altibase_stmt_set_array_fetch() altibase_stmt_set_attr() altibase_stmt_sqlstate() altibase_stmt_status() altibase_stmt_store_result() Array Binding과 Array Fetch 개요 Array Binding Array Fetch Fail-Over 개요 사용법 찾아보기 목차 5

6

7 서문 서문 7

8 이매뉴얼에대하여 이매뉴얼은 Altibase C API 의사용법에대해설명한다. 대상사용자 이매뉴얼은다음과같은 ALTIBASE HDB 사용자를대상으로작성되었다. 데이터베이스관리자 성능관리자 데이터베이스사용자 응용프로그램개발자 기술지원부다음과같은배경지식을가지고이매뉴얼을읽는것이좋다. 컴퓨터, 운영체제및운영체제유틸리티운용에필요한기본지식 관계형데이터베이스사용경험또는데이터베이스개념에대한이해 컴퓨터프로그래밍경험 데이터베이스서버관리, 운영체제관리또는네트워크관리경험 소프트웨어환경 이매뉴얼은데이터베이스서버로 ALTIBASE HDB 버전 을 사용한다는가정하에작성되었다. 이매뉴얼의구성 이매뉴얼은다음과같이구성되어있다. 제 1 장 Altibase C 인터페이스소개이장은 Altibase C 인터페이스가무엇인지소개하고기본적인사용법에대해서설명한다. 제 2 장데이터타입이장은 Altibase C 인터페이스와함께사용되는데이터타입에 8 Altibase C Interface Manual

9 대해서설명한다. 제 3 장함수이장은 Altibase C 인터페이스함수의명세를기술한다. 제 4 장 Prepared Statement 관련함수이장은 Prepared Statement 와관련된 Altibase C 인터페이스함수의명세를기술한다. 제 5 장 Array Binding 과 Array Fetch 이장은여러건의데이터를한꺼번에처리하는방법인 array binding 과 array fetch 에대해서설명한다. 제 6 장 Fail-Over 이장은 Altibase C 인터페이스를사용해서 Failover 관련작업을수행하는방법을설명한다. 문서화규칙 이절에서는이매뉴얼에서사용하는규칙에대해설명한다. 이규칙을이해하면이매뉴얼과설명서세트의다른매뉴얼에서정보를쉽게찾을수있다. 여기서설명하는규칙은다음과같다. 구문다이어그램 샘플코드규칙 구문다이어그램 이매뉴얼에서는다음구성요소로구축된다이어그램을사용하여, 명령문의구문을설명한다. 구성요소 예약어 의미명령문이시작한다. 완전한명령문이아닌구문요소는화살표로시작한다. 명령문이다음라인에계속된다. 완전한명령문이아닌구문요소는이기호로종료한다. 명령문이이전라인으로부터계속된다. 완전한명령문이아닌구문요소는이기호로시작한다. ; 명령문이종료한다. SELECT 필수항목 서문 9

10 선택적항목 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 SWNO HJNO HSCHOI Altibase C Interface Manual

11 그밖에기호기울임꼴소문자대문자 위에서보여진기호이외에기호들구문요소에서사용자가지정해야하는변수, 특수한값을제공해야만하는위치지정자사용자가제공하는프로그램의요소들, 예를들어테이블이름, 칼럼이름, 파일이름등시스템에서제공하는요소들또는구문에나타나는키워드 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 Precompiler User s Manual CLI User's Manual isql User s Manual Utilities Manual Error Message Reference 온라인매뉴얼 Altibase 고객서비스포털 ( 에서국문및 영문매뉴얼 (PDF, HTML) 을받을수있다. Altibase 는여러분의의견을환영합니다. 이매뉴얼에대한여러분의의견을보내주시기바랍니다. 사용자의의견은다음버전의매뉴얼을작성하는데많은도움이됩니다. 보내실때에는아래내용과함께고객서비스포털 ( 로보내주시기바랍니다. 서문 11

12 사용중인매뉴얼의이름과버전 매뉴얼에대한의견 사용자의성함, 주소, 전화번호이외에도 Altibase 기술지원설명서의오류와누락된부분및기타기술적인문제들에대해서이주소로보내주시면정성껏처리하겠습니다. 또한, 기술적인부분과관련하여즉각적인도움이필요한경우에도고객서비스포털을통해서비스를요청하시기바랍니다. 여러분의의견에항상감사드립니다. 12 Altibase C Interface Manual

13 1. Altibase C 인터페이스 소개 이장은 Altibase C 인터페이스가무엇인지소개하고기본적인 사용법에대해서설명한다. Altibase C 인터페이스소개 13

14 Altibase C 인터페이스란? Altibase C 인터페이스 (Altibase C Interface, 앞으로 ACI 라칭함 ) 는클라이언트응용프로그램에서 ALTIBASE HDB 에접근하기위해사용할수있는 C 함수이다. C 언어로클라이언트응용프로그램작성시 ACI 를이용할수있다. ACI 를이용해서 ALTIBASE HDB 에연결, 데이터를조회또는조작할수있다.. ACI vs. CLI Altibase CLI 는 ODBC 표준인터페이스인반면, ACI 는 ALTIBASE HDB 전용인터페이스이다. ACI 를사용하면 ODBC 보다적은수의 함수호출로도동일한 SQL 문을수행할수있다. 14 Altibase C Interface Manual

15 ACI 사용방법 이절은 ACI 를이용한응용프로그램작성에필요한사전지식을 제공한다. 기본사용법 ACI 응용프로그램은일반적으로다음의 3 단계로구성된다. 초기설정 트랜잭션처리 종료위단계에더해서, 오류발생시에는진단메시지를확인하는단계가추가될수있다 altibase_init() altibase_connect() Initializing Handles altibase_stmt_init() Transaction Processing altibase_stmt_close() altibase_close() Releasing Handles 초기설정 이단계에서는연결핸들및명령문핸들을할당하고초기화한다. 핸들은이전단계의실행결과에관한정보를저장하고있는메모리포인터이며, 한단계에서다음단계로의전이는적절한핸들을전달함으로써이루어진다. ACI 응용프로그램작성을위해제공되는핸들의종류는다음과같다. ALTIBASE 핸들 ALTIBASE 핸들은 ACI 가관리하는연결과관련된정보를저장하는 메모리포인터이다. 이정보에는연결상태와트랜잭션의상태가 Altibase C 인터페이스소개 15

16 포함된다. 응용프로그램에서는각연결별로 ALTIBASE 핸들을생성하고초기화해야하며, 이핸들을이용해서 ALTIBASE HDB 로연결을시도할수있다. 또한, 이핸들을사용해서 ALTIBASE HDB 에대해 SQL 문을수행할수도있다. ALTIBASE_STMT 핸들 Prepare-Execution 방식으로 SQL 문을수행하려면 ALTIBASE_STMT 핸들을사용해야한다. 하나의연결핸들에대해 최대 1024 개의 ALTIBASE_STMT 핸들이할당될수있다. 트랜잭션처리 다음의도식은트랜잭션을처리하기위해서함수가호출되는 일반적인절차를보여준다. Prepare a statement altibase_stmt_prepare() altibase_stmt_bind_param() Execute a statement directly altibase_query() Execute a statement altibase_stmt_execute() Get entire ResultSets (Option) altibase_stmt_store_result() Get ResultSet Handles altibase_use_result() altibase_store_result() Fetch each row from a ResultSet (Using SELECT) altibase_stmt_field_count() altibase_stmt_bind_result() altibase_stmt_fetch() Fetch each row from a ResultSet (Using SELECT) altibase_field_count() altibase_fetch_lengths() altibase_fetch_row() Release a ResultSet handle altibase_stmt_free_result() Release a ResultSet handle altibase_free_result() 종료 이단계에서는핸들과핸들이참조하는정보가저장된메모리를 해제하며, 응용프로그램을종료한다. 16 Altibase C Interface Manual

17 진단 진단이란응용프로그램내에서 ACI 함수호출시발생한오류나경고상태를확인하는것을말한다. ACI 함수호출의반환값을검사해서함수가성공적으로수행되었는지여부를확인할수있다. 함수별반환값은 3 장의각함수에대한설명을참고하라. 함수가성공적으로수행되지못한경우, 진단메시지가생성된다. 진단메시지를확인하기위해서, 다음의함수를사용할수있다. 함수호출시사용된핸들의종류에따라서사용할수있는진단함수가달라진다. 핸들타입 ALTIBASE ALTIBASE_STMT 설명함수 altibase_errno() altibase_stmt_errno() 에러코드조회 altibase_error() altibase_stmt_error() 에러메시지조회 altibase_sqlstate() altibase_stmt_sqlstate( ) SQLSTATE 코드조회 함수반환값이 ALTIBASE_SUCCESS, ALTIBASE_NO_DATA_FOUND 및 ALTIBASE_INVALID_HANDLE 이아닌경우에만진단메시지를조회할수있다. 진단메시지 진단메시지중 SQLSTATE 코드는 5 개의알파벳과숫자로이루어진문자열이다. 첫두문자는클래스를가리키며, 뒤의세문자는하위클래스를가리킨다. ACI 진단메시지는 X/Open SQL CAE 명세를준수한다. 주의사항 멀티쓰레드프로그램을작성할때, 쓰레드별로환경핸들, 연결핸들을각각할당해야한다. ALTIBASE HDB 클라이언트라이브러리는신호처리를하지않는다. 따라서외부원인에의해네트워크접속이종료된경우, SIGPIPE 신호를받아진행중인응용프로그램이강제로종료될수있다. 이러한강제종료를막기위해서는 SIGPIPE 신호를사용자응용프로그램에서처리해야한다. SIGPIPE 신호처리를처리하는함수내에서 ALTIBASE HDB 클라이언트라이브러리함수를호출하면프로그램이멈출수도있으므로, 신호처리함수작성에 Altibase C 인터페이스소개 17

18 주의해야한다. 하지만신호처리가끝난후에는 ALTIBASE HDB 클라이언트라이브러리함수를호출하는것이가능하다. 18 Altibase C Interface Manual

19 클라이언트응용프로그램빌드 이절은클라이언트응용프로그램을빌드하는데필요한헤더 파일과라이브러리파일에대해기술한다. 헤더파일 응용프로그램작성시에포함되고, 컴파일시에참조되는헤더파일은 alticapi.h 로, 이는 $ALTIBASE_HOME/include 디렉토리에존재한다. 컴파일시에는컴파일명령어에다음의옵션을사용하라 : -I$ALTIBASE_HOME/include 라이브러리파일 응용프로그램을빌드하려면, 컴파일된오브젝트파일을 ALTIBASE HDB 가제공하는 ACI 라이브러리및 ODBC 라이브러리와함께링크해야한다. 이들라이브러리는아래의파일들이며, $ALTIBASE_HOME/lib 디렉토리에존재한다. libalticapi.a libodbccli.a 링크시에는링크명령어에다음의옵션을사용하라 : -L$ALTIBASE_HOME/lib -lalticapi -lodbccli Altibase C 인터페이스소개 19

20

21 2. 데이터타입 이장은 Altibase C 인터페이스와함께사용되는데이터타입에 대해서설명한다. 데이터타입 21

22 ACI 자료구조 이절은 Altibase C 인터페이스의자료구조들을기술한다. 이자료구조들은응용프로그램작성시 ACI 함수들과함께사용될것이다. 자료구조들은크게다음과같이분류된다. 핸들타입 구조체타입 그외데이터타입 핸들 ACI 핸들에는다음의세개가있다. ALTIBASE ALTIBASE_STMT ALTIBASE_RES ALTIBASE ALTIBASE 는데이터베이스에대한연결핸들이다. 연결핸들은대부분의 ACI 함수에사용된다. 반드시 altibase_init() 을이용해서이핸들을초기화하고, altibase_close() 를이용해서이핸들을해제해야한다. 연결핸들은하나의결과집합핸들 (ALTIBASE_RES) 만을반환하고관리한다. 즉, 하나의결과집합을사용하다가다른결과집합의핸들을얻으려면, 먼저사용중인결과집합핸들을해제해야한다. ALTIBASE_STMT ALTIBASE_STMT 는명령문핸들이다. Prepare-execution 방식으로 SQL 문을수행하려면, 이핸들을사용해야한다. 또한, SQL 문에파라미터마크가포함되어있거나 SELECT 문의결과를변수바인딩을통해가져오려면반드시준비된문장 (prepared statement) 을사용해야한다. 반드시 altibase_stmt_init() 을이용해서이핸들을초기화하고, altibase_stmt_close() 를이용해서이핸들을해제해야한다. ALTIBASE_RES 22 Altibase C Interface Manual

23 ALTIBASE_RES 는질의결과집합에대한핸들이다. 이핸들을이용해서질의결과집합과칼럼의정보를얻을수있다. 이핸들은 altibase_use_result() 또는 altibase_store_result() 함수를통해얻을수있으며, 핸들사용후에는반드시 altibase_free_result() 를사용해서해제해야한다. 구조체타입 ACI 와함께사용가능한데이터구조체는다음과같다. struct ALTIBASE_BIND struct ALTIBASE_CHARSET_INFO struct ALTIBASE_FIELD struct ALTIBASE_NUMERIC struct ALTIBASE_TIMESTAMP struct ALTIBASE_BIND 이구조체는입출력변수바인딩시사용되며, 사용자는바인딩 정보를여기에지정한다. altibase_stmt_bind_param() 는입력 파라미터를위한버퍼를바인딩하는함수이고, altibase_stmt_bind_result() 는조회된결과집합의칼럼데이터를 가져올버퍼를바인딩하는함수이다. 이구조체는다음과같은멤버를포함한다. 구조체멤버 타입 설명 buffer_type ALTIBASE_BIND_TY PE 바인딩할 buffer의타입을지정하는데사용되는멤버변수이다. "enum ALTIBASE_BIND_TYPE" 를참고하라. buffer void * 입출력데이터를담는버퍼를가리키는포인터이다. buffer_leng th ALTIBASE_LONG 입력바인딩의경우, buffer는 SQL문에물음표 (?) 로표시된파라미터에바인딩될변수일것이다. 출력바인딩의경우, buffer는조회된결과집합의각칼럼값을저장할변수일것이다. buffer의실제크기를지정하는데사용되는멤버변수이다. 길이가고정된데이터타입의변수로바인딩할때는이멤버의값을설정하지않아도된다. 그러나설정을생략하려면반드시이값이 0 으로초기화되어있어야한다. 다음타입에대해서만길이설정을생략할수있다 : 데이터타입 23

24 ALTIBASE_BIND_SMALLINT, ALTIBASE_BIND_INTEGER, ALTIBASE_BIND_BIGINT, ALTIBASE_BIND_REAL, ALTIBASE_BIND_DOUBLE, ALTIBASE_BIND_DATE 그러나, ALTIBASE_BIND_STRING과 같이 길이가 정해져있지않은데이터타입의변수로바인딩할 때는 반드시 buffer_length를 올바른 값으로 설정해야한다. 출력 변수 바인딩시, 만약 buffer_length에 설정된크기보다가져온데이터의길이가더길다면 buffer_length에설정된길이만큼만 buffer에 저장될 것이다. 예를 들어 int 값을 얻을 때 buffer_length에 4 대신 2 를주면, int 값의처음 2 바이트만 buffer에 복사된다. 올바른 값을 얻으려면 반드시 buffer_length를 바르게 설정해야한다. length ALTIBASE_LONG * 데이터의실제길이를지정하는데사용되는멤버변수이다. short, int 처럼데이터길이가고정되어있는경우에는이변수값을설정하지않아도된다. 문자열이나바이너리데이터를입력바인딩할경우, 데이터의길이가버퍼의크기보다작을수있으므로이변수에데이터의실제길이를설정해야한다. 출력바인딩으로사용되었을때, 이변수의값이 ALTIBASE_NULL_DATA로반환되면, 이는조회된칼럼의데이터가 NULL임을나타낸다. is_null ALTIBASE_BOOL * 출력바인딩으로사용되었을때, 조회된칼럼의 데이터가 NULL이면 여기에 ALTIBASE_TRUE가 반환된다. 칼럼데이터를사용하기전에먼저이 변수를이용해서해당데이터가 NULL인지여부를 확인할것을권장한다. error int 바인딩 수행 결과를 반환하는 멤버 변수이다. 바인딩에실패했을때, 이변수값을확인하면어떤 인자의바인딩에실패했는지알수있다. error 값은 altibase_errno() 로얻을수있는에러 번호중하나로반환된다. 이에대한자세한내용은 altibase_errno() 를참고한다. struct ALTIBASE_CHARSET_INFO 문자집합 (Character Set) 정보가담긴구조체이다. altibase_get_charset_info() 함수호출시이구조체로문자집합에대한정보가반환된다. 이구조체는다음과같은멤버를포함한다. 24 Altibase C Interface Manual

25 구조체멤버 타입 설명 id unsigned int 문자집합식별자 name void * 문자셋의이름 name_length int 문자집합이름의길이 mbmaxlen int 한문자를저장하기위해필요한최대크기 ( 바이트단위 ) struct ALTIBASE_FIELD SELECT 문으로조회되는결과집합의칼럼정보가담긴구조체이다. altibase_field() 또는 altibase_fields() 함수를이용해서칼럼정보를 이구조체타입으로구할수있다. 이렇게얻은구조체포인터가 가리키는메모리의값은 ACI 내부적으로관리되므로, 사용자가 임의로값을변경하거나해제해서는안된다. 이구조체는다음의멤버를포함한다. 구조체멤버 타입 설명 type ALTIBASE_FIELD_TYPE 칼럼의데이터타입 name char 칼럼의이름. [ALTIBASE_MAX_FIELD_ 질의에서 칼럼에 별칭 (alias) 를 준 NAME_LEN] 경우, 이값은주어진별칭이될 것이다. name_length int name의길이 org_name char 칼럼의이름 [ALTIBASE_MAX_FIELD_ NAME_LEN] org_name_leng th int org_name의길이 table char [ALTIBASE_MAX_TABLE _NAME_LEN] 이칼럼을포함하는테이블의이름. 질의에서테이블에별칭 (alias) 를준경우, 이값은주어진별칭이될것이다. table_length int table의길이 org_table char 테이블이름 [ALTIBASE_MAX_TABLE _NAME_LEN] org_table_len gth int org_table의길이 size int 칼럼 크기 또는 숫자형 타입의 precision scale int 숫자형타입의 scale 데이터타입 25

26 struct ALTIBASE_NUMERIC 숫자형데이터를저장하는구조체이다. NUMERIC 타입의데이터를 가져올때사용된다. 이구조체는다음의멤버를포함한다. 구조체멤버 precision scale sign val 타입 unsigned char unsigned char char unsigned char [ALTIBASE_MAX_NUMERIC_LEN] struct ALTIBASE_TIMESTAMP 날짜형데이터를저장하는구조체이다. DATE 타입의데이터를 가져올때사용된다. 이구조체는다음의멤버를포함한다. 구조체멤버 타입 설명 year short 년 month unsigned short 월 day unsigned short 일 hour unsigned short 시 minute unsigned short 분 second unsigned short 초 fraction int 1/ 초 그외타입 위에서설명한핸들과구조체외에다음의타입이사용될수있다. ALTIBASE_ROW ALTIBASE_LONG ALTIBASE_NTS enum ALTIBASE_BIND_TYPE enum ALTIBASE_FAILOVER_EVENT enum ALTIBASE_FIELD_TYPE enum ALTIBASE_OPTION 26 Altibase C Interface Manual

27 enum ALTIBASE_STMT_ATTR_TYPE ALTIBASE_ROW 이타입은질의결과의한행을타입안전방식으로표현 (type-safe representation) 한다. SELECT 와같이결과집합을반환하는질의를 altibase_query() 로실행한후, altibase_fetch_row() 를호출해서이타입의값을얻을수있다. 각칼럼의값은문자열또는바이너리데이터로구성된다. BLOB, BYTE, NIBBLE, BIT, VARBIT, GEOMETRY 타입의칼럼값은바이너리로표현되며, 그외의데이터타입값은문자열로표현된다. 특히, NIBBLE, BIT, VARBIT 타입은특별한형식을가진다. NIBBLE 은 4 비트, BIT 는 1 비트단위로값이이루어져있으므로, 이를사용자가인식하기쉬운값으로얻기위해서는 GET_NIBBLE_VALUE(), GET_BIT_VALUE() 와같은매크로를사용하면된다. 매크로정의는 alticapi.h 헤더파일을참조하라. 이타입의값 ( 내부적으로 char 포인터 ) 이가리키는메모리는내부에서관리되므로사용자가임의로변경하거나해제를시도해서는절대안된다. ALTIBASE_LONG 32 비트또는 64 비트정수형이다. ODBC 스펙에정의된 SQLLEN 타입과동일하다. 이타입은행번호나행의개수를 나타내는데사용된다. ALTIBASE_NTS 이는데이터가널로끝나는문자열임을나타내기위해사용되는매크로이다. 문자열을입력바인딩할때, 데이터길이를실제길이대신에이값으로설정할수있다. 바이너리데이터를입력바인딩할때는, 데이터길이를 ALTIBASE_NTS 로설정하면안된다. enum ALTIBASE_BIND_TYPE 바인딩할데이터의타입을지정할때사용된다. 이열거형의원소는다음과같다. 원소 설명 데이터타입 27

28 ALTIBASE_BIND_NULL NULL 데이터를칼럼에입력하고자할때 사용된다. ALTIBASE_BIND 구조체의 is_null 멤버변수를 ALTIBASE_TRUE로 설정한것과같다. 파라미터를바인딩할때만쓸수있다. ALTIBASE_BIND_BINARY 바이너리데이터. BYTE, NIBBLE, BIT, VARBIT, BLOB, GEOMETRY 타입에 데이터입력시사용된다. ALTIBASE_BIND_STRING 문자열. CHAR, VARCHAR, NCHAR, NVARCHAR 타입에 데이터 입력시 사용된다. ALTIBASE_BIND_WSTRING 유니코드문자열 ALTIBASE_BIND_SMALLINT 16 비트정수. SMALLINT 타입에데이터 입력시사용된다. ALTIBASE_BIND_INTEGER 32 비트정수. INTEGER 타입에데이터 입력시사용된다. ALTIBASE_BIND_BIGINT 64 비트정수. BIGINT 타입에데이터 입력시사용된다. ALTIBASE_BIND_REAL 실수. REAL 타입에 데이터 입력시 사용된다. ALTIBASE_BIND_DOUBLE 배정밀도실수. DOUBLE 타입에데이터 입력시사용된다. ALTIBASE_BIND_NUMERIC 숫자형 데이터. NUMERIC, DECIMAL, NUMBER, FLOAT 타입에데이터입력시 사용된다. ALTIBASE_BIND_DATE 날짜와시간. DATE 타입에데이터입력시 사용된다. enum ALTIBASE_FAILOVER_EVENT Failover 이벤트를나타내는열거형이다. Failover 콜백함수를 등록했다면, 등록된함수의 event 인자를통해서이열거형원소 중의한값이전달된다. 또한, 사용자는콜백함수에서이열거형값 중의하나를반환해서 Failover 의다음작업과정을계속진행할지 여부를지정할수있다. 이에대한자세한내용은 6 장. FailOver 를 참고한다. 이열거형의원소는다음과같다. 원소 설명 ALTIBASE_FO_BEGIN STF가시작됨을콜백함수에알리는값이다. ALTIBASE_FO_END STF가 성공하였음을 콜백 함수에 알리는 값이다. 28 Altibase C Interface Manual

29 ALTIBASE_FO_ABORT STF가 실패하였음을 콜백 함수에 알리는 값이다. ALTIBASE_FO_GO 사용자가콜백함수에서라이브러리로 STF의 다음 과정을 진행하라는 의미로 반환하는 값이다. ALTIBASE_FO_QUIT 사용자가콜백함수에서라이브러리로 STF의 다음 과정을 진행하지 말라는 의미로 반환하는값이다. enum ALTIBASE_FIELD_TYPE 이는칼럼의데이터타입이포함된열거형이다. 숫자타입인지확인하기위해 IS_NUM_TYPE() 매크로를사용할수있다. 숫자타입에는 SMALLINT, INTEGER, BIGINT, REAL, DOUBLE, FLOAT, NUMERIC 이있다. 바이너리타입인지확인하기위해 IS_BIN_TYPE() 매크로을사용할수있다. 바이너리타입에는 BYTE, BLOB, NIBBLE, BIT, VARBIT, GEOMETRY 가있다. IS_NUM_TYPE() 과 IS_BIN_TYPE() 매크로의정의는 alticapi.h 헤더파일을참조하라. 이열거형의원소는다음과같다. 원소 ALTIBASE_TYPE_CHAR ALTIBASE_TYPE_VARCHAR ALTIBASE_TYPE_NCHAR ALTIBASE_TYPE_NVARCHAR ALTIBASE_TYPE_SMALLINT ALTIBASE_TYPE_INTEGER ALTIBASE_TYPE_BIGINT ALTIBASE_TYPE_REAL ALTIBASE_TYPE_DOUBLE ALTIBASE_TYPE_FLOAT ALTIBASE_TYPE_NUMERIC ALTIBASE_TYPE_DATE ALTIBASE_TYPE_BLOB ALTIBASE_TYPE_CLOB ALTIBASE_TYPE_BYTE ALTIBASE_TYPE_NIBBLE CHAR VARCHAR NCHAR NVARCHAR SMALLINT INTEGER BIGINT REAL DOUBLE FLOAT NUMERIC DATE BLOB CLOB BYTE NIBBLE 설명 데이터타입 29

30 ALTIBASE_TYPE_BIT ALTIBASE_TYPE_VARBIT ALTIBASE_TYPE_GEOMETRY BIT VARBIT GEOMETRY enum ALTIBASE_OPTION 서버와의연결속성을설정할때사용되는열거형이다. 이중 ALTIBASE_AUTOCOMMIT 속성은 altibase_set_autocommit() 함수를사용해서설정하기를권장한다. 이열거형의원소 ( 즉, 연결속성 ) 와각속성에지정할수있는값의 타입및최대크기는다음과같다. 원소 ( 연결속성 ) 속성값의 속성값의 설명 타입 최대크기 ALTIBASE_AUTOCOMMI int sizeof(int) AUTOCOMMIT 여부를 T 설정하는속성. 속성의 값은 32 비트 크기이다. 이 속성의 값은 ALTIBASE_AUTOCOMMIT_ ON 또는 ALTIBASE_AUTOCOMMIT_ OFF 로설정할수있다. ALTIBASE_CONNECTION int sizeof(int) 네트워크 불안정으로 인해 _TIMEOUT 데이터송수신시발생할수 있는블록킹을방지하기위한타임아웃값을설정하는속성 ALTIBASE_PORT int sizeof(int) ALTIBASE HDB 서버의포트번호를설정하는속성 ALTIBASE_TXN_ISOLATI int sizeof(int) 트랜잭션의 고립화 수준을 ON 설정하는속성 ALTIBASE_APP_INFO char * ALTIBASE_MAX_A 클라이언트 식별자를 PP_INFO_LEN 지정하는속성. 클라이언트에 대한 보다 정확한정보를설정하기위해사용된다. ALTIBASE_DATE_FORM char * ALTIBASE_MAX_D 날짜형식을지정하는속성. AT ATE_FORMAT_LEN 기본값은 "YYYY/MM/DD HH:MI:SS" 이다. ALTIBASE_NLS_USE char * ALTIBASE_MAX_NL 클라이언트 사용 언어를 S_USE_LEN 지정하는속성. (US7ASCII: 영어, 30 Altibase C Interface Manual

31 KO16KSC5601: 한국어 ) ALTIBASE_NLS_NCHAR_ int sizeof(int) SQL 구문에 NCHAR 리터럴 LITERAL_REPLACE 문자열이 존재하는지 검사 여부를설정하는속성. ALTIBASE_IPC_FILEPATH char * ALTIBASE_MAX_IP 유닉스 환경에서 서버와 C_FILEPATH_LEN 클라이언트가 IPC로 접속할 때 ALTIBASE_HOME이서로 다르다면, 유닉스 도메인의 소켓경로가일치하지않아 접속이불가능하다. 이때이 속성의 값을 서버의 $ALTIBASE_HOME/trc/cmipc 파일로설정하여서버와 클라이언트가 같은 소켓 파일을사용하도록하면, IPC 접속이가능해진다. enum ALTIBASE_STMT_ATTR_TYPE 명령문핸들에대한속성을설정하기위해사용되는열거형이다. 이열거형의원소는다음과같다. 원소 ( 명령문속성 ) ALTIBASE_STMT_ATTR_ ATOMIC_ARRAY 속성값의타입 속성값의최대크기 설명 int sizeof(int) Atomic Array Insert 사용여부를 설정하는속성이다. 일반적인 Array Insert의경우배열내의각 SQL문이 서버에서다른 statement로처리되는 것에비해, Atomic Array Insert는 배열에속한모든 SQL문들이서버에서 한개의 statement로처리된다. 이 속성은 ALTIBASE_ATOMIC_ARRAY_ON 또는 ALTIBASE_ATOMIC_ARRAY_OFF로 설정할 수 있다. 이 외의 값을 설정하면에러가발생한다. ALTIBASE_ATOMIC_ARRAY_ON을 설정하면 Atomic Array Insert 방식으로실행된다. 그러나 Atomic Array Insert가 기존의 Array Insert보다 빠른 성능을 발휘하기 위해서는 Array Size를지정해야한다. Atomic Array Insert 수행시에는 데이터타입 31

32 배열에속한모든 SQL문들이서버에서한개의 statement로처리되므로, altibase_stmt_status(), altibase_stmt_processed() 가반환하는결과값 ( 반환타입이배열이다 ) 의첫번째요소값만이유효하다. 데이터타입간의관계 아래의그림은 ACI 의각핸들과데이터타입들사이의관계를보여준다. start altibase_init() ALTIBASE altibase_use_result() altibase_store_result() altibase_list_fields() altibase_list_tables() altibase_stmt_init() ALTIBASE_STMT altibase_stmt_result_metadata() altibase_stmt_close() altibase_stmt_free_result() End ALTIBASE_RES altibase_free_result() altibase_field() altibase_fields() ALTIBASE_FIELD altibase_fetch_row() ALTIBASE_ROW 위관계도를보면 ALTIBASE_STMT 핸들을사용해서얻은 ALTIBASE_RES 로는 ALTIBASE_ROW 를얻을수없음을알수있다 ( 점선으로표시 ). ALTIBASE_ROW 는바인딩없이 SQL 문을직접수행 (direct execution) 하는 altibase_query() 관련함수를통해서만구할수있다. 이에대한자세한내용은각함수의설명을참고하라. 32 Altibase C Interface Manual

33 3. ACI 함수 이장은 Altibase C 인터페이스함수들중연결핸들인 ALTIBASE 핸들을사용하는함수들의명세를기술한다. 각 ACI 함수별로다음의정보가제공된다. 함수명 : 사용목적 구문 : 이함수의 C 언어프로토타입 인자 : 함수의각인자별자료유형, 입 / 출력, 부연설명 반환값 : 반환가능한이함수의리턴값 설명 : 함수사용방법및주의사항 관련함수 : 이함수와관련된함수리스트 예제 : 이함수가사용된소스코드의일부 ACI 함수 33

34 altibase_affected_rows() 바로이전에실행한 UPDATE, DELETE 또는 INSERT 문에의해 영향을받은레코드의수를구하는함수이다. 구문 ALTIBASE_LONG altibase_affected_rows ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 반환값 설명 0 보다큰값 SQL문에의해영향을받은레코드의개수 0 SQL문에의해영향을받은레코드가없음 ALTIBASE_INVALID_AFFECTEDROW UPDATE, DELETE, 또는 INSERT 수행중에러발생 설명 이함수는마지막으로수행한 SQL 문의종류에따라다음과같은값을반환한다 : UPDATE 문 : 변경된레코드수 DELETE 문 : 삭제된레코드수 INSERT 문 : 추가된레코드수만약마지막으로수행한 SQL 문이 SELECT 문이었다면이함수는 0 을반환할것이다. SELECT 문에의해선택된레코드의개수를얻고자할때는 altibase_num_rows() 를사용해야한다. 예제 34 Altibase C Interface Manual

35 #define QSTR "UPDATE employees SET salary = salary * 1.1 WHERE group = 1" rc = altibase_query(altibase, QSTR); /*... check return value... */ printf("%ld updated\n", altibase_affected_rows(altibase)); ACI 함수 35

36 altibase_client_version() 클라이언트라이브러리의버전을구하는함수이다. 구문 int altibase_client_version( void ); 반환값 클라이언트라이브러리버전을나타내는상수가반환된다. 설명 이함수는클라이언트라이브러리의버전을나타내는상수를 반환한다. 반환값의형식은 MMmmttSSpp 이며각각의의미는다음과 같다. 형식 설명 비고 MM 주버전 mm 부버전 버전의자리수가 2보다작을경우, 나머지자리는 0으로채워서반환된다. tt 텀 버전의자리수가 2보다작을경우, 나머지자리는 0으로채워서반환된다. SS 패치셋 버전의자리수가 2보다작을경우, 나머지자리는 0으로채워서반환된다. pp 패치 버전의자리수가 2보다작을경우, 나머지자리는 0으로채워서반환된다. 예를들어, 이함수의반환값이 이면클라이언트 라이브러리의버전은 이다. 36 Altibase C Interface Manual

37 altibase_client_verstr() 클라이언트라이브러리의버전을구하는함수이다. 구문 const char * altibase_client_verstr ( void ); 반환값 클라이언트라이브러리버전을나타내는문자열이반환된다. 설명 이함수는클라이언트라이브러리의버전을나타내는문자열을반환한다. 반환값의형식은 x.x.x.x.x 이며순서대로주버전, 부버전, 텀, 패치셋, 패치를의미한다. 이함수가반환한 char 포인터가가리키는메모리는라이브러리내부에서관리되므로절대로사용자가임의로변경하거나해제해서는안된다. ACI 함수 37

38 altibase_close() 서버와의연결을닫는함수이다. 구문 int altibase_close ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 함수수행에성공하면 ALTIBASE_SUCCESS, 실패하면 ALTIBASE_ERROR 이반환된다. 설명 이함수는서버와의연결을종료하고, 연결핸들을위해할당된모든자원을해제한다. 이함수가호출되면인자로전달되는연결핸들에속한모든명령문핸들 (ALTIBASE_STMT) 에관련된 SQL 문처리가중단되고그결과들은폐기되며이들명령문핸들과관련된모든자원도해제된다. 연결핸들을사용해서반환받은결과집합핸들이있다면, 이함수를실행하기전에반드시 altibase_free_result() 함수를호출해서결과집합핸들을먼저해제해야한다. 예제 altibase = altibase_init(); if (altibase == NULL) { return 1; } 38 Altibase C Interface Manual

39 /*... omit... */ rc = altibase_close(altibase); /*... check return value... */ ACI 함수 39

40 altibase_commit() 이함수는현재트랜잭션을커밋한다. 구문 int altibase_commit ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 함수수행에성공하면 ALTIBASE_SUCCESS, 실패하면 ALTIBASE_ERROR 이반환된다. 설명 이함수는현재연결된세션에서수행중인트랜잭션을커밋한다. 해당세션이 AUTOCOMMIT 모드가아닌경우, 이함수수행후다음 SQL 문실행시에자동으로새로운트랜잭션이시작된다 예제 altibase_set_autocommit() 의예제를참고하라. 40 Altibase C Interface Manual

41 altibase_connect() 서버에접속하는함수이다. 구문 int altibase_connect ( ALTIBASE altibase, const char* connstr ); 인자 자료유형 인자 입 / 출력 설명 ALTIBASE altibase 입력 연결핸들 const char* connstr 입력 연결속성문자열 반환값 함수수행에성공하면 ALTIBASE_SUCCESS 이, 실패하면 ALTIBASE_ERROR 이반환된다. 설명 이함수는사용자가명시한연결속성을사용하여서버에연결한다. 연결속성에는 DSN, PORT_NO, UID, PWD, CONNTYPE, NLS_USE 등이있다. 이에대한자세한내용은 CLI User's Manual 를참고하기바란다. 연결속성문자열은반드시 NULL 종료문자열이어야한다. 예제 #define CONNSTR "DSN= ;PORT_NO=20300;UID=sys;PWD=manager" ALTIBASE altibase; altibase = altibase_init(); /*... check return value... */ ACI 함수 41

42 rc = altibase_set_option(altibase, ALTIBASE_APP_INFO, "your_app_name"); /*... check return value... */ rc = altibase_connect(altibase, CONNSTR); if (ALTIBASE_NOT_SUCCEEDED(rc)) { fprintf(stderr, "Failed to connect : %s\n", altibase_error(altibase)); } 42 Altibase C Interface Manual

43 altibase_data_seek() 질의결과집합에서가져올행의위치를지정하는함수이다. 구문 int altibase_data_seek ( ALTIBASE_RES result, ALTIBASE_LONG offset ); 인자 자료유형 인자 입 / 출력 설명 ALTIBASE_RES result 입력 결과집합핸들 ALTIBASE_LONG offset 입력 다음에가져올행의위치 (0 부터시작 ) 반환값 함수수행에성공하면 ALTIBASE_SUCCESS, 실패하면 ALTIBASE_ERROR 이반환된다. 설명 이함수는결과집합에서다음에가져올행의위치를특정위치로이동시킨다. 위치로지정하는행번호의값은 0 부터 ( 결과집합의행개수 1) 까지의값이어야한다. altibase_store_result() 호출이후에만이함수를실행할수있다. 예제 #define QSTR "SELECT last_name, first_name FROM friends" rc = altibase_qeury(altibase, QSTR); /*... check return value... */ result = altibase_store_result(altibase); /*... check return value... */ ACI 함수 43

44 row_count = altibase_num_rows(result); for (i = 0; i < row_count; i++) { rc = altibase_data_seek(result, i); if (ALTIBASE_NOT_SUCCEEDED(rc)) { printf("err : %d : ", i, altibase_error()); continue; } } /*... omit... */ rc = altibase_free_result(result); /*... check return value... */ 44 Altibase C Interface Manual

45 altibase_errno() 바로이전에실행된함수에서발생한오류의에러코드를구하는 함수이다. 구문 unsigned int altibase_errno ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 바로이전에호출된함수가성공했으면 0, 실패했으면에러코드가 반환된다. 설명 이함수는바로이전에실행된함수가실패했을경우, 실패원인을알려주는에러코드를반환한다. 바로이전에실행된함수가실패했더라도, 모든함수에대해서에러코드가반환되지는않는다. 직전에수행된함수가주로 SQL 문수행과관련된함수였을경우에만에러코드가생성된다. 에러코드에대한자세한내용은 Error Message Reference 를참고한다. 어떤함수수행시오류가발생한경우바로오류를확인하지않고다른함수를호출하면, 이오류에대한정보가사라진다. 따라서오류발생시바로이함수를사용해서오류정보를확인해야한다. altibase_errno() 가반환하는값은 ALTIBASE HDB 자체정의오류코드로 ODBC 표준명세에정의된 SQLSTATE 과는다르다. SQLSTATE 를얻으려면 altibase_sqlstate() 를사용해야한다. 일반적으로 altibase_errno() 의반환값을확인해서에러처리루틴을 ACI 함수 45

46 작성하는것을권장하지않는다. 예제 rc = altibase_query(altibase, QSTR); if (ALTIBASE_NOT_SUCCEEDED(rc)) { printf("error no : %05X\n", altibase_errno(altibase)); printf("error msg : %s\n", altibase_error(altibase)); printf("sqlstate : %s\n", altibase_sqlstate(altibase)); return 1; } /*... omit... */ 46 Altibase C Interface Manual

47 altibase_error() 바로이전에실행된함수에서발생한오류의에러메시지를구하는 함수이다. 구문 const char * altibase_error ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 바로이전에호출된함수가성공했으면빈문자열이, 실패했으면 에러메시지문자열이반환된다. 설명 이함수는바로이전에실행된함수가실패했을경우, 실패원인을알려주는에러메시지를반환한다. 어떤함수수행시오류가발생한경우바로오류를확인하지않고다른함수를호출하면, 이오류에대한정보가사라진다. 따라서오류발생시바로이함수를사용해서오류정보를확인해야한다. 이함수가반환한 char 포인터가가리키는메모리는라이브러리내부에서관리되므로절대로사용자가임의로변경하거나해제해서는안된다. 예제 altibase_errno() 의예제를참고하라. ACI 함수 47

48 altibase_fetch_lengths() 결과집합에서현재행의칼럼들의길이를반환한다. 구문 ALTIBASE_LONG * altibase_fetch_lengths ( ALTIBASE_RES result ); 인자 자료유형인자입 / 출력설명 ALTIBASE_RES result 입력결과집합핸들 반환값 칼럼들의크기를담은배열이반환된다. 에러가발생하면 NULL 이 반환된다. 설명 이함수는현재행을구성하고있는각칼럼의데이터길이를배열로반환한다. 사용자는이함수의반환값을이용해서각칼럼의데이터를담을버퍼의크기를결정할수있다. 칼럼의데이터가문자열인경우, NULL 종료문자를제외한길이가반환된다. 칼럼의데이터가 NULL 인경우, 반환되는길이는 ALTIBASE_NULL_DATA 이다. 이함수호출전에반드시결과집합핸들에대해서 altibase_fetch_row() 함수가한번이상실행되어야한다. altibase_fetch_row() 를실행하기전이거나결과집합에더이상반환될행이없는경우에이함수는 NULL 을반환한다. altibase_fetch_row() 로얻은데이터에는바이너리데이터가포함되어있을수있기때문에, strlen() 함수를이용해서데이터의길이를추정해서는안된다. 반드시 altibase_fetch_lengths() 함수를 48 Altibase C Interface Manual

49 사용해서반환될데이터의길이를확인해야한다. 이함수가반환한포인터가가리키는메모리는라이브러리내부에서 관리되므로절대로사용자가임의로변경하거나해제해서는안된다. 예제 ALTIBASE_LONG *lengths; int num_fields; int i; /*... omit... */ num_fields = altibase_num_fields(result); row = altibase_fetch_row(result); if (row!= NULL) { lengths = altibase_fetch_lengths(result); for (i = 0; i < num_fields; i++) { printf("column length %d : %ld\n", i, lengths[i]); } } /*... omit... */ ACI 함수 49

50 altibase_fetch_row() 결과집합으로부터한행을가져오는함수이다. 구문 ALTIBASE_ROW altibase_fetch_row ( ALTIBASE_RES result ); 인자 자료유형인자입 / 출력설명 ALTIBASE_RES result 입력결과집합핸들 반환값 한행의데이터가배열로반환된다. 결과집합에더이상행이없거나데이터를가져오는중에오류가발생한경우 NULL 이반환된다. 설명 이함수는결과집합에서다음행의데이터를가져온다. altibase_store_result() 후에이함수를호출했다면, 더이상가져올행이없을때만 NULL 이반환된다. 반환되는행데이터는배열로배열요소의개수는 altibase_num_fields(result) 로구할수있다. 각배열요소접근시사용가능한인덱스의범위는 0 에서 (altibase_num_fields(result) 1) 까지이다. 반환된각칼럼의데이터는타입안전방식으로표현 (type-safe representation) 되므로문자열또는바이너리형식을가진다. 그러므로숫자형데이터가필요한경우에는사용자가직접변환해서사용해야한다. 타입안전방식에대한자세한내용은 2 장의 "ALTIBASE_ROW" 타입을참고한다. 칼럼의데이터가 NULL 이면반환된배열중그칼럼에해당하는 50 Altibase C Interface Manual

51 배열요소도 NULL 포인터를가리킬것이다. altibase_fetch_row() 로얻은데이터에는바이너리값이포함되어있을수있기때문에, strlen() 함수를이용해서데이터의길이를추정해서는안된다. 반드시 altibase_fetch_lengths() 함수를사용해서반환될데이터의길이를확인해야한다. altibase_fetch_row() 가반환한데이터는한행을이루는칼럼들의값을모두포함하고있다. 그러므로결과집합내에 LOB 또는 GEOMETRY 타입의대용량데이터가포함된경우에메모리가과도하게사용될수있다. 그러므로대용량데이터를조회할때에는데이터를나눠서처리할수있는 Prepared Statement 방식을사용할것을권장한다. altibase_fetch_row() 로가져온행데이터의값은다음 altibase_fetch_row() 를호출하기전까지만유효하다. 그러므로한번가져온데이터를다시쓸계획이있다면, 다른변수에그값을복사해두어야한다. altibase_fetch_row() 함수가반환한포인터가가리키는메모리는라이브러리내부에서관리되므로절대로사용자가임의로변경하거나해제해서는안된다. 예제 altibase_query() 의예제를참고하라. ACI 함수 51

52 altibase_field() 특정칼럼에대한정보를구하는함수이다. 구문 ALTIBASE_FIELD * altibase_field ( ALTIBASE_RES result, int fieldnr ); 인자 자료유형 인자 입 / 출력 설명 ALTIBASE_RES result 입력 결과집합핸들 int fieldnr 입력 칼럼의번호 (0 부터시작 ) 반환값 지정한칼럼정보가저장된메모리를가리키는포인터가반환된다. 반환할칼럼정보가없거나오류가발생한경우 NULL 이반환된다. 설명 이함수는지정한칼럼에대한정보를 ALTIBASE_FIELD 포인터로반환한다. 지정가능한칼럼번호는 0 에서 (altibase_num_fields(result)-1) 까지의값이다. 이함수가반환한포인터가가리키는메모리는라이브러리내부에서관리되므로절대로사용자가임의로변경하거나해제해서는안된다. 예제 ALTIBASE_FIELD *field; int num_fields; int i; num_fields = altibase_num_fields(result); for (i = 0; i < num_fields; i++) { field = altibase_field(result, i); printf("%d : %s\n", i, field->name); 52 Altibase C Interface Manual

53 } ACI 함수 53

54 altibase_field_count() 가장최근에수행된 SELECT 질의결과집합의칼럼수를구하는 함수이다. 구문 int altibase_field_count ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 반환값 설명 0 보다큰값 결과집합의칼럼개수 0 결과집합이없음 ALTIBASE_INVALID_FIELDCOUNT 질의수행중에러발생 설명 이함수는바로이전에수행된 SELECT 질의결과집합의칼럼수를반환한다. 바로이전에수행된 SQL 문이 SELECT 문이아니라면, 0 이반환된다. 예제 /*... omit... */ rc = altibase_query(altibase, qstr); /*... check return value... */ printf("field count = %d\n", altibase_field_count(altibase)); 54 Altibase C Interface Manual

55 altibase_free_result() 결과집합핸들을닫는함수이다. 구문 int altibase_free_result ( ALTIBASE_RES result ); 인자 자료유형인자입 / 출력설명 ALTIBASE_RES result 입력결과집합핸들 반환값 함수수행이성공하면 ALTIBASE_SUCCESS, 그렇지않으면 ALTIBASE_ERROR 이반환된다. 설명 이함수는결과집합의저장을위해할당된메모리를시스템에반환한다. 다음의함수를이용해서결과집합의핸들을얻었다면, 결과집합핸들의사용이완료된후반드시 altibase_free_result() 를호출해서할당된메모리를해제해야한다. altibase_store_result() altibase_use_result() altibase_list_fields() altibase_list_tables() 핸들이해제된후에는그핸들을사용해서 ACI 함수를호출하면안된다. 연결핸들을사용해서결과집합의핸들을얻었다면 altibase_close() 함수를호출하거나핸들을재사용하기전에 altibase_free_result() 함수를호출하여결과집합핸들을먼저해제해야한다. 또한명령문 ACI 함수 55

56 핸들을사용하여결과집합핸들을얻었다면 altibase_stmt_close() 함수를호출하기전에 altibase_free_result() 함수를호출한다. 예제 altibase_query() 의예제를참고하라. 56 Altibase C Interface Manual

57 altibase_get_charset() 클라이언트가사용중인문자집합을반환한다. 구문 const char * altibase_get_charset ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 문자집합의이름이반환된다. 설명 이함수는클라이언트세션이사용중인문자집합의이름을문자열로반환한다. 이문자집합은 NLS_USE 환경변수, 연결문자열의속성또는 altibase_set_charset() 함수로설정이가능하며, 어떤문자집합도설정되어있지않은경우에는기본문자집합의이름이반환될것이다. 이함수가반환한 char 포인터가가리키는메모리는라이브러리내부에서관리되므로절대로사용자가임의로변경하거나해제해서는안된다. 예제 rc = altibase_set_charset(altibase, "KO16KSC5601"); /*... check return value... */ printf("nls_use = %s\n", altibase_get_charset(altibase)); ACI 함수 57

58 altibase_get_charset_info() 이함수는현재지원되지않는다. 58 Altibase C Interface Manual

59 altibase_host_info() 이함수는현재지원되지않는다. ACI 함수 59

60 altibase_init() 연결핸들을생성하는함수이다. 구문 ALTIBASE altibase_init ( void ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 함수수행이성공하면연결핸들이반환되고, 그렇지않으면 NULL 포인터가반환된다. 설명 이함수는 altibase_connect() 에사용될연결핸들을생성하고초기화하여반환한다. 이연결핸들은 altibase_close() 호출시에해제된다. 예제 altibase = altibase_init(); if (altibase == NULL) { return 1; } /*... omit... */ rc = altibase_close(altibase); /*... check return value... */ 60 Altibase C Interface Manual

61 altibase_list_fields() 조건에일치하는칼럼의정보를구하는함수이다. 구문 ALTIBASE_RES altibase_list_fields ( ALTIBASE altibase, const char * conditions[] ); 인자 자료유형 인자 입 / 출력 설명 ALTIBASE altibase 입력 연결핸들 const char ** conditions 입력 제한조건. 3 개의문자열로구성된배열 반환값 함수수행이성공하면결과집합핸들이반환되고, 그렇지않으면 NULL 포인터가반환된다. 설명 이함수는명시한조건에일치하는칼럼에대한정보를결과집합 핸들로반환한다. 제한조건은문자열 3 개로구성된배열로지정해야한다. 배열 요소가 3 개보다많으면앞의 3 개를제외한나머지는무시된다. 이배열의각요소가의미하는바는다음과같다. 인덱스 조건 설명 0 사용자이름 사용자이름을사용해서결과집합을제한하기위한패턴값이다. 이 값을 NULL 또는 ALTIBASE_ALL_USERS로 지정하면 모든 사용자를의미한다. 1 테이블이름 테이블이름을사용해서결과집합을제한하기위한패턴값이다. 이값을 NULL 또는 ALTIBASE_ALL_TABLES로지정하면모든테이블을의미한다. ACI 함수 61

62 2 칼럼이름 칼럼이름을사용해서결과집합을제한하기위한패턴값이다. 이값을 NULL, ALTIBASE_ALL_COLUMNS, 또는빈문자열로 지정하면모든칼럼을의미한다. 제한조건으로지정한값은패턴을의미한다. 패턴의형식은 SQL 문의 LIKE 조건에지정하는방식과동일하다. 이에대한자세한 설명은 SQL Reference 를참고한다. 이함수의두번째인자를 NULL 로입력하면안된다. 배열요소 중의하나, 즉제한조건중적어도하나는유효한값이어야한다. 다른질의문을수행하는중에이함수를호출하거나, 이함수를 실행해서반환된결과집합을사용하는중에다른질의문을 수행해서는안된다. 이함수가반환하는결과집합의열은다음과같다. 열번호 열이름 자료유형 설명 1 TABLE_CAT VARCHAR 항상 NULL이반환된다. 2 TABLE_SCHEM VARCHAR TABLE_NAME 테이블이 속한 스키마의이름 3 TABLE_NAME VARCHAR 테이블의이름 (NOT NULL) 4 COLUMN_NAME VARCHAR (NOT NULL) 칼럼의이름. 5 DATA_TYPE VARCHAR (NOT NULL) 칼럼의 SQL 데이터타입 6 TYPE_NAME VARCHAR DATA_TYPE에 대응하는 데이터 (NOT NULL) 타입의이름을문자열로반환 7 COLUMN_SIZE INTEGER 문자데이터타입의경우, 칼럼의최대문자열길이가반환된다. Date 데이터타입의경우, 이칼럼은 날짜 값을 문자열로 변환한 값을 표시하는데 필요한 문자의 개수를 반환한다. 숫자데이터타입의경우, 이값은숫자의자리수이다. 8 BUFFER_LENGTH INTEGER 칼럼의데이터를저장하는데필요한버퍼의최대크기를바이트단위로반환 9 DECIMAL_DIGITS SMALLINT 칼럼의소수점이하자리수 (scale). scale이적용될수없는데이터타입의경우, NULL이반환된다. 10 NUM_PREC_RADIX SMALLINT 칼럼이숫자형데이터타입일경우이 62 Altibase C Interface Manual

63 값은 10 이 반환되며, COLUMN_SIZE와 DECIMAL_DIGITS는이칼럼에허용된 십진자릿수가반환된다. 예를들어 DECIMAL(12,5) 인 칼럼의 경우 NUM_PREC_RADIX는 10, COLUMN_SIZE는 12 그리고 DECIMAL_DIGITS는 5 가 반환될 것이다. 11 NULLABLE SMALLINT (NOT NULL) 칼럼이 NULL을허용하면 1, 허용하지않으면 0 이반환된다. 12 REMARKS VARCHAR 칼럼에대한설명 13 COLUMN_DEF VARCHAR 칼럼의디폴트값 14 SQL_DATA_TYPE SMALLINT (NOT NULL) 칼럼의 SQL 데이터타입. DATA_TYPE과동일한값이다. 15 SQL_DATETIME_SUB SMALLINT DATE 데이터타입을위한 subtype 코드. DATE 타입이 아닌 칼럼의 경우 NULL이반환된다. 16 CHAR_OCTET_LENGTH INTEGER 문자또는바이너리타입의칼럼일 경우 칼럼의 최대 길이가 바이트 단위로반환된다. 그 외의 타입일 경우 NULL이 반환된다. 17 ORDINAL_POSITION INTEGER (NOT NULL) 테이블에서칼럼의순서위치. 1 부터시작된다. 18 IS_NULLABLE VARCHAR NULL을 허용하면 "YES", 허용하지 않으면 "NO" 가반환된다. 19 STORE_TYPE CHAR(1) 칼럼의데이터가저장되는방식. 가변 (Variable) 방식일 경우 'V', 고정 (Fixed) 방식일 경우 'F' 가 반환된다. 결과집합은 TABLE_CAT, TABLE_SCHEM, TABLE_NAME, 및 ORDINAL_POSITION 의값으로정렬되어반환된다. altibase_list_fields() 는 altibase_use_result(), altibase_list_tables() 함수처럼결과집합을반환하는다른함수들과섞어서사용할수 없다. 즉, 결과집합을반환하는함수들의경우, 한함수에의해 반환된결과집합을먼저해제한후에다른함수를사용해서다른 결과집합을가져올수있다. 이함수를통해얻은결과집합은사용이끝난후에 ACI 함수 63

64 64 Altibase C Interface Manual altibase_free_result() 를이용해서해제해야한다.

65 altibase_list_tables() 조건에일치하는테이블의정보를구하는함수이다. 구문 ALTIBASE_RES altibase_list_tables ( ALTIBASE altibase, const char * conditions[] ); 인자 자료유형 인자 입 / 출력 설명 ALTIBASE altibase 입력 연결핸들 const char ** conditions 입력 제한조건. 3 개의문자열로구성된배열 반환값 함수수행이성공하면결과집합핸들이반환되고, 그렇지않으면 NULL 포인터가반환된다. 설명 이함수는명시한조건에일치하는테이블에대한정보를결과집합 핸들로반환한다. 제한조건은문자열 3 개로구성된배열로지정해야한다. 배열 요소가 3 개보다많으면앞의 3 개를제외한나머지는무시된다. 이배열의각요소가의미하는바는다음과같다. 인덱스 조건 설명 0 사용자이름 사용자이름을이용해서결과집합을제한하기위한패턴값이다. 이값을 NULL 또는 ALTIBASE_ALL_USERS로지정하면모든사용자를의미한다. 1 테이블이름 테이블이름을이용해서결과집합을제한하기위한패턴값이다. 이값을 NULL 또는 ALTIBASE_ALL_TABLES로지정하면모든테이블을의미한다. ACI 함수 65

66 2 테이블유형 테이블유형을이용해서결과집합을제한하기위한패턴값이다. 이값을 NULL 또는 ALTIBASE_ALL_TABLE_TYPES로지정하면모든테이블유형을의미한다. 제한조건으로지정한값은패턴을의미한다. 패턴의형식은 SQL 문의 LIKE 조건에지정하는방식과동일하다. 이에대한자세한 설명은 SQL Reference 를참고한다. 이함수의두번째인자를 NULL 로입력하면안된다. 배열요소 중의하나, 즉제한조건중적어도하나는유효한값이어야한다. 다른질의문을수행하는중에이함수를호출하거나, 이함수를 실행해서반환된결과집합을사용하는중에다른질의문을 수행해서는안된다. 이함수가반환하는결과집합의열은다음과같다. 열번호 열이름 자료유형 설명 1 TABLE_CAT VARCHAR 항상 NULL이반환된다. 2 TABLE_SCHEM VARCHAR TABLE_NAME 테이블이 속한 스키마의이름 3 TABLE_NAME VARCHAR 테이블의이름 (NOT NULL) 4 TABLE_TYPE VARCHAR 테이블유형. 항상 TABLE 이반환된다. 5 REMARKS VARCHAR 사용되지않음 6 MAXROW BIGINT 테이블에입력가능한최대레코드의 개수. 이값이 0 이면최대레코드 개수에제한이없음을나타낸다. 7 TABLESPACE_NAME VARCHAR 테이블이저장된테이블스페이스의이름 8 TABLESPACE_TYPE INTEGER 테이블스페이스타입 9 PCTFREE INTEGER 테이블에설정된 PCTFREE 값. PCTFREE에 대한 설명은 SQL Reference의 CREATE TABLE 구문을참고하라. 10 PCTUSED INTEGER 테이블에설정된 PCTUSED 값. PCTUSED에 대한 설명은 SQL Reference의 CREATE TABLE 구문을 참고하라. 결과집합은 TABLE_TYPE, TABLE_CAT, TABLE_SCHEM, 및 TABLE_NAME 의값으로정렬되어반환된다. altibase_list_tables() 는 altibase_use_result(), altibase_list_fields() 66 Altibase C Interface Manual

67 함수처럼결과집합을반환하는다른함수들과섞어서사용할수없다. 즉, 결과집합을반환하는함수들의경우, 한함수에의해반환된결과집합을먼저해제한후에다른함수를사용해서다른결과집합을가져올수있다. 이함수를통해얻은결과집합은사용이끝난후에 altibase_free_result() 를이용해서해제해야한다. ACI 함수 67

68 altibase_next_result() 다음결과집합에접근하기위해사용되는함수이다. 구문 int altibase_next_result ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 반환값 ALTIBASE_SUCCESS ALTIBASE_NO_DATA ALTIBASE_ERROR 설명다음결과집합이존재함다음결과집합이존재하지않음에러발생 설명 이함수는이전에여러결과집합을가져오는명령을수행한경우, 다음결과집합에접근하기위해사용된다. 이전에가져온결과집합이있다면, altibase_next_result() 를호출하기전에 altibase_free_result() 로그결과집합을먼저해제해야한다. 이함수수행후에는 altibase_query() 를사용해서그다음구문을수행한것과같은상황이된다. 이는 altibase_store_result(), altibase_affected_rows() 등의함수를호출할수있음을의미한다. 68 Altibase C Interface Manual

69 altibase_num_fields() 결과집합의칼럼수를구하는함수이다. 구문 int altibase_num_fields ( ALTIBASE_RES result ); 인자 자료유형인자입 / 출력설명 ALTIBASE_RES result 입력결과집합핸들 반환값 결과집합의칼럼수가반환된다. SQL 문수행시오류가발생했으면 ALTIBASE_INVALID_FIELDCOUNT 가반환될것이다. 설명 이함수는결과집합의칼럼수를반환한다 : 칼럼수는결과집합핸들또는연결핸들을사용해서얻을수있다. 만약이전의 altibase_store_result() 또는 altibase_use_result() 호출에서 NULL 이반환된경우에는연결핸들을이용해야된다. 연결핸들로칼럼개수를구할때는 altibase_field_count() 함수를이용해야한다. ACI 함수 69

70 altibase_num_rows() 결과집합의행의개수를구하는함수이다. 구문 ALTIBASE_LONG altibase_num_rows ( ALTIBASE_RES result ); 인자 자료유형인자입 / 출력설명 ALTIBASE_RES result 입력결과집합핸들 반환값 결과집합의행의개수가반환된다. 설명 이함수는결과집합의행의개수를반환한다. 결과집합을가져온함수가 altibase_store_result() 였는지, 아니면 altibase_use_result() 였는지에따라서이함수의결과는달라진다. 만약 altibase_store_result() 가사용되었다면, 결과집합에포함된전체레코드의개수가정확하게반환된다. 하지만 altibase_use_result() 가사용되었다면, 전체레코드가모두 fetch 되기전까지는정확한레코드수가반환되지않는다. INSERT, UPDATE, 또는 DELETE 문수행으로인해변경된행의개수를구하려면 altibase_affected_rows() 를사용하라. 70 Altibase C Interface Manual

71 altibase_proto_version() 클라이언트와서버사이에사용되는통신프로토콜의버전을구하는 함수이다. 구문 int altibase_proto_version ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 통신프로토콜의버전을나타내는상수가반환된다. 입력된연결핸들이유효하지않거나아직서버와연결되기전이거나또는프로토콜버전을얻을수없는경우에는 ALTIBASE_INVALID_VERSION 이반환된다. 설명 이함수는통신프로토콜의버전을나타내는상수값을반환한다. 반환값의형식은 MMmmttSSpp 이며각각의의미는다음과같다. 형식 설명 비고 MM 주버전 mm 부버전 버전의자리수가 2보다작을경우, 나머지자리는 0으로채워서반환된다. tt 텀 항상 0으로채워서반환된다. SS 패치셋 항상 0으로채워서반환된다. pp 패치 버전의자리수가 2보다작을경우, 나머지자리는 0으로채워서 ACI 함수 71

72 반환된다. 예를들어, 이함수의반환값이 이면통신프로토콜의 버전은 이다. 72 Altibase C Interface Manual

73 altibase_proto_verstr() 클라이언트와서버사이에사용되는통신프로토콜의버전을구하는 함수이다. 구문 const char * altibase_proto_verstr ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 통신프로토콜의버전을나타내는문자열이반환된다. 입력된연결핸들이유효하지않거나아직서버와연결되기전이거나또는프로토콜버전을얻을수없는경우에는 NULL 이반환된다. 설명 이함수는통신프로토콜의버전을나타내는문자열을반환한다. 반환값의형식은 x.x.0.0.x 이며순서대로주버전, 부버전, 패치를의미한다. 이함수가반환한 char 포인터가가리키는메모리는라이브러리내부에서관리되므로절대로사용자가임의로변경하거나해제해서는안된다. ACI 함수 73

74 altibase_query() 질의를수행하는함수이다. 구문 int altibase_query ( ALTIBASE altibase, const char * qstr ); 인자 자료유형 인자 입 / 출력 설명 ALTIBASE altibase 입력 연결핸들 const char * qstr 입력 질의문 (NULL 종료 문자열이어야 한다 ) 반환값 함수수행이성공하면 ALTIBASE_SUCCESS, 그렇지않으면 ALTIBASE_ERROR 가반환된다. 설명 이함수는질의문을실행한다. 질의문은반드시널종료문자열이여야하며, 한개의 SQL 문이어야한다. 세미콜론 (;) 으로연결된다중 SQL 문은지원되지않는다. 다중 SQL 문을실행하려면저장프로시저를활용하라. 예제 #define QSTR "SELECT last_name, first_name FROM friends" ALTIBASE altibase; ALTIBASE_RES result; ALTIBASE_ROW row; ALTIBASE_LONG *lengths; int num_fields; int rc; int i; 74 Altibase C Interface Manual

75 /*... omit... */ rc = altibase_qeury(altibase, QSTR); /*... check return value... */ result = altibase_use_result(altibase); /*... check return value... */ num_fields = altibase_num_fields(result); while ((row = altibase_fetch_row(result))!= NULL) { lengths = altibase_fetch_lengths(result); for (i = 0; i < num_fields; i++) { printf("(%ld) %s", lengths[i], (row[i] == NULL? "null" : row[i])); } printf("\n"); } rc = altibase_free_result(result); /*... check return value... */ /*... omit... */ ACI 함수 75

76 altibase_rollback() 이함수는현재트랜잭션을롤백한다. 구문 int altibase_rollback ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 함수수행에성공하면 ALTIBASE_SUCCESS, 실패하면 ALTIBASE_ERROR 이반환된다. 설명 이함수는현재연결된세션에서수행중인트랜잭션을철회 ( 롤백 ) 한다. 해당세션이 AUTOCOMMIT 모드가아닌경우, 이함수수행후다음 SQL 문실행시에자동으로새로운트랜잭션이시작된다 예제 altibase_set_autocommit() 의예제를참고하라. 76 Altibase C Interface Manual

77 altibase_server_version() ALTIBASE HDB 서버의버전을구하는함수이다. 구문 int altibase_server_version ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 ALTIBASE HDB 서버의버전을나타내는상수가반환된다. 입력된연결핸들이유효하지않거나아직서버와연결되기전이거나또는서버의버전을얻을수없는경우에는 ALTIBASE_INVALID_VERSION 이반환된다. 설명 이함수는 ALTIBASE HDB 서버의버전을나타내는상수값을 반환한다. 반환값의형식은 MMmmttSSpp 이며각각의의미는 다음과같다. 형식 설명 비고 MM 주버전 mm 부버전 버전의자리수가 2보다작을경우, 나머지자리는 0으로채워서반환된다. tt 텀 버전의자리수가 2보다작을경우, 나머지자리는 0으로채워서반환된다. SS 패치셋 버전의자리수가 2보다작을경우, 나머지자리는 0으로채워서 ACI 함수 77

78 반환된다. pp 패치 버전의자리수가 2보다작을경우, 나머지자리는 0으로채워서반환된다. 예를들어, 이함수의반환값이 이면 ALTIBASE HDB 서버의버전은 이다. 78 Altibase C Interface Manual

79 altibase_server_verstr() ALTIBASE HDB 서버의버전을구하는함수이다. 구문 const char * altibase_server_verstr ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 ALTIBASE HDB 서버의버전을나타내는문자열이반환된다. 입력된연결핸들이유효하지않거나아직서버와연결되기전이거나또는프로토콜버전을얻을수없는경우에는 NULL 이반환된다. 설명 이함수는 ALTIBASE HDB 서버의버전을나타내는문자열을반환한다. 반환값의형식은 x.x.x.x.x 이며순서대로주버전, 부버전, 텀, 패치셋, 패치를의미한다. 이함수가반환한 char 포인터가가리키는메모리는라이브러리내부에서관리되므로절대로사용자가임의로변경하거나해제해서는안된다. ACI 함수 79

80 altibase_set_charset() 문자집합 (character set) 을설정하는함수이다. 구문 int altibase_set_charset ( ALTIBASE altibase, const char * charset ); 인자 자료유형 인자 입 / 출력 설명 ALTIBASE altibase 입력 연결핸들 const char * charset 입력 설정할문자집합 반환값 함수수행에성공하면 ALTIBASE_SUCCESS, 실패하면 ALTIBASE_ERROR 이반환된다. 설명 이함수는클라이언트세션에서사용할문자집합을설정한다. 문자집합은서버와연결하기전에설정되어야한다. 문자집합은이함수외에 ALTIBASE_NLS_USE 환경변수또는서버접속시연결문자열의속성을사용해서도설정이가능한다. 문자집합설정은 altibase_set_charset() 함수, 연결속성문자열, ALTIBASE_NLS_USE 환경변수순으로우선순위가주어진다. 예제 ALTIBASE altibase; altibase = altibase_init(); /*... check return value... */ rc = altibase_set_charset(altibase, "KO16KSC5601")); if (ALTIBASE_NOT_SUCCEEDED(rc)) 80 Altibase C Interface Manual

81 { } /*... error handling... */ rc = altibase_connect(altibase, CONNSTR); /*... check return value... */ ACI 함수 81

82 altibase_set_autocommit() 자동커밋 (autocommit) 여부를설정하는함수이다. 구문 int altibase_set_autocommit ( ALTIBASE altibase, int mode ); 인자 자료유형 인자 입 / 출력 설명 ALTIBASE altibase 입력 연결핸들 int mode 입력 Autocommit 여부. ALTIBASE_AUTOCOMMIT_ON 또는 ALTIBASE_AUTOCOMMIT_OFF로 설정가능하다. 반환값 함수수행에성공하면 ALTIBASE_SUCCESS, 실패하면 ALTIBASE_ERROR 이반환된다. 설명 mode 가 ALTIBASE_AUTOCOMMIT_ON 이면자동커밋, ALTIBASE_AUTOCOMMIT_OFF 이면수동커밋으로설정된다. 아무것도설정하지않았을때는기본적으로자동커밋모드이다. 반드시위의두값중하나만을사용해야한다. 그렇지않을경우, 함수수행은실패할것이다. 예제 rc = altibase_set_autocommit(altibase, ALTIBASE_AUTOCOMMIT_OFF); /*... check return value... */ 82 Altibase C Interface Manual

83 /*... omit... */ rc = (error_exist)? altibase_rollback(altibase) : altibase_commit(altibase); if (ALTIBASE_NOT_SUCCEEDED(rc)) { /*... error handling... */ } rc = altibase_set_autocommit(altibase, ALTIBASE_AUTOCOMMIT_ON); /*... check return value... */ ACI 함수 83

84 altibase_set_failover_callback() Failover 를위한콜백함수를등록하는함수이다. 구문 int altibase_set_failover_callback ( ALTIBASE altibase, ALTIBASE_FAILOVER_CALLBACK callback, void * app_context ); 인자 자료유형 인자 입 / 출력 설명 ALTIBASE altibase 입력 연결핸들 ALTIBASE_FAILOVER_C callback 입력 등록할콜백함수. ALLBACK 등록을 해제하려면 여기에 NULL을 입력한다. void * app_context 입력 사용자컨텍스트. 콜백함수내에서사용할데이터가저장된버퍼를가리키는포인터 반환값 함수수행에성공하면 ALTIBASE_SUCCESS, 실패하면 ALTIBASE_ERROR 이반환된다. 설명 이함수는 STF (Service Time Failover) 발생시응용프로그램과 ACI 라이브러리의통신을위한콜백함수를등록한다. STF 발생시사용자가특별히처리해주어야할작업이있을경우, 콜백함수에처리할작업을지시하고 altibase_set_failover_callback 함수를사용해서콜백함수를등록하면된다. 콜백함수의사용을해제하려면, 두번째인자로 NULL 을입력하여 altibase_set_failover_callback 함수를호출하면된다. Failover 콜백함수의등록은 altibase_connect() 가성공한후에 84 Altibase C Interface Manual

85 수행되어야한다. 예제 6 장 Failover 를참고하라. ACI 함수 85

86 altibase_set_option() 연결옵션을설정하는함수이다. 구문 int altibase_set_option ( ALTIBASE altibase, ALTIBASE_OPTION option, const void * arg ); 인자 자료유형 인자 입 / 출력 설명 ALTIBASE altibase 입력 연결핸들 ALTIBASE_OPTION option 입력 설정할옵션 const void * arg 입력 설정할옵션값 반환값 함수수행에성공하면 ALTIBASE_SUCCESS, 실패하면 ALTIBASE_ERROR 이반환된다. 설명 이함수는 ALTIBASE HDB 서버에접속할때사용되는옵션을설정한다. 여러옵션을설정하려면, 각각의옵션과함께이함수를여러번호출해야한다. 이함수는 altibase_init() 를호출한후, altibase_connect() 를호출하기전에사용되어야한다. 연결옵션에대한자세한내용은 2 장의 "enum ALTIBASE_OPTION" 절을참고한다. 예제 ALTIBASE altibase; 86 Altibase C Interface Manual

87 altibase = altibase_init(); /*... check return value... */ rc = altibase_set_option(altibase, ALTIBASE_APP_INFO, "myapp"); /*... check return value... */ rc = altibase_set_option(altibase, ALTIBASE_NLS_USE, "KO16KSC5601"); /*... check return value... */ rc = altibase_connect(altibase, CONNSTR); if (ALTIBASE_NOT_SUCCEEDED(rc)) { fprintf(stderr, "Failed to connect: %s\n", altibase_error(altibase)); } ACI 함수 87

88 altibase_sqlstate() 바로이전에실행된 SQL 명령문에대한 SQLSTATE 를구하는 함수이다. 구문 const char * altibase_sqlstate ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 SQLSTATE 에러코드를나타내는널종료문자열이반환된다. 설명 이함수는가장최근에실행된 SQL 명령문에대한 SQLSTATE 에러코드를나타내는널종료문자열을반환한다. SQLSTATE 는 5 개의문자로이루어진다. 대표적으로 "00000" 은 " 에러없음 " 을나타낸다. SQLSTATE 에대한자세한내용은 Error Message Reference 를참고한다. SQLSTATE 는 altibase_errno() 가반환하는값과는다르다. 에러정보를확인해서처리해야할루틴이있다면 SQLSTATE 값을사용할것을권장한다. 일반적으로 altibase_errno() 의반환값을확인해서에러처리루틴을작성하는것을권장하지않는다. SQLSTATE 와 altibase_errno() 의반환값은 1:1 로맵핑되지않는다. 그러므로 altibase_errno() 의반환값을보고 SQLSTATE 를추측하거나, SQLSTATE 를이용해서 altibase_errno() 의반환값을추측해서는안된다. 어떤함수수행시오류가발생한경우바로오류를확인하지않고 88 Altibase C Interface Manual

89 다른함수를호출하면, 이오류에대한정보가사라진다. 따라서오류발생시바로이함수를사용해서오류정보를확인해야한다. 이함수가반환한 char 포인터가가리키는메모리는라이브러리내부에서관리되므로절대로사용자가임의로변경하거나해제해서는안된다. 예제 altibase_errno() 의예제를참고하라. ACI 함수 89

90 altibase_store_result() 질의수행에대한결과집합전체를가져오는함수이다. 구문 ALTIBASE_RES altibase_store_result ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 질의수행결과에대한결과집합의핸들이반환된다. 에러가발생한 경우 NULL 이반환된다. 설명 이함수는질의수행의전체결과집합에대한핸들을반환한다. 이함수를수행하면질의수행결과를서버로부터모두가져와서클라이언트에저장해둔다. 이함수호출후 altibase_fetch_row() 를호출할때는이미서버로부터모든결과집합을받아온상태이므로서버와통신하지않으며, 받아둔결과집합의데이터가반환된다. 이함수수행시에는모든결과집합을받아두므로 LOB 이나 GEOMETRY 와같은대용량칼럼이포함되어있거나결과행의개수가많다면, 메모리가과다하게사용될수있으므로이함수를쓸때는주의가필요하다. altibase_store_result() 는질의결과가없을때에도 NULL 대신빈결과집합을반환한다. altibase_store_result() 를호출해서 NULL 이반환되었다면, 결과집합을읽는데실패한것이다. altibase_use_result() 대신 altibase_store_result() 를사용하면다음과같은함수를추가로사용할수있다 : 90 Altibase C Interface Manual

91 altibase_num_rows() altibase_data_seek() altibase_store_result() 는 altibase_use_result(), altibase_list_tables() 함수처럼결과집합을반환하는다른함수들과섞어서사용할수없다. 즉, 결과집합을반환하는함수들의경우, 한함수에의해반환된결과집합을먼저해제한후에다른함수를사용해서다른결과집합을가져올수있다. 이함수를통해얻은결과집합은사용이끝난후에 altibase_free_result() 를이용해서해제해야한다. 예제 altibase_query() 과 altibase_data_seek() 의예제를참고하라. ACI 함수 91

92 altibase_use_result() 질의수행에대한결과집합을가져오는함수이다. 구문 ALTIBASE_RES altibase_use_result ( ALTIBASE altibase ); 인자 자료유형인자입 / 출력설명 ALTIBASE altibase 입력연결핸들 반환값 질의수행결과에대한결과집합의핸들이반환된다. 에러가발생한 경우 NULL 이반환된다. 설명 이함수는질의수행의결과집합에대한핸들을반환한다. 이함수는 altibase_store_result() 와달리서버로부터모든결과집합을한꺼번에가져오지않는다. 이함수호출후 altibase_fetch_row() 를호출할때마다서버로부터데이터를가져온다. altibase_use_result() 는질의결과가없을때에도 NULL 대신빈결과집합을반환한다. altibase_use_result() 를호출해서 NULL 이반환되었다면, 결과집합을읽는데실패한것이다. altibase_use_result() 는 altibase_store_result(), altibase_list_tables() 함수처럼결과집합을반환하는다른함수들과섞어서사용할수없다. 즉, 결과집합을반환하는함수들의경우, 한함수에의해반환된결과집합을먼저해제한후에다른함수를사용해서다른결과집합을가져올수있다. 이함수를통해얻은결과집합은사용이끝난후에 92 Altibase C Interface Manual

93 altibase_free_result() 를이용해서해제해야한다. 예제 altibase_query() 의예제를참고하라. ACI 함수 93

94

95 4. Prepared Statement 관련 ACI 함수 이장은 Prepared Statement 와관련된 Altibase C 인터페이스 함수의명세를기술한다. Prepared Statement 관련 ACI 함수 95

96 altibase_stmt_affected_rows() 바로이전에실행한 UPDATE, DELETE 또는 INSERT 문에의해 영향을받은레코드의수를구하는함수이다. 구문 ALTIBASE_LONG altibase_stmt_affected_rows ( ALTIBASE_STMT stmt ); 인자 자료유형인자입 / 출력설명 ALTIBASE_STMT stmt 입력명령문핸들 반환값 반환값 설명 0 보다큰값 SQL문에의해영향을받은레코드의개수 0 SQL문에의해영향을받은레코드가없음 ALTIBASE_INVALID_AFFECTEDROW UPDATE, DELETE, 또는 INSERT 수행중에러발생 설명 이함수는마지막으로수행한 SQL 문의종류에따라다음과같은값을반환한다 : UPDATE 문 : 변경된레코드수 DELETE 문 : 삭제된레코드수 INSERT 문 : 추가된레코드수만약마지막으로수행한 SQL 문이 SELECT 문이었다면이함수는 0 을반환할것이다. SELECT 문에의해선택된레코드의개수를얻고자할때는 altibase_stmt_num_rows() 를사용해야한다. 예제 char *qstr = "UPDATE t1 SET val = val * 1.1 WHERE type = 1"; 96 Altibase C Interface Manual

97 rc = altibase_stmt_prepare(stmt, qstr); /*... check return value... */ rc = altibase_stmt_execute(stmt); /*... check return value... */ printf("%ld updated\n", altibase_stmt_affected_rows(stmt)); Prepared Statement 관련 ACI 함수 97

98 altibase_stmt_bind_param() SQL 문의파라미터마커에입력데이터를바인딩하는함수이다. 구문 int altibase_stmt_bind_param ( ALTIBASE_STMT stmt, ALTIBASE_BIND * bind ); 인자 자료유형 인자 입 / 출력 설명 ALTIBASE_STMT stmt 입력 명령문핸들 ALTIBASE_BIND * bind 입력 바인딩할데이터와그정보가저장된배열 반환값 함수수행에성공하면 ALTIBASE_SUCCESS, 실패하면 ALTIBASE_ERROR 이반환된다. 설명 이함수는 altibase_stmt_prepare() 로전달된 SQL 문의파라미터마커 (?) 에입력데이터를바인딩한다. 이함수의두번째인자 bind 는배열이며, 배열요소의개수는 SQL 문의파라미터마커의개수와동일해야한다. 예를들어, SQL 문에 3 개의파라미터마커가포함되어있으면, 배열의크기가 3 인 ALTIBASE_BIND 구조체의배열을선언하고, 이배열의주소를두번째인자로전달해야한다. 이함수로바인딩된정보는 altibase_stmt_reset(), altibase_stmt_close() 또는 altibase_close() 가호출되기전까지는클라이언트라이브러리내에서유효하다. 그러므로, 하나의 SQL 문으로데이터만바꿔가면서수행하고자할때, altibase_stmt_prepare() 와 altibase_stmt_bind_param() 은한번만 98 Altibase C Interface Manual

99 수행한후바인딩된변수의값만변경하면서 altibase_stmt_execute() 을여러번호출하면된다. 이함수는 altibase_stmt_prepare() 와 altibase_stmt_set_array_bind() 호출후, altibase_stmt_execute() 가호출되기전에사용되어야한다. 예제 #define PARAM_COUNT 2 #define STR_SIZE 50 #define QSTR "INSERT INTO t1 VALUES (?,?)" int int_dat; char str_dat[str_size]; ALTIBASE_LONG length[param_count]; ALTIBASE altibase; ALTIBASE_STMT stmt; ALTIBASE_BIND bind[param_count]; int rc; int i; /*... omit... */ int_dat = 1; strcpy(str_dat, "test1"); length[0] = sizeof(int); length[1] = ALTIBASE_NTS; memset(bind, 0, sizeof(bind)); bind[0].buffer_type bind[0].buffer bind[0].length = ALTIBASE_BIND_INTEGER; = &int_dat; = &length[0]; bind[1].buffer_type = ALTIBASE_BIND_STRING; bind[1].buffer = str_dat; bind[1].buffer_length = STR_SIZE; bind[1].length = &length[1]; stmt = altibase_stmt_init(altibase); /*... check return value... */ rc = altibase_stmt_prepare(stmt, QSTR); /*... check return value... */ rc = altibase_stmt_bind_param(stmt, bind); if (ALTIBASE_NOT_SUCCEEDED(rc)) { for (i = 0; i < PARAM_COUNT; i++) { printf("bind %d : %d\n", i, bind[i].error); } /*... error handling... */ } rc = altibase_stmt_execute(stmt); /*... check return value... */ Prepared Statement 관련 ACI 함수 99

100 altibase_stmt_bind_result() 질의수행결과집합의칼럼데이터를출력할버퍼에연결 ( 즉, 바인드 ) 하는함수이다. 구문 int altibase_stmt_bind_result ( ALTIBASE_STMT stmt, ALTIBASE_BIND * bind ); 인자 자료유형 인자 입 / 출력 설명 ALTIBASE_STMT stmt 입력 명령문핸들 ALTIBASE_BIND * bind 입력 데이터와데이터관련정보를받을버퍼의배열 반환값 함수수행이성공하면 ALTIBASE_SUCCESS, 그렇지않으면 ALTIBASE_ERROR 가반환된다. 설명 이함수는결과집합의칼럼을응용프로그램의변수에바인딩한다. 이함수의두번째인자 bind 는배열로, 배열요소의개수는결과집합의칼럼개수와동일해야한다. 예를들어, 결과집합의칼럼수가 3 개이면, 배열의크기가 3 인 ALTIBASE_BIND 구조체의배열을선언하고이배열의주소를이함수의두번째인자로전달해야한다. 이함수로바인딩된정보는 altibase_stmt_reset(), altibase_stmt_close() 또는 altibase_close() 가호출되기전까지는클라이언트라이브러리내에서유효하다. altibase_stmt_fetch() 를호출할때마다결과집합의한행이바인딩된버퍼에반환된다. 100 Altibase C Interface Manual

101 이함수는 altibase_stmt_prepare() 와 altibase_stmt_set_array_fetch() 호출후, altibase_stmt_store_result() 또는 altibase_stmt_use_result() 가호출되기전에사용되어야한다. 예제 #define FIELD_COUNT 2 #define STR_SIZE 50 #define QSTR "SELECT * FROM t1" ALTIBASE altibase; ALTIBASE_STMT stmt; ALTIBASE_BIND bind[field_count]; int int_dat; char str_dat[str_size]; ALTIBASE_LONG length[field_count]; ALTIBASE_BOOL is_null[field_count]; int rc; int row; /*... omit... */ stmt = altibase_stmt_init(altibase); /*... check return value... */ rc = altibase_stmt_prepare(stmt, QSTR); /*... check return value... */ rc = altibase_stmt_execute(stmt); /*... check return value... */ memset(bind, 0, sizeof(bind)); bind[0].buffer_type bind[0].buffer bind[0].length bind[0].is_null = ALTIBASE_BIND_INTEGER; = &int_dat; = &length[0]; = &is_null[0]; bind[1].buffer_type = ALTIBASE_BIND_STRING; bind[1].buffer = str_dat; bind[1].buffer_length = STR_SIZE; bind[1].length = &length[1]; bind[1].is_null = &is_null[1]; rc = altibase_stmt_bind_result(stmt, bind); if (ALTIBASE_NOT_SUCCEEDED(rc)) { for (i = 0; i < FIELD_COUNT; i++) { printf("bind %d : %d\n", i, bind[i].error); } /*... error handling... */ } /* altibase_stmt_store_result() is optional */ rc = altibase_stmt_store_result(stmt); /*... check return value... */ for (row = 0; (rc = altibase_stmt_fetch(stmt))!= ALTIBASE_NO_DATA; row++) { Prepared Statement 관련 ACI 함수 101

102 if (ALTIBASE_NOT_SUCCEEDED(rc)) { /*... error handling... */ break; } } printf("row %d : ", row); if (is_null[0] == ALTIBASE_TRUE) { printf("{null}"); } else { printf("%d", int_dat); } printf(", "); if (is_null[1] == ALTIBASE_TRUE) { printf("{null}"); } else { printf("(%d) %s", length[1], str_dat); } printf("\n"); rc = altibase_stmt_free_result(stmt); /*... check return value... */ 102 Altibase C Interface Manual