CCI 드라이버¶

CCI 개요¶

CCI(C Client Interface)는 CUBRID 브로커와 응용 클라이언트 사이에 위치하여, C 기반의 응용 클라이언트가 브로커를 통해 CUBRID 데이터베이스 서버로 접근할 수 있는 인터페이스로서, 브로커 응용 서버(CAS)를 이용하는 도구(예: PHP, ODBC)를 만들기 위한 하부 구조로도 사용된다. 여기서, CUBRID 브로커는 응용 클라이언트로부터 받은 질의를 데이터베이스에 전달하고, 실행 결과를 응용 클라이언트로 전송하는 역할을 수행한다.

CCI를 사용하기 위해서는 헤더 파일과 라이브러리 파일이 필요하다.

CCI 드라이버는 CUBRID에서 제공되는 C 언어 인터페이스로, CUBRID 설치 패키지에 포함되어 있다. CCI는 브로커를 통해서 접속하므로 다른 인터페이스인 JDBC, PHP, ODBC, Python, Ruby 등과 동일하게 관리될 수 있다. 실제로 PHP, ODBC, Python, Ruby 인터페이스는 CCI를 기반으로 개발되었다. 단, JDBC는 CCI를 기반으로 개발되지 않았다.

별도로 CCI 드라이버를 다운로드하거나 CCI 드라이버에 대한 최신 정보를 확인하려면 http://www.cubrid.org/wiki_apis/entry/cubrid-cci-driver 에 접속한다.

CCI 프로그래밍¶

// Example to execute a simple query
// In Linux: gcc -o simple simple.c -m64 -I${CUBRID}/include -lnsl ${CUBRID}/lib/libcascci.so -lpthread

#include <stdio.h>
#include "cas_cci.h"
#define BUFSIZE  (1024)

int
main (void)
{
    int con = 0, req = 0, col_count = 0, i, ind;
    int error;
    char *data;
    T_CCI_ERROR cci_error;
    T_CCI_COL_INFO *col_info;
    T_CCI_CUBRID_STMT stmt_type;
    char *query = "select * from code";

    //getting a connection handle for a connection with a server
    con = cci_connect ("localhost", 33000, "demodb", "dba", "");
    if (con < 0)
    {
        printf ("cannot connect to database\n");
        return 1;
    }

    //preparing the SQL statement
    req = cci_prepare (con, query, 0, &cci_error);
    if (req < 0)
    {
        printf ("prepare error: %d, %s\n", cci_error.err_code,
                cci_error.err_msg);
        goto handle_error;
    }

    //getting column information when the prepared statement is the SELECT query
    col_info = cci_get_result_info (req, &stmt_type, &col_count);
    if (col_info == NULL)
    {
        printf ("get_result_info error: %d, %s\n", cci_error.err_code,
                cci_error.err_msg);
        goto handle_error;
    }

    //Executing the prepared SQL statement
    error = cci_execute (req, 0, 0, &cci_error);
    if (error < 0)
    {
        printf ("execute error: %d, %s\n", cci_error.err_code,
                cci_error.err_msg);
        goto handle_error;
    }
    while (1)
    {

        //Moving the cursor to access a specific tuple of results
        error = cci_cursor (req, 1, CCI_CURSOR_CURRENT, &cci_error);
        if (error == CCI_ER_NO_MORE_DATA)
        {
            break;
        }
        if (error < 0)
        {
            printf ("cursor error: %d, %s\n", cci_error.err_code,
                    cci_error.err_msg);
            goto handle_error;
        }

        //Fetching the query result into a client buffer
        error = cci_fetch (req, &cci_error);
        if (error < 0)
        {
            printf ("fetch error: %d, %s\n", cci_error.err_code,
                    cci_error.err_msg);
            goto handle_error;
        }
        for (i = 1; i <= col_count; i++)
        {

            //Getting data from the fetched result
            error = cci_get_data (req, i, CCI_A_TYPE_STR, &data, &ind);
            if (error < 0)
            {
                printf ("get_data error: %d, %d\n", error, i);
                goto handle_error;
            }
            printf ("%s\t|", data);
        }
        printf ("\n");
    }

    //Closing the request handle
    error = cci_close_req_handle (req);
    if (error < 0)
    {
        printf ("close_req_handle error: %d, %s\n", cci_error.err_code,
                cci_error.err_msg);
        goto handle_error;
    }

    //Disconnecting with the server
    error = cci_disconnect (con, &cci_error);
    if (error < 0)
    {
        printf ("error: %d, %s\n", cci_error.err_code, cci_error.err_msg);
        goto handle_error;
    }

    return 0;

handle_error:
    if (req > 0)
        cci_close_req_handle (req);
    if (con > 0)
    cci_disconnect (con, &cci_error);

    return 1;
}

// Example to execute a query with a bind variable
// In Linux: gcc -o cci_bind cci_bind.c -m64 -I${CUBRID}/include -lnsl ${CUBRID}/lib/libcascci.so -lpthread

#include <stdio.h>
#include <string.h>
#include "cas_cci.h"
#define BUFSIZE  (1024)

int
main (void)
{
    int con = 0, req = 0, col_count = 0, i, ind;
    int error;
    char *data;
    T_CCI_ERROR cci_error;
    T_CCI_COL_INFO *col_info;
    T_CCI_CUBRID_STMT stmt_type;
    char *query = "select * from nation where name = ?";
    char namebuf[128];

    //getting a connection handle for a connection with a server
    con = cci_connect ("localhost", 33000, "demodb", "dba", "");
    if (con < 0)
    {
        printf ("cannot connect to database\n");
        return 1;
    }

    //preparing the SQL statement
    req = cci_prepare (con, query, 0, &cci_error);
    if (req < 0)
    {
        printf ("prepare error: %d, %s\n", cci_error.err_code,
              cci_error.err_msg);
        goto handle_error;
    }

    //Binding date into a value
    strcpy (namebuf, "Korea");
    error =
    cci_bind_param (req, 1, CCI_A_TYPE_STR, namebuf, CCI_U_TYPE_STRING,
                    CCI_BIND_PTR);
    if (error < 0)
    {
        printf ("bind_param error: %d ", error);
        goto handle_error;
    }

    //getting column information when the prepared statement is the SELECT query
    col_info = cci_get_result_info (req, &stmt_type, &col_count);
    if (col_info == NULL)
    {
        printf ("get_result_info error: %d, %s\n", cci_error.err_code,
              cci_error.err_msg);
        goto handle_error;
    }

    //Executing the prepared SQL statement
    error = cci_execute (req, 0, 0, &cci_error);
    if (error < 0)
    {
        printf ("execute error: %d, %s\n", cci_error.err_code,
              cci_error.err_msg);
        goto handle_error;
    }

    //Executing the prepared SQL statement
    error = cci_execute (req, 0, 0, &cci_error);
    if (error < 0)
    {
        printf ("execute error: %d, %s\n", cci_error.err_code,
              cci_error.err_msg);
        goto handle_error;
    }

    while (1)
    {

        //Moving the cursor to access a specific tuple of results
        error = cci_cursor (req, 1, CCI_CURSOR_CURRENT, &cci_error);
        if (error == CCI_ER_NO_MORE_DATA)
        {
            break;
        }
        if (error < 0)
        {
            printf ("cursor error: %d, %s\n", cci_error.err_code,
                  cci_error.err_msg);
            goto handle_error;
        }

        //Fetching the query result into a client buffer
        error = cci_fetch (req, &cci_error);
        if (error < 0)
        {
            printf ("fetch error: %d, %s\n", cci_error.err_code,
                  cci_error.err_msg);
            goto handle_error;
        }
        for (i = 1; i <= col_count; i++)
        {

            //Getting data from the fetched result
            error = cci_get_data (req, i, CCI_A_TYPE_STR, &data, &ind);
            if (error < 0)
            {
                printf ("get_data error: %d, %d\n", error, i);
                goto handle_error;
            }
            if (ind == -1)
            {
                printf ("NULL\t");
            }
            else
            {
                printf ("%s\t|", data);
            }
        }
            printf ("\n");
    }

    //Closing the request handle
    error = cci_close_req_handle (req);
    if (error < 0)
    {
        printf ("close_req_handle error: %d, %s\n", cci_error.err_code,
                cci_error.err_msg);
        goto handle_error;
    }

    //Disconnecting with the server
    error = cci_disconnect (con, &cci_error);
    if (error < 0)
    {
        printf ("error: %d, %s\n", cci_error.err_code, cci_error.err_msg);
        goto handle_error;
    }

    return 0;

handle_error:
    if (req > 0)
        cci_close_req_handle (req);
    if (con > 0)
        cci_disconnect (con, &cci_error);
    return 1;
}

// Example to use connection/statement pool in CCI
// In Linux: gcc -o cci_pool cci_pool.c -m64 -I${CUBRID}/include -lnsl ${CUBRID}/lib/libcascci.so -lpthread

#include <stdio.h>
#include "cas_cci.h"

int main ()
{
    T_CCI_PROPERTIES *ps = NULL;
    T_CCI_DATASOURCE *ds = NULL;
    T_CCI_ERROR err;
    T_CCI_CONN cons;
    int rc = 1, i;

    ps = cci_property_create ();
    if (ps == NULL)
    {
        fprintf (stderr, "Could not create T_CCI_PROPERTIES.\n");
        rc = 0;
        goto cci_pool_end;
    }

    cci_property_set (ps, "user", "dba");
    cci_property_set (ps, "url", "cci:cubrid:localhost:33000:demodb:::");
    cci_property_set (ps, "pool_size", "10");
    cci_property_set (ps, "max_wait", "1200");
    cci_property_set (ps, "pool_prepared_statement", "true");
    cci_property_set (ps, "login_timeout", "300000");
    cci_property_set (ps, "query_timeout", "3000");

    ds = cci_datasource_create (ps, &err);
    if (ds == NULL)
    {
        fprintf (stderr, "Could not create T_CCI_DATASOURCE.\n");
        fprintf (stderr, "E[%d,%s]\n", err.err_code, err.err_msg);
        rc = 0;
        goto cci_pool_end;
    }

    for (i = 0; i < 3; i++)
    {
        cons = cci_datasource_borrow (ds, &err);
        if (cons < 0)
        {
            fprintf (stderr,
                    "Could not borrow a connection from the data source.\n");
            fprintf (stderr, "E[%d,%s]\n", err.err_code, err.err_msg);
            continue;
        }
        // put working code here.
        cci_work (cons);
        cci_datasource_release (ds, cons, &err);

    }

cci_pool_end:
  cci_property_destroy (ps);
  cci_datasource_destroy (ds);

  return 0;
}

