콘텐츠로 이동
≡

Administrator

Developer

Tools

External Tools

4. Prepared Statement 관련 ACI 함수#

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

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";

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));

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()은 한 번만 수행한 후 바인딩된 변수의 값만 변경하면서 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   = ALTIBASE_BIND_INTEGER;
bind[0].buffer        = &int_dat;
bind[0].length        = &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 ... */

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()를 호출할 때마다 결과 집합의 한 행이 바인딩된 버퍼에 반환된다.

이 함수는 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   = ALTIBASE_BIND_INTEGER;
bind[0].buffer        = &int_dat;
bind[0].length        = &length[0];
bind[0].is_null       = &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++)
{
    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 ... */

altibase_stmt_close()#

명령문 핸들을 닫는 함수이다.

구문#

int  altibase_stmt_close (
    ALTIBASE_STMT stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

함수 수행이 성공하면 ALTIBASE_SUCCESS, 그렇지 않으면 ALTIBASE_ERROR가 반환된다.

설명#

이 함수는 명령문 핸들을 닫고 명령문 핸들을 위해서 할당된 모든 자원을 해제한다.

예제#

altibase_stmt_init()의 예제를 참고하라.

altibase_stmt_data_seek()#

질의 결과 집합에서 가져올 행의 위치를 지정하는 함수이다.

구문#

int  altibase_stmt_data_seek (
    ALTIBASE_STMT  stmt,
    ALTIBASE_LONG  offset );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들
ALTIBASE_LONG offset 입력 다음에 가져올 행의 위치 (0부터 시작)

반환 값#

함수 수행이 성공하면 ALTIBASE_SUCCESS, 그렇지 않으면 ALTIBASE_ERROR가 반환된다.

설명#

이 함수는 결과 집합에서 다음에 가져올 행의 위치를 특정 위치로 이동시킨다. 위치로 지정하는 행 번호의 값은 0부터 (결과 집합의 행 개수 - 1) 까지의 값이어야 한다.

altibase_store_result() 호출 이후에만 이 함수를 실행할 수 있다.

예제#

#define QSTR "SELECT last_name, first_name FROM friends"

/* ... omit ... */

rc = altibase_stmt_store_result(stmt);
/* ... check return value ... */

row_count = altibase_stmt_num_rows(stmt);
for (i = 0; i < row_count; i++)
{
    rc = altibase_stmt_data_seek(stmt, i);
    if (ALTIBASE_NOT_SUCCEEDED(rc))
    {
        printf("ERR : %d : ", i, altibase_error());
        continue;
    }

    rc = altibase_stmt_fetch(stmt);
    /* ... check return value ... */

    /* ... omit ... */
}

rc = altibase_stmt_free_result(stmt);
/* ... check return value ... */

altibase_stmt_errno()#

바로 이전에 실행된 함수에서 발생한 오류의 에러 코드를 구하는 함수이다.

구문#

unsigned int  altibase_stmt_ errno (
    ALTIBASE_STMT stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

바로 이전에 호출된 함수가 성공했으면 0, 실패했으면 에러 코드가 반환된다.

설명#

이 함수는 바로 이전에 실행된 SQL 문 수행 함수가 실패했을 경우, 실패 원인을 알려주는 에러 코드를 반환한다.

바로 이전에 실행된 함수가 실패했더라도, 모든 함수에 대해서 에러 코드가 반환되지는 않는다. 직전에 수행된 함수가 주로 SQL 문 수행과 관련된 함수였을 경우에만 에러 코드가 생성된다. 에러 코드에 대한 자세한 내용은 Error Message Reference를 참고한다.

어떤 함수 수행시 오류가 발생한 경우 바로 오류를 확인하지 않고 다른 함수를 호출하면, 이 오류에 대한 정보가 사라진다. 따라서 오류 발생시 바로 이 함수를 사용해서 오류 정보를 확인해야 한다.

altibase_stmt_errno()가 반환하는 값은 Altibase 자체 정의 오류 코드로 ODBC표준 명세에 정의된 SQLSTATE과는 다르다. SQLSTATE를 얻으려면 altibase_stmt_sqlstate()를 사용해야 한다. 일반적으로 altibase_errno()의 반환 값을 확인해서 에러 처리 루틴을 작성하는 것을 권장하지 않는다.

예제#

rc = altibase_stmt_execute(stmt);
if (ALTIBASE_NOT_SUCCEEDED(rc))
{
    printf("error no  : %05X\n", altibase_stmt_errno(stmt));
    printf("error msg : %s\n", altibase_stmt_error(stmt));
    printf("sqlstate  : %s\n", altibase_stmt_sqlstate(stmt));
    return 1;
}

/* ... omit ... */

altibase_stmt_error()#

바로 이전에 실행된 함수에서 발생한 오류의 에러 메시지를 구하는 함수이다.

구문#

const char *  altibase_stmt_error (
ALTIBASE_STMT stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

바로 이전에 호출된 함수가 성공했으면 빈 문자열이, 실패했으면 에러 메시지 문자열이 반환된다.

설명#

이 함수는 바로 이전에 실행된 함수가 실패했을 경우, 실패 원인을 알려주는 에러 메시지를 반환한다. 이전에 실행된 함수가 실패하지 않았을 경우에는, 빈 문자열 또는 그 이전에 발생했던 오류와 관련된 에러 메시지가 반환될 것이다.

어떤 함수 수행시 오류가 발생한 경우 바로 오류를 확인하지 않고 다른 함수를 호출하면, 이 오류에 대한 정보가 사라진다. 따라서 오류 발생시 바로 이 함수를 이용해서 오류 정보를 확인해야 한다.

이 함수가 반환한 char 포인터가 가리키는 메모리는 라이브러리 내부에서 관리되므로 절대로 사용자가 임의로 변경하거나 해제해서는 안 된다.

예제#

altibase_stmt_errno()의 예제를 참고하라.

altibase_stmt_execute()#

이전에 준비된 문장 (prepared statement)을 실행하는 함수이다.

구문#

int  altibase_stmt_execute (
    ALTIBASE_STMT stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

반환 값 설명
ALTIBASE_SUCCESS SQL 문 수행 성공
ALTIBASE_NEED_DATA altibase_stmt_send_long_data()를 이용해서 서버로 보내야 할 데이타가 있음
ALTIBASE_ERROR 함수 수행 중 오류가 발생함

설명#

이 함수는 명령문 핸들에 준비되어 있는 문장 (prepared statement)을 실행한다.

명령문이 UPDATE, DELETE 또는 INSERT문이라면 이 함수 수행 후에 몇 개의 행이 변경되었는지 확인하기 위해 altibase_stmt_affected_rows()를 사용할 수 있다.

명령문이 SELECT문 처럼 결과 집합을 반환하는 것이라면, 데이터를 가져오기 위해서 altibase_stmt_fetch()를 사용해야 하며, 결과 집합 사용 완료 후에는 altibase_stmt_free_result()를 이용해서 결과 집합을 해제해야 한다.

예제#

altibase_stmt_bind_param()과 altibase_stmt_bind_result()의 예제를 참고하라.

altibase_stmt_fetch()#

결과 집합으로부터 한 행을 가져오는 함수이다.

구문#

int  altibase_stmt_fetch (
    ALTIBASE_STMT stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

반환 값 설명
ALTIBASE_SUCCESS 성공적으로 데이타를 가져옴
ALTIBASE_SUCCESS_WITH_INFO 성공적으로 데이타를 가져왔으나 경고가 있음
ALTIBASE_NO_DATA 더 가져올 데이타가 없음
ALTIBASE_ERROR 함수 수행 중 오류가 발생함

설명#

이 함수는 결과 집합에서 다음 행의 데이터를 가져와서, altibase_stmt_bind_result()로 바인딩한 버퍼에 저장한다.

예제#

altibase_stmt_bind_result()의 예제를 참고하라.

altibase_stmt_fetch_column()#

결과 집합의 현재 행에서 한 칼럼의 데이터를 가져오는 함수이다.

구문#

int  altibase_stmt_bind_result (
    ALTIBASE_STMT    stmt,
    ALTIBASE_BIND    *  bind,
    int              column,
    ALTIBASE_LONG    offset );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들
ALTIBASE_BIND * bind 입력 데이터를 받아올 버퍼
int column 입력 데이터를 가져올 칼럼의 번호 (0부터 시작)
ALTIBASE_LONG offset 입력 가져올 칼럼 데이터내에서의 시작 위치 (0부터 시작)

반환 값#

함수 수행이 성공하면 ALTIBASE_SUCCESS, 그렇지 않으면 ALTIBASE_ERROR가 반환된다.

설명#

이 함수는 결과 집합 내의 현재 행에서 한 칼럼의 데이터를 버퍼에 반환한다.

offset은 대용량 데이터를 여러 번 나눠서 가져올 때, 데이터 내의 어느 위치에서부터 가져올 것인지를 지정하는 인자이다. 이 값을 0으로 지정하면 데이터의 처음부터 가져온다. offset 인자에는 미리 정의된 ALTIBASE_FETCH_COUNT 매크로를 사용할 수 있는데, 이는 직전에 가져온 데이터에 바로 이어서 가져오라는 의미이다. 만약 이전에 한 번도 데이터를 가져온 적이 없으면, 데이터의 처음부터 가져올 것이다.

이전에 altibase_stmt_store_result()를 호출했는지 여부에 따라서 이 함수의 사용법이 약간 달라진다.

altibase_stmt_store_result() 호출 여부 bind 인자 offset 인자
Yes (즉, 결과 집합을 모두 클라이어언트에 가져와 있는 상태) 버퍼의 타입이 altibase_stmt_bind_result()에서 사용했던 버퍼의 타입과 동일해야 함 임의의 값 사용 가능
No 임의의 버퍼 타입 사용 가능 ALTIBASE_FETCH_COUNT를 사용해서 데이터를 순차적으로 가져와야 함

위 표에서 기술한 bind 인자와 offset 인자의 제약 조건을 만족하지 않을 경우 에러가 반환될 것이다.

예제#

#define STR_SIZE 50

char           str_dat[STR_SIZE];
ALTIBASE_LONG  length;
ALTIBASE_BOOL  is_null;
ALTIBASE_BIND  bind;
int            rc;
int            i;

/* ... omit ... */

rc = altibase_stmt_execute(stmt);
/* ... check return value ... */

memset(bind, 0, sizeof(bind));

bind.buffer_type   = ALTIBASE_BIND_STRING;
bind.buffer        = str_dat;
bind.buffer_length = STR_SIZE;
bind.length        = &length;
bind.is_null       = &is_null;

while (1)
{
    rc = altibase_stmt_fetch(stmt);
    if (rc == ALTIBASE_NO_DATA)
    {
        break;
    }
    if (ALTIBASE_NOT_SUCCEEDED(rc))
    {
        /* ... error handling ... */
    }

    for (i = 0; ; i++)
    {
        rc = altibase_stmt_fetch_column(stmt, &bind, 0, ALTIBASE_FETCH_CONT);
        if (ALTIBASE_NOT_SUCCEEDED(rc))
        {
            /* ... error handling ... */
        }

        printf("%d : (%d) %s\n", i, length, str_dat);
    }
}

altibase_stmt_fetched()#

배열 변수를 이용해서 fetch를 수행한 후, 얻어 온 행의 개수를 구하는 함수이다.

구문#

ALTIBASE_LONG  altibase_stmt_fetched (
    ALTIBASE_STMT stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

가져온 행의 개수가 반환된다. 함수 수행 중에 오류가 발생했다면, ALTIBASE_INVALID_FETCHED가 반환될 것이다.

설명#

이 함수는 결과 집합으로부터 한꺼번에 여러 행을 배열 변수로 가져온 (이를 array fetch라고 함) 후 사용할 수 있는데, 이는 이 때 가져온 행의 개수를 반환한다. Array fetch를 이용해서 결과 집합으로부터 데이터를 가져올 때, altibase_stmt_fetch() 반복 수행의 조건 검사에 이 함수의 반환 값을 사용하면 된다.

이 함수는 array fetch의 사용을 설정했을 경우에만 사용될 수 있다.

예제#

5장의 array fetch를 참고하라.

altibase_stmt_field_count()#

가장 최근에 준비된 명령문의 결과 집합의 칼럼 수를 구하는 함수이다.

구문#

int  altibase_stmt_field_count (
    ALTIBASE_STMT stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

반환 값 설명
0 보다 큰 값 가장 최근에 준비된 명령문의 결과 집합의 칼럼 수를 의미한다.
0 준비된 명령문이 결과 집합을 생성하지 않는 명령문임을 의미한다.
ALTIBASE_INVALID_FIELDCOUNT 함수 수행 중 에러 발생

설명#

이 함수는 가장 최근에 준비된 명령문의 결과 집합의 칼럼 수를 반환한다.

만약 준비된 명령문이 INSERT, UPDATE, 또는 DELETE 문처럼 결과 집합을 생성하지 않는 명령문이라면 0이 반환된다.

이 함수는 altibase_stmt_prepare()를 실행한 후에 사용될 수 있다.

예제#

altibase_stmt_prepare()의 예제를 참고하라.

altibase_stmt_free_result()#

명령문 핸들의 결과 집합을 닫는 함수이다.

구문#

int  altibase_stmt_free_result (
    ALTIBASE_STMT stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

함수 수행이 성공하면 ALTIBASE_SUCCESS, 그렇지 않으면 ALTIBASE_ERROR가 반환된다.

설명#

이 함수는 명령문 핸들의 준비된 문장 (prepared statement)의 수행으로 생성된 결과 집합을 위해 할당된 자원을 해제한다.

예제#

altibase_stmt_bind_result()과 altibase_stmt_data_seek()의 예제를 참고하라.

altibase_stmt_get_attr()#

현재 명령문 핸들에 설정되어 있는 속성 값을 구하는 함수이다.

구문#

int  altibase_stmt_get_attr (
    ALTIBASE_STMT               stmt,
    ALTIBASE_STMT_ATTR_TYPE     option,
    void *                      arg );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들
ALTIBASE_STMT_ATTR_TYPE option 입력 속성
void * arg 입력 속성 값을 가져올 버퍼

반환 값#

함수 수행이 성공하면 ALTIBASE_SUCCESS, 그렇지 않으면 ALTIBASE_ERROR가 반환된다.

설명#

이 함수는 현재 명령문 핸들에 설정되어 있는 특정 속성 값을 반환한다.

클라이언트 라이브러리는 arg 버퍼의 크기가 충분히 크다고 간주하므로, 사용자는 얻고자 하는 속성 값이 가질 수 있는 최대 크기의 버퍼를 인자로 전달해야 한다.

명령문 속성에 대한 자세한 내용은 2장의 "enum ALTIBASE_STMT_ATTR_TYPE"을 참고하라.

예제#

altibase_stmt_set_attr()의 예제를 참고하라.

altibase_stmt_init()#

명령문 핸들을 생성하는 함수이다.

구문#

ALTIBASE_STMT  altibase_stmt_init (
    ALTIBASE  altibase );

인자#

자료유형 인자 입/출력 설명
ALTIBASE altibase 입력 연결 핸들

반환 값#

함수 수행이 성공하면 명령문 핸들이 반환되고, 실패하면 NULL이 반환된다.

설명#

이 함수는 입력된 연결 핸들에 속하는 명령문 핸들을 생성하여 반환한다.

명령문 핸들의 사용이 완료되면, 반드시 altibase_stmt_close()를 이용해서 이를 해제해야 한다.

예제#

stmt = altibase_stmt_init(altibase);
if (stmt == NULL)
{
    /* ... error handling ... */
}

/* ... omit ... */

rc = altibase_stmt_close(stmt);
if (! ALTIBASE_SUCCEEDE(rc))
{
    /* ... error handling ... */
}

altibase_stmt_next_result()#

다음 결과 집합에 접근하기 위해 사용되는 함수이다.

구문#

int altibase_stmt_next_result ( ALTIBASE_STMT stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

반환 값 설명
ALTIBASE_SUCCESS 다음 결과 집합이 존재함
ALTIBASE_NO_DATA 다음 결과 집합이 존재하지 않음
ALTIBASE_ERROR 에러 발생

설명#

이 함수는 이전에 준비된 문장(prepared statement)을 사용하여 여러 결과 집합을 가져오는 명령을 수행한 경우, 다음 결과 집합에 접근하기 위해 사용한다.

이전에 가져온 결과 집합이 있다면, altibase_stmt_next_result()를 호출하기 전에 altibase_stmt_free_result()로 그 결과 집합을 먼저 해제해야 한다.

이 함수를 수행하면 altibase_stmt_execute()를 수행한 것과 같은 상태가 된다. 이는 altibase_stmt_bind_result(), altibase_stmt_affected_rows() 등의 함수를 호출할 수 있음을 의미한다.

예제#

sRC = altibase_stmt_prepare(sStmt, "EXEC PROC_RESULTSET");
/* ... omit ... */
sRC = altibase_stmt_execute(sStmt);
/* ... check return value ... */
while (1)
{
    sFieldCount = altibase_stmt_field_count(sStmt);

    sRC = altibase_stmt_bind_result(sStmt, bind);
    /* ... check return value ... */

    while ((sRC = altibase_stmt_fetch(sStmt)) != ALTIBASE_NO_DATA)
    {
        /* ... check return value ... */
        for (i = 0; i < sFieldCount; i++)
        {
            /* ... omit ... */
        }
    }
    sRC = altibase_stmt_free_result(sStmt);
    /* ... check return value ... */
    sRC = altibase_stmt_next_result(sStmt);

    if (sRC == ALTIBASE_NO_DATA)
    {
        break;
    }
    CDBC_TEST_RAISE(ALTIBASE_NOT_SUCCEEDED(sRC), stmt_error);
}

altibase_stmt_num_rows()#

결과 집합의 행의 개수를 구하는 함수이다.

구문#

ALTIBASE_LONG altibase_stmt_num_rows (
    ALTIBASE_STMT stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

결과 집합의 행의 개수가 반환된다.

설명#

이 함수는 결과 집합의 행의 개수를 반환한다.

결과 집합을 가져온 함수가 altibase_store_result()였는지, 아니면 altibase_use_result()였는지에 따라서 이 함수의 결과는 달라진다. 만약 altibase_store_result()가 사용되었다면, 결과 집합에 포함된 전체 레코드의 개수가 정확하게 반환된다. 하지만 altibase_use_result()가 사용되었다면, 전체 레코드가 모두 fetch 되기 전까지는 정확한 레코드 수가 반환되지 않을 것이다.

INSERT, UPDATE, 또는 DELETE 문 수행으로 인해 변경된 행의 개수를 구하려면 altibase_stmt_affected_rows()를 사용하라.

예제#

altibase_stmt_data_seek()의 예제를 참고하라.

altibase_stmt_param_count()#

준비된 문장 (prepared statement) 내의 파라미터 마커 개수를 구하는 함수이다.

구문#

int  altibase_stmt_param_count (
    ALTIBASE_STMT  stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

함수 수행이 성공하면 파라미터 마커의 개수가 반환되고, 실패하면 ALTIBASE_INVALID_PARAMCOUNT가 반환된다.

설명#

이 함수는 준비된 문장 (prepared statement) 내의 파라미터 마커의 개수를 반환한다. SQL 문에 파라미터 마커가 없었다면 0이 반환될 것이다.

이 함수는 altibase_stmt_prepare() 호출 후에 사용해야 한다.

예제#

altibase_stmt_prepare()의 예제를 참고하라.

altibase_stmt_prepare()#

SQL 문장의 실행을 준비하는 함수이다.

구문#

int  altibase_stmt_prepare (
    ALTIBASE_STMT       stmt,
    const char *        qstr );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들
const char * qstr 입력 SQL 문 (널 종료 문자열이어야 한다)

반환 값#

함수 수행이 성공하면 ALTIBASE_SUCCESS, 실패하면 ALTIBASE_ERROR가 반환된다.

설명#

이 함수는 SQL 문장의 실행을 준비한다.

SQL 문은 반드시 널 종료 문자열이여야 하며, 한 개의 SQL 문이어야 한다. 세미콜론(;)으로 연결된 다중 SQL 문은 지원되지 않는다. 다중 SQL 명령문을 실행하려면 저장 프로시저를 활용하라.

SQL 문은 한 개 이상의 파라미터 마커를 포함할 수 있다. 물음표(?)가 파라미터 마커로 사용된다. SQL 문에 파라미터 마커가 포함되어 있으면, altibase_stmt_execute()을 수행하기 전에 반드시 altibase_stmt_bind_param()을 사용해서 파라미터 마커에 대한 바인딩을 해야 한다.

한 번 준비된 문장은 다른 SQL 문을 이 준비된 문장의 명령문 핸들을 사용해서 altibase_stmt_prepare()을 수행하거나, altibase_stmt_close() 또는 altibase_close()를 호출해서 관련된 핸들이 해제되기 전까지 유효하다.

altibase_stmt_prepare()가 수행되면 명령문 핸들과 관련된 이전의 정보가 모두 초기화 된다. 즉, 이전에 설정된 바인딩 정보와 array 관련 정보가 모두 사라진다. 그러므로 필요하다면 새로운 SQL 문을 위한 바인딩 정보와 array 관련 정보를 다시 설정해야 한다.

데이터만 다른 동일한 구조의 SQL 문을 여러 번 수행하는 경우, altibase_stmt_prepare(), altibase_stmt_bind_param() 및 altibase_stmt_execute()을 사용하면 altibase_query()로 SQL 문을 매번 실행하는 것보다 나은 성능을 기대할 수 있다.

예제#

rc = altibase_stmt_prepare(stmt, qstr);
if (ALTIBASE_NOT_SUCCEEDED(rc))
{
    /* ... error handling ... */
}

printf("field count : %d\n", altibase_stmt_param_count(stmt));
printf("field count : %d\n", altibase_stmt_field_count(stmt));

altibase_stmt_processed()#

입력 바인딩된 배열의 요소 중 처리된 개수를 구하는 함수이다.

구문#

ALTIBASE_LONG  altibase_stmt_processed (
    ALTIBASE_STMT  stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

처리된 배열 요소의 개수가 반환된다. 오류가 발생하면 ALTIBASE_INVALID_PROCESSED가 반환된다.

설명#

이 함수는 배열 변수를 입력 바인딩에 사용 (이를 array binding이라고 함)했을 때, 배열의 요소 중 처리된 요소의 개수를 반환한다. 정상적으로 수행되었을 경우, 반환 값은 바인딩한 배열의 크기와 동일할 것이다.

이 함수는 array binding을 했을 경우에만 사용될 수 있다.

예제#

5장의 array binding을 참고하라.

altibase_stmt_reset()#

명령문 핸들에 설정된 정보를 초기화하는 함수이다.

구문#

int  altibase_stmt_reset (
    ALTIBASE_STMT  stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

함수 수행이 성공하면 ALTIBASE_SUCCESS, 실패하면 ALTIBASE_ERROR가 반환된다.

설명#

이 함수는 명령문 핸들에 설정된 정보를 초기화한다. 즉, 이 함수가 수행되면 이전에 설정된 바인딩 정보와 array 관련 설정이 모두 사라진다. 그러나 prepare 된 상태는 그대로 유지된다.

그러므로 필요하다면 새로운 SQL 문을 위한 바인딩 정보와 array fetch 관련 정보를 다시 설정해야 한다.

결과 집합을 가져와서 사용중이라면, 반드시 이 함수를 사용하기 전에 altibase_stmt_free_result()를 먼저 호출해야 한다. 그렇지 않고 이 함수를 호출하면 에러가 반환된다.

altibase_stmt_result_metadata()#

altibase_stmt_prepare()로 서버에 전달한 SQL 문이 결과 집합을 생성하는 구문이라면, 이 함수는 결과 집합의 메타 데이터를 반환한다.

구문#

ALTIBASE_RES  altibase_stmt_result_metadata (
    ALTIBASE_RES  stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

메타 데이터를 담고 있는 결과 집합의 핸들이 반환된다. 오류가 발생하면 NULL이 반환된다.

설명#

altibase_stmt_prepare()로 준비한 문장이 SELECT문처럼 결과 집합을 생성하는 구문일 경우, 이 함수는 결과 집합의 칼럼 정보를 담고 있는 결과 집합의 핸들을 반환한다.

다음 함수들의 인자로 이 함수가 반환한 결과 집합 핸들을 전달하면, 여러 칼럼 정보를 얻을 수 있다.

  • altibase_num_fields()

  • altibase_field()

  • altibase_fields()

이 함수가 반환한 결과 집합은 반드시 altibase_free_result()를 이용해서 해제되어야 한다.

altibase_stmt_send_long_data()#

이 함수는 현재 지원되지 않는다.

altibase_stmt_set_array_bind()#

array binding을 하고자 할 경우, 배열의 크기를 설정하는 함수이다.

구문#

int  altibase_stmt_set_array_bind (
    ALTIBASE_ STMT     stmt,
    int                array_size );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들
int array_size 입력 바인딩할 배열의 크기

반환 값#

함수 수행이 성공하면 ALTIBASE_SUCCESS, 실패하면 ALTIBASE_ERROR가 반환된다.

설명#

이 함수는 array binding을 하고자 할 경우, 배열의 크기를 설정하는 데 사용된다. array_size의 값이 1보다 클 때에만 array binding을 하는 것으로 설정된다. Array binding을 해제하려면 array_size의 값을 1로 전달하라.

설정된 array binding 정보는 altibase_stmt_reset(), altibase_stmt_prepare() 또는 altibase_stmt_close()가 호출되기 전까지 유효하다.

이 함수는 altibase_stmt_prepare()가 호출된 후 altibase_stmt_bind_param()이 호출되기 전에 사용되어야 한다.

예제#

5장의 array binding을 참고하라.

altibase_stmt_set_array_fetch()#

array fetch를 하고자 할 경우, 배열의 크기를 설정하는 함수이다.

구문#

int  altibase_stmt_set_array_fetch (
    ALTIBASE_ STMT     stmt,
    int                array_size );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들
int array_size 입력 바인딩할 배열의 크기

반환 값#

함수 수행이 성공하면 ALTIBASE_SUCCESS, 실패하면 ALTIBASE_ERROR가 반환된다.

설명#

이 함수는 array fetch를 하고자 할 경우, 배열의 크기를 설정하는 데 사용된다. array_size의 값이 1보다 클 때에만 array fetch를 하는 것으로 설정된다. Array fetch를 해제하려면 array_size의 값을 1로 전달한다.

설정된 array fetch 정보는 altibase_stmt_reset(), altibase_stmt_prepare() 또는 altibase_stmt_close()가 호출되기 전까지 유효하다.

이 함수는 altibase_stmt_prepare()가 호출된 후 altibase_stmt_bind_result()가 호출되기 전에 사용되어야 한다.

예제#

5장의 array fetch를 참고하라.

altibase_stmt_set_attr()#

명령문 핸들에 속성 값을 설정하는 함수이다.

구문#

int  altibase_stmt_bind_result (
    ALTIBASE_STMT               stmt,
    ALTIBASE_STMT_ATTR_TYPE     option,
    void *                      arg );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들
ALTIBASE_STMT_ATTR_TYPE option 입력 속성
void * arg 입력 지정할 속성 값이 저장된 버퍼

반환 값#

함수 수행이 성공하면 ALTIBASE_SUCCESS, 실패하면 ALTIBASE_ERROR가 반환된다.

설명#

한번 설정된 명령문 속성은 altibase_stmt_set_attr()을 이용해서 같은 속성을 다시 설정하거나 altibase_stmt_close() 또는 altibase_close()로 핸들이 해제될 때까지 유효하다.

명령문 속성에 대한 자세한 내용은 2장의 "enum ALTIBASE_STMT_ATTR_TYPE"을 참고하라.

예제#

int atomic_array = ALTIBASE_ATOMIC_ARRAY_ON;

rc = altibase_stmt_set_attr(stmt, ALTIBASE_STMT_ATTR_ATOMIC_ARRAY,
                            (void*)atomic_array);
/* ... check return value ... */

rc = altibase_stmt_get_attr(stmt, ALTIBASE_STMT_ATTR_ATOMIC_ARRAY,
                            &atomic_array);
/* ... check return value ... */

printf("Atomic array : %d\n", atomic_array);

altibase_stmt_sqlstate()#

바로 이전에 실행된 SQL 명령문에 대한 SQLSTATE를 구하는 함수이다.

구문#

const char *  altibase_stmt_sqlstate (
    ALTIBASE_STMT  stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

SQLSTATE 에러 코드를 나타내는 널 종료 문자열이 반환된다.

설명#

이 함수는 가장 최근에 실행된 SQL 명령문에 대한 SQLSTATE 에러 코드를 나타내는 널 종료 문자열을 반환한다.

SQLSTATE는 5개의 문자로 이루어진다. 대표적으로 "00000"은 "에러 없음"을 나타낸다. SQLSTATE에 대한 자세한 내용은 Error Message Reference를 참고한다.

SQLSTATE는 altibase_errno()가 반환하는 값과는 다르다. 에러 정보를 확인해서 처리해야 할 루틴이 있다면 SQLSTATE 값을 사용할 것을 권장한다. 일반적으로 altibase_errno()의 반환 값을 확인해서 에러 처리 루틴을 작성하는 것을 권장하지 않는다.

SQLSTATE와 altibase_errno()의 반환 값은 1:1로 맵핑되지 않는다. 그러므로 altibase_stmt_errno()의 반환 값을 보고 SQLSTATE를 추측하거나, SQLSTATE를 이용해서 altibase_stmt_errno()의 반환 값을 추측해서는 안된다.

어떤 함수 수행시 오류가 발생한 경우 바로 오류를 확인하지 않고 다른 함수를 호출하면, 이 오류에 대한 정보가 사라진다. 따라서 오류 발생시 바로 이 함수를 사용해서 오류 정보를 확인해야 한다.

이 함수가 반환한 char 포인터가 가리키는 메모리는 라이브러리 내부에서 관리되므로 절대로 사용자가 임의로 변경하거나 해제해서는 안 된다.

예제#

altibase_stmt_errno()의 예제를 참고하라.

altibase_stmt_status()#

array binding 또는 array fetch 수행의 결과를 얻는 함수이다.

구문#

unsigned short *  altibase_stmt_status (
    ALTIBASE_STMT  stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

array binding 또는 array fetch 수행의 결과를 담은 배열이 반환된다.

설명#

이 함수는 fetch 수행 여부에 따라서 array binding 또는 array fetch의 결과를 반환한다. Array binding 또는 array fetch 사용을 설정했을 때만 이 함수가 사용될 수 있다.

결과 집합을 가져오기 전이라면, 이 함수는 array binding의 결과를 반환한다. 이 함수가 반환한 배열에는 바인딩된 배열의 각 요소 값을 사용해서 SQL 문을 수행한 결과가 저장되어 있는데, 그 상태값은 다음의 값들 중 하나일 것이다.

반환 값 설명
ALTIBASE_PARAM_SUCCESS 성공적으로 수행됨
ALTIBASE_PARAM_SUCCESS_WITH_INFO 성공적으로 수행되었으나, 경고가 발생했음
ALTIBASE_PARAM_ERROR 파라미터 변수의 값으로 수행시 오류가 발생함
ALTIBASE_PARAM_UNUSED 이 파라미터 변수의 값은 사용되지 않음. 아마도 이전 파라미터 값으로 수행시 오류가 발생되어 이후 진행이 중단됨.

결과 집합을 가져온 후이면, 이 함수는 array fetch의 결과를 반환한다. 이 함수가 반환한 배열에는 결과 집합의 각 행을 바인딩된 배열 변수에 fetch한 결과가 저장되어 있는데, 그 상태값은 다음의 값들 중 하나일 것이다.

반환 값 설명
ALTIBASE_ROW_SUCCESS 성공적으로 가져옴
ALTIBASE_ROW_SUCCESS_WITH_INFO 성공적으로 fetch 되었으나, 경고가 발생했음
ALTIBASE_ROW_NOROW Fetch된 행의 개수가 바인딩된 배열의 크기보다 작을 때, 이 상태 값은 사용되지 않은 배열 요소임을 나타냄
ALTIBASE_ROW_ERROR Fetch할 때 오류가 발생함

이 함수가 반환한 포인터가 가리키는 메모리는 라이브러리 내부에서 관리되므로 절대로 사용자가 임의로 변경하거나 해제해서는 안 된다.

예제#

5장의 array binding과 array fetch를 참고하라.

altibase_stmt_store_result()#

질의 수행에 대한 결과 집합 전체를 가져오는 함수이다.

구문#

int  altibase_stmt_store_result (
    ALTIBASE_STMT  stmt );

인자#

자료유형 인자 입/출력 설명
ALTIBASE_STMT stmt 입력 명령문 핸들

반환 값#

함수 수행이 성공하면 ALTIBASE_SUCCESS, 실패하면 ALTIBASE_ERROR가 반환된다.

설명#

이 함수는 질의 수행의 전체 결과 집합을 가져온다.

이 함수를 수행하면 질의 수행 결과를 서버로부터 모두 가져와서 클라이언트에 저장해 둔다. 이 함수 호출 후 altibase_stmt_fetch()를 호출할 때는 이미 서버로부터 모든 결과 집합을 받아온 상태이므로 서버와 통신하지 않으며, 받아둔 결과 집합의 데이터가 반환된다.

이 함수 수행시에는 모든 결과 집합을 받아두므로 LOB이나 GEOMETRY와 같은 대용량 칼럼이 포함되어 있거나 결과 행의 개수가 많다면, 메모리가 과다하게 사용될 수 있으므로 이 함수를 쓸 때는 주의가 필요하다.

altibase_stmt_bind_result() 호출 후 altibase_stmt_fetch() 호출 전에 altibase_stmt_store_result()가 수행되어야 한다.

altibase_stmt_store_result() 사용 후에 다음과 같은 함수를 추가로 사용할 수 있다:

  • altibase_stmt_num_rows()

  • altibase_stmt_data_seek()

이 함수를 통해 얻은 결과 집합은 사용이 끝난 후에 altibase_stmt_free_result()를 이용해서 해제해야 한다.

예제#

altibase_stmt_bind_result()와 altibase_stmt_data_seek()의 예제를 참고하라.