tbCLI 소개
티베로 DB CLI 기능의 기본 개념과 구성요소, 프로그램의 구조를 소개합니다.
개요
tbCLI는 Tibero가 제공하는 Call Level Interface(CLI)로 사용자의 애플리케이션 프로그램과 Tibero 간의 SQL 인터페이스 역할을 수행합니다. 사용자는 tbCLI 라이브러리를 통해 Tibero에 접근하려는 C 또는 C++ 애플리케이션 프로그램을 쉽게 작성할 수 있습니다.
tbCLI는 ODBC(Open Database Connectivity) 및 X/Open Call Level Interface Standard를 기초로 개발되었습니다. tbCLI는 ODBC 2.0의 Level 2 및 ODBC 3.0의 Level 1의 모든 조건, 그리고 ODBC 3.0 Level 2의 대부분의 조건을 만족합니다. 따라서 ODBC나 CLI를 이용해 작성된 기존의 애플리케이션 프로그램은 tbCLI환경으로 쉽게 전환될 수 있습니다.
특히 tbCLI는 아래 그림과 같은 클라이언트/서버 환경에서 유용합니다.
[그림 1] 클라이언트/서버 환경
클라이언트의 애플리케이션 프로그램이 tbCLI의 API를 호출하면, 데이터베이스 시스템이 이를 처리하고 그 결과를 클라이언트로 반환해줍니다. 물론 사용자는 tbESQL 등의 인터페이스를 이용하여 데이터를 처리 할 수 있지만, tbCLI를 사용함으로써 애플리케이션 프로그램과 데이터를 더 세밀하게 조작할 수 있습니다.
tbCLI 특징
실행 파일을 생성할 때 프리컴파일러(Precompiler)가 필요 없습니다. tbCLI는 tbESQL과 마찬가지로 일반적인 프로그램 언어와 SQL 문장의 장점을 융합한 인터페이스입니다. 하지만 tbESQL과 다르게 일반적인 프로그램에 가깝습니다.
모듈을 효율적으로 관리할 수 있으며, 가독성이 뛰어납니다.
애플리케이션 패키지를 바인딩할 필요가 없습니다.
접근할 데이터베이스의 통계(statistics)를 사용할 수 있습니다.
스레드의 안정성을 보장합니다. 애플리케이션 프로그램을 멀티 스레드로 작성할 수 있도록 스레드의 안정성을 보장합니다.
구성요소
본 절에서는 tbCLI 프로그램을 작성하거나 실행하기 전에 기본적으로 알아야 할 구성요소에 대해 설명합니다.
tbCLI 핸들
핸들은 tbCLI에서 관리하고 있는 몇 가지 주요 데이터 구조에 대한 포인터(pointer)입니다. 핸들을 사용함으로써 tbCLI 프로그램은 복잡한 구조를 갖는 데이터를 보다 편리하게 관리할 수 있습니다.
핸들의 내부 데이터는 데이터 구조에 작업이 이루어지면 자동으로 갱신되기 때문에 애플리케이션 프로그램 개발자는 핸들이 가리키는 데이터 구조의 세부 사항에 대해 알 필요가 없으며, 내부 데이터를 직접 접근할 필요도 없습니다.
tbCLI 프로그램은 아래와 같이 네 가지 핸들을 사용합니다.
환경 핸들(environment handle) tbCLI 프로그램의 환경에 대한 데이터를 포함합니다. 포함되는 데이터로는 현재 환경의 상태, 환경에 할당되어 있는 연결 핸들의 리스트, 환경에 대한 에러 정보 등입니다.
연결 핸들(connection handle) 데이터소스(data source)와의 연결에 대한 데이터를 포함합니다. 포함되는 데이터로는 현재 연결 상태, 연결에 할당되어 있는 문장 핸들의 리스트, 연결에 대한 에러 정보 등입니다.
문장 핸들(statement handle) tbCLI 프로그램에서 실행할 하나의 SQL 문장에 대한 데이터를 포함합니다. 포함되는 데이터로는 현재 문장 상태, 문장 내의 입력 파라미터 및 출력 컬럼의 리스트, 문장에 대한 에러 정보 등입니다.
서술자 핸들(descriptor handle) 문장 핸들과 연관된 결과 집합(ResultSet)의 각 컬럼이나 바인드된 파라미터의 데이터를 포함합니다. 포함되는 데이터로는 SQL 문장의 입력 파라미터, 출력 컬럼에 대한 메타데이터(metadata) 등입니다.
tbCLI 함수
tbCLI 프로그램에서 데이터베이스 작업을 수행하기 위해서는 tbCLI 함수를 사용해야 합니다. 대부분의 tbCLI 함수는 대상이 되는 핸들을 입력 파라미터로 받으며, SQLRETURN 타입의 반환 코드를 갖습니다.
아래는 tbCLI 함수 중에서 SQL 문장을 직접 실행할 수 있는 SQLExecDirect 함수의 프로토 타입입니다.
SQLRETURN SQLExecDirect(SQLHSTMT StatementHandle, SQLCHAR *SQLString,
SQLINTEGER SQLStringSize);tbCLI 함수는 기능별로 몇 개의 그룹으로 나누어 제공됩니다. 예를 들면 핸들을 할당하거나 연결과 관련된 함수, SQL 문장 실행과 관련된 함수, SQL 질의 결과의 검색과 관련된 함수, 서술자 관련 함수, 에러 정보 와 관련된 함수, 데이터소스 정보와 관련된 함수 등이 있습니다.
tbCLI 에러 메시지
tbCLI 프로그램은 tbCLI 함수를 실행한 후 반환되는 코드에 의해 실행 결과를 얻습니다. 그러나 사용자는 보다 더 다양한 정보를 필요로 합니다. 이러한 정보를 제공하기 위해서 tbCLI는 진단 레코드를 생성합니다.
진단 레코드는 수행한 함수의 반환 코드뿐만 아니라 실행 결과에 대한 다양한 정보를 갖고 있습니다.
진단 레코드는 아래와 같이 두 가지 레코드로 구성됩니다.
헤더 레코드(header record) 반환 코드, 로우 개수, 상태 레코드의 개수, 실행된 명령의 타입 등의 필드로 구성되어 있습니다. 반환 코드가 SQL_INVALID_HANDLE인 경우를 제외하고 tbCLI 함수가 실행되면 항상 헤더 레코드가 생성됩니다.
상태 레코드(status record) 상태 레코드는 경고 및 에러에 대한 정보를 포함합니다. 반환 코드가 SQL_ERROR, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_NEED_DATA, SQL_STILL_EXECUTING인 경우 생성됩니다. 상태 레코드의 필드 중에서 가장 중요한 필드 중의 하나는 SQLSTATE 필드입니다. 에러 또는 경고 코드를 표준화한 것으로 값은 X/Open과 ISO/IEC 표준으로 정해져 있습니다. 형식은 CCSSS 다섯 자리의 문자 열이며, CC는 에러 클래스, SSS는 에러 서브 클래스를 의미합니다.
진단 레코드는 하나의 헤더 레코드로 시작되고 경우에 따라 1개 이상의 상태 레코드가 추가됩니다. 진단 레코드의 값을 얻기 위해서는 SQLGetDiagRec와 SQLGetDiagField 함수를 사용해야 합니다. 이 두 함수는 파라미터로 주어진 핸들에 포함된 진단 레코드의 정보를 반환하는 역할만을 수행합니다. 진단 레코드는 환경, 연결, 문장, 서술자 핸들에서 사용되고 관리됩니다.
SQLGetDiagField
진단 레코드 중 단일 필드의 정보를 얻기 위해 사용하는 함수
헤더 레코드와 상태 레코드 모두에 사용 가능
SQLGetDiagRec
상태 레코드에 포함된 SQLSTATE 코드, 에러 코드, 진단 메시지 등의 여러 개 의 필드 값을 동시에 얻기 위해 사용하는 함수
상태 레코드에만 사용 가능
프로그램 구조
tbCLI 프로그램은 아래 그림과 같이 크게 나눕니다.
[그림 2] tbCLI 프로그램 구조
시작 설정 부분 (Starting setting)
SQL 문장 실행 및 에러 처리 부분 (SQL query execution and error handling)
종료 설정 부분 (Ending setting)
시작 설정 부분
tbCLI 프로그램을 시작하기 위해서는 우선 초기화 설정을 해야 합니다. 초기화 설정을 하려면 환경 핸들과 연결 핸들을 할당하고 데이터 소스와의 실제 연결을 수행해야 합니다. 여기서 데이터 소스란 Tibero의 소프트웨어 및 하드웨어의 전체 구성을 의미합니다.
아래는 tbCLI 프로그램을 시작하는 예입니다.
[예 1] tbCLI 프로그램의 시작 설정
SQLHENV h_env;
SQLHDBC h_dbc;
SQLRETURN rc = SQL_SUCCESS;
...
rc = SQLAllocHandle(SQL_HANDLE_ENV, NULL, &h_env); ... ① ...
if (rc != SQL_SUCCESS) ...
rc = SQLAllocHandle(SQL_HANDLE_DBC, h_env, &h_dbc); ... ② ...
if (rc != SQL_SUCCESS) ...
rc = SQLConnect(h_dbc, (SQLCHAR *)ds_name, SQL_NTS, (SQLCHAR *)user,
SQL_NTS, (SQLCHAR *)passwd, SQL_NTS); ... ③ ...
if (rc != SQL_SUCCESS && rc != SQL_SUCCESS_WITH_INFO) ...①, ② 초기화 설정을 위해 환경 핸들과 연결 핸들을 할당합니다.
③ SQLConnect 함수를 통해 데이터소스에 연결합니다. 이 함수를 호출할 때에는 파라미터로 데이터소스의 이름(ds_name)과 사용자의 이름(user), 패스워드 (passwd)를 함께 전달해야 합니다. 뿐만 아니라 파라미터의 길이도 함께 설정해 주어야 하는데 위의 예 에서는 길이 대신 NULL로 끝나는 문자열(null-terminating string) 즉 SQL_NTS를 설정합니다.
④ 데이터소스에 연결하는 과정이 끝나면 tbCLI 프로그램은 SQL 문장을 실행하기 위해 다음과 같이 반드시 한 개 이상의 문장 핸들을 할당합니다.
SQLHSTMT h_stmt;
...
rc = SQLAllocHandle(SQL_HANDLE_STMT, h_dbc, &h_stmt); ... ④ ...
if (rc != SQL_SUCCESS) ...SQL 문장 실행 및 에러 처리 부분
SQL 문장을 실행하는 방법은 아래와 같이 두 가지가 있습니다.
직접실행
SQL 문장을 SQLExecDirect 함수를 이용하여 한 번에 실행하는 방법입니다.
아래는 직접 실행의 예입니다.
[예 2]tbCLI 프로그램의 SQL 문장 실행 - 직접 실행
SQLCHAR *update = "UPDATE EMP SET SALARY = SALARY * 1.05 "
"WHERE DEPTNO = 5";
rc = SQLExecDirect(h_stmt, update, SQL_NTS);
if (rc != SQL_SUCCESS) ...준비된 실행
SQLPrepare와 SQLExecute 함수를 이용하여 두 단계에 걸쳐 실행하는 방법입니다.
대부분 SQL 문장 내에 파라미터가 포함된 경우에는 주로 준비된 실행 방법을 이용합니다. SQLPrepare SQLExecute 함수 사이에 SQLBindParameter 함수를 호출하여 파라미터에 실제 값을 설정합니다.
아래는 두 개의 입력 파라미터를 포함한 SQL 문장을 실행하는 예입니다.
[예 3] tbCLI 프로그램의 SQL 문장 실행 - 준비된 실행
SQLCHAR *update = "UPDATE EMP SET SALARY = SALARY * ? "
"WHERE DEPTNO = ?";
double ratio = 0.0;
short deptno = 0;
...
rc = SQLPrepare(h_stmt, update, SQL_NTS); ... ① ...
if (rc != SQL_SUCCESS) ...
rc = SQLBindParameter(h_stmt, 1, SQL_PARAM_INPUT, SQL_C_DOUBLE,
SQL_DOUBLE, 5, 2, &ratio, 0, NULL); ... ⓐ ...
if (rc != SQL_SUCCESS) ...
rc = SQLBindParameter(h_stmt, 2, SQL_PARAM_INPUT, SQL_C_SHORT,
SQL_SMALLINT, 0, 0, &deptno, 0, NULL); ... ⓑ ...
if (rc != SQL_SUCCESS) ...
ratio = 1.05;
deptno = 5;
SQLExecute(h_stmt); ... ② ...
if (rc != SQL_SUCCESS) ...위의 예에서는 SQL 문장 내의 입력 파라미터를 물음표(?)로 표시합니다. 입력 파라미터의 위치를 표시할 때에는 1 이상의 정수를 사용합니다.
① 준비된(prepared) SQL 문장에 포함된 각각의 입력 파라미터의 값을 저장하고 있는 변수의 포인터를 설정합니다. 각각의 입력 파라미터(ⓐ, ⓑ)에 입출력 방향, C 또는 C++의 데이터 타입, SQL의 데이터 타입, 정밀도(precision), 범위(scale) 등을 함께 설정합니다.
② SQL 문장을 실행합니다. 이 문장을 실행하면 설정된 입력 파라미터에 의해 EMP 테이블이 갱신됩니다.
SQL 문장을 실행하고 나서 몇 개의 로우가 갱신되었는지 확인하려면 SQLRowCount 함수를 사용합니다. 사용하는 방법은 다음과 같습니다.
rc = SQLRowCount(h_stmt, &count);각 함수의 반환 코드는 수행 결과에 대한 정보를 가지고 있으므로, 함수를 호출한 후에는 항상 반환 코드를 확인해야 합니다.
종료 설정 부분
tbCLI 프로그램을 종료하기 위해서는 “시작 설정 부분”에서 수행한 작업과 반대되는 작업을 수행해야 합니다.
아래는 tbCLI 프로그램을 종료하는 예입니다.
[예 4] tbCLI 프로그램의 종료 설정
rc = SQLDisconnect(h_dbc); ... ① ...
if (rc != SQL_SUCCESS) ...
SQLFreeHandle(SQL_HANDLE_DBC, h_dbc); ... ② ...
SQLFreeHandle(SQL_HANDLE_ENV, h_env); ... ③ ...① 데이터소스의 연결을 해제합니다.
②, ③ 할당한 연결 핸들과 환경 핸들을 시스템에 반환합니다.
Last updated