// working code
int cci_work (T_CCI_CONN con)
{
    T_CCI_ERROR err;
    char sql[4096];
    int req, res, error, ind;
    int data;

    cci_set_autocommit (con, CCI_AUTOCOMMIT_TRUE);
    cci_set_lock_timeout (con, 100, &err);
    cci_set_isolation_level (con, TRAN_REP_CLASS_COMMIT_INSTANCE, &err);

    error = 0;
    snprintf (sql, 4096, "SELECT host_year FROM record WHERE athlete_code=11744");
    req = cci_prepare (con, sql, 0, &err);
    if (req < 0)
    {
        printf ("prepare error: %d, %s\n", err.err_code, err.err_msg);
        return error;
    }

    res = cci_execute (req, 0, 0, &err);
    if (res < 0)
    {
        printf ("execute error: %d, %s\n", err.err_code, err.err_msg);
        goto cci_work_end;
    }

    while (1)
    {
    error = cci_cursor (req, 1, CCI_CURSOR_CURRENT, &err);
    if (error == CCI_ER_NO_MORE_DATA)
    {
        break;
    }
    if (error < 0)
    {
        printf ("cursor error: %d, %s\n", err.err_code, err.err_msg);
        goto cci_work_end;
    }

    error = cci_fetch (req, &err);
    if (error < 0)
    {
        printf ("fetch error: %d, %s\n", err.err_code, err.err_msg);
        goto cci_work_end;
    }

    error = cci_get_data (req, 1, CCI_A_TYPE_INT, &data, &ind);
    if (error < 0)
    {
        printf ("get data error: %d\n", error);
        goto cci_work_end;
    }
    printf ("%d\n", data);
    }

    error = 1;
cci_work_end:
    cci_close_req_handle (req);
    return error;
}

라이브러리 적용¶

CCI를 이용한 응용 프로그램을 작성했다면 프로그램 특성에 따라 정적 링크 형태로 프로그램을 수행시킬 것인지, 아니면 동적으로 CCI를 호출하여 사용할 것인지를 결정하여 프로그램을 빌드한다. CCI 개요 의 표를 참조하여 사용할 라이브러리를 결정한다.

다음은 유닉스/Linux에서 동적인 라이브러리를 사용하여 링크하는 Makefile의 예제이다.

CC=gcc
CFLAGS = -g -Wall -I. -I$CUBRID/include
LDFLAGS = -L$CUBRID/lib -lcascci -lnsl
TEST_OBJS = test.o
EXES = test
all: $(EXES)
test: $(TEST_OBJS)
    $(CC) -o $@ $(TEST_OBJS) $(LDFLAGS)

다음은 Windows에서 정적 라이브러리를 적용하기 위한 설정이다.

int con = 0; /* connection handle */
int req = 0; /* request handle */
int res;
int n_executed;
int i;
T_CCI_ERROR error;
T_CCI_BLOB blob = NULL;
char data[1024] = "bulabula";

con = cci_connect ("localhost", 33000, "tdb", "PUBLIC", "");
if (con < 0) {
    goto handle_error;
}
req = cci_prepare (con, "insert into doc (doc_id, content) values (?,?)", 0, &error);
if (req< 0)
{
    goto handle_error;
}

res = cci_bind_param (req, 1 /* binding index*/, CCI_A_TYPE_STR, "doc-10", CCI_U_TYPE_STRING, CCI_BIND_PTR);

/* Creating an empty LOB data file */
res = cci_blob_new (con, &blob, &error);
res = cci_blob_write (con, blob, 0 /* start position */, 1024 /* length */, data, &error);

/* Binding BLOB data */
res = cci_bind_param (req, 2 /* binding index*/, CCI_A_TYPE_BLOB, (void *)blob, CCI_U_TYPE_BLOB, CCI_BIND_PTR);

n_executed = cci_execute (req, 0, 0, &error);
if (n_executed < 0)
{
    goto handle_error;
}

/* Commit */
if (cci_end_tran(con, CCI_TRAN_COMMIT, &error) < 0)
{
    goto handle_error;
}

/* Memory free */
cci_blob_free(blob);
return 0;

handle_error:
if (blob != NULL)
{
    cci_blob_free(blob);
}
if (req > 0)
{
    cci_close_req_handle (req);
}
if (con > 0)
{
    cci_disconnect(con, &error);
}
return -1;

int con = 0; /* connection handle */
int req = 0; /* request handle */
int ind; /* NULL indicator, 0 if not NULL, -1 if NULL*/
int res;
int i;
T_CCI_ERROR error;
T_CCI_BLOB blob;
char buffer[1024];

con = cci_connect ("localhost", 33000, "image_db", "PUBLIC", "");
if (con < 0)
{
    goto handle_error;
}
req = cci_prepare (con, "select content from doc_t", 0 /*flag*/, &error);
if (req< 0)
{
    goto handle_error;
}

res = cci_execute (req, 0/*flag*/, 0/*max_col_size*/, &error);

while (1) {
    res = cci_cursor (req, 1/* offset */, CCI_CURSOR_CURRENT/* cursor position */, &error);
    if (res == CCI_ER_NO_MORE_DATA)
    {
        break;
    }
    res = cci_fetch (req, &error);

    /* Fetching CLOB Locator */
    res = cci_get_data (req, 1 /* colume index */, CCI_A_TYPE_BLOB,
    (void *)&blob /* BLOB handle */, &ind /* NULL indicator */);
    /* Fetching CLOB data */
    res = cci_blob_read (con, blob, 0 /* start position */, 1024 /* length */, buffer, &error);
    printf ("content = %s\n", buffer);
}

/* Memory free */
cci_blob_free(blob);
res=cci_close_req_handle(req);
res = cci_disconnect (con, &error);
return 0;

handle_error:
if (req > 0)
{
    cci_close_req_handle (req);
}
if (con > 0)
{
    cci_disconnect(con, &error);
}
return -1;

// gcc -o err err.c -m64 -I${CUBRID}/include -lnsl ${CUBRID}/lib/libcascci.so -lpthread
#include <stdio.h>
#include "cas_cci.h"

#define BUFSIZE  (1024)

int
main (void)
{
    int con = 0, req = 0, col_count = 0, i, ind;
    int error;
    char *data;
    T_CCI_ERROR err_buf;
    char *query = "select * from notable";

    //getting a connection handle for a connection with a server
    con = cci_connect ("localhost", 33000, "demodb", "dba", "");
    if (con < 0)
    {
        printf ("cannot connect to database\n");
        return 1;
    }

    //preparing the SQL statement
    req = cci_prepare (con, query, 0, &err_buf);
    if (req < 0)
    {
        if (req == CCI_ER_DBMS)
        {
            printf ("error from server: %d, %s\n", err_buf.err_code, err_buf.err_msg);
        }
        else
        {
            printf ("error from cci or cas: %d, %s\n", err_buf.err_code, err_buf.err_msg);
        }
        goto handle_error;
    }
    // ...
}

CCI 예제 프로그램¶

예제 프로그램은 CUBRID 설치 과정에서 기본적으로 배포되는 데이터베이스인 demodb 를 활용하여 CCI를 사용하는 응용 프로그램을 간단하게 작성한 것이다. 예제를 통하여 CAS와 연결하기, 질의 준비, 질의 수행, 응답 처리, 연결 끊기 등의 과정을 따라한다. 예제는 Linux 기반의 동적 링크를 적용하는 방법으로 작성되었다.

다음은 예제에서 사용하는 demodb 데이터베이스의 olympic 테이블의 스키마 정보이다.

csql> ;sc olympic

=== <Help: Schema of a Class> ===


 <Class Name>

     olympic

 <Attributes>

     host_year            INTEGER NOT NULL
     host_nation          CHARACTER VARYING(40) NOT NULL
     host_city            CHARACTER VARYING(20) NOT NULL
     opening_date         DATE NOT NULL
     closing_date         DATE NOT NULL
     mascot               CHARACTER VARYING(20)
     slogan               CHARACTER VARYING(40)
     introduction         CHARACTER VARYING(1500)

 <Constraints>

     PRIMARY KEY pk_olympic_host_year ON olympic (host_year)

준비

예제 프로그램을 수행하기 전에 반드시 확인해야 할 사항은 demodb 데이터베이스와 브로커의 가동 여부이다. demodb 데이터베이스와 브로커는 cubrid 유틸리티를 이용하여 시작할 수 있다. 다음은 cubrid 유틸리티를 이용하여 데이터베이스 서버와 브로커를 가동하는 예제이다.

[tester@testdb ~]$ cubrid server start demodb
@ cubrid master start
++ cubrid master start: success
@ cubrid server start: demodb

This may take a long time depending on the amount of recovery works to do.

CUBRID 9.2

++ cubrid server start: success
[tester@testdb ~]$ cubrid broker start
@ cubrid broker start
++ cubrid broker start: success

빌드

프로그램 소스와 Makefile이 준비된 상태에서 make 를 수행하면 test 라는 실행 파일이 생성된다. 정적 라이브러리를 사용하면 추가로 파일을 배포할 필요가 없고 속도가 빠르다. 하지만, 프로그램의 크기와 메모리 사용량이 커지는 단점이 있다. 동적 라이브러리를 사용하면 성능상의 오버헤드는 있지만, 메모리와 프로그램 크기에 있어 최적화를 이룰 수 있다.

다음은 Linux에서 make 를 사용하지 않고 동적인 라이브러리를 사용하여 테스트 프로그램을 빌드하는 명령 행의 예제이다.

cc -o test test.c -I$CUBRID/include -L$CUBRID/lib -lnsl -lcascci

예제 코드

