2. 데이터 타입

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

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

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_TYPE	바인딩할 buffer의 타입을 지정하는데 사용되는 멤버 변수이다. "enum ALTIBASE_BIND_TYPE"를 참고하라.
buffer	void *	입출력 데이터를 담는 버퍼를 가리키는 포인터이다. 입력 바인딩의 경우, buffer는 SQL문에 물음표(?)로 표시된 파라미터에 바인딩될 변수일 것이다. 출력 바인딩의 경우, buffer는 조회된 결과 집합의 각 칼럼 값을 저장할 변수일 것이다.
buffer_length	ALTIBASE_LONG	buffer의 실제 크기를 지정하는 데 사용되는 멤버 변수이다. 길이가 고정된 데이터 타입의 변수로 바인딩 할 때는 이 멤버의 값을 설정하지 않아도 된다. 그러나 설정을 생략하려면 반드시 이 값이 0으로 초기화 되어 있어야 한다. 다음 타입에 대해서만 길이 설정을 생략할 수 있다: 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() 함수 호출시 이 구조체로 문자 집합에 대한 정보가 반환된다.

이 구조체는 다음과 같은 멤버를 포함한다.

구조체 멤버	타입	설명
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_NAME_LEN]	칼럼의 이름. 질의에서 칼럼에 별칭(alias)를 준 경우, 이 값은 주어진 별칭이 될 것이다.
name_length	int	name의 길이
org_name	char [ALTIBASE_MAX_FIELD_NAME_LEN]	칼럼의 이름
org_name_length	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_length	int	org_table의 길이
size	int	칼럼 크기 또는 숫자형 타입의 precision
scale	int	숫자형 타입의 scale

struct ALTIBASE_NUMERIC

숫자형 데이터를 저장하는 구조체이다. NUMERIC 타입의 데이터를 가져올 때 사용된다.

이 구조체는 다음의 멤버를 포함한다.

구조체 멤버	타입
precision	unsigned char
scale	unsigned char
sign	char
val	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/100000초

그 외 타입

위에서 설명한 핸들과 구조체 외에 다음의 타입이 사용될 수 있다.

• ALTIBASE_ROW

• ALTIBASE_LONG

• ALTIBASE_NTS

• enum ALTIBASE_BIND_TYPE

• enum ALTIBASE_FAILOVER_EVENT

• enum ALTIBASE_FIELD_TYPE

• enum ALTIBASE_OPTION

• 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

이는 데이터가 널로 끝나는 문자열임을 나타내기 위해 사용되는 매크로이다. 문자열을 입력 바인딩할 때, 데이터 길이를 실제 길이 대신에 이 값으로 설정할 수 있다.

문자형이 아닌 바이너리형 데이터를 입력 바인딩할 때 데이터 길이(length)를 ALTIBASE_NTS로 설정하면, 버퍼 길이(buffer_length)에 설정한 값이 데이터의 길이로 사용된다.

enum ALTIBASE_BIND_TYPE

바인딩할 데이터의 타입을 지정할 때 사용된다.

이 열거형의 원소는 다음과 같다.

원소	설명
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가 성공하였음을 콜백 함수에 알리는 값이다.
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	CHAR
ALTIBASE_TYPE_VARCHAR	VARCHAR
ALTIBASE_TYPE_NCHAR	NCHAR
ALTIBASE_TYPE_NVARCHAR	NVARCHAR
ALTIBASE_TYPE_SMALLINT	SMALLINT
ALTIBASE_TYPE_INTEGER	INTEGER
ALTIBASE_TYPE_BIGINT	BIGINT
ALTIBASE_TYPE_REAL	REAL
ALTIBASE_TYPE_DOUBLE	DOUBLE
ALTIBASE_TYPE_FLOAT	FLOAT
ALTIBASE_TYPE_NUMERIC	NUMERIC
ALTIBASE_TYPE_DATE	DATE
ALTIBASE_TYPE_BLOB	BLOB
ALTIBASE_TYPE_CLOB	CLOB
ALTIBASE_TYPE_BYTE	BYTE
ALTIBASE_TYPE_NIBBLE	NIBBLE
ALTIBASE_TYPE_BIT	BIT
ALTIBASE_TYPE_VARBIT	VARBIT
ALTIBASE_TYPE_GEOMETRY	GEOMETRY

