ALTIBASE Application Development ODBC User s Manual Release 5.3.3
----------------------------------------------------------- ALTIBASE Application Development ODBC User s Manual Release 5.3.3 Copyright c 2001~2009 ALTIBASE Corp. All Rights Reserved. 본문서의저작권은 알티베이스에있습니다. 이문서에대하여당사의동의없이무단으로복제또는전용할수없습니다. 알티베이스 152-790 서울시구로구구로동 182-13 대륭포스트타워 Ⅱ 10 층전화 : 02-2082-1114 팩스 : 02-2082-1099 e-mail: support@altibase.com homepage: http://www.altibase.com -----------------------------------------------------------
목차 서문... i 이매뉴얼에대하여... ii 1. ODBC 소개... 1 ODBC의개요... 2 ODBC 사용방법... 4 ODBC 연동... 8 기본프로그래밍순서... 10 ODBC 함수종류... 15 2. ODBC 함수... 19 SQLAllocConnect... 20 SQLAllocEnv... 22 SQLAllocHandle... 24 SQLAllocStmt... 28 SQLBindCol... 30 SQLBindParameter... 35 SQLCloseCursor... 46 SQLColAttribute... 48 SQLColumns... 52 SQLConnect... 56 SQLDescribeCol... 58 SQLDescribeParam... 61 SQLDisconnect... 65 SQLDriverConnect... 67 SQLEndTran... 72 SQLError... 74 SQLExecDirect... 76 SQLExecute... 79 SQLFetch... 82 목차 I
SQLFetchScroll... 86 SQLForeignKeys... 89 SQLFreeConnect... 94 SQLFreeEnv... 96 SQLFreeHandle... 97 SQLFreeStmt... 100 SQLGetConnectAttr... 102 SQLGetData... 105 SQLGetDescField... 109 SQLGetDescRec... 111 SQLGetDiagField... 113 SQLGetDiagRec... 116 SQLGetEnvAttr... 118 SQLGetFunctions... 120 SQLGetInfo... 122 SQLGetPlan... 124 SQLGetStmtAttr... 125 SQLGetTypeInfo... 127 SQLMoreResult... 130 SQLNativeSql... 131 SQLNumParams... 133 SQLNumResultCols... 136 SQLParamData... 138 SQLPrepare... 140 SQLPrimaryKeys... 143 SQLProcedureColumns... 146 SQLProcedures... 151 SQLPutData... 154 SQLRowCount... 156 SQLSetConnectAttr... 158 SQLSetDescField... 161 SQLSetEnvAttr... 163 SQLSetStmtAttr... 165 SQLSpecialColumns... 172 SQLStatistics... 176 II ALTIBASE5 ODBC User s Manual
SQLTablePrivileges... 180 SQLTables... 184 SQLTransact... 188 3. LOB 인터페이스... 191 LOB data types... 192 LOB Function Overview... 194 SQLBindFileToCol... 195 SQLBindFileToParam... 201 SQLGetLobLength... 207 SQLGetLob... 210 SQLPutLob... 214 SQLFreeLob... 221 A. 부록 : Sample Code... 223 프로그래밍시각단계에서주의할점... 224 ODBC 프로그램기본예제... 226 메타정보검색프로그램예제... 234 프로시저테스트프로그램예제... 242 B. 부록 : 데이터형... 247 SQL 데이터형... 248 C 데이터형... 251 SQL 데이터형을 C 데이터형으로변환하기... 253 C 데이터형을 SQL 데이터형으로변환하기... 254 C. 부록 : ODBC 오류코드... 255 ODBC 오류... 256 명령문상태전이... 260 상태전이테이블... 266 D. 부록 : ODBC 적합성... 267 인터페이스적합성레벨... 268 E. 부록 : 업그레이드... 271 데이터타입... 272 기타변경사항... 285 찾아보기... 293 목차 III
서문 서문 i
이매뉴얼에대하여 이매뉴얼은 ODBC 사용법에대해설명한다. 대상사용자 이매뉴얼은다음과같은알티베이스사용자를대상으로작성되었다. 데이터베이스관리자 성능관리자 데이터베이스사용자 응용프로그램개발자 기술지원부 다음과같은배경지식을가지고이매뉴얼을읽는것이좋다. 컴퓨터, 운영체제및운영체제유틸리티운용에필요한기본지식 관계형데이터베이스사용경험또는데이터베이스개념에대한이해 컴퓨터프로그래밍경험 데이터베이스서버관리, 운영체제관리또는네트워크관리경험 소프트웨어환경 이매뉴얼은데이터베이스서버로알티베이스버전 5.3.3 을사용한다는가정하에작성되었다. 이매뉴얼의구성 이매뉴얼은다음과같이구성되어있다. 제 1 장 ODBC 소개이장은 ODBC 의배경, 사용법, 프로그래밍순서등에대해간략히설명한다. 그리고 ODBC 함수를요약해서설명한다. 제 2 장 ODBC 함수이장은 ODBC 함수들에대해구문, 인자, 결과값, 예제등으로나눠서자세히설명한다. 제 3 장 LOB 인터페이스이장은 LOB 데이터를사용하는데필요한함수및데이터타입을설명한다. A. 부록 : Sample Code ii ALTIBASE5 ODBC User s Manual
본매뉴얼에서전반적으로사용된예에대한전체코드리스트를나타낸다. B. 부록 : 데이터형알티베이스데이터베이스의데이터타입과 SQL 데이터타입, C 데이터타입의종류와각타입간의변경가능유무에대해서설명한다. C. 부록 : ODBC 오류코드 ODBC 사용중발생하는오류를 SQLSTATE 별로분류하여설명한다. D. 부록 : ODBC 적합성현재알티베이스 ODBC 에서지원하는함수들과앞으로지원예정인함수들, 그리고지원되지않는함수들에대하여 ODBC 함수적합성에입각하여설명한다. E. 부록 : 업그레이드알티베이스를업그레이드하면서이전버전에서사용하던 ODBC 응용프로그램들을사용할수있도록추가되었거나재정의된데이터타입과기타변경사항들에대해설명한다. 문서화규칙 이절에서는이매뉴얼에서사용하는규칙에대해설명한다. 이규칙을이해하면이매뉴얼과설명서세트의다른매뉴얼에서정보를쉽게찾을수있다. 여기서설명하는규칙은다음과같다. 구문다이어그램 샘플코드규칙 구문다이어그램 이매뉴얼에서는다음구성요소로구축된다이어그램을사용하여, 명령문의구문을설명한다. 구성요소 예약어 의미 명령문이시작한다. 완전한명령문이아닌구문요소는화살표로시작한다. 명령문이다음라인에계속된다. 완전한명령문이아닌구문요소는이기호로종료한다. 명령문이이전라인으로부터계속된다. 완전한명령문이아닌구문요소는이기호로시작한다. ; 명령문이종료한다. 서문 iii
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 ----------------------- SWNO HJNO HSCHOI... iv ALTIBASE5 ODBC User s Manual
그밖에기호 기울임꼴 소문자 대문자 위에서보여진기호이외에기호들 구문요소에서사용자가지정해야하는변수, 특수한값을제공해야만하는위치지정자사용자가제공하는프로그램의요소들, 예를들어테이블이름, 칼럼이름, 파일이름등 시스템에서제공하는요소들또는구문에나타나는키워드 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_; 관련자료 자세한정보를위하여다음문서목록을참조하기바란다. ALTIBASE Installation User s Manual ALTIBASE Administrator s Manual ALTIBASE Replication User s Manual ALTIBASE Precompiler User s Manual ALTIBASE ODBC User s Manual ALTIBASE Application Program Interface User s Manual ALTIBASE isql User s Manual ALTIBASE Tools Utilities User s Manual ALTIBASE Error Message Reference 온라인매뉴얼 알티베이스테크니컬센터 (http://atc.altibase.com/) 에서국문및영문매뉴얼 (PDF, HTML) 을받을수있다. 알티베이스는여러분의의견을환영합니다. 이매뉴얼에대한여러분의의견을보내주시기바랍니다. 사용자의의견은다음버전의매뉴얼을작성하는데많은도움이됩니다. 보내실때에는아래내용과함께기술지원센터 (support@altibase.com) 로보내주시기바랍니다. 사용중인매뉴얼의이름과버전 매뉴얼에대한의견 사용자의성함, 주소, 전화번호 서문 v
이외에도알티베이스기술지원설명서의오류와누락된부분및기타기술적인문제들에대해서이주소로보내주시면정성껏처리하겠습니다. 기술적인부분과관련하여즉각적인도움이필요한경우에는기술지원센터로연락하시기바랍니다. 여러분의의견에항상감사드립니다. vi ALTIBASE5 ODBC User s Manual
1. ODBC 소개 ODBC 는호출가능한 SQL 프로그래밍인터페이스이다. 호출가능한 SQL 인터페이스는데이터베이스접근용애플리케이션프로그램인터페이스로써, 함수를호출하여 SQL 문을실행한다. ODBC 소개 1
ODBC 의개요 ODBC 는데이터베이스에접근하기위한표준개방형응용프로그램인터페이스이다. 애플리케이션이데이터베이스서버와연결하여 SQL 작업을처리할수있도록호출수준의인터페이스를제공한다. 데이터베이스에접근하기위해서는 ODBC 소프트웨어외에, 접근하려는데이터베이스에서제공하는별도의모듈이나드라이버가필요하다. ODBC 배경 ODBC 는 SQL Access Group (SAG) 에의해만들어졌으며, 1992 년 9 월에처음나왔다. 처음엔마이크로소프트가윈도우용 ODBC 제품을공급했지만, 현재는유닉스, OS/2 및매킨토시등을위한버전들이생겨났다. ODBC 는표준 SQL 호출수준의인터페이스에근간을두고밀접하게맞추어져있다. ODBC 는프로그램들이데이터베이스의독점적인인터페이스를몰라도데이터베이스에접근하기위한 SQL 요청을사용할수있게한다. ODBC 는 SQL 요청을받아서, 그것을개개의데이터베이스시스템들이이해할수있는요청으로변환한다. ODBC 와 C/C++ Precompiler 의차이점 C/C++ Precompiler 인터페이스를사용하는애플리케이션은 SQL 문을코드로변환하기위한전처리기 (precompiler) 가필요하다. 그러나 ODBC 애플리케이션은전처리가필요없는대신 SQL 문을실행하는표준함수를사용한다. ODBC 의장점은표준함수를제공하는다른데이터베이스제품군에대해서도사용이가능하다는것이다. 즉, ODBC 를사용하면특정데이터베이스제품에독립적인애플리케이션개발이가능하다. ODBC 함수분류 ODBC 의 API 는애플리케이션작성에필요한환경정의, 연결관리, SQL 문처리, 트랜잭션처리등에관련된기능을제공하는함수들로구성된다. 각함수들은제공하는기능에따라다음과같은그룹으로구분할수있다. 환경 / 연결관리 2 ALTIBASE5 ODBC User s Manual
SQL 처리 속성처리 메타정보처리 환경 / 연결관리 데이터베이스서버연결에필요한환경설정과연결에관련된기능등을제공하는 API 로구성된다. 또한모든작업이종료된후할당된메모리등을해제한다. SQL 처리 SQL 처리를위한명령문할당과준비, 실행요청과결과값처리기능등을제공하는 API 로구성된다. 속성처리 SQL 처리를위한환경설정, 연결설정, 명령문속성설정기능등을제공하는 API 로구성된다. 메타정보처리 테이블정의, 열정의등메타정보검색을위한기능등을제공하는 API 로구성된다. ODBC 소개 3
ODBC 사용방법 본절에서는 ODBC 를이용한애플리케이션작성에필요한사전지식을살펴본다. 기본사용법 ODBC 애플리케이션프로그램은아래 [ 그림 1-1] 과같이전형적으로크게세단계로구성된다. 초기설정 트랜잭션처리 종료 위의세가지외에도진단메세지처리와같은작업등이있는데, 이러한작업은애플리케이션전반에걸쳐발생한다. SQLAllocEnv() SQLAllocConnect() SQLConnect() SQLAllocStmt() 초기설정 (Handle 할당, 초기화 ) Transaction 처리 SQLFreeStmt() SQLDisconnect() SQLFreeConnect() SQLFreeEnv() 종료 ( 할당된 Handle 해제 ) [ 그림 1-1] ODBC 애플리케이션단계 4 ALTIBASE5 ODBC User s Manual
초기설정 초기화는환경및연결핸들을할당하고초기화한다. 각단계에서다음단계로의전환은적절한핸들을전달함으로써이전단계의실행결과에관한정보를전달하는것으로이루어진다. ODBC 에서제공하는핸들의종류는다음과같다. 환경핸들 환경핸들은애플리케이션상태에대한전체적인환경을참조한다. 환경핸들은연결핸들이할당되기전에할당되어야하며, 하나의애플리케이션내에서여러개의환경핸들을할당할수있다. 연결핸들 연결핸들은 ODBC 가관리하는연결과관련된정보를참조한다. 이정보에는일반적인상태정보, 트랜잭션상태, 진단정보가포함된다. 애플리케이션은각연결에대한연결핸들을할당하여 Altibase 서버로의연결을시도하게된다. 명령문핸들 명령문핸들은 ODBC 가관리하는 SQL 문에대한정보를참조한다. 명령문핸들은연결핸들과연관이있다. 명령문을실행하기위해명령문핸들을할당한다. 하나의연결에최대 1024 개의명령문을할당할수있다. 트랜잭션처리 [ 그림 1-2] 는일반적인함수호출순서를보여준다. ODBC 소개 5
명령문준비 SQLPrepare() SQLBindParameter() 명령문직접실행 SQLExecDirect() 명령문실행 SQLExecute() 결과검색 (SELECT) SQLNumResultCols() SQLDescribeCol() SQLColAttribute() SQLBindCol() SQLFetch() 결과검색 (INSERT, UPDATE, DELETE) SQLRowCount() [ 그림 1-2] 함수호출순서 종료 애플리케이션에서할당되었던핸들을단절하고, 할당되었던메모리를회수한후애플리케이션을종료한다. 진단메세지처리 진단이란애플리케이션내에서생성된경고나오류상태를처리하는것을말한다. 애플리케이션의결과값 결과값 설명 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_NO_DATA_FOUND SQL_ERROR 함수가성공적으로완료 경고및기타정보와함께실행이성공적으로완료 함수가성공적이지만관련자료가없다 함수가실패 6 ALTIBASE5 ODBC User s Manual
SQL_INVALID_HANDLE 입력핸들이유효하지않아함수실패 SQL_SUCCESS, SQL_NO_DATA_FOUND, SQL_INVALID_HANDLE 을제외하고는진단메세지를생성한다. 진단메세지를확인하려면 SQLGetDiagRec() 및 SQLGetDiagField() 를호출하여확인할수있다. 진단메세지 진단메세지는 5 자 ( 바이트 ) 로된영어 / 숫자의스트링이다. 여기에서상위 2 자는클래스, 하위 3 자는하위클래스를나타낸다. 알티베이스가제공하는진단메세지는 X/Open SQL CAE 가정의하는표준을준수한다. 주의사항 ALTIBASE 클라이언트라이브러리는신호처리를하지않는다. 따라서외부원인에의해네트워크접속이종료된경우, SIGPIPE 신호를받아진행중인응용프로그램이강제로종료될수있다. 이러한강제종료를막기위해서는 SIGPIPE 신호를사용자애플리케이션에서처리해야한다. 그러나 SIGPIPE 신호처리를하기위해 ALTIBASE 클라이언트라이브러리의함수를호출하면프로그램이멈출수있기때문에사용하면안된다. 하지만신호처리가끝난후에는 ALTIBASE 클라이언트라이브러리의함수를호출하는것이가능하다. ODBC 소개 7
ODBC 연동 본절에서는 Unix, Windows 에서 ODBC 를연동하는방법에대해서기술한다. 시스템별 ODBC 연동 Unix 모든 API 의사용법은동일하다. 그러나서버에연결할때 (SQLDriverConnect) 연결스트링에서차이가있다. DSN=host_ip;PORT_NO=20300;UID=SYS;PWD=MANAGER;CONNT YPE=1;NLS_USE=US7ASCII ALTIBASE ODBC 라이브러리가설치된 Unix-ODBC 또는 iodbc 의공용라이브러리이름은기본적으로 libodbcinst.so (HP 의경우확장자가 sl) 이다. 그러나라이브러리파일명을직접설정할경우에는환경변수 UNIX_ODBC_INST_LIB_NAME 에설정하면된다. 예제 ) iodbc 의경우환경변수설정을변경한다. export UNIX_ODBC_INST_LIB_NAME=libiodbcinst.so Unix-ODBC Unix ODBC Manager 는연동을위해별도의설정이필요하지않다. iodbc ALTIBASE Unix 용 ODBC 드라이버를 iodbc Manager 와연동하기위해서는다음과같은환경변수를설정해야한다. export UNIX_ODBC_INST_LIB_NAME=libiodbcinst.so 필요에따라서다음과같은환경설정을한다. export LD_PRELOAD=/lib/libdemangle.so 추가적으로운영체제가 AIX 일경우 iodbc Manager 와연동이실패하면, 다음사항을확인하여추가작업을해야한다. iodbc 라이브러리가설치된경로로이동하여 iodbcinst.a 아카이브파일에서 iodbcinst.so. 파일을추출한다. $> ar -x libiodbcinst.a 파일확장자를 so.2 에서 so 로변경한다. $> mv libiodbcinst.so.2 libiodbcinst.so iodbc 공유라이브러리탐색경로를 LIBPATH 환경변수에설 8 ALTIBASE5 ODBC User s Manual
정한다. 예 ) 공유라이브러리경로가 /usr/local/lib 인경우 : export LIBPATH=/usr/local/lib:$LIBPATH Windows ODBC 설치후 " 설정 -> 관리도구 -> 데이터원본 " 에서등록한데이터원본이름을 DSN=datasource_name 으로설정한다. ODBC 소개 9
기본프로그래밍순서 STEP 1 : CONNECT SQLAllocHandle(ENV) SQLSetEnvAttr SQLAllocHandle(DBC) SQLDriverConnect SQLSetConnectAttr STEP 2 : INITIALIZE SQLAllocHandle(STMT) SQLSetStmtAttr STEP 3 : EXECUTE Catalog function or SQLBindParameter SQLExecDirect Statement Type? (1) Select or Catalog STEP 4a: FETCH RESULTS SQLNumResultCols SQLDescribeCol SQLBindCol SQLFetch SQLGetData (2)Update/Delete/Insert STEP 4b: FETCH ROW COUNT SQLRowCount (3) Other STEP 5 : TRANSACT SQLEndTran STEP 6 : DISCONNECT SQLFreeHandle(STMT) SQLDisconnect SQLFreeHandle(DBC) SQLFreeHandle(ENV) 10 ALTIBASE5 ODBC User s Manual
단계 1 Connect to the Database 어떤애플리케이션에건첫번째단계는데이터베이스에연결하는것이다. 이단계에서필요한함수는다음그림과같다. STEP 1: CONNECT SQLAllocHandle() SQLSetEnvAttr() SQLAllocHandle() SQLDriverConnect() SQLSetConnectAttr() 데이터베이스에연결하는첫번째작업은 SQLAllocHandle() 을이용하여환경핸들을할당하는것이다. 애플리케이션은 SQLSetEnvAttr() 을호출하여현재환경에대한환경속성을설정한다. 다음으로애플리케이션은 SQLAllocHandle() 로연결핸들을할당하고 SQLDriverConnect() 을호출하여데이터소스에연결한다. 그런다음애플리케이션은 SQLSetConnectAttr() 을이용하여연결속성값을설정한다. 단계 2 Initialize the Application 두번째단계는다음그림에설명된것처럼애플리케이션을초기화하는것이다. 정확한작업은애플리케이션마다다르다. STEP 2: INITIALIZE SQLAllocStmt() SQLSetStmtAttr() 애플리케이션은 SQLAllocStmt() 로명령문핸들을할당하고, 대부분의애플리케이션들은 SQLSetStmtAttr() 로커서종류와같은상태요인을지정한다. 단계 3 Build and Execute an SQL Statement 세번째단계는다음그림에보이는것처럼 SQL ODBC 소개 11
명령문 (statement) 을만들고실행하는것이다. 이단계의처리형태는매우다양하다. 애플리케이션은사용자가입력한 SQL 문에기초하여 SQL 문을만들거나실행한다. STEP 3: EXECUTE Catalog function or SQLBindParameter() SQLExecDirect() SQL 문이만들어지고인자들이바인드되면, 명령문 (statement) 은 SQLExecDirect 를실행한다. 만약명령문 (statement) 이여러번실행되려면, SQLPrepare() 로준비되고, SQLExecute 로실행되어진다. 만약 SQL 문이인자들을포함하면, 애플리케이션은 SQLBindParameter() 를호출하여각인자들을애플리케이션변수에바인드시킨다. 인자를바인딩하기전에 SQLPrepare() 를실행해야하며, 바인딩후에 SQLExecute() 을실행할수있다. 애플리케이션은 SQL 문실행을보류하고카탈로그정보를포함한결과집합을리턴하는함수를호출할수도있다. 애플리케이션의다음취할행동은 SQL 문의실행형태에달려있다. SQL 문의종류다음취할행동 SELECT 또는카탈로그함수단계 4a: 결과를가져온다. UPDATE, DELETE 또는단계 4b: 행의개수를가져온다. INSERT 그밖의 SQL 문 단계 3: SQL 문을만들고실행한다. 또는단계 5: 트랜잭션을반영 (commit) 한다. 단계 4a Fetch the Results STEP 4a: FETCH RESULTS SQLNumResultCols() SQLDescribeCol() SQLBindCol() SQLFetch() SQLCloseCursor() 12 ALTIBASE5 ODBC User s Manual
다음단계는다음그림처럼결과를 fetch 하는것이다. 만약단계 3 에서실행된명령문 (statement) 이 SELECT 문이나카탈로그함수라면, 애플리케이션은먼저결과집합의칼럼수를알아보기위해 SQLNumResultCols() 를호출한다. 애플리케이션은이미결과집합열의개수를알고있다면이단계는필요없다. 그다음, 애플리케이션은 SQLDescribeCol() 로각결과집합열의이름, 데이터형, 정밀도등을가져온다. 마찬가지로애플리케이션이이런정보들을미리알고있다면이단계도필요없다. 그후애플리케이션은애플리케이션변수와결과집합의열을바인드하는 SQLBindCol() 에이런정보를보낸다. 이제애플리케이션은 SQLFetch() 를호출하여첫번째행데이터를가져오고 SQLBindCol() 로바인드된변수에데이터를저장한다. 행에긴데이터가있으면 SQLGetData() 로데이터를가져올수도있다. 애플리케이션은추가적으로데이터를가져오기위해 SQLFetch() 와 ( 필요하다면 ) SQLGetData() 의호출을계속한다. 위의과정을거쳐모든 data 를 fetch 해온후에는다른명령문 (statement) 을 SQLPrepare() 와 SQLExecute() 를이용하여실행하기전에반드시 SQLCloseCursor() 를호출하여데이터를 fetch 하기위해열려있던커서를닫아주어야한다. 애플리케이션은같은트랜잭션내의다른명령문 (statement) 을실행하기위해단계 3 으로되돌아가거나트랜잭션을반영하거나롤백하기위해단계 5 로넘어간다. 단계 4b Fetch the Row Count STEP 4b: FETCH ROW COUNT SQLRowCount() 만일단계 3 에서수행된명령문 (statement) 이 UPDATE, DELETE, INSERT 였다면, 애플리케이션은 SQLRowCount() 로영향을받은행들의개수를가져온다. 만약 array bind 등을이용하여여러개의명령문 (statement) 를실행하였다면각각의명령문 (statement) 의실행으로영향을받은행들을 SQLMoreResults() 함수와 SQLRowCount() 함수의조합을이용하여가져올수있다. 애플리케이션은같은트랜잭션내의다른명령문 (statement) 을실행하기위해단계 3 으로되돌아가거나트랜잭션을반영또는 ODBC 소개 13
롤백하기위해단계 5 로넘어간다. 단계 5 Commit the Transation STEP 5: TRANSACT SQLEndTran() 다섯번째단계는트랜잭션을반영하거나롤백하기위해 SQLEndTran() 을호출한다. 애플리케이션은트랜잭션반영모드가수동반영 (non-auto-commit) 으로설정되어있을때만이단계를수행한다. 만일트랜잭션반영모드가자동반영 (auto-commit) 이면, 트랜잭션은명령문 (statement) 이실행되었을때자동으로반영된다. 새로운트랜잭션에서명령문을수행하기위해, 애플리케이션은단계 3 으로되돌아간다. 데이터베이스와단절하기위해선단계 6 으로진행한다. 단계 6 Disconnect from the Altibase database 마지막단계는다음그림과같이, 데이터베이스로부터단절 (disconnect) 하는것이다. 먼저, 애플리케이션은 SQLFreeHandle() 을호출하여핸들을반환 (free) 시킨다. STEP 6 : DISCONNECT SQLFreeHandle() SQLDisconnect() SQLFreeConnect() SQLFreeEnv() 다음애플리케이션은 SQLDisconnect() 를이용해데이터베이스로부터단절하고, SQLFreeConnect() 를이용해연결핸들을반환시킨다. 마지막으로애플리케이션은 SQLFreeEnv() 을가지고환경핸들을반환시키고프로그램을종료한다. 14 ALTIBASE5 ODBC User s Manual
ODBC 함수종류 알티베이스에서지원하는 ODBC 함수는아래의표와같다. 각각의함수에대한보다자세한설명은 ODBC 함수를참조한다. 작업 함수명 목적 연결관리 SQLAllocConnect 자원과연결핸들초기화및할당 SQLAllocEnv 환경핸들초기화및메모리할당 SQL 실행 요청 SQLAllocStmt SQLAllocHandle SQLCloseCursor SQLConnect SQLDisconnect SQLDriverConnect SQLEndTran SQLFreeConnect SQLFreeEnv SQLFreeHandle SQLFreeStmt SQLTransact SQLBindParameter SQLExecDirect SQLExecute SQLNativeSql SQLParamData SQLPrepare 명령문핸들초기화및메모리할당 자원, 환경, 명령문핸들초기화및메모리할당 열려진커서를닫고보류중인결과들을폐기목표데이터베이스와연결설정연결핸들과연관된연결을종료 연결스트링을이용해목표데이터베이스와연결설정 현재트랜잭션을반영하거나철회실행 연결핸들을무효화하고할당된메모리해제 환경핸들을무효화하고할당된메모리해제 연결, 핸들, 명령문에할당된메모리해제 명령문핸들을무효화하고할당된메모리해제 데이터베이스에대한모든변경을반영하거나철회 SQL문장에매개변수 (parameter) 를바인드 SQL문장을직접실행준비된 SQL문장을실행 SQL 구문을 ODBC 드라이버가지원하는문장으로변환 수행중인명령문에데이터를넣을때사용실행할 SQL문을준비 ODBC 소개 15
작업함수명목적 검색 SQLPutData SQLBindCol SQLColAttribute SQLDescribeCol SQLDescribeParam SQLError SQLFetch SQLFetchScroll SQLGetConnectAttr SQLGetData SQLGetInfo SQLGetStmtAttr SQLGetTypeInfo SQLNumParams SQLNumResultCols SQLRowCount 수행중인명령문에데이터를넣을때사용 결과집합의열을받아올버퍼와데이터형지정결과집합의열에대한속성을확인 결과집합에서한개의행에대한정보확인 결과집합에서매개변수마커 (?) 와연관된정보확인 가장최근에호출된함수와연관된진단정보확인 결과집합의바인드된열에대한정보확인 결과집합에서커서를원하는방향으로진행시키고, 바인드된열을가져옴특정연결에설정된속성값검색 결과집합의현재행에서단일열에대한자료검색 애플리케이션에접속한 DBMS 정보를검색설정된명령문핸들관련속성값검색 데이터베이스에서지원되는데이터타입에관한정보반환 SQL 문에서의매개변수개수를반환결과집합의열의숫자를반환 테이블에대해실행한 SQL 문에의해나타난결과집합의행의숫자를반환 Multiple result 가생성된 execution SQLMoreResults 일경우, 다음 result로관심 result를 변경한다. 속성처리 SQLGetEnvAttr 환경핸들의속성값을설정 SQLGetFunctions ODBC 드라이버가지원하는함수목록설정 SQLSetConnectAttr 연결속성값을설정 SQLSetEnvAttr 환경속성값을설정 SQLSetStmtAttr 명령문속성값을설정 메타정보처리 SQLColumns 특정테이블의행에대한정보검색 16 ALTIBASE5 ODBC User s Manual
작업함수명목적 SQLForeignKeys SQLGetDescField SQLGetDescRec SQLGetDiagField SQLGetDiagRec SQLPrimaryKeys SQLProcedureColumns SQLProcedures SQLSetDescField SQLSpecialColumns SQLStatistics SQLTablePrivileges SQLTables 특정테이블의외래키에대한정보검색 descriptor의속성을한개검색 descriptor의속성을여러개검색함수사용후결과진단검색 함수사용후결과진단을여러개검색 특정테이블의기본키에대한정보검색 프로시저에대한입력 / 출력매개변수정보를검색프로시저이름목록검색 descriptor의속성을한개지정특정열들을검색테이블에대한색인정보검색 테이블의목록과각테이블과관련된권한들을검색테이블목록검색 ODBC 소개 17
2. ODBC 함수 이장에서는 ODBC 에서사용할수있는함수에대해설명한다. 각각의 ODBC 함수에는다음과같은정보가포함된다. 함수명 : 사용목적 구 문 : 함수작성시필요한 'C' 프로토타입 인 자 : 각함수인자의자료유형, 입력 / 출력, 부연설명 결과값 : 함수에서리턴될수있는값 설 명 : 함수사용방법및주의사항 진 단 : 함수에서오류시나타날수있는진단메세지 관련함수 : 이함수와관련된함수 예 제 : 해당함수가사용된소스코드의일부 ODBC 함수 19
SQLAllocConnect 입력환경핸들에의해식별된환경내에서연관된자원과연결핸들을할당한다. 연결핸들과입력환경핸들에의해식별된환경에서관련자원을할당한다. SQLAllocConnect() 는 SQLAllocHandle() 로대체될수있다. 구문 SQLRETURN SQLAllocConnect ( SQLHENV env, SQLHDBC * dbc ); 인자 자료유형 인자 사용 설명 SQLHENV env 입력 환경핸들 SQLHDBC * dbc 출력 연결핸들의포인터 결과값 SQL_SUCCESS SQL_INVALID_HANDLE SQL_ERROR 설명 출력연결핸들은일반적인상태정보, 트랜잭션상태, 오류정보를포함한연결과관련되는모든정보를참조하기위해 ODBC 에의해사용된다. 연결핸들을가리키는포인터 (dbc) 가 SQLAllocConnect () 에의해할당된유효한연결핸들을가리키면, 이호출의결과에의해원래의값이바뀐다. 이것은애플리케이션프로그래밍오류로, ODBC 에의해감지되지않는다. * 이함수를호출하기전에 SQLAllocEnv () 를호출해야한다. 진단 20 ALTIBASE5 ODBC User s Manual
SQLSTATE 설명부연설명 HY000 일반오류채널초기화오류 HY001 메모리할당오류 명시된핸들을위한메모리할당에실패함. HY009 유효하지않은인자 (null pointer) 사용 dbc가 null pointer 임. 관련함수 SQLAllocEnv SQLConnect SQLDisconnect SQLFreeConnect 예제 < $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp 참고 > /* Environment 을위한메모리를할당 */ if (SQLAllocEnv (&env)!= SQL_SUCCESS) printf("sqlallocenv error!! n"); return SQL_ERROR; /* Connection 을위한메모리를할당 */ if (SQLAllocConnect (env, &dbc)!= SQL_SUCCESS) printf("sqlallocconnect error!! n"); return SQL_ERROR; ODBC 함수 21
SQLAllocEnv 환경핸들과관련된자원들을할당한다. SQLAllocEnv () 는 SQLAllocHandle() 로대체될수있다. 구문 SQLRETURN SQLAllocEnv ( SQLHENV * env ); 인자 자료유형 인자 사용 설명 SQLHENV * env 출력 환경핸들의포인터 결과값 SQL_SUCCESS SQL_ERROR 설명 한애플리케이션에서여러개의환경을사용할수있다. 모든 ODBC 자원이계속사용중이려면 SQLAllocEnv () 를호출한프로그램이종료되거나스택을벗어나서는안된다. 그렇지않으면, 애플리케이션은명령문핸들과할당한다른자원들을잃을수있다. 애플리케이션은 SQLAllocConnect () 또는다른 ODBC 함수를호출하기전에이함수를먼저호출해야한다. 이후에입력값으로환경핸들을필요로하는모든함수에 env 값이전달된다. 관련함수 SQLAllocConnect SQLAllocStmt SQLFreeEnv 22 ALTIBASE5 ODBC User s Manual
예제 < $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp 참고 > /* Environment 을위한메모리를할당 */ if (SQLAllocEnv (&env)!= SQL_SUCCESS) printf("sqlallocenv error!! n"); return SQL_ERROR; ODBC 함수 23
SQLAllocHandle 환경, 연결, 그리고명령문핸들을위한메모리를할당하고초기화한다. 구문 SQLRETURN SQLAllocHandle ( SQLSMALLINT HandleType, SQLHANDLE InputHandle, SQLHANDLE * OutputHandlePtr ); 인자 자료유형 인자 사용 설명 SQLSMALLINT HandleType 입력 할당될핸들타입으로다음세값중에하나이다. SQL_HANDLE_ENV, SQL_HANDLE_DBC, SQL_HANDLE_STMT SQLHANDLE InputHandle 입력 입력핸들 HandleType이 SQL_HANDLE_ENV이면 InputHandle은 SQL_NULL_HANDLE이고 SQL_HANDLE_DBC이면환경핸들이어야하고 SQL_HANDLE_STMT이면연결핸들이어야한다. SQLHANDLE * OutputHand leptr 출력 할당받은핸들의포인터 결과값 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_INVALID_HANDLE SQL_ERROR 24 ALTIBASE5 ODBC User s Manual
설명 SQLAllocHandle() 은다음단락에서묘사될환경, 연결, 그리고명령문핸들을할당한다. 이함수는 SQLAllocEnv (), SQLAllocConnect () 및 SQLAllocStmt() 함수들을대치한다. 환경핸들을요구하기위하여애플리케이션은 HandleType 이 SQL_HANDLE_ENV 이고, InputHandle 이 SQL_NULL_HANDLE 인 SQLAllocHandle() 을호출한다. 연결핸들을요구하기위하여애플리케이션은 HandleType 이 SQL_HANDLE_DBC 인 SQLAllocHandle() 을호출하고, 그때의 InputHandle 은유효한환경핸들이어야한다. 명령문핸들을요구하기위하여애플리케이션은 HandleType 이 SQL_HANDLE_STMT 인 SQLAllocHandle() 을호출하고, 그때의 InputHandle 은유효한연결핸들이어야한다. 한애플리케이션에의해한번에한개이상의환경, 연결, 그리고명령문핸들들이할당될수있는데, 한프로세스내의다른쓰레드상에서같은환경, 연결, 또는명령문핸들은동시에사용할수없다. 환경핸들할당 환경핸들은연결핸들이유효하다든지활성화돼있다든지하는전역적인정보를제공한다. 환경핸들을요구하기위해애플리케이션은 Handletype 이 SQL_HANDLE_ENV 이고 InputHandle 이 SQL_NULL_HANDLE 인 SQLAllocHandle() 을호출한다. ODBC 는환경정보에필요한메모리를할당하고, *OutputHandle 에관련핸들의값을돌려준다. 애플리케이션은 *OutputHandle 값을환경핸들을필요로하는후속호출들에전달한다. 연결핸들할당 연결핸들은연결핸들상에서명령문핸들이유효한가, 트랜잭션이현재열려있는가와같은정보를제공한다. 연결핸들을요구하기위해, 애플리케이션은 HandleType 이 SQL_HANDLE_DBC 인 SQLAllocHandle() 을호출한다. InputHandle 인자는 SQLAllocHandle() 을호출함으로서반환된환경핸들로설정된다. ODBC 는연결정보에필요한메모리를할당하고, *OutputHandle 에관련핸들의값을돌려준다. 애플리케이션은 *OutputHandle 값을연결핸들을필요로하는후속호출들에전달한다. 명령문핸들할당 명령문핸들은 SQL 문처리에대한오류메세지그리고상태정보등과같은명령문정보를제공한다. ODBC 함수 25
명령문핸들을요구하기위해, 애플리케이션은데이터베이스와연결하고, SQL 문을보내기전에 SQLAllocHandle() 을호출한다. 이러한호출에서 HandleType 은 SQL_HANDLE_STMT 로설정돼야만하고 InputHandle 인자는 SQLAllocHandle() 을호출함으로서반환된연결핸들로설정되야만한다. ODBC 는명령문정보에필요한메모리를할당하고, 명시된연결로명령문핸들과연결하고, *OutputHandle 에관련핸들의값을돌려준다. 애플리케이션은 *OutputHandle 값을명령문핸들을필요로하는후속호출들에전달한다. 진단 SQLSTATE 설명 부연설명 HY000 일반오류 HY001 메모리할당오류 명시된핸들을위한메모리할당에실패함. HY009 유효하지않은인자 (null pointer) 사용 OutputHandlePtr가 null pointer 임. 관련함수 SQLExecDirect SQLExecute SQLFreeHandle SQLPrepare SQLSetConnectAttr SQLSetEnvAttr SQLSetStmtAttr 예제 < $ALTIBASE_HOME/sample/SQLCLI/demo_meta1.cpp 참고 > /* Environment 을위한메모리를할당 */ if (SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HENV, &env)!= SQL_SUCCESS) printf("sqlallocenv error!! n"); return SQL_ERROR; 26 ALTIBASE5 ODBC User s Manual
/* Connection 을위한메모리를할당 */ if (SQLAllocHandle(SQL_HANDLE_DBC, env, &dbc)!= SQL_SUCCESS) printf("sqlallocconnect error!! n"); return SQL_ERROR; ODBC 함수 27
SQLAllocStmt 명령문을위한메모리를할당하고초기화한다. 하나의연결에 1024 개의명령문까지할당이가능하다. SQLAllocStmt() 는 SQLAllocHandle() 로대체될수있다. 구문 SQLRETURN SQLAllocStmt ( SQLHDBC dbc, SQLHSTMT * stmt ); 인자 자료유형 인자 사용 설명 SQLHDBC dbc 입력 연결핸들 SQLHSTMT * stmt 출력 명령문핸들의포인터 결과값 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_INVALID_HANDLE SQL_ERROR SQL_ERROR 가반환되면 stmt 인수가 SQL_NULL_STMT 로설정된다. 애플리케이션은 stmt 인수를 SQL_NULL_STMT 로설정하여 SQLError() 를호출해야한다. 설명 ODBC 는각각의명령문핸들을사용하여모든설명자, 결과값, 상태정보를처리된 SQL 명령문과연관시킨다. 각각의 SQL 문에명령문핸들이있어야하지만다른명령문에서핸들을다시사용할수있다. 이함수에대한호출시에서는 dbc 가사용중인데이터베이스연결을참조해야한다. 28 ALTIBASE5 ODBC User s Manual
명령문핸들을가리키는입력포인터가이전의 SQLAllocStmt() 호출에의해할당된유효한명령문핸들을가리키면원래의값이이호출의결과에따라바뀐다. 이것은애플리케이션프로그래밍오류로 ODBC 에의해감지되지않는다. * 이함수를호출하기전에 SQLDriverConnect() 를호출해야한다. 그리고 SQLPrepare(), SQLExecute(), SQLExecDirect() 또는명령문핸들을입력인수로갖는다른함수이전에이함수를호출해야한다. 진단 SQLSTATE 설명 부연설명 HY000 일반오류 stmt 수 (1024) 초과 HY001 메모리할당오류 stmt를위한메모리할당에실패함. HY009 유효하지않은인자 (null pointer) 사용 stmt가 null pointer 임. HY010 함수연속오류 ( 연결이되지않거나끊어진상태 ) dbc 가연결이되있지않거나끊긴상태 관련함수 SQLConnect SQLFreeStmt 예제 < $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp 참고 > /* Statement 을위한메모리를할당 */ if (SQL_ERROR == SQLAllocStmt(dbc, &stmt)) printf("sqlallocstmt error!! n"); return SQL_ERROR; ODBC 함수 29
SQLBindCol 모든데이터타입에대해애플리케이션변수들을 (application data buffers) 결과집합의열들에바인드한다. 구문 SQLRETURN SQLBindCol ( SQLHSTMT stmt, SQLSMALLINT col, SQLSMALLINT ctype, SQLPOINTER value, SQLINTEGER max, SQLINTEGER * valuelength ); 인자 자료유형인자사용설명 SQLHSTMT stmt 입력 명령문핸들 SQLSMALLINT col 입력 바인드할결과집합에서의 column의순서. 1부터시작 SQLSMALLINT ctype 입 / 출력 ( 유예중 ) *value 버퍼의 C 데이터타입식별자 ( 부록참고 ). SQLFetch() 를이용하여데이터베이스에서데이터를검색할때 ODBC 는데이터를이타입으로변환한다. SQLPOINTER value 출력 데이터를저장할버퍼의포인터. SQLFetch() 는이버퍼에데이터를반환한다. value가 null pointer 면 ODBC는결과집합 column에대한 data buffer를언바인드한다. 애플리케이션은 SQL_UNBIND option을이용해 SQLFreeStmt() 를호출함으로써모든 30 ALTIBASE5 ODBC User s Manual
column들을언바인드한다. 그러나 value 인자가 null pointer 일지라도 valuelength 인자가유효한값이면애플리케이션은여전히 length 버퍼바운드를갖는다. SQLINTEGER max 입력 버퍼의최대크기 (byte 단위 ). *value에 character data를반환할때 *value 인자는 nulltermination character를위한공간을포함해야만한다. 그렇지않으면, ODBC는데이터를자른다. 고정길이 data (integer 또는 data structure 등 ) 를반환할경우는 max를무시하기때문에충분한버퍼크기를할당해야만한다. 그렇지않으면 ODBC는버퍼의끝을지나저장한다. SQLINTEGER * valuelength 입 / 출력 ( 유예중 ) NULL이거나버퍼에저장된데이터의길이를저장할포인터 SQLFetch() 는이버퍼에다음값들을반환할수있다 : 데이터길이, SQL_NULL_DATA 결과값 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_INVALID_HANDLE ODBC 함수 31
SQL_ERROR 설명 이함수에대해포인터 value 와 valuelength 는유예중인출력변수로 (SQLFetch() 가호출될때까지이포인터들이가리키는기억장치위치가갱신되지않음 ), 이포인터들에의해참조된위치는 SQLFetch() 가호출될때까지유효한상태로남아있어야한다. SQLBindCol() 은모든데이터타입에대해애플리케이션변수들을 ( 기억장치버퍼 ) 결과집합의열들에바인드한다. SQLFetch() 가호출되면데이터가 DBMS 에서애플리케이션으로전송된다. 애플리케이션은결과집합의각열에대해한번씩 SQLBindCol() 을호출한다. SQLFetch() 가호출되면, 각바인드된열의데이터는 value 나 valuelength 포인터에의해서할당된위치에저장된다. 애플리케이션은 SQLDescribeCol() 이나또는 SQLColAttribute() 를호출함으로서열의데이터타입이나길이등과같은속성들을질의할수있다. 이러한정보는정확한데이터타입을명시하거나데이터를다른데이터타입으로변환하는데사용할수있다. 열들은 1 부터시작해서왼쪽부터오른쪽으로연속적인번호에의해식별된다. 결과집합의열의개수는 SQLNumResultCols() 나또는 fieldidentifier 인자에 SQL_DESC_COUNT 를설정해서 SQLColAttribute() 를호출함으로서결정될수있다. 애플리케이션은모든열을바인드하지않을수도있고, 어떠한열과도바인드하지않을수있다. 언바인드된열의데이터는 ( 언바인드된열들만 ) SQLFetch() 가호출된후에 SQLGetData() 를사용해서검색될수있다. SQLBindCol() 은 SQLGetData() 보다더효율적이다. * 이호출에의해지정된버퍼에자료를얻기위해, SQLFetch() 전에 SQLBindCol() 을호출해야한다. 진단 SQLSTATE 설명부연설명 07009 유효하지않은결과집합에서의 column 번호 HY000 일반오류 col 인수의값이결과집합에서의최대 column 수를초과함 HY001 메모리할당오류 명시된핸들에대한 메모리할당실패 32 ALTIBASE5 ODBC User s Manual
HY003 Application buffer type 이유효하지않음 ctype 인자의값이유효하지않음 관련함수 SQLDescribeCol SQLFetch SQLFreeStmt SQLGetData SQLNumResultCols 예제 < $ALTIBASE_HOME/sample/SQLCLI/demo_ex2.cpp 참고 > sprintf(query,"select id,name,age FROM DEMO_EX2 WHERE id=?"); if (SQLPrepare(stmt,query, SQL_NTS)!= SQL_SUCCESS) execute_err(dbc, stmt, query); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; if (SQLBindParameter(stmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 8, 0, id_in, sizeof(id_in), NULL)!= SQL_SUCCESS) execute_err(dbc, stmt, query); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; /* Select 의결과값을가져올변수지정 */ if (SQLBindCol(stmt, 1, SQL_C_CHAR, id, sizeof(id), NULL)!= SQL_SUCCESS) printf("sqlbindcol error!!! n"); execute_err(dbc, stmt, query); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; if (SQLBindCol(stmt, 2, SQL_C_CHAR, name, sizeof(name), NULL)!= SQL_SUCCESS) printf("sqlbindcol error!!! n"); execute_err(dbc, stmt, query); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; ODBC 함수 33
if (SQLBindCol(stmt, 3, SQL_C_SLONG, &age, 0, NULL)!= SQL_SUCCESS) printf("sqlbindcol error!!! n"); execute_err(dbc, stmt, query); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; /* 결과값이있는동안결과값을받아화면에출력 */ printf("id tname tage tbirth t sex tetc n"); printf("================================= n"); for ( i=1; i<=3; i++ ) sprintf(id_in, "%d0000000", i); if ( SQLExecute(stmt)!= SQL_SUCCESS ) execute_err(dbc, stmt, "SQLExecute : "); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; if ( (rc = SQLFetch(stmt))!= SQL_NO_DATA && rc == SQL_SUCCESS ) printf("%-10s%-20s%-5d%4d/%02d/%02d %02d:%02d:%02d t%-2d t", id, name, age, birth.year, birth.month, birth.day, birth.hour, birth.minute, birth.second, sex); if (etc_ind == SQL_NULL_DATA) printf("null n"); else printf("%.3f n", etc); else execute_err(dbc, stmt, query); break; 34 ALTIBASE5 ODBC User s Manual
SQLBindParameter SQL 문의매개변수마커를애플리케이션변수에바인드시킨다. SQLExecute() 가호출될때자료가애플리케이션에서데이터베이스관리시스템으로전송된다. 구문 SQLRETURN SQLBindParameter ( SQLHSTMT stmt, SQLSMALLINT par, SQLSMALLINT ptype, SQLSMALLINT ctype, SQLSMALLINT sqltype, SQLINTEGER columnsize, SQLSMALLINT scale, SQLPOINTER value, SQLINTEGER valuemax, SQLINTEGER * valuelength ); 인자 자료유형 인자 사용 설명 SQLHSTMT stmt 입력 명령문핸들 SQLSMALLINT par 입력 매개변수의순서, 1부터시작 SQLSMALLINT ptype 입력 매개변수 type SQL 문내의모든매개변수들은입력변수들이고 (SQL_PARAM_INPUT), 프로시져호출시매개변수들은입력, 출력, 또는입 / 출력변수들이다. (SQL_PARAM_INPUT, SQL_PARAM_OUTPUT, SQL_PARAM_INPUT_OUT PUT) SQLSMALLINT ctype 입력 매개변수의 C 데이터타입 SQL_C_CHAR SQL_C_SBIGINT 등 < 부록참조 > ODBC 함수 35
SQLSMALLINT sqltype 입력 매개변수의 SQL 데이터타입 SQL_CHAR SQL_VARCHAR 등 < 부록참조 > SQLINTEGER columnsize 입력 해당매개변수마커의정밀도를나타내는인자로 SQL 타입에따라서다음과같이사용된다. * SQL_CHAR, SQL_VARCHAR: 매개변수마커가사용할수있는최대길이를나타낸다. (columnsize가 0인경우디폴트 columnsize로해석되며, SQL_CHAR, SQL_VARCHAR인경우 32,000으로 columnsize가할당된다.) * SQL_DECIMAL, SQL_NUMERIC: 매개변수마커의십진유효숫자크기를나타낸다. (columnsize가 0인경우디폴트 columnszie로해석되며, SQL_DECIMAL, SQL_NUMERIC 두가지모두최대유효숫자크기인 38로 columnsize가할당된다.) * SQL_BINARY, SQL_BYTES, SQL_NIBBLE, SQL_VARBIT: 매개변수마커가사용할수있는최대길이를나타낸다. (columnsize가 0인경우디폴트 columnsize로해석되며, 각타입에따른디폴트 columnsize는 36 ALTIBASE5 ODBC User s Manual
다음과같다 SQL_BINARY, SQL_BYTE, SQL_VARBIT 인경우 32000, SQL_NIBBLE 은 254). * 그외의타입에서는 사용자가지정한 columnsize 인자가 무시되고, 다음과같이 고정된값이사용된다. SQL_SMALLINT 5 SQL_INTEGER 10 SQL_BIGINT 19 SQL_REAL 7 SQL_FLOAT 38 SQL_DOUBLE 15 SQL_TYPE_DATE 30 SQL_TYPE_TIME 30 SQL_TYPE_TIMESTAMP 30 SQL_INTERVAL 10 SQL_GEOMETRY 3200 SQLSMALLINT scale 입력 *value 또는매개변수마커에따른십진숫자 SQL 데이터타입이 SQL_NUMERIC일경우소수점아래의자리수 SQLPOINTER value 입력 ( 유예 중 ) SQLINTEGER valuemax 입 / 출 력 SQLINTEGER * valuelength 입력 ( 유예 중 ) SQLExecute() 또는 SQLExecDirect() 가호출되었을때매개변수에대한실제데이터의포인터 문자또는이진 C 데이터에대한 *value 버퍼의최대길이 SQLExecute() 또는 SQLExecDirect() 가호출되었을때입력 / 출력된데이터길이의포인터 ODBC 함수 37
결과값 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_INVALID_HANDLE SQL_ERROR 설명 ODBC Array Binding 하나의문장에매개변수를배열로전달하여네트워크 round-trip 횟수를줄여서속도의향상을얻을수있는방법이다. [ 그림 2-1] 은 Array binding 을간략하게도식화한것이다. 네트워크호출횟수가줄어들어짧은시간에더많은데이터를전송할수있다. DBMS Applicatio DBMS Applicatio Success Insert Success Insert Success Insert Success Success Insert Insert Success Insert Success Insert Success Insert Success Success Insert Insert Success Insert Success Insert < 기존방식 > < Array Binding 방식 > [ 그림 2-1] Array Binding 도식화 Array binding 에는아래와같이두종류가있다. 열양식매개변수바인딩 (Column-wise parameter binding) 열양식바인딩을사용하기위해애플리케이션은함수 SQLSetStmtAttr() 의인자 Attribute 에 SQL_ATTR_PARAM_BIND_TYPE 을설정하고인자 param 에 SQL_PARAM_BIND_BY_COLUMN 을설정한다. 바인드될각열에대해애플리케이션은다음단계를수행한다. 38 ALTIBASE5 ODBC User s Manual
1. 매개변수버퍼배열을할당한다. 2. 지시자버퍼배열을할당한다. 3. 인자들과함께 SQLBindParameter() 를호출한다. ctype 은매개변수버퍼배열내에단일원소의 C 데이터타입이다. sqltype 은매개변수의 SQL 데이터타입이다. value 는매개변수버퍼배열의주소이다. valuemax 는매개변수버퍼배열내에단일원소의크기이다. valuelength 는길이 / 지시자배열의주소이다. 다음그림은각열에대해어떻게열양식바인딩이작동하는가를보여준다. Column A (parameter A) Column B (parameter B) Column C (parameter C) value array length/ indicator array value array length/ indicator array value array length/ indicator array [ 그림 2-2] 열양식바인딩 예제 #define DESC_LEN 51 #define ARRAY_SIZE 10 SQLCHAR * Statement = "INSERT INTO Parts (PartID, Description, Price) " "VALUES (?,?,?)"; SQLUINTEGER PartIDArray[ARRAY_SIZE]; SQLCHAR DescArray[ARRAY_SIZE][DESC_LEN]; SQLREAL PriceArray[ARRAY_SIZE]; SQLINTEGER PartIDIndArray[ARRAY_SIZE], DescLenOrIndArray[ARRAY_SIZE], PriceIndArray[ARRAY_SIZE]; ODBC 함수 39
SQLUSMALLINT i, ParamStatusArray[ARRAY_SIZE]; SQLUINTEGER ParamsProcessed; // Set the SQL_ATTR_PARAM_BIND_TYPE statement attribute to use // column-wise binding. SQLSetStmtAttr(hstmt, SQL_ATTR_PARAM_BIND_TYPE, SQL_PARAMETER_BIND_BY_COLUMN, 0); // Specify the number of elements in each parameter array. SQLSetStmtAttr(hstmt, SQL_ATTR_PARAMSET_SIZE, ARRAY_SIZE, 0); // Specify an array in which to return the status of each set of // parameters. SQLSetStmtAttr(hstmt, SQL_ATTR_PARAM_STATUS_PTR, ParamStatusArray, 0); // Specify an SQLUINTEGER value in which to return the number of sets of // parameters processed. SQLSetStmtAttr(hstmt, SQL_ATTR_PARAMS_PROCESSED_PTR, &ParamsProcessed, 0); // Bind the parameters in column-wise fashion. SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_ULONG, SQL_INTEGER, 5, 0, PartIDArray, 0, PartIDIndArray); SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, DESC_LEN - 1, 0, DescArray, DESC_LEN, DescLenOrIndArray); SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_FLOAT, SQL_REAL, 7, 0, PriceArray, 0, PriceIndArray); 행양식매개변수바인딩 (Row-wise parameter binding) 행양식바인딩을사용할때, 애플리케이션은바인드될각매개변수에대해매개변수와길이 / 지시자버퍼를포함한구조 ( 배열 ) 를정의한다. 행양식바인딩을사용하기위해애플리케이션은다음단계를수행한다. 매개변수들 ( 매개변수와길이 / 지시자버퍼를포함 ) 의단일집합을보유하기위한구조 ( 배열 ) 를정의한다. 행양식바인딩을사용하기위해애플리케이션은함수 SQLSetStmtAttr() 의인자 Attribute 에 SQL_ATTR_PARAM_BIND_TYPE 을설정하고인자 param 에프로그램변수들을 ( 매개변수들의단일집합 ) 보유하고있는구조 ( 배열 ) 의크기를설정하고배열의첫원소에각구성요소 (member) 의주소를바인드한다. 다음인자들과함께 SQLBindParameter() 를호출한다. ctype 은매개변수버퍼구성요소의타입이다. 40 ALTIBASE5 ODBC User s Manual
sqltype 은매개변수의 SQL 데이터타입이다. value 는첫배열원소 (element) 에매개변수버퍼구성요소의주소이다. valuemax 는매개변수버퍼구성요소의크기이다. valuelength 는바운드될길이 / 지시자구성요소의주소이다. 다음그림은행양식바인딩이작동하는방법을보여준다. Column A Column B Column C (parameter A) (parameter B) (parameter C) array[0] array[1] array[2] array[3] [ 그림 2-3] 행양식바인딩 예제 #define DESC_LEN 51 #define ARRAY_SIZE 10 typedef tagpartstruct SQLREAL Price; SQLUINTEGER PartID; SQLCHAR Desc[DESC_LEN]; SQLINTEGER PriceInd; SQLINTEGER PartIDInd; SQLINTEGER DescLenOrInd; PartStruct; PartStruct PartArray[ARRAY_SIZE]; SQLCHAR * Statement = "INSERT INTO Parts (PartID, Description, Price) " "VALUES (?,?,?)"; SQLUSMALLINT i, ParamStatusArray[ARRAY_SIZE]; SQLUINTEGER ParamsProcessed; // Set the SQL_ATTR_PARAM_BIND_TYPE statement attribute to use // column-wise binding. SQLSetStmtAttr(hstmt, SQL_ATTR_PARAM_BIND_TYPE, sizeof(partstruct), 0); // Specify the number of elements in each parameter array. ODBC 함수 41
SQLSetStmtAttr(hstmt, SQL_ATTR_PARAMSET_SIZE, ARRAY_SIZE, 0); // Specify an array in which to return the status of each set of // parameters. SQLSetStmtAttr(hstmt, SQL_ATTR_PARAM_STATUS_PTR, ParamStatusArray, 0); // Specify an SQLUINTEGER value in which to return the number of sets of // parameters processed. SQLSetStmtAttr(hstmt, SQL_ATTR_PARAMS_PROCESSED_PTR, &ParamsProcessed, 0); // Bind the parameters in row-wise fashion. SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_ULONG, SQL_INTEGER, 5, 0, &PartArray[0].PartID, 0, &PartArray[0].PartIDInd); SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, DESC_LEN - 1, 0, PartArray[0].Desc, DESC_LEN, &PartArray[0].DescLenOrInd); SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_FLOAT, SQL_REAL, 7, 0, &PartArray[0].Price, 0, &PartArray[0].PriceInd); 제약사항 SQL_BINARY, SQL_BYTES, SQL_NIBBLE, SQL_VARBIT 타입은 buffer size 나 column size 를반드시기술해야한다. SQL_CHAR, SQL_VARCHAR 타입의경우디폴트 precision 은칼럼이가질수있는최대크기이며 SQL_NUMERIC, SQL_NUMBER 타입의경우에는 precision 값으로 38 을갖는다. 진단 SQLSTATE 설명부연설명 07006 제한된데이터타입속성위반 ctype 데이터타입은 sqltype 데이터타입으로변환될수없다. 07009 유효하지않은번호 명시된 par의값이 1 보다 작음 HY000 일반오류 HY001 메모리할당오류 명시된핸들에대한메모리 할당실패 HY003 Application buffer type 이유효하지않음 ctype 의값이유효한 C 데이터타입이아님 42 ALTIBASE5 ODBC User s Manual
HY009 HY090 HY105 유효하지않은인자사용 (null pointer) 유효하지않은버퍼길이유효하지않은매개변수타입 value가 null pointer, valuelength가 null pointer 그리고 ptype이 SQL_PARAM_OUTPUT이아님. valuemax 값이 0 보다작거나 64K 보다큼 ptype 이유효한값이아님 (in, out, inout) 관련함수 SQLExecDirect SQLExecute SQLFreeStmt 예제 < $ALTIBASE_HOME/sample/SQLCLI/demo_ex2.cpp 참고 > sprintf(query,"insert INTO DEMO_EX2 VALUES(?,?,?,?,?,? )"); /* Statement 를준비하고변수를바인드한다. */ if (SQLPrepare(stmt, query, SQL_NTS)!= SQL_SUCCESS) execute_err(dbc, stmt, query); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; if (SQLBindParameter(stmt, 1, /*? 로표시한호스트변수의순서, 1 부터시작 */ SQL_PARAM_INPUT, /* in, out, inout 표시 */ SQL_C_CHAR, /* 바인딩하는변수의 c type */ SQL_CHAR, /* 데이터베이스의해당칼럼의데이터타입 : char(8)*/ 8, /* 테이블생성시칼럼타입의 precision */ 0, /* 테이블생성시칼럼타입의 scale */ id, /* 바인딩하는버퍼의포인터 */ sizeof(id), /* 바인딩하는버퍼의사이즈 */ &id_ind /* indicator */ )!= SQL_SUCCESS) execute_err(dbc, stmt, query); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; if (SQLBindParameter(stmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR, 20, /* varchar(20) */ ODBC 함수 43
0, name, sizeof(name), &name_ind)!= SQL_SUCCESS) execute_err(dbc, stmt, query); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; if (SQLBindParameter(stmt, 3, SQL_PARAM_INPUT, SQL_C_SLONG, SQL_INTEGER, 0, 0, &age, 0,/* 바인딩하는버퍼가 fixed size 타입일경우사용되지않음 */ NULL)!= SQL_SUCCESS) execute_err(dbc, stmt, query); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; if (SQLBindParameter(stmt, 4, SQL_PARAM_INPUT, SQL_C_TYPE_TIMESTAMP, SQL_DATE, 0, 0, &birth, 0, NULL)!= SQL_SUCCESS) execute_err(dbc, stmt, query); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; if (SQLBindParameter(stmt, 5, SQL_PARAM_INPUT, SQL_C_SSHORT, SQL_SMALLINT, 0, 0, &sex, 0, NULL)!= SQL_SUCCESS) execute_err(dbc, stmt, query); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; if (SQLBindParameter(stmt, 6, SQL_PARAM_INPUT, SQL_C_DOUBLE, SQL_NUMERIC, 10, 3, &etc, 0, &etc_ind)!= SQL_SUCCESS) execute_err(dbc, stmt, query); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; /* 준비된 Statement 를수행 */ sprintf(id, "10000000"); sprintf(name, "name1"); age = 28; birth.year=1980;birth.month=10;birth.day=10; birth.hour=8;birth.minute=50;birth.second=10; sex = 1; etc = 10.2; id_ind = SQL_NTS; /* id => null terminated string */ name_ind = 5; /* name => length=5 */ etc_ind = 0; /* etc 는 fixed size type 이므로 indicator 의값이 SQL_NULL_DATA 가아니면무시된다 */ if (SQLExecute(stmt)!= SQL_SUCCESS) execute_err(dbc, stmt, query); 44 ALTIBASE5 ODBC User s Manual
SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; ODBC 함수 45
SQLCloseCursor 열려진커서를닫고보류중인결과들을폐기한다. 구문 SQLRETURN SQLCloseCurosr ( SQLHSTMT stmt); 인자 자료유형 인자 사용 설명 SQLHSTMT stmt 입력 명령문핸들 결과값 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_INVALID_HANDLE SQL_ERROR 설명 열려진커서를닫고보류중인결과들을폐기한다. SQLFreeStmt() 에서 SQL_CLOSE 옵션을사용한것과동일하다. 단 SQLCloseCorsor() 에서커서가열려지지않았을때오류 24000 을발생시킨다. 진단 SQLSTATE 설명 부연설명 HY000 일반오류 HY001 메모리할당오류 24000 커서상태가잘못됨 명시된핸들을위한메모리할당에실패함명령문핸들에열려진커서가없음 46 ALTIBASE5 ODBC User s Manual
관련함수 SQLFreeHandle ODBC 함수 47
SQLColAttribute 결과집합의열에대한속성을가져오며열의수를판별하는데사용한다. Unicode SQLColAttributeW() 동작은 SQLColAttribute() 와동일하다. 구문 64 비트윈도우환경 그외 platform SQLRETURN SQLColAttribute ( SQLHSTMT stmt, SQLSMALLINT columnnumber, SQLSMALLINT fieldidentifier, SQLCHAR * charattributeptr, SQLSMALLINT bufferlength, SQLSMALLINT * stringlengthptr, SQLLEN * numericattributeptr ); SQLRETURN SQLColAttribute ( SQLHSTMT stmt, SQLSMALLINT columnnumber, SQLSMALLINT fieldidentifier, SQLCHAR * charattributeptr, SQLSMALLINT bufferlength, SQLSMALLINT * stringlengthptr, SQLPOINTER* numericattributeptr ); 인자자료유형 인자 사용 설명 SQLHSTMT stmt 입력 명령문핸들 SQLSMALLINT columnnumber 입력 결과집합에서의 column의순서, 1부터시작 48 ALTIBASE5 ODBC User s Manual
SQLSMALLINT fieldidentifier 입력 알고자하는정보의식별자 SQL_DESC_CASE_SENSITIVE, SQL_DESC_CATALOG_NAME, SQL_DESC_COUNT, SQL_DESC_DISPLAY_SIZE, SQL_DESC_LABEL, SQL_DESC_LENGTH, SQL_DESC_NAME, SQL_DESC_NULLABLE, SQL_DESC_PRECISION, SQL_DESC_SCALE, SQL_DESC_SCHEMA_NAME, SQL_DESC_TABLE_NAME, SQL_DESC_TYPE, SQL_DESC_TYPE_NAME, SQL_DESC_UNSIGNED SQLCHAR * charattributeptr 출력 columnnumber 행의 fieldidentifier 필드가문자열인경우반환된데이터를저장할버퍼의포인터, 필드값이정수이면사용안함 SQLSMALLINT bufferlength 입력 *charattributeptr의문자개수, *charattributeptr가정수이면무시 SQLSMALLINT * stringlengthptr 출력 *charattributeptr에반환되는총문자열의바이트길이 (nulltermination을제외 ) 의포인터 SQLINTEGER * numericattribute Ptr 출력 columnnumber 행의 fieldidentifier 필드안의값이반환될정수버퍼의포인터 결과값 SQL_SUCCESS SQL_INVALID_HANDLE SQL_ERROR 설명 SQLDescribeCol() 과같은특정인수집합을리턴하는대신, ODBC 함수 49
fieldidentifier 설명자유형 SQLColAttribute() 를사용하여특정열에대해수신하려는속성을지정할수있다. 원하는정보가스트링이면 charattributeptr 에반환된다. 원하는정보가숫자이면 numericattributeptr 에반환된다. 열은번호 ( 왼쪽에서오른쪽으로, 1 부터번호가매겨짐 ) 에의해식별되며다른순서로도설명될수있다. 결과집합의존재여부를판별하기위해 SQLColAttribute() 를호출하기전에 SQLNumResultCols() 를호출한다. 애플리케이션이다양한속성 ( 자료유형과길이등 ) 을모를경우 SQLBindCol() 을호출하기전에이함수 ( 또는 SQLDescribeCol()) 를호출해야한다. 다음테이블은 SQLColAttribute() 에의해반환된설명자유형을나열한것이다. 설명자 (fieldidentifier) 유형 설명 SQL_DESC_CASE_SENSITIVE SQLINTEGER 대소문자구별유무 SQL_DESC_CATALOG_NAME SQLCHAR * 열을포함하는테이블의카탈로그 SQL_DESC_COUNT SQLINTEGER 결과집합의열번호가반환 SQL_DESC_DISPLAY_SIZE SQLINTEGER 열의데이터를보여주기위한문자들의최대수 SQL_DESC_LABLE SQLCHAR * 열의레이블이나제목 SQL_DESC_LENGTH SQLINTEGER 열과관련자료의바이트수 SQL_DESC_NAME SQLCHAR * 열의이름 SQL_DESC_NULLABLE SQLINTEGER NULL의유무판단유 SQL_NULLABLE 무 SQL_NO_NULLS SQL_DESC_PRECISION SQLINTEGER 열의정밀도속성 SQL_DESC_SCALE SQLINTEGER 열의소수자리수속성 SQL_DESC_SCHEMA_NAME SQLCHAR * 열을포함하는테이블의스키마 SQL_DESC_TABLE_NAME SQLCHAR * 테이블이름 SQL_DESC_TYPE SQLINTEGER SQL 데이터타입 SQL_DESC_TYPE_NAME SQLCHAR * 데이터베이스타입이름 SQL_DESC_UNSIGNED SQLINTEGER 열의항목검사 진단 SQLSTATE 설명부연설명 50 ALTIBASE5 ODBC User s Manual
07009 유효하지않은열번호 HY000 일반오류 columnnumber 가 0 이거나결과집합의 column 의수보다큼 관련함수 SQLBindCol SQLDescribeCol SQLFetch 예제 < $ALTIBASE_HOME/sample/SQLCLI/demo_meta8.cpp 참고 > sprintf(query,"select * FROM DEMO_META8"); if (SQLExecDirect(stmt,query, SQL_NTS)!= SQL_SUCCESS) execute_err(dbc, stmt, query); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; SQLNumResultCols(stmt, &columncount); for ( i=0; i<columncount; i++ ) SQLColAttribute(stmt, i+1, SQL_DESC_NAME, columnname, sizeof(columnname), &columnnamelength, NULL); SQLColAttribute(stmt, i+1, SQL_DESC_TYPE, NULL, 0, NULL, &datatype); SQLColAttribute(stmt, i+1, SQL_DESC_PRECISION, NULL, 0, NULL, &columnprecision); SQLColAttribute(stmt, i+1, SQL_DESC_SCALE, NULL, 0, NULL, &scale); SQLColAttribute(stmt, i+1, SQL_DESC_NULLABLE, NULL, 0, NULL, &nullable); ODBC 함수 51
SQLColumns 특정테이블의열들의정보들을결과집합형태로받을수있다. Unicode SQLColumnsW() 동작은 SQLColumns() 와동일하다. 구문 SQLRETURN SQLColumns ( SQLHSTMT stmt, SQLCHAR * cname, SQLSMALLINT cnamelength, SQLCHAR * sname, SQLSMALLINT snamelength, SQLCHAR * tname, SQLSMALLINT tnamelength, SQLCHAR * colname, SQLSMALLINT colnamelength ); 인자 자료유형인자사용설명 SQLHSTMT stmt 입력 명령문핸들 SQLCHAR* cname 입력 카탈로그이름 SQLSMALLINT cnamelength 입력 *cname의문자개수 SQLCHAR * sname 입력 검색할스키마이름 SQLSMALLINT snamelength 입력 *sname의문자개수 SQLCHAR * tname 입력 검색할테이블의이름 SQLSMALLINT tnamelength 입력 *tname의문자개수 SQLCHAR * colname 입력 검색할열 SQLSMALLINT colnamelength 입력 *colname의문자개수 결과값 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_INVALID_HANDLE SQL_ERROR 52 ALTIBASE5 ODBC User s Manual
설명 이함수는전형적으로데이터베이스카탈로그에서테이블열에대한정보를검색하기위해명령문실행전에사용된다. SQLColumns() 는 SQLTables() 에의해반환된모든데이터타입의데이터를검색하는데사용할수있다. 대조적으로, 함수 SQLColAttribute() 와 SQLDescribeCol() 은결과집합의열들을묘사하고함수 SQLNumResultCols() 는결과집합의열들의수를반환한다. SQLColumns() 은 TABLE_CAT, TABLE_SCHEM, TABLE_NAME, 그리고 ORDINAL_POSITION 에의해순서화된표준결과집합형태로결과들을반환한다. SQLStatistics() 에의해반환된열들중몇몇은 SQLColumns() 에의해반환되지않는다. 예를들어, SQLColumns() 는 SALARY + BENEFITS 또는 DEPT = 0012 등의표현식이나필터에의해생성된인덱스열들은반환하지않는다. SQLColumns() 에의해반환되는열 다음테이블은결과집합의열들을나열한다. 열이름 열번호 자료유형 설명 TABLE_CAT 1 VARCHAR 항상 NULL 반환 TABLE_SCHEM 2 VARCHAR 스키마이름 ; 데이터베이스에적절하지않은경우 NULL TABLE_NAME 3 VARCHAR (NOT NULL) 테이블이름 COLUMN_NAME 4 VARCHAR (NOT NULL) DATA_TYPE 5 SMALLINT (NOT NULL) TYPE_NAME 6 VARCHAR (NOT NULL) 열이름. ODBC는이름을갖지않은열에대해빈문자열을반환한다. SQL 데이터타입 DATA_TYPE 에대응하는데이터타입의이름을나타내는문자스트링 COLUMN_SIZE 7 INTEGER 열의크기. 열의크기가적합치않으면 NULL 이반환됨 BUFFER_LENGTH 8 INTEGER 자료를저장하는최대바이트 DECIMAL_DIGITS 9 SMALLINT 열의소수자리수, 소수자리수를적용할수없는데이터타입은널이반환 ODBC 함수 53
NUM_PREC_RADIX 10 SMALLINT Numeric 데이터타입인경우 10: COLUMN_SIZE와 DECIMAL_DIGITS의값은이열에허용되는십진자릿수가주어진다. 예를들어 DECIMAL(12,5) 열은 NUM_PREC_RADIX가 10, COLUMN_SIZE가 12 그리고 DECIMAL_DIGITS의값 5를반환할수있다. NULLABLE 11 SMALLINT (NOT NULL) 열이널값을허용하지않는경우 SQL_NO_NULLS 허용할경우 SQL_NULLABLE REMARKS 12 VARCHAR 열에대한설명정보 COLUMN_DEF 13 VARCHAR 열의디폴트값 SQL_DATA_TYPE 14 SMALLINT (NOT NULL) SQL 데이터타입 SQL_DATETIME_SUB 15 SMALLINT Date 데이터타입을위한 subtype 코드. 이외의데이터타입인경우 null이반환 CHAR_OCTET_LENGTH 16 INTEGER 문자나바이너리데이터타입열의최대자릿수. 이외의데이터타입일경우널이반환 ORDINAL_POSITION 17 INTEGER (NOT NULL) 테이블의열의순서위치. 테이블의처음열은번호가 1 이다. IS_NULLABLE 18 VARCHAR NO : 열이널들을포함하지 않을때. YES : 열이널들을포함할때 진단 SQLSTATE 설명 부연설명 08S01 통신회선장애 ( 데이터송수신실패 ) ODBC와데이터베이스간에함수처리가완료되기전에통신회선실패 HY000 일반오류 관련함수 54 ALTIBASE5 ODBC User s Manual
SQLBindCol SQLFetch SQLStatistics SQLTables 예제 < $ALTIBASE_HOME/sample/SQLCLI/demo_meta2.cpp 참고 > if (SQLColumns(stmt,NULL, 0, NULL, 0, "DEMO_META2", SQL_NTS, NULL, 0)!= SQL_SUCCESS) execute_err(dbc, stmt, "SQLColumns"); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; SQLBindCol(stmt, 1, SQL_C_CHAR, szcatalog, STR_LEN,&cbCatalog); SQLBindCol(stmt, 2, SQL_C_CHAR, szschema, STR_LEN, &cbschema); SQLBindCol(stmt, 3, SQL_C_CHAR, sztablename, STR_LEN,&cbTableName); SQLBindCol(stmt, 4, SQL_C_CHAR, szcolumnname, STR_LEN, &cbcolumnname); SQLBindCol(stmt, 5, SQL_C_SSHORT, &DataType, 0, &cbdatatype); SQLBindCol(stmt, 6, SQL_C_CHAR, sztypename, STR_LEN, &cbtypename); SQLBindCol(stmt, 7, SQL_C_SLONG, &ColumnSize, 0, &cbcolumnsize); SQLBindCol(stmt, 8, SQL_C_SLONG, &BufferLength, 0, &cbbufferlength); SQLBindCol(stmt, 9, SQL_C_SSHORT, &DecimalDigits, 0, &cbdecimaldigits); SQLBindCol(stmt, 10, SQL_C_SSHORT, &NumPrecRadix, 0, &cbnumprecradix); SQLBindCol(stmt, 11, SQL_C_SSHORT, &Nullable, 0, &cbnullable); SQLBindCol(stmt, 17, SQL_C_SLONG, &OrdinalPosition, 0, &cbordinalposition); SQLBindCol(stmt, 18, SQL_C_CHAR, szisnullable, STR_LEN, &cbisnullable); while ( (rc = SQLFetch(stmt))!= SQL_NO_DATA) if ( rc == SQL_ERROR ) execute_err(dbc, stmt, "SQLColumns:SQLFetch"); break; printf(...); ODBC 함수 55
SQLConnect ODBC 와데이터베이스와의연결을설정한다. 연결핸들은상태, 트랜잭션상태, 그리고오류정보를포함한데이터베이스연결에관한모든정보를참조한다. Unicode SQLConnectW() 동작은 SQLConnect() 와동일하다. 구문 SQLRETURN SQLConnect ( SQLHDBC dbc, SQLCHAR * db, SQLSMALLINT dblength, SQLCHAR * usr, SQLSMALLINT usrlength, SQLCHAR * pwd, SQLSMALLINT pwdlength ); 인자 자료유형인자사용설명 SQLHDBC dbc 입력 연결핸들 SQLCHAR * db 입력 호스트 IP SQLSMALLINT dblength 입력 *db의문자개수 SQLCHAR * usr 입력 사용자식별자 SQLSMALLINT usrlength 입력 *usr의문자개수 SQLCHAR * pwd 입력 인증문자열 ( 암호 ) SQLSMALLINT pwdlength 입력 *pwd의문자개수 결과값 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_INVALID_HANDLE SQL_ERROR 설명 56 ALTIBASE5 ODBC User s Manual
입력길이인수 (dblength, usrlength, pwdlength) 는연관된자료의실제길이로설정될수있다. 여기에는연관된자료가널로종료된다는것을표시하기위한 SQL_NTS 나널종료문자가포함되지않는길이값을설정할수있다. * 이함수를호출하기전에 SQLAllocConnect () 를호출해야한다. SQLAllocStmt() 를호출하기전에이함수를호출해야한다. 서버연결시필요한정보 ( 인자로넘기는 IP, 사용자명, 암호를제외한 ) 는 SQLSetConnectAttr() 를이용해설정할수있다. 분산트랜잭션상황에서 (SQLSetConnectAttr 참조 ) dbc 를제외한매개변수는널 (NULL) 또는 0 으로설정한다. 진단 SQLSTATE 설명부연설명 08001 server 에연결할수없음 ODBC 가데이터베이스에연결을설정할수없음 08002 연결이름이사용중 해당 dbc는이미 데이터베이스에연결되 있음 08S01 통신회선장애 ( 데이터송수신실패 ) ODBC 와데이터베이스간에함수처리가완료되기전에통신회선실패 HY000 일반오류 Character set가존재하지않음 HY001 메모리할당오류 ODBC가함수를실행하고완료하기위해요구된메모리를할당할수없음 관련함수 SQLAllocHandle SQLDisconnect SQLDriverConnect SQLSetConnectAttr ODBC 함수 57
SQLDescribeCol 결과집합에서한열의이름, 데이터형, 십진숫자, nullability 를돌려준다. Unicode SQLDescribeColW() 동작은 SQLDescribeCol() 와동일하다. 구문 SQLRETURN SQLDescribeCol ( SQLHSTMT stmt, SQLSMALLINT col, SQLCHAR * name, SQLSMALLINT namemax, SQLSMALLINT * namelength, SQLSMALLINT * type, SQLINTEGER * precision, SQLSMALLINT * scale, SQLSMALLINT * nullable ); 인자 자료유형 인자 사용 설명 SQLHSTMT stmt 입력 명령문핸들 SQLSMALLINT col 입력 1 부터시작하는매개변수마커순서 SQLCHAR* name 출력 열이름의포인터 SQLSMALLINT namema x 입력 *name의문자개수 SQLSMALLINT * namelen gth 출력 *name 에반환가능한총바이트수 (nulltermination byte 제외 ) SQLSMALLINT * type 출력 열의 SQL 데이터타입의포인터 SQLINTEGER * precision 출력 데이터베이스에대한열크기의포인터열크기가결정될수없다면 ODBC는 0을반환 SQLSMALLINT * scale 출력 데이터베이스에대한열의 58 ALTIBASE5 ODBC User s Manual
십진숫자의개수의포인터십진숫자의개수가결정될수없거나적절하지않으면 ODBC는 0을반환 SQLSMALLINT * nullable 출력 열이 null이허용되는지를보여주는값의포인터 SQL_NO_NULLS: 열이 NULL을허용하지않음 SQL_NULLABLE: 열은 NULL을허용 결과값 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_INVALID_HANDLE SQL_ERROR 설명 애플리케이션은전형적으로 SQLPrepare() 를호출한후에그리고 SQLExecute() 를호출하기전에 SQLDescribeCol() 을호출한다. 또한애플리케이션은 SQLExecDirect() 를호출한후에 SQLDescribeCol() 를호출할수있다. SQLDescribeCol() 은 SELECT 문에의해생성된열의이름, 타입, 그리고길이를검색한다. 만약열이표현식이면 *name 은표현식이다. 진단 SQLSTATE 설명 부연설명 01004 자료가잘림 버퍼 *name이전체열이름을반환할만큼크지않아서열이름이잘림잘리지않은열이름의길이는 *namelength로반환된다. ODBC 함수 59
07009 유효하지않은설명자인덱스 HY000 HY090 일반오류 유효하지않은문자열또는버퍼길이 명시된 col 값이 0임명시된 col 값이결과집합의열의개수보다큼 명시된 namemax 값이 0 보다작음 SQLDescribeCol() 이 SQLPrepare() 후, SQLExecute() 전에호출됐을때 SQLPrepare() 나 SQLExecute() 에의해반환될수있는모든 SQLSTATE 를반환할수있다. 관련함수 SQLBindCol SQLColAttribute SQLFetch SQLNumResultCols SQLPrepare 예제 < $ALTIBASE_HOME/sample/SQLCLI/demo_meta2.cpp 참고 > sprintf(query,"select * FROM DEMO_EX1"); if (SQLExecDirect(stmt,query, SQL_NTS)!= SQL_SUCCESS) execute_err(dbc, stmt, query); SQLFreeStmt(stmt, SQL_DROP); return SQL_ERROR; SQLNumResultCols(stmt, &columncount); for ( i=0; i<columncount; i++ ) SQLDescribeCol(stmt, i+1, columnname, sizeof(columnname), &columnnamelength, &datatype, &columnsize, &scale, &nullable); 60 ALTIBASE5 ODBC User s Manual
SQLDescribeParam 동적 SQL 문의매개변수마커 (?) 와연관된칼럼의 SQL 데이터타입, 크기, 데이터타입, 해당매개변수마커의표현식, 십진숫자의개수, 그리고 nullability 를돌려준다. 구문 SQLRETURN SQLDescribeParam ( SQLHSTMT stmt, SQLSMALLINT iparam, SQLSMALLINT * type, SQLINTEGER * size, SQLSMALLINT * decimaldigit, SQLSMALLINT * nullable );, 인자 자료유형 인자 사용 설명 SQLHSTMT stmt 입력 명령문핸들 SQLSMALLINT iparam 입력 1 부터시작하는매개변수마커순서 SQLSMALLINT * type 출력 매개변수의 SQL 데이터타입의포인터 SQLINTEGER * size 출력 매개변수의 SQL 데이터타입의포인터열의크기또는해당매개변수마커의표현식의포인터 SQLSMALLINT * decimaldigit 출력 열의십진숫자의개수또는해당매개변수의표현식의포인터 SQLSMALLINT * nullable 출력 매개변수가 null이허용되는지를보여주는값의포인터 결과값 SQL_SUCCESS ODBC 함수 61
SQL_SUCCESS_WITH_INFO SQL_INVALID_HANDLE SQL_ERROR 설명 매개변수 iparam 은번호에의해식별되며왼쪽에서오른쪽으로, 1 부터번호가매겨지고, 다른순서로도설명될수있다. * 이함수를호출하기전에 SQLPrepare() 를호출해야한다. SQLBindParameter() 를호출하기전에일반적으로 SQLDescribeParam() 을호출해야한다. * 임의의매개변수의 type, size, decimaldigit, nullable 은다음과같은제한조건이있다. type: SQL_VACHAR size: 4000 decimaldigit: 0 nullable: SQL_NULLABLE_UNKNOWN (ODBC 는매개변수가 NULL 값을허용하는지결정할수없다.) 진단 SQLSTATE 설명부연설명 07009 유효하지않은열번호 HY010 함수호출순서오류 iparam 값이전체인자의범위를벗어남 SQLPrepare() / SQLExecDirect() 보다앞서호출됨 관련함수 SQLExecDirect SQLNumParams SQLPrepare 예제 62 ALTIBASE5 ODBC User s Manual
< $ALTIBASE_HOME/sample/SQLCLI/demo_info2.cpp 참고 > SQLPrepare(hstmt, Statement, SQL_NTS); // Check to see if there are any parameters. If so, process them. SQLNumParams(hstmt, &NumParams); if (NumParams) // Allocate memory for three arrays. The first holds pointers to buffers in w hich // each parameter value will be stored in character form. The second contains the // length of each buffer. The third contains the length/indicator value for e ach // parameter. PtrArray = (SQLPOINTER *) malloc(numparams * sizeof(sqlpointer)); BufferLenArray = (SQLINTEGER *) malloc(numparams * sizeof(sqlinteger)); LenOrIndArray = (SQLINTEGER *) malloc(numparams * sizeof(sqlinteger)); for (i = 0; i < NumParams; i++) // Describe the parameter. SQLDescribeParam(hstmt, i + 1, &DataType, &ParamSize, &DecimalDigits, &Nullab le); // Call a helper function to allocate a buffer in which to store the paramete r // value in character form. The function determines the size of the buffer fr om // the SQL data type and parameter size returned by SQLDescribeParam and retu rns // a pointer to the buffer and the length of the buffer. PtrArray[i] = (char*)malloc(paramsize); BufferLenArray[i] = SQL_NTS; // Bind the memory to the parameter. Assume that we only have input parameter s. SQLBindParameter(hstmt, i + 1, SQL_PARAM_INPUT, SQL_C_CHAR, DataType, ParamSi ze, DecimalDigits, PtrArray[i], BufferLenArray[i], &LenOrIndArray[i]); // Prompt the user for the value of the parameter and store it in the memory // allocated earlier. For simplicity, this function does not check the value // against the information returned by SQLDescribeParam. Instead, the driver ODBC 함수 63
64 ALTIBASE5 ODBC User s Manual does // this when the statement is executed. strcpy((char*)ptrarray[i], "AAAAAAA"); BufferLenArray[i] = 7;
SQLDisconnect 특정연결핸들과관련된연결을종료한다. 구문 SQLRETURN SQLDisconnect ( SQLHDBC dbc ); 인자 자료유형인자사용설명 SQLHDBC dbc 입력연결핸들 결과값 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_INVALID_HANDLE SQL_ERROR 설명 연결과연관된명령문핸들을모두해제하기전에애플리케이션이 SQLDisconnect() 를호출하면, 데이터베이스로부터연결을단절한다. SQL_SUCCESS_WITH_INFO 가리턴되면, 이는데이터베이스단절이성공적이지만추가오류또는특정구현프로그램정보가있음을의미한다. 예를들면다음과같다. 단절후에정리하는과정에서문제가발생하였거나 애플리케이션과는독립적으로발생한이벤트 ( 통신실패같은 ) 로인해현재는연결되지않은경우 성공적인 SQLDisconnect() 호출후에또다른 SQLConnect() 요구를하기위해애플리케이션은 dbc 를다시사용할수있다. * 이함수를호출한후에다른데이터베이스에연결하기위해 SQLConnect() 를호출하거나 SQLDriverConnect() 를호출해야한다. ODBC 함수 65
진단 SQLSTATE 설명부연설명 HY000 일반오류 관련함수 SQLAllocHandle SQLConnect SQLDriverConnect SQLEndTran SQLFreeConnect 예제 < $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp 참고 > SQLDisconnect( dbc ); 66 ALTIBASE5 ODBC User s Manual
SQLDriverConnect SQLDriverConnect() 는 SQLConnect() 를대체할수있다. 이함수는 SQLConnect() 의세개의인자 (DSN, 사용자 ID, 비밀번호 ) 보다더많은정보를요구하는연결스트링을지원한다. SQLDriverConnect() 는다음과같은연결속성을제공한다. 호스트 IP 또는호스트이름, 하나이상의사용자 ID, 하나이상의암호, 연결방법, 포트번호, NLS_USE, TIMEOUT 설정등의연결스트링을사용하여연결을설정한다. Unicode SQLDriverConnectW() 동작은 SQLDriverConnect() 와동일하다. 구문 SQLRETURN SQLDriverConnect ( SQLHDBC dbc, SQLPOINTER windowhandle, SQLCHAR * InConnectionString, SQLSMALLINT length1, SQLCHAR * OutConnectionString, SQLSMALLINT bufferlength, SQLSMALLINT * strlength2ptr, SQLSMALLINT DriverCompletion ); 인자 자료유형 인자 사용 설명 SQLHDBC dbc 입력연결핸들 SQLPOINTER windowhandle 입력사용하지않음 SQLCHAR* InConnectionString 입력 완전연결스트링부분연결스트링빈문자열아래설명참조 SQLSMALLINT length1 입력 *InConnectionString의문자개수 SQLCHAR * OutConnectionString 출력 사용하지않음 SQLSMALLINT bufferlength 입력 사용하지않음 SQLSMALLINT * strlength2ptr 출력 사용하지않음 SQLSMALLINT DriverCompletion 입력 사용하지않음 ODBC 함수 67