#include <stdio.h>
#include <cas_cci.h>
char *cci_client_name = "test";
int main (int argc, char *argv[])
{
    int con = 0, req = 0, col_count = 0, res, ind, i;
    T_CCI_ERROR error;
    T_CCI_COL_INFO *res_col_info;
    T_CCI_CUBRID_STMT stmt_type;
    char *buffer, db_ver[16];
    printf("Program started!\n");
    if ((con=cci_connect("localhost", 30000, "demodb", "PUBLIC", ""))<0) {
        printf( "%s(%d): cci_connect fail\n", __FILE__, __LINE__);
        return -1;
    }

    if ((res=cci_get_db_version(con, db_ver, sizeof(db_ver)))<0) {
        printf( "%s(%d): cci_get_db_version fail\n", __FILE__, __LINE__);
        goto handle_error;
    }
    printf("DB Version is %s\n",db_ver);
    if ((req=cci_prepare(con, "select * from event", 0,&error))<0) {
        if (req < 0) {
            printf( "%s(%d): cci_prepare fail(%d)\n", __FILE__, __LINE__,error.err_code);
        }
        goto handle_error;
    }
    printf("Prepare ok!(%d)\n",req);
    res_col_info = cci_get_result_info(req, &stmt_type, &col_count);
    if (!res_col_info) {
        printf( "%s(%d): cci_get_result_info fail\n", __FILE__, __LINE__);
        goto handle_error;
    }

    printf("Result column information\n"
           "========================================\n");
    for (i=1; i<=col_count; i++) {
        printf("name:%s  type:%d(precision:%d scale:%d)\n",
            CCI_GET_RESULT_INFO_NAME(res_col_info, i),
            CCI_GET_RESULT_INFO_TYPE(res_col_info, i),
            CCI_GET_RESULT_INFO_PRECISION(res_col_info, i),
            CCI_GET_RESULT_INFO_SCALE(res_col_info, i));
    }
    printf("========================================\n");
    if ((res=cci_execute(req, 0, 0, &error))<0) {
        if (req < 0) {
            printf( "%s(%d): cci_execute fail(%d)\n", __FILE__, __LINE__,error.err_code);
        }
        goto handle_error;
    }

    while (1) {
        res = cci_cursor(req, 1, CCI_CURSOR_CURRENT, &error);
        if (res == CCI_ER_NO_MORE_DATA) {
            printf("Query END!\n");
            break;
        }
        if (res<0) {
            if (req < 0) {
                printf( "%s(%d): cci_cursor fail(%d)\n", __FILE__, __LINE__,error.err_code);
            }
            goto handle_error;
        }

        if ((res=cci_fetch(req, &error))<0) {
            if (res < 0) {
                printf( "%s(%d): cci_fetch fail(%d)\n", __FILE__, __LINE__,error.err_code);
            }
            goto handle_error;
        }

        for (i=1; i<=col_count; i++) {
            if ((res=cci_get_data(req, i, CCI_A_TYPE_STR, &buffer, &ind))<0) {
                printf( "%s(%d): cci_get_data fail\n", __FILE__, __LINE__);
                goto handle_error;
            }
            printf("%s \t|", buffer);
        }
        printf("\n");
    }
    if ((res=cci_close_req_handle(req))<0) {
        printf( "%s(%d): cci_close_req_handle fail", __FILE__, __LINE__);
       goto handle_error;
    }
    if ((res=cci_disconnect(con, &error))<0) {
        if (res < 0) {
            printf( "%s(%d): cci_disconnect fail(%d)", __FILE__, __LINE__,error.err_code);
        }
        goto handle_error;
    }
    printf("Program ended!\n");
    return 0;

    handle_error:
    if (req > 0)
        cci_close_req_handle(req);
    if (con > 0)
        cci_disconnect(con, &error);
    printf("Program failed!\n");
    return -1;
}

CCI API 레퍼런스¶

int cci_bind_param(int req_handle, int index, T_CCI_A_TYPE a_type, void *value, T_CCI_U_TYPE u_type, char flag)¶

prepared statement에서 bind 변수에 데이터를 바인딩하기 위하여 사용되는 함수이다. 이때, 주어진 a_type 의 value 의 값을 실제 바인딩되어야 하는 타입으로 변환하여 저장한다. 이후, cci_execute()가 호출될 때 저장된 데이터가 서버로 전송된다. 같은 index 에 대해서 여러 번 cci_bind_param()을 호출할 경우 마지막으로 설정한 값이 유효하다.

Parameters:	req_handle -- (IN) prepared statement의 요청 핸들. index -- (IN) 바인딩될 위치이며, 1부터 시작. a_type -- (IN) value 의 타입. value -- (IN) 바인딩될 데이터 값. u_type -- (IN) 데이터베이스에 반영될 데이터 타입. flag -- (IN) bind_flag(CCI_BIND_PTR).
Returns:	에러 코드(0: 성공) CCI_ER_BIND_INDEX CCI_ER_CON_HANDLE CCI_ER_NO_MORE_MEMORY CCI_ER_REQ_HANDLE CCI_ER_TYPE_CONVERSION CCI_ER_USED_CONNECTION

데이터베이스에 NULL을 바인딩하려면 다음의 두 가지 중 하나를 설정한다.

• value 값을 NULL 포인터로 설정
• u_type을 CCI_U_TYPE_NULL로 설정

다음은 NULL을 바인딩하는 코드의 일부이다.

res = cci_bind_param (req, 2 /* binding index*/, CCI_A_TYPE_STR, NULL, CCI_U_TYPE_STRING, CCI_BIND_PTR);

또는

res = cci_bind_param (req, 2 /* binding index*/, CCI_A_TYPE_STR, data, CCI_U_TYPE_NULL, CCI_BIND_PTR);

가 사용될 수 있다.

flag에 CCI_BIND_PTR이 설정되어 있을 경우 value 변수의 포인터만 복사하고(shallow copy) 값은 복사하지 않는다. flag가 설정되지 않는 경우 메모리를 할당하여 value 변수의 값을 복사(deep copy)한다. 만약 같은 메모리 버퍼를 이용하여 여러 개의 칼럼을 바인딩할 경우라면, CCI_BIND_PTR flag를 설정하지 않아야 한다.

T_CCI_A_TYPE은 CCI 응용 프로그램 내에서 데이터 바인딩에 사용되는 C 언어의 타입을 의미하며, int, float 등의 primitive 타입과 T_CCI_BIT, T_CCI_DATE 등의 CCI 가 정의한 user-defined 타입으로 구성된다. 각 타입에 대한 식별자는 아래의 표와 같이 정의되어 있다.

a_type	value 타입
CCI_A_TYPE_STR	char *
CCI_A_TYPE_INT	int *
CCI_A_TYPE_FLOAT	float *
CCI_A_TYPE_DOUBLE	double *
CCI_A_TYPE_BIT	T_CCI_BIT *
CCI_A_TYPE_SET	T_CCI_SET
CCI_A_TYPE_DATE	T_CCI_DATE *
CCI_A_TYPE_BIGINT	int64_t * (For Windows: __int64 *)
CCI_A_TYPE_BLOB	T_CCI_BLOB
CCI_A_TYPE_CLOB	T_CCI_CLOB

T_CCI_U_TYPE은 데이터베이스의 칼럼 타입으로, value 인자를 통해 바인딩된 데이터를 이 타입으로 변환한다. cci_bind_param() 함수는 C 언어가 이해하는 A 타입의 데이터를 데이터베이스가 이해할 수 있는 U 타입의 데이터로 변환하기 위한 정보를 전달하기 위해서 두 가지 타입을 사용한다.

U 타입이 허용하는 A 타입은 여러 가지이다. 예를 들어 CCI_U_TYPE_INT 는 CCI_A_TYPE_INT 외에 CCI_A_TYPE_STR 도 A 타입으로 받을 수 있다. 타입 변환은 묵시적 타입 변환을 따른다.

T_CCI_A_TYPE 및 T_CCI_U_TYPE enum은 모두 cas_cci.h 파일에 정의되어 있다. 각 타입에 대한 식별자 정의는 아래 표를 참고한다.

u_type	대응되는 기본 a_type
CCI_U_TYPE_CHAR	CCI_A_TYPE_STR
CCI_U_TYPE_STRING	CCI_A_TYPE_STR
CCI_U_TYPE_BIT	CCI_A_TYPE_BIT
CCI_U_TYPE_VARBIT	CCI_A_TYPE_BIT
CCI_U_TYPE_NUMERIC	CCI_A_TYPE_STR
CCI_U_TYPE_INT	CCI_A_TYPE_INT
CCI_U_TYPE_SHORT	CCI_A_TYPE_INT
CCI_U_TYPE_FLOAT	CCI_A_TYPE_FLOAT
CCI_U_TYPE_DOUBLE	CCI_A_TYPE_DOUBLE
CCI_U_TYPE_DATE	CCI_A_TYPE_DATE
CCI_U_TYPE_TIME	CCI_A_TYPE_DATE
CCI_U_TYPE_TIMESTAMP	CCI_A_TYPE_DATE
CCI_U_TYPE_OBJECT	CCI_A_TYPE_STR
CCI_U_TYPE_BIGINT	CCI_A_TYPE_BIGINT
CCI_U_TYPE_DATETIME	CCI_A_TYPE_DATE
CCI_U_TYPE_BLOB	CCI_A_TYPE_BLOB
CCI_U_TYPE_CLOB	CCI_A_TYPE_CLOB
CCI_U_TYPE_ENUM	CCI_A_TYPE_STR

날짜를 포함하는 문자열을 DATE, DATETIME 또는 TIMESTAMP 의 입력 인자로 할 때, 날짜 문자열의 형식은 "YYYY/MM/DD" 형식 또는 "YYYY-MM-DD" 형식만 허용한다. 즉, "2012/01/31" 또는 "2012-01-31"과 같은 형식은 허용하지만 "01/31/2012"와 같은 형식은 허용하지 않는다. 날짜를 포함하는 문자열을 날짜 타입의 입력 인자로 하는 예는 다음과 같다.

// "CREATE TABLE tbl(aa date, bb datetime)";

char *values[][3] =
{
    {"1994/11/30", "1994/11/30 20:08:08"},
    {"2008-10-31", "2008-10-31 20:08:08"}
};

req = cci_prepare(conn, "insert into tbl (aa, bb) values ( ?, ?)", CCI_PREPARE_INCLUDE_OID, &error);

for(i=0; i< 2; i++)
{
    res = cci_bind_param(req, 1, CCI_A_TYPE_STR, values[i][0], CCI_U_TYPE_DATE, (char)NULL);
    res = cci_bind_param(req, 2, CCI_A_TYPE_STR, values[i][1], CCI_U_TYPE_DATETIME, (char)NULL);
    cci_execute(req, CCI_EXEC_QUERY_ALL, 0, err_buf);
}

int cci_bind_param_array(int req_handle, int index, T_CCI_A_TYPE a_type, void *value, int *null_ind, T_CCI_U_TYPE u_type)¶

prepare된 req_handle 에 대해서 파라미터 배열을 바인딩한다. 이후, cci_execute_array()가 호출될 때 저장된 value 포인터에 의해 데이터가 서버로 전송된다. 같은 index 에 대해서 여러 번 cci_bind_param_array()가 호출될 경우 마지막 설정된 값이 유효하다. 데이터에 NULL을 바인딩할 경우 null_ind에 0이 아닌 값을 설정한다. value 값이 NULL 포인터인 경우, 또는 u_type이 CCI_U_TYPE_NULL인 경우 모든 데이터가 NULL로 바인딩되며 value에 의해 사용되는 데이터 버퍼는 재사용될 수 없다. a_type에 대한 value의 데이터 타입은 cci_bind_param()의 설명을 참조한다.

Parameters:	req_handle -- (IN) prepared statement의 요청 핸들 index -- (IN) 바인딩될 위치 a_type -- (IN) value 의 타입 value -- (IN) 바인딩될 데이터 값 null_ind -- (IN) NULL 식별자 배열(0 : not NULL, 1 : NULL) u_type -- (IN) 데이터베이스에 반영될 데이터 타입
Returns:	에러 코드(0: 성공) CCI_ER_BIND_INDEX CCI_ER_BIND_ARRAY_SIZE CCI_ER_CON_HANDLE CCI_ER_NO_MORE_MEMORY CCI_ER_REQ_HANDLE CCI_ER_TYPE_CONVERSION CCI_ER_USED_CONNECTION

int cci_bind_param_array_size(int req_handle, int array_size)¶

cci_bind_param_array()에서 사용될 array의 크기를 결정한다. cci_bind_param_array()가 사용되기 전에 반드시 cci_bind_param_array_size()가 먼저 호출 되어야 한다.