enum ALTIBASE_OPTION

서버와의 연결 속성을 설정할 때 사용되는 열거형이다. 이 중 ALTIBASE_AUTOCOMMIT 속성은 altibase_set_autocommit() 함수를 사용해서 설정하기를 권장한다.

이 열거형의 원소 (즉, 연결 속성)와 각 속성에 지정할 수 있는 값의 타입 및 최대 크기는 다음과 같다.

원소 (연결 속성)	속성 값의 타입	속성 값의 최대 크기	설명
ALTIBASE_AUTOCOMMIT	int	sizeof(int)	AUTOCOMMIT 여부를 설정하는 속성. 속성의 값은 32비트 크기이다. 이 속성의 값은 ALTIBASE_AUTOCOMMIT_ON 또는 ALTIBASE_AUTOCOMMIT_OFF 로 설정할 수 있다.
ALTIBASE_CONNECTION_TIMEOUT	int	sizeof(int)	네트워크 불안정으로 인해 데이터 송수신 시 발생할 수 있는 블록킹을 방지하기 위한 타임아웃 값을 설정하는 속성
ALTIBASE_PORT	int	sizeof(int)	Altibase 서버의 포트 번호를 설정하는 속성
ALTIBASE_TXN_ISOLATION	int	sizeof(int)	트랜잭션의 고립화 수준을 설정하는 속성
ALTIBASE_APP_INFO	char *	ALTIBASE_MAX_APP_INFO_LEN	클라이언트 식별자를 지정하는 속성. 클라이언트에 대한 보다 정확한 정보를 설정하기 위해 사용된다.
ALTIBASE_DATE_FORMAT	char *	ALTIBASE_MAX_DATE_FORMAT_LEN	날짜 형식을 지정하는 속성. 기본값은 "YYYY/MM/DD HH:MI:SS"이다.
ALTIBASE_NLS_USE	char *	ALTIBASE_MAX_NLS_USE_LEN	클라이언트 사용 언어를 지정하는 속성. (US7ASCII: 영어, KO16KSC5601: 한국어)
ALTIBASE_NLS_NCHAR_LITERAL_REPLACE	int	sizeof(int)	SQL 구문에 NCHAR 리터럴 문자열이 존재하는지 검사 여부를 설정하는 속성.
ALTIBASE_IPC_FILEPATH	char *	ALTIBASE_MAX_IPC_FILEPATH_LEN	유닉스 환경에서 서버와 클라이언트가 IPC로 접속할 때 ALTIBASE_HOME이 서로 다르다면, 유닉스 도메인의 소켓 경로가 일치하지 않아 접속이 불가능하다. 이 때 이 속성의 값을 서버의 $ALTIBASE_HOME/trc/cm-ipc 파일로 설정하여 서버와 클라이언트가 같은 소켓 파일을 사용하도록 하면, 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 수행 시에는 배열에 속한 모든 SQL문들이 서버에서 한 개의 statement로 처리되므로, altibase_stmt_status(), altibase_stmt_processed()가 반환하는 결과값 (반환 타입이 배열이다)의 첫 번째 요소 값 만이 유효하다.

데이터 타입간의 관계

아래의 그림은 ACI의 각 핸들과 데이터 타입들 사이의 관계를 보여준다.

위 관계도를 보면 ALTIBASE_STMT 핸들을 사용해서 얻은 ALTIBASE_RES로는 ALTIBASE_ROW를 얻을 수 없음을 알 수 있다(점선으로 표시). ALTIBASE_ROW는 바인딩 없이 SQL문을 직접 수행(direct execution)하는 altibase_query() 관련 함수를 통해서만 구할 수 있다. 이에 대한 자세한 내용은 각 함수의 설명을 참고하라.