Parameters:	req_handle -- (IN) prepared statement의 요청 핸들 array_size -- (IN) 바인딩할 배열 크기
Returns:	에러 코드(0: 성공) CCI_ER_CON_HANDLE CCI_ER_REQ_HANDLE CCI_ER_USED_CONNECTION

int cci_bind_param_ex(int req_handle, int index, T_CCI_A_TYPE a_type, void *value, int length, T_CCI_U_TYPE u_type, char flag)¶

cci_bind_param()과 동일한 동작을 수행한다. 다만 문자열 타입인 경우 문자열의 바이트 길이를 지정하는 length 인자가 추가로 존재한다.

Parameters:	req_handle -- (IN) prepared statement의 요청 핸들 index -- (IN) 바인딩될 위치이며, 1부터 시작 a_type -- (IN) value 의 타입 value -- (IN) 바인딩할 데이터 값 length -- (IN) 바인딩할 문자열의 바이트 길이 u_type -- (IN) 데이터베이스에 반영될 데이터 타입 flag -- (IN) bind_flag(CCI_BIND_PTR)
Returns:	에러 코드(0: 성공)

length 인자는 아래와 같이 '\0'을 포함하는 문자열을 바인딩하기 위해 사용할 수 있다.

cci_bind_param_ex(statement, 1, CCI_A_TYPE_STR, "aaa\0bbb", 7, CCI_U_TYPE_STRING, 0);

int cci_blob_free(T_CCI_BLOB blob)¶

BLOB 구조체에 대한 메모리를 해제한다.

Returns:	에러 코드(0: 성공) CCI_ER_INVALID_LOB_HANDLE

int cci_blob_new(int conn_handle, T_CCI_BLOB* blob, T_CCI_ERROR* error_buf)¶

LOB 데이터가 저장될 빈 파일을 하나 생성하고, 해당 파일을 참조하는 Locator를 blob 구조체에 반환한다.

Parameters:	conn_handle -- (IN) 연결 핸들 blob -- (OUT) LOB Locator error_buf -- (OUT) 에러 버퍼
Returns:	에러 코드(0: 성공) CCI_ER_COMMUNICATION CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_DBMS CCI_ER_INVALID_LOB_HANDLE CCI_ER_LOGIN_TIMEOUT CCI_ER_NO_MORE_MEMORY CCI_ER_USED_CONNECTION

int cci_blob_read(int conn_handle, T_CCI_BLOB blob, long start_pos, int length, char *buf, T_CCI_ERROR* error_buf)¶

blob 에 명시한 LOB 데이터 파일의 start_pos 부터 length 만큼 데이터를 읽어 buf 에 저장한 후 이를 반환한다.

Parameters:	conn_handle -- (IN) 연결 핸들 blob -- (OUT) LOB Locator start_pos -- (IN) LOB 데이터 파일의 위치 인덱스 length -- (IN) 파일로부터 가져올 LOB 데이터 길이 buf -- (IN) 데이터 읽기 버퍼 error_buf -- (OUT) 에러 버퍼
Returns:	에러 코드(0: 성공) CCI_ER_COMMUNICATION CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_DBMS CCI_ER_INVALID_LOB_HANDLE CCI_ER_INVALID_LOB_READ_POS CCI_ER_LOGIN_TIMEOUT CCI_ER_NO_MORE_MEMORY CCI_ER_QUERY_TIMEOUT CCI_ER_USED_CONNECTION

long long cci_blob_size(T_CCI_BLOB* blob)¶

blob 에 명시한 데이터 파일의 크기를 반환한다.

Parameters:	blob -- (OUT) LOB Locator
Returns:	BLOB 데이터 파일의 크기(>=0 : 성공), 에러 코드(<0 : 에러) CCI_ER_INVALID_LOB_HANDLE

int cci_blob_write(int conn_handle, T_CCI_BLOB blob, long start_pos, int length, const char *buf, T_CCI_ERROR* error_buf)¶

buf 로부터 length 만큼 데이터를 읽어 blob 에 명시한 LOB 데이터 파일의 start_pos 부터 저장한다.

Parameters:	conn_handle -- (IN) 연결 핸들 blob -- (OUT) LOB Locator start_pos -- (IN) LOB 데이터 파일의 위치 인덱스 length -- (IN) 버퍼로부터 가져올 데이터 길이 buf -- (OUT) 데이터 쓰기 버퍼 error_buf -- (OUT) 에러 버퍼
Returns:	write한 크기(>=0 : 성공), 에러 코드(<0 : 에러) CCI_ER_COMMUNICATION CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_DBMS CCI_ER_INVALID_LOB_HANDLE CCI_ER_LOGIN_TIMEOUT CCI_ER_NO_MORE_MEMORY CCI_ER_QUERY_TIMEOUT CCI_ER_USED_CONNECTION

int cci_cancel(int conn_handle)¶

다른 스레드에서 실행 중인 질의를 취소시킨다. Java의 Statement.cancel() 메서드와 같은 기능을 수행한다.

Parameters:	conn_handle -- (IN) 연결 핸들
Returns:	에러 코드 CCI_ER_COMMUNICATION CCI_ER_CON_HANDLE CCI_ER_CONNECT

다음은 main 함수에서 스레드의 질의 실행을 취소하는 예이다.

/* gcc -o pthr pthr.c -m64 -I${CUBRID}/include -lnsl ${CUBRID}/lib/libcascci.so -lpthread
*/


#include <stdio.h>
#include <cas_cci.h>
#include <unistd.h>
#include <pthread.h>
#include <string.h>
#include <time.h>

#define QUERY "select * from db_class A, db_class B, db_class C, db_class D, db_class E"

static void *thread_main (void *arg);
static void *execute_statement (int con, char *sql_stmt);

int
main (int argc, char *argv[])
{
    int thr_id = 0, conn_handle = 0, res = 0;
    void *jret;
    pthread_t th;
    char url[1024];
    T_CCI_ERROR error;
    snprintf (url, 1024, "cci:CUBRID:localhost:33000:demodb:PUBLIC::");

    conn_handle = cci_connect_with_url_ex (url, NULL, NULL, &error);

    if (conn_handle < 0)
    {
        printf ("ERROR: %s\n", error.err_msg);
        return -1;
    }

    res = pthread_create (&th, NULL, &thread_main, (void *) &conn_handle);

    if (res < 0)
    {
        printf ("thread fork failed.\n");
        return -1;
    }
    else
    {
        printf ("thread started\n");
    }
    sleep (5);
    // If thread_main is still running, below cancels the query of thread_main.
    res = cci_cancel (conn_handle);
    if (res < 0)
    {
        printf ("cci_cancel failed\n");
        return -1;
    }
    else
    {
        printf ("The query was canceled by cci_cancel.\n");
    }
    res = pthread_join (th, &jret);
    if (res < 0)
    {
        printf ("thread join failed.\n");
        return -1;
    }

    printf ("thread_main was cancelled with\n\t%s\n", (char *) jret);
    free (jret);

    res = cci_disconnect (conn_handle, &error);
    if (res < 0)
    {
        printf ("ERROR: %s\n", error.err_msg);
      return res;
    }

    return 0;
}

void *
thread_main (void *arg)
{
    int con = *((int *) arg);
    int ret_val;
    void *ret_ptr;
    T_CCI_ERROR error;

    cci_set_autocommit (con, CCI_AUTOCOMMIT_TRUE);
    ret_ptr = execute_statement (con, QUERY);
    return ret_ptr;
}

static void *
execute_statement (int con, char *sql_stmt)
{
    int col_count = 1, ind, i, req;
    T_CCI_ERROR error;
    char *buffer;
    char *error_msg;
    int res = 0;

    error_msg = (char *) malloc (128);
    if ((req = cci_prepare (con, sql_stmt, 0, &error)) < 0)
    {
        snprintf (error_msg, 128, "cci_prepare ERROR: %s\n", error.err_msg);
        goto conn_err;
    }

    if ((res = cci_execute (req, 0, 0, &error)) < 0)
    {
        snprintf (error_msg, 128, "cci_execute ERROR: %s\n", error.err_msg);
        goto execute_error;
    }

    if (res >= 0)
    {
        while (1)
        {
            res = cci_cursor (req, 1, CCI_CURSOR_CURRENT, &error);
            if (res == CCI_ER_NO_MORE_DATA)
            {
                break;
            }
            if (res < 0)
            {
                snprintf (error_msg, 128, "cci_cursor ERROR: %s\n",
                    error.err_msg);
                return error_msg;
            }

            if ((res = cci_fetch (req, &error)) < 0)
            {
                snprintf (error_msg, 128, "cci_fetch ERROR: %s\n",
                    error.err_msg);
                return error_msg;
            }

            for (i = 1; i <= col_count; i++)
            {
                if ((res = cci_get_data (req, i, CCI_A_TYPE_STR, &buffer, &ind)) < 0)
                {
                    snprintf (error_msg, 128, "cci_get_data ERROR\n");
                    return error_msg;
                }
            }
        }
    }

    if ((res = cci_close_query_result (req, &error)) < 0)
    {
        snprintf (error_msg, 128, "cci_close_query_result ERROR: %s\n", error.err_msg);
        return error_msg;
    }
execute_error:
    if ((res = cci_close_req_handle (req)) < 0)
    {
        snprintf (error_msg, 128, "cci_close_req_handle ERROR\n");
    }
conn_err:
    return error_msg;
}

int cci_clob_free(T_CCI_CLOB clob)¶

CLOB 구조체에 대한 메모리를 해제한다.

Parameters:	clob -- (IN) LOB Locator
Returns:	에러 코드(0: 성공) CCI_ER_INVALID_LOB_HANDLE

int cci_clob_new(int conn_handle, T_CCI_CLOB* clob, T_CCI_ERROR* error_buf)¶

LOB 데이터가 저장될 빈 파일을 하나 생성하고, 해당 파일을 참조하는 Locator를 clob 구조체에 반환한다.

Parameters:	conn_handle -- (IN) 연결 핸들 clob -- (OUT) LOB Locator error_buf -- (OUT) 에러 버퍼
Returns:	에러 코드(<0 : 에러) CCI_ER_COMMUNICATION CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_DBMS CCI_ER_INVALID_LOB_HANDLE CCI_ER_LOGIN_TIMEOUT CCI_ER_NO_MORE_MEMORY CCI_ER_USED_CONNECTION

int cci_clob_read(int conn_handle, T_CCI_CLOB clob, long start_pos, int length, char *buf, T_CCI_ERROR* error_buf)¶

clob 에 명시한 LOB 데이터 파일의 start_pos 부터 length 만큼 데이터를 읽어 buf 에 저장한 후 이를 반환한다.

Parameters:	conn_handle -- (IN) 연결 핸들 clob -- (IN) LOB Locator start_pos -- (IN) LOB 데이터 파일의 위치 인덱스 length -- (IN) 파일로부터 가져올 LOB 데이터 길이 buf -- (IN) 데이터 읽기 버퍼 error_buf -- (OUT) 에러 버퍼
Returns:	read한 크기(>=0 : 성공), 에러 코드(<0 : 에러) CCI_ER_COMMUNICATION CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_DBMS CCI_ER_INVALID_LOB_HANDLE CCI_ER_INVALID_LOB_READ_POS CCI_ER_LOGIN_TIMEOUT CCI_ER_NO_MORE_MEMORY CCI_ER_QUERY_TIMEOUT CCI_ER_USED_CONNECTION

long long cci_clob_size(T_CCI_CLOB* clob)¶

clob 에 명시한 데이터 파일의 크기를 반환한다.

Parameters:	clob -- (IN) LOB Locator
Returns:	CLOB 데이터 파일의 크기(>=0 : 성공), 에러 코드(<0 : 에러) CCI_ER_INVALID_LOB_HANDLE

int cci_clob_write(int conn_handle, T_CCI_CLOB clob, long start_pos, int length, const char *buf, T_CCI_ERROR* error_buf)¶

buf 로부터 length 만큼 데이터를 읽어 clob 에 명시한 LOB 데이터 파일의 start_pos 부터 저장한다.

Parameters:	conn_handle -- (IN) 연결 핸들 clob -- (IN) LOB Locator start_pos -- (IN) LOB 데이터 파일의 위치 인덱스 length -- (IN) 버퍼로부터 가져올 데이터 길이 buf -- (OUT) 데이터 쓰기 버퍼 error_buf -- (OUT) 에러 버퍼
Returns:	write한 크기(>=0 : 성공), 에러 코드(<0 : 에러) CCI_ER_COMMUNICATION CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_DBMS CCI_ER_INVALID_LOB_HANDLE CCI_ER_LOGIN_TIMEOUT CCI_ER_NO_MORE_MEMORY CCI_ER_QUERY_TIMEOUT CCI_ER_USED_CONNECTION

int cci_close_query_result(int req_handle, T_CCI_ERROR *err_buf)¶

cci_execute(), cci_execute_array() 또는 cci_execute_batch() 함수가 반환한 resultset을 종료(close)한다. 요청 핸들(req_handle)의 종료 없이 cci_prepare()를 반복 수행하는 경우 cci_close_req_handle() 함수를 호출하기 전에 이 함수를 호출할 것을 권장한다.

Parameters:	req_handle -- (IN) 요청 핸들 err_buf -- (OUT) 에러 버퍼
Returns:	에러 코드 (0: 성공) CCI_ER_CON_HANDLE CCI_ER_COMMUNICATION CCI_ER_DBMS CCI_ER_NO_MORE_MEMORY CCI_ER_REQ_HANDLE CCI_ER_RESULT_SET_CLOSED CCI_ER_USED_CONNECTION

int cci_close_req_handle(int req_handle)¶

cci_prepare()로 획득한 요청 핸들을 종료(close)한다.

Parameters:	req_handle -- (IN) 요청 핸들
Returns:	에러 코드(0 : 성공) CCI_ER_CON_HANDLE CCI_ER_REQ_HANDLE CCI_ER_COMMUNICATION CCI_ER_DBMS CCI_ER_NO_MORE_MEMORY CCI_ER_USED_CONNECTION

int cci_col_get(int conn_handle, char *oid_str, char *col_attr, int *col_size, int *col_type, T_CCI_ERROR *err_buf)¶

collection type의 속성 값을 가져온다. 클래스 이름이 C이고 set_attr의 domain이 set(multiset, sequence)인 경우 다음의 질의와 같다.

SELECT a FROM C, TABLE(set_attr) AS t(a) WHERE C = oid;

즉, 멤버 개수가 레코드 개수가 된다.

Parameters:	conn_handle -- (IN) 연결 핸들 oid_str -- (IN) oid col_attr -- (IN) collection 속성 이름 col_size -- (OUT) collection 크기 (-1 : null) col_type -- (OUT) collection 타입 (set, multiset, sequence : u_type) err_buf -- (OUT) 에러 버퍼
Returns:	요청 핸들 CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_OBJECT CCI_ER_DBMS

int cci_col_seq_drop(int conn_handle, char *oid_str, char *col_attr, int index, T_CCI_ERROR *err_buf)¶

sequence 속성 값에 index(base:1) 번째의 멤버를 drop시킨다. 다음은 seq 속성 값에서 첫 번째 값을 삭제하는 예이다.

cci_col_seq_drop(conn_handle, oid_str, seq_attr, 1, err_buf);

Parameters:	conn_handle -- (IN) 연결 핸들 oid_str -- (IN) oid col_attr -- (IN) collection 속성 이름 index -- (IN) 인덱스 err_buf -- (OUT) 에러 버퍼
Returns:	에러 코드 CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_OBJECT CCI_ER_DBMS

int cci_col_seq_insert(int conn_handle, char *oid_str, char *col_attr, int index, char *value, T_CCI_ERROR *err_buf)¶

sequence 속성 값에서 index(base:1) 번째에 멤버를 추가시킨다. 다음은 seq 속성 값에서 1번에 값 'a'를 추가하는 예이다.

cci_col_seq_insert(conn_handle, oid_str, seq_attr, 1, "a", err_buf);

Parameters:	conn_handle -- (IN) 연결 핸들 oid_str -- (IN) oid col_attr -- (IN) collection 속성 이름 index -- (IN) 인덱스 value -- (IN) 순차적 엘리먼트(스트링) err_buf -- (OUT) 에러 버퍼
Returns:	에러 코드 CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_OBJECT CCI_ER_DBMS

int cci_col_seq_put(int conn_handle, char *oid_str, char *col_attr, int index, char *value, T_CCI_ERROR *err_buf)¶

sequence 속성 값에 index(base:1) 번째의 멤버를 새로운 값으로 대체한다.. 다음은 seq 속성 값에서 1번 값을 'a'로 대체하는 예이다.

cci_col_seq_put(conn_handle, oid_str, seq_attr, 1, "a", err_buf);

Parameters:	conn_handle -- (IN) 연결 핸들 oid_str -- (IN) oid col_attr -- (IN) collection 속성 이름 index -- (IN) 인덱스 value -- (IN) 순차적 값 err_buf -- (OUT) 에러 버퍼
Returns:	에러 코드 CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_OBJECT CCI_ER_DBMS

int cci_col_set_add(int conn_handle, char *oid_str, char *col_attr, char *value, T_CCI_ERRROR *err_buf)¶

set 속성 값에 member 하나를 추가한다. 다음은 set 속성 값에 'a'를 추가하는 예이다.

cci_col_set_add(conn_handle, oid_str, set_attr, "a", err_buf);

Parameters:	conn_handle -- (IN) 연결 핸들 oid_str -- (IN) oid col_attr -- (IN) collection 속성 이름 value -- (IN) set 엘리먼트 err_buf -- (OUT) 에러 버퍼
Returns:	에러 코드 CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_OBJECT CCI_ER_DBMS

int cci_col_set_drop(int conn_handle, char *oid_str, char *col_attr, char *value, T_CCI_ERROR *err_buf)¶

set 속성 값에서 멤버 하나를 drop시킨다. 다음은 set 속성 값에서 'a'를 삭제하는 예이다.

cci_col_set_drop(conn_handle, oid_str, set_attr, "a", err_buf);

Parameters:	conn_handle -- (IN) 연결 핸들 oid_str -- (IN) oid col_attr -- (IN) collection 속성 이름 value -- (IN) set 엘리먼트(스트링) err_buf -- (OUT) 에러 버퍼
Returns:	에러 코드 CCI_ER_CON_HANDLE CCI_ER_QUERY_TIMEOUT CCI_ER_LOGIN_TIMEOUT CCI_ER_COMMUNICATION

int cci_col_size(int conn_handle, char *oid_str, char *col_attr, int *col_size, T_CCI_ERROR *err_buf)¶

set(seq) 속성의 개수를 가져온다.

Parameters:	conn_handle -- (IN) 연결 핸들 oid_str -- (IN) oid col_attr -- (IN) collection 속성 이름 col_size -- (OUT) collection 크기 (-1 : NULL) err_buf -- (OUT) 에러 버퍼
Returns:	에러 코드(0 : 성공) CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_OBJECT CCI_ER_DBMS

int cci_connect(char *ip, int port, char *db_name, char *db_user, char *db_password)¶

DB 서버에 대한 연결 핸들을 할당받고 해당 서버와 연결을 시도한다. 서버 연결에 성공하면 연결 핸들 ID를 반환하고, 실패하면 에러 코드를 반환한다.

Parameters:	ip -- (IN) 서버 IP 문자 스트링 (호스트 이름) port -- (IN) 브로커 포트( $CUBRID/conf/cubrid_broker.conf 파일에 설정된 포트를 사용) db_name -- (IN) DB 이름 db_user -- (IN) DB 사용자 이름 db_passwd -- (IN) DB 사용자 암호
Returns:	연결 핸들 ID(성공), 에러 코드(실패) CCI_ER_NO_MORE_MEMORY CCI_ER_HOSTNAME CCI_ER_CON_HANDLE CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_CONNECT

int cci_connect_ex(char *ip, int port, char *db_name, char *db_user, char *db_password, T_CCI_ERROR * err_buf)¶

CCI_ER_DBMS 에러를 반환하면 세부 에러 내용을 DB 에러 버퍼(err_buf)를 통해 확인할 수 있다는 점만 cci_connect()와 다르고 나머지는 동일하다.

Parameters:	ip -- (IN) 서버 IP 문자 스트링 (호스트 이름) port -- (IN) 브로커 포트( $CUBRID/conf/cubrid_broker.conf 파일에 설정된 포트를 사용) db_name -- (IN) DB 이름 db_user -- (IN) DB 사용자 이름 db_passwd -- (IN) DB 사용자 암호 err_buf -- (OUT) 에러 버퍼
Returns:	연결 핸들 ID(성공), 에러 코드(실패) CCI_ER_NO_MORE_MEMORY CCI_ER_HOSTNAME CCI_ER_CON_HANDLE CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_CONNECT

int cci_connect_with_url(char *url, char *db_user, char *db_password)¶

url 인자로 전달된 접속 정보를 이용하여 데이터베이스로 연결을 시도한다. CCI에서 브로커의 HA 기능을 사용하는 경우 이 함수의 url 인자 내의 altHosts 속성을 이용하여, 장애 발생 시 failover할 standby 브로커 서버의 연결 정보를 명시해야 한다. 서버 연결에 성공하면 연결 핸들 ID를 반환하고, 실패하면 에러 코드를 반환한다. 브로커의 HA 기능에 대한 자세한 내용은 브로커 이중화를 참고한다.

Parameters:	url -- (IN) 서버 연결 정보 문자 스트링 db_user -- (IN) DB 사용자 이름. NULL 혹은 빈 문자열인 경우 url 의 <db_user>가 사용된다. 이 값과 url 내의 <db_user>가 모두 정의되지 않은 경우 DB 사용자 이름은 PUBLIC 이 된다. db_passwd -- (IN) DB 사용자 비밀번호. NULL 혹은 빈 문자열인 경우 url 의 <db_password>를 사용한다. 이 값과 url 내의 <db_password>가 모두 정의되지 않은 경우 비밀번호는 NULL이 된다.
Returns:	연결 핸들 ID(성공), 에러 코드(실패) CCI_ER_NO_MORE_MEMORY CCI_ER_HOSTNAME CCI_ER_INVALID_URL CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_LOGIN_TIMEOUT

<url> ::= cci:CUBRID:<host>:<port>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]
<property> ::= altHosts=<alternative_hosts> [ &rcTime=<time>] [ &loadBalance=true|false]
             |{login_timeout|loginTimeout}=<milli_sec>
             |{query_timeout|queryTimeout}=<milli_sec>
             |{disconnect_on_query_timeout|disconnectOnQueryTimeout}=true|false
             | logFile=<file_name>
             | logBaseDir=<dir_name>
             | logSlowQueries=true|false[&slowQueryThresholdMillis=<milli_sec>]
             | logTraceApi=true|false
             | logTraceNetwork=true|false

<alternative_hosts> ::= <host>:<port> [,<host>:<port>]

<host> := HOSTNAME | IP_ADDR
<time> := SECOND
<milli_sec> := MILLI SECOND

연결 대상과 관련된 속성은 altHosts 이며, 타임아웃과 관련된 속성은 loginTimeout, queryTimeout, disconnectOnQueryTimeout 이다. 디버깅용 로그 정보 설정과 관련된 속성은 logSlowQueries, logTraceApi, logTraceNetwork 이다. url 인자에 입력하는 모든 속성(property) 이름은 대소문자 구별을 하지 않는다.

• host: 마스터 데이터베이스의 호스트 이름 또는 IP 주소

• port: 포트 번호

• db_name: 데이터베이스 이름

• db_user: 데이터베이스 사용자 이름

• db_password: 데이터베이스 사용자 암호

• altHosts = standby_broker1_host, standby_broker2_host, ...: active 서버에 연결할 수 없는 경우, 그 다음으로 연결을 시도(failover)할 standby 서버의 브로커 정보를 나타낸다. failover할 브로커를 여러 개 지정할 수 있고, altHosts 에 나열한 순서대로 연결을 시도한다.

  Note

  메인 호스트와 altHosts 브로커들의 ACCESS_MODE설정에 RW와 RO가 섞여 있다 하더라도, 응용 프로그램은 ACCESS_MODE와 무관하게 접속 대상 호스트를 결정한다. 따라서 사용자는 접속 대상 브로커의 ACCESS_MODE를 감안해서 메인 호스트와 altHosts를 정해야 한다.

• rcTime: 첫 번째로 접속했던 브로커에 장애가 발생한 이후 altHosts 에 명시한 브로커로 접속한다(브로커 failover). 이후, rcTime 만큼 시간이 경과할 때마다 원래의 브로커에 재접속을 시도한다(기본값 600초).

• loadBalance: 이 값이 true면 응용 프로그램이 메인 호스트와 altHosts에 지정한 호스트들에 랜덤한 순서로 연결한다(기본값: false)

• login_timeout | loginTimeout: 데이터베이스에 로그인 시 타임아웃 값 (단위: msec). 이 시간을 초과하면 CCI_ER_LOGIN_TIMEOUT (-38) 에러를 반환한다. 기본값은 30,000(30초)이다. 이 값이 0인 경우 무한 대기를 의미한다. 이 값은 최초 접속 이후 내부적인 재접속이 발생하는 경우에도 적용된다.

• query_timeout | queryTimeout: cci_prepare(), cci_execute() 등의 함수를 호출했을 때 이 값으로 설정한 시간이 지나면 서버로 보낸 질의 요청에 대한 취소 메시지를 보내고 호출된 함수는 CCI_ER_QUERY_TIMEOUT (-39) 에러를 반환한다. 질의를 수행한 함수에서 타임아웃 발생 시 함수의 반환 값은 disconnect_on_query_timeout의 설정에 따라 달라질 수 있다. 자세한 내용은 다음의 disconnect_on_query_timeout을 참고한다.

  Note

  cci_execute()에 CCI_EXEC_QUERY_ALL 플래그를 설정하거나 cci_execute_batch() 또는 cci_execute_array()를 사용하여 여러 개의 질의를 한 번에 실행하는 경우, 질의 타임 아웃은 질의 하나에 대해 적용되는 것이 아니라 함수 하나에 대해 적용된다. 즉, 함수 시작 이후 타임아웃이 발생하면 함수 수행이 중단된다.

• disconnect_on_query_timeout | disconnectOnQueryTimeout : 질의 요청 타임아웃 시 즉시 소켓 연결 종료 여부. cci_prepare(), cci_execute() 등의 함수를 호출했을 때 query_timeout 으로 설정한 시간이 지나면 질의 취소 요청 후 즉시 소켓 연결을 종료할 것인지, 아니면 질의 취소 요청을 받아들인다는 서버의 응답을 기다릴 것인지를 설정한다. 기본값은 false 로, 서버의 응답을 기다린다. 이 값이 true 이면 cci_prepare(), cci_execute() 등의 함수 호출 도중 질의 타임아웃이 발생할 때 서버에 질의 취소 메시지를 보낸 후, 소켓을 닫고 CCI_ER_QUERY_TIMEOUT (-39) 에러를 반환한다. (브로커가 아닌 데이터베이스 서버 쪽에서 에러가 발생한 경우 -1을 반환한다. 상세 에러를 확인하고 싶으면 "데이터베이스 에러 버퍼"의 에러 코드를 확인한다. 데이터베이스 에러 버퍼에서 에러 코드를 확인하는 방법은 CCI 에러 코드와 에러 메시지 를 참고한다.) 응용 프로그램이 질의 취소 메시지를 보낸 후 에러를 반환했음에도 불구하고, 데이터베이스 서버는 그 메시지를 받지 못하고 해당 질의를 수행할 수 있음을 주의한다. false 이면 서버에 취소 메시지를 보낸 후, 서버의 질의 요청에 대한 응답이 올 때 까지 대기한다.

• logFile: 디버깅용 로그 파일 이름(기본값: cci_<handle_id>.log). <handle_id>는 이 함수가 반환하는 연결 핸들 ID이다.

• logBaseDir: 디버깅용 로그 파일이 생성되는 디렉터리. 경로를 포함한 파일 이름의 형식은 logBaseDir/logFile이 되며, 상대 경로로 지정할 수 있다.

• logSlowQueries: 디버깅용 슬로우 쿼리 로깅 여부(기본값: false)

• slowQueryThresholdMillis: 디버깅용 슬로우 쿼리 로깅 시 슬로우 쿼리 제한 시간(기본값: 60000). 단위는 밀리 초이다.

• logTraceApi: CCI 함수 시작과 끝의 로깅 여부

• logTraceNetwork: CCI 함수 네트워크 데이터 전송 내용의 로깅 여부

예제

--connection URL string when a property(altHosts) is specified for HA
URL=cci:CUBRID:192.168.0.1:33000:demodb:::?altHosts=192.168.0.2:33000,192.168.0.3:33000

--connection URL string when properties(altHosts,rcTime) is specified for HA
URL=cci:CUBRID:192.168.0.1:33000:demodb:::?altHosts=192.168.0.2:33000,192.168.0.3:33000&rcTime=600

--connection URL string when properties(logSlowQueries,slowQueryThresholdMills, logTraceApi, logTraceNetwork) are specified for interface debugging
URL = "cci:cubrid:192.168.0.1:33000:demodb:::?logSlowQueries=true&slowQueryThresholdMillis=1000&logTraceApi=true&logTraceNetwork=true"

int cci_connect_with_url_ex(char *url, char *db_user, char *db_password, T_CCI_ERROR * err_buf)¶

CCI_ER_DBMS 에러를 반환하면 세부 에러 내용을 데이터베이스 에러 버퍼(err_buf)를 통해 확인할 수 있다는 점만 cci_connect_with_url()과 다르고 나머지는 동일하다.

Parameters:	url -- (IN) 서버 연결 정보 문자 스트링 db_user -- (IN) 데이터베이스 사용자 이름. NULL 혹은 빈 문자열인 경우 url 의 <db_user>를 사용한다. db_passwd -- (IN) 데이터베이스 사용자 비밀번호. NULL 혹은 빈 문자열인 경우 url 의 <db_password>를 사용한다. err_buf -- (OUT) 에러 버퍼
Returns:	연결 핸들 ID(성공), 에러 코드(실패) CCI_ER_NO_MORE_MEMORY CCI_ER_HOSTNAME CCI_ER_INVALID_URL CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_LOGIN_TIMEOUT

int cci_cursor(int req_handle, int offset, T_CCI_CURSOR_POS origin, T_CCI_ERROR *err_buf)¶

cci_execute()로 실행한 질의 결과 내의 특정 레코드에 접근하기 위하여 요청 핸들에 설정된 커서를 이동시킨다. 인자로 지정되는 origin 변수 값과 offset 값을 통해 커서의 위치가 이동되며, 이동할 커서의 위치가 유효하지 않을 경우 CCI_ER_NO_MORE_DATA 를 반환한다.

Parameters:	req_handle -- (IN) 요청 핸들 offset -- (IN) 이동할 오프셋 origin -- (IN) 커서 위치를 나타내는 변수로서, 타입은 T_CCI_CURSOR_POS 이다. T_CCI_CURSOR_POS enum은 CCI_CURSOR_FIRST, CCI_CURSOR_CURRENT, CCI_CURSOR_LAST 의 세 가지 값으로 구성된다. err_buf -- (OUT) 에러 버퍼
Returns:	에러 코드 (0: 성공) CCI_ER_REQ_HANDLE CCI_ER_NO_MORE_DATA CCI_ER_COMMUNICATION

예제

//the cursor moves to the first record
cci_cursor(req, 1, CCI_CURSOR_FIRST, &err_buf);

//the cursor moves to the next record
cci_cursor(req, 1, CCI_CURSOR_CURRENT, &err_buf);

//the cursor moves to the last record
cci_cursor(req, 1, CCI_CURSOR_LAST, &err_buf);

//the cursor moves to the previous record
cci_cursor(req, -1, CCI_CURSOR_CURRENT, &err_buf);

int cci_cursor_update(int req_handle, int cursor_pos, int index, T_CCI_A_TYPE a_type, void *value, T_CCI_ERROR *err_buf)¶

cursor_pos 의 커서 위치에 대해서 index 번째의 칼럼 값을 value 값으로 update한다. 데이터베이스에 NULL 로 update할 경우 value 를 NULL 로 한다. update할 수 있는 조건은 cci_prepare()를 참조한다.

Parameters:	req_handle -- (IN) 요청 핸들 cursor_pos -- (IN) 커서 위치 index -- (IN) 칼럼 인덱스 a_type -- (IN) value 타입 value -- (IN) 새로운 값 err_buf -- (OUT) 에러 버퍼
Returns:	에러 코드 (0: 성공) CCI_ER_REQ_HANDLE CCI_ER_TYPE_CONVERSION CCI_ER_ATYPE

a_type 에 대한 value 의 데이터 타입은 다음과 같다.

a_type	value 타입
CCI_A_TYPE_STR	char *
CCI_A_TYPE_INT	int *
CCI_A_TYPE_FLOAT	float *
CCI_A_TYPE_DOUBLE	double *
CCI_A_TYPE_BIT	T_CCI_BIT *
CCI_A_TYPE_SET	T_CCI_SET
CCI_A_TYPE_DATE	T_CCI_DATE *
CCI_A_TYPE_BIGINT	int64_t * (For Windows: __int64 *)
CCI_A_TYPE_BLOB	T_CCI_BLOB
CCI_A_TYPE_CLOB	T_CCI_CLOB

T_CCI_CONN cci_datasource_borrow(T_CCI_DATASOURCE *datasource, T_CCI_ERROR *err_buf)¶

T_CCI_DATASOURCE 구조체에서 사용할 CCI 연결을 획득한다.

Parameters:	datasource -- (IN) CCI 연결을 획득할 T_CCI_DATASOURCE 구조체 포인터 err_buf -- (OUT) 에러 버퍼 (에러가 발생하면 에러 코드와 메시지를 반환)
Returns:	CCI 연결 핸들 식별자 (성공), -1 (실패)

See also

cci_property_create(), cci_property_destroy(), cci_property_get(), cci_property_set(), cci_datasource_create(), cci_datasource_destroy(), cci_datasource_release(), cci_datasource_change_property()

int cci_datasource_change_property(T_CCI_DATASOURCE *datasource, const char *key, const char *val)¶

DATASOURCE의 속성(property) 이름은 key*에 명시하고, 값을 *val에 설정한다. 이 함수를 사용하여 변경한 속성 값은 datasource 내 모든 연결에 적용된다.

Parameters:	datasource -- (IN) CCI 연결을 획득할 T_CCI_DATASOURCE 구조체 포인터 key -- (IN) 속성 이름 문자열에 대한 포인터 val -- (IN) 속성 값 문자열에 대한 포인터
Returns:	에러 코드(0: 성공) CCI_ER_NO_MORE_MEMORY CCI_ER_NO_PROPERTY CCI_ER_PROPERTY_TYPE

변경 가능한 속성(property)의 이름 및 값은 다음과 같다.

속성 이름	타입	값	의미
default_autocommit	bool	true/false	autocommit 여부. 기본값은 cubrid_broker.conf의 CCI_DEFAULT_AUTOCOMMIT이며, 이 값의 기본값은 ON(true)임.
default_lock_timeout	msec	숫자	lock timeout
default_isolation	string	cci_property_set()의 표 참고	isolation level. 기본값은 cubrid.conf의 isolation_level이며, 이 값의 기본값은 "TRAN_READ_UNCOMMITTED"임.
login_timeout	msec	숫자	login timeout. 기본값은 0(무한대기)임. prepare 또는 execute 함수 호출 시 내부적으로 재접속이 발생할 수 있으며, 이 때에도 사용됨.

예제

...
ps = cci_property_create ();
...
ds = cci_datasource_create (ps, &err);
...
cci_datasource_change_property(ds, "login_timeout", "5000");
cci_datasource_change_property(ds, "default_lock_timeout", "2000");
cci_datasource_change_property(ds, "default_isolation", "TRAN_REP_CLASS_COMMIT_INSTANCE");
cci_datasource_change_property(ds, "default_autocommit", "true");
...

See also

cci_property_create(), cci_property_destroy(), cci_property_get(), cci_property_set(), cci_datasource_create(), cci_datasource_borrow(), cci_datasource_destroy(), cci_datasource_release()

T_CCI_DATASOURCE *cci_datasource_create(T_CCI_PROPERTIES *properties, T_CCI_ERROR *err_buf)¶

CCI의 DATASOURCE를 생성한다.

Parameters:	properties -- (IN) 설정이 저장된 T_CCI_PROPERTIES 구조체 포인터. cci_property_set()으로 속성 값들을 설정한다. err_buf -- (OUT) 에러 버퍼 (에러가 발생하면 에러 코드와 메시지를 반환)
Returns:	생성된 T_CCI_DATASOURCE 구조체 포인터 (성공), NULL (실패)

See also

cci_property_create(), cci_property_destroy(), cci_property_get(), cci_property_set(), cci_datasource_borrow(), cci_datasource_destroy(), cci_datasource_release(), cci_datasource_change_property()

void cci_datasource_destroy(T_CCI_DATASOURCE *datasource)¶

CCI의 DATASOURCE를 삭제한다.

Parameters:	datasource -- (IN) 삭제할 T_CCI_DATASOURCE 구조체 포인터
Returns:	void

See also

cci_property_create(), cci_property_destroy(), cci_property_get(), cci_property_set(), cci_datasource_create(), cci_datasource_borrow(), cci_datasource_release(), cci_datasource_change_property()

int cci_datasource_release(T_CCI_DATASOURCE *datasource, T_CCI_CONN conn, T_CCI_ERROR *err_buf)¶

T_CCI_DATASOURCE 구조체에 사용을 끝낸 CCI 연결을 반환한다. 연결이 연결 풀에 반환된 이후 재사용하려면 반드시 cci_datasource_borrow() 함수를 재호출해야 한다.

Parameters:	datasource -- (IN) CCI 연결을 반환할 T_CCI_DATASOURCE 구조체 포인터 conn -- (IN) 사용을 끝낸 CCI 연결의 핸들 식별자 err_buf -- (OUT) 에러 버퍼 (에러가 발생하면 에러 코드와 메시지를 반환)
Returns:	1 (성공), 0 (실패)

See also

cci_property_create(), cci_property_destroy(), cci_property_get(), cci_property_set(), cci_datasource_create(), cci_datasource_destroy(), cci_datasource_borrow(), cci_datasource_change_property()

int cci_disconnect(int conn_handle, T_CCI_ERROR *err_buf)¶

conn_handle 에 대해 생성된 모든 요청 핸들을 삭제한다. 트랜잭션이 진행 중일 경우 cci_end_tran()을 실행한 다음 삭제된다.

Parameters:	conn_handle -- (IN) 연결 핸들 err_buf -- (OUT) 에러 버퍼
Returns:	에러 코드(0 : 성공) CCI_ER_CON_HANDLE CCI_ER_DBMS CCI_ER_COMMUNICATION

int cci_end_tran(int conn_handle, char type, T_CCI_ERROR *err_buf)¶

현재 진행 중인 트랜잭션에 대해서 커밋(commit)이나 롤백(rollback)을 수행한다. 이때, 열려 있는 요청 핸들은 모두 종료되고, 데이터베이스 서버와 연결이 해제된다. 단, 서버와 연결이 끊어진 후에도 해당 연결 핸들은 유효하며, 이는 cci_connect() 함수로 연결 핸들을 하나 할당 받은 경우와 동일한 상태다. type 이 CCI_TRAN_COMMIT 으로 지정되면 트랜잭션을 커밋하고, CCI_TRAN_ROLLBACK 으로 지정되면 트랜잭션을 롤백한다.

Parameters:	conn_handle -- (IN) 연결 핸들 type -- (IN) CCI_TRAN_COMMIT 또는 CCI_TRAN_ROLLBACK err_buf -- (OUT) 에러 버퍼
Returns:	에러 코드(0 : 성공) CCI_ER_CON_HANDLE CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_TRAN_TYPE

브로커 파라미터인 CCI_DEFAULT_AUTOCOMMIT으로 응용 프로그램 시작 시 자동 커밋 모드의 기본값을 설정할 수 있으며, 브로커 파라미터 설정을 생략하면 기본값은 ON이다. 응용 프로그램 내에서 자동 커밋 모드를 변경하려면 cci_set_autocommit() 함수를 이용하며, 자동 커밋 모드가 OFF 이면 cci_end_tran() 함수를 이용하여 명시적으로 트랜잭션을 커밋하거나 롤백해야 한다.

long cci_escape_string(int conn_handle, char *to, const char *from, unsigned long length, T_CCI_ERROR *err_buf)¶

입력 문자열을 CUBRID 질의문에서 사용할 수 있는 문자열로 변환한다. 이 함수의 인자로 연결 핸들 또는 no_backslash_escapes 설정 값, 출력 문자열 포인터, 입력 문자열 포인터, 입력 문자열의 바이트 길이, 오류 정보를 담을 T_CCI_ERROR 구조체 변수의 주소가 지정된다.

Parameters:	conn_handle -- (IN) 연결 핸들 또는 no_backslash_escapes 설정 값. 연결 핸들이 주어지는 경우, 연결된 서버의 no_backslash_escapes 파라미터 설정 값을 읽어서 변환 방법을 결정한다. 연결 핸들 대신 CCI_NO_BACKSLASH_ESCAPES_TRUE 또는 CCI_NO_BACKSLASH_ESCAPES_FALSE 설정 값을 전달하여 변환 방법을 결정할 수 있다. to -- (OUT) 결과 문자열 from -- (IN) 입력 문자열 length -- (IN) 입력 문자열의 최대 바이트 길이 err_buf -- (OUT) 에러 버퍼
Returns:	변경된 문자열의 바이트 길이(성공), 에러 코드(실패) CCI_ER_CON_HANDLE CCI_ER_COMMUNICATION

시스템 파라미터 no_backslash_escapes의 값이 yes(기본값)이거나 연결 핸들 위치에 CCI_NO_BACKSLASH_ESCAPES_TRUE 값을 전달하는 경우, 변환되는 문자는 다음과 같다.

• ' (single quote) => ' + ' (escaped single quote)

시스템 파라미터 no_backslash_escapes의 값이 no이거나 연결 핸들 위치에 CCI_NO_BACKSLASH_ESCAPES_FALSE 값을 전달하는 경우, 변환되는 문자는 다음과 같다.

• \n (new line character, ASCII 10) => \ + n (백슬래시 + 알파벳 n)
• \r (carriage return, ASCII 13) => \ + r (백슬래시 + 알파벳 r)
• \0 (ASCII 0) => \ + 0 (백슬래시 + 0(ASCII 48)
• \ (백슬래시) => \ + \

결과 문자열을 저장할 공간은 length 인자로 사용자가 직접 할당하며, 최대 입력 문자열의 바이트 길이 * 2 + 1만큼이 필요할 수 있다.

int cci_execute(int req_handle, char flag, int max_col_size, T_CCI_ERROR *err_buf)¶

cci_prepare()를 수행한 SQL 문(prepared statement)을 실행한다. 이 함수의 인자로 요청 핸들, flag, fetch하는 칼럼의 문자열 최대 길이, 오류 정보를 담을 T_CCI_ERROR 구조체 변수의 주소가 지정된다.

Parameters:	req_handle -- (IN) prepared statement의 요청 핸들 flag -- (IN) exec flag ( CCI_EXEC_QUERY_ALL ) max_col_size -- (IN) 문자열 타입인 경우 fetch하는 칼럼의 문자열 최대 길이(단위: 바이트). 이 값이 0이면 전체 길이를 fetch한다. err_buf -- (OUT) 에러 버퍼
Returns:	SELECT : 결과 행의 개수를 반환 INSERT, UPDATE : 반영된 행의 개수 기타 질의 : 0 실패 : 에러 코드 CCI_ER_REQ_HANDLE CCI_ER_BIND CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_QUERY_TIMEOUT CCI_ER_LOGIN_TIMEOUT

flag를 통해 질의문 수행 방식을 모두 수행하게 하거나 첫번째 질의문만 수행하도록 지정할 수 있다.

Note

2008 R4.4와 9.2 이상 버전에서 flag 설정 시 비동기 방식으로 결과를 가져오게 하는 CCI_EXEC_ASYNC를 더 이상 지원하지 않는다.

flag에 CCI_EXEC_QUERY_ALL을 설정하면 prepare 시에 전달된 여러 개의 질의문(세미콜론으로 여러 개의 질의문을 구분)을 모두 수행하며, 그렇지 않은 경우 제일 앞에 있는 질의문만 수행한다.

flag에 CCI_EXEC_QUERY_ALL을 설정하면 다음의 규칙이 적용된다.

• 리턴 값은 첫 번째 질의에 대한 결과이다.
• 어느 하나의 질의에서 에러가 발생할 경우 execute는 실패한 것으로 처리된다.
• q1; q2; q3와 같이 구성된 질의에 대해서 q1을 성공하고 q2에서 에러가 발생해도 q1의 수행 결과는 유효하다. 즉, 에러가 발생했을 때 이전에 성공한 질의 수행에 대해서 롤백하지 않는다.
• 질의가 성공적으로 수행된 경우 두 번째 질의에 대한 결과는 cci_next_result()를 통해서 얻을 수 있다.

max_col_size 는 prepared statement의 칼럼이 CHAR, VARCHAR, BIT, VARBIT 일 경우 클라이언트로 전송되는 칼럼의 문자열 최대 길이를 결정하기 위한 값이며, 이 값이 0이면 전체 길이를 fetch한다.

int cci_execute_array(int req_handle, T_CCI_QUERY_RESULT **query_result, T_CCI_ERROR *err_buf)¶

prepared statement에 하나 이상의 값이 바인딩되는 경우, 바인딩되는 변수의 값을 배열(array)로 전달받아 각각의 값을 변수에 바인딩하여 질의를 실행한다.

Parameters:	req_handle -- (IN) prepared statement의 요청 핸들 query_result -- (OUT) 질의 결과 err_buf -- (OUT) 데이터베이스 에러 버퍼
Returns:	수행된 질의의 개수(성공), 에러 코드(실패) CCI_ER_REQ_HANDLE CCI_ER_BIND CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_QUERY_TIMEOUT CCI_ER_LOGIN_TIMEOUT

데이터를 바인딩하기 위해서는 cci_bind_param_array_size() 함수를 호출하여 배열의 크기를 지정한 후, cci_bind_param_array() 함수를 이용하여 각각의 값을 변수에 바인딩하고, cci_execute_array() 함수를 호출하여 질의를 실행한다. 질의 결과는 T_CCI_QUERY_RESULT 구조체의 배열에 저장된다.

cci_execute_array() 함수는 query_result 변수에 질의 결과를 반환한다. 실행 결과에 대한 정보를 얻기 위해서는 아래와 같은 매크로를 이용할 수 있다. 매크로에서는 입력받는 각 인자에 대한 유효성 검사가 이루어지지 않으므로 주의한다.

query_result 변수의 사용이 끝나면 cci_query_result_free() 함수를 이용하여 질의 결과를 삭제해야 한다.

매크로	리턴 타입	의미
CCI_QUERY_RESULT_RESULT	int	영향을 끼친 행의 개수 또는 에러 식별자 (-1: CAS 에러, -2: DBMS 에러)
CCI_QUERY_RESULT_ERR_NO	int	질의에 대한 에러 번호
CCI_QUERY_RESULT_ERR_MSG	char *	질의에 대한 에러 메시지
CCI_QUERY_RESULT_STMT_TYPE	int(T_CCI_CUBRID_STMT enum)	질의문의 타입

자동 커밋이 ON인 경우 배열 내의 각 질의가 수행될 때마다 커밋된다.

Note

• 2008 R4.3 이전 버전에서 자동 커밋이 ON인 경우 배열 내의 모든 질의가 수행된 이후에 커밋되었으나, 2008 R4.3부터는 질의 하나가 수행될 때마다 커밋된다.
• 자동 커밋이 OFF일 때 질의문을 일괄 처리하는 cci_execute_array 함수에서 배열 내의 질의 일부에 일반적인 오류가 발생하는 경우, 이를 건너뛰고 다음 질의를 계속 수행한다. 그러나, 교착 상태가 발생하면 트랜잭션을 롤백하고 오류 처리한다.

char *query =
    "update participant set gold = ? where host_year = ? and nation_code = 'KOR'";
int gold[2];
char *host_year[2];
int null_ind[2];
T_CCI_QUERY_RESULT *result;
int n_executed;
...

req = cci_prepare (con, query, 0, &cci_error);
if (req < 0)
{
    printf ("prepare error: %d, %s\n", cci_error.err_code, cci_error.err_msg);
    goto handle_error;
}

gold[0] = 20;
host_year[0] = "2004";

gold[1] = 15;
host_year[1] = "2008";

null_ind[0] = null_ind[1] = 0;
error = cci_bind_param_array_size (req, 2);
if (error < 0)
{
    printf ("bind_param_array_size error: %d\n", error);
    goto handle_error;
}

error =
    cci_bind_param_array (req, 1, CCI_A_TYPE_INT, gold, null_ind, CCI_U_TYPE_INT);
if (error < 0)
{
    printf ("bind_param_array error: %d\n", error);
    goto handle_error;
}
error =
    cci_bind_param_array (req, 2, CCI_A_TYPE_STR, host_year, null_ind, CCI_U_TYPE_INT);
if (error < 0)
{
    printf ("bind_param_array error: %d\n", error);
    goto handle_error;
}

n_executed = cci_execute_array (req, &result, &cci_error);
if (n_executed < 0)
{
    printf ("execute error: %d, %s\n", cci_error.err_code, cci_error.err_msg);
    goto handle_error;
}
for (i = 1; i <= n_executed; i++)
{
    printf ("query %d\n", i);
    printf ("result count = %d\n", CCI_QUERY_RESULT_RESULT (result, i));
    printf ("error message = %s\n", CCI_QUERY_RESULT_ERR_MSG (result, i));
    printf ("statement type = %d\n",
            CCI_QUERY_RESULT_STMT_TYPE (result, i));
}
error = cci_query_result_free (result, n_executed);
if (error < 0)
{
    printf ("query_result_free: %d\n", error);
    goto handle_error;
}
error = cci_end_tran(con, CCI_TRAN_COMMIT, &cci_error);
if (error < 0)
{
    printf ("end_tran: %d, %s\n", cci_error.err_code, cci_error.err_msg);
    goto handle_error;
}

int cci_execute_batch(int conn_handle, int num_sql_stmt, char **sql_stmt, T_CCI_QUERY_RESULT **query_result, T_CCI_ERROR *err_buf)¶

CCI에서 INSERT / UPDATE / DELETE 와 같은 DML 질의를 사용하는 경우에는 여러 작업을 한 번에 처리할 수 있는데, 이러한 배치 작업을 위해서 cci_execute_array() 함수와 cci_execute_batch() 함수가 이용될 수 있다. 단, cci_execute_batch() 함수에서는 prepared statement를 사용할 수 없다. 질의 결과는 T_CCI_QUERY_RESULT 구조체의 배열에 저장된다.

Parameters:	conn_handle -- (IN) 연결 핸들 num_sql_stmt -- (IN) sql_stmt 의 개수 sql_stmt -- (IN) SQL 문 array query_result -- (OUT) sql_stmt 의 결과 err_buf -- (OUT) 데이터베이스 에러 버퍼
Returns:	수행된 질의의 개수(성공), 에러 코드(실패) CCI_ER_CON_HANDLE CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_NO_MORE_MEMORY CCI_ER_CONNECT CCI_ER_QUERY_TIMEOUT CCI_ER_LOGIN_TIMEOUT

인자로 지정된 num_sql_stmt 개의 sql_stmt 를 수행하며, query_result 변수로 수행된 질의 개수를 반환한다. 각각의 질의에 대한 결과는 CCI_QUERY_RESULT_RESULT, CCI_QUERY_RESULT_ERR_NO, CCI_QUERY_RESULT_ERR_MSG, CCI_QUERY_RESULT_STMT_TYPE매크로를 이용할 수 있다. 전체 매크로에 대한 요약 설명은 cci_execute_array()를 참고한다.

매크로에서는 입력받은 인자에 대한 유효성을 검사하지 않으므로 주의한다.

query_result 변수의 사용이 끝나면 cci_query_result_free() 함수를 이용하여 질의 결과를 삭제해야 한다.

자동 커밋이 ON인 경우 배열 내의 각 질의가 수행될 때마다 커밋된다.

Note

• 2008 R4.3 이전 버전에서 자동 커밋이 ON인 경우 배열 내의 모든 질의가 수행된 이후에 커밋되었으나, 2008 R4.3부터는 질의 하나가 수행될 때마다 커밋된다.
• 자동 커밋이 OFF일 때 질의문을 일괄 처리하는 cci_execute_batch 함수에서 배열 내의 질의 일부에 일반적인 오류가 발생하는 경우, 이를 건너뛰고 다음 질의를 계속 수행한다. 그러나, 교착 상태가 발생하면 트랜잭션을 롤백하고 오류 처리한다.

...
char **queries;
T_CCI_QUERY_RESULT *result;
int n_queries, n_executed;
...
count = 3;
queries = (char **) malloc (count * sizeof (char *));
queries[0] =
    "insert into athlete(name, gender, nation_code, event) values('Ji-sung Park', 'M', 'KOR', 'Soccer')";
queries[1] =
    "insert into athlete(name, gender, nation_code, event) values('Joo-young Park', 'M', 'KOR', 'Soccer')";
queries[2] =
    "select * from athlete order by code desc limit 2";

//calling cci_execute_batch()
n_executed = cci_execute_batch (con, count, queries, &result, &cci_error);
if (n_executed < 0)
{
    printf ("execute_batch: %d, %s\n", cci_error.err_code, cci_error.err_msg);
    goto handle_error;
}
printf ("%d statements were executed.\n", n_executed);

for (i = 1; i <= n_executed; i++)
{
    printf ("query %d\n", i);
    printf ("result count = %d\n", CCI_QUERY_RESULT_RESULT (result, i));
    printf ("error message = %s\n", CCI_QUERY_RESULT_ERR_MSG (result, i));
    printf ("statement type = %d\n",
            CCI_QUERY_RESULT_STMT_TYPE (result, i));
}

error = cci_query_result_free (result, n_executed);
if (error < 0)
{
    printf ("query_result_free: %d\n", error);
    goto handle_error;
}
...