API 공통사항

• 모든 API 호출은 정상 처리 결과를 "0"으로 반환하며 오류에는 개별 상황에 따른 에러코드를 반환한다.

• Compile 할 때 $DBM_HOME/include/dbmUserAPI.h을 사용자가 작성한 Makefile 내에 포함해야 한다.

• Linking 할 때 $DBM_HOME/lib/libdbmCore.so을 사용자가 작성한 Makefile 내에 포함해야 하며 사용자 환경 변수인 LD_LIBRARY_PATH에도 추가해야 한다.

• 모든 API 동작은 non-autoCommit 모드이기 때문에 select를 제외한 트랜잭션 마지막에는 dbmCommit 또는 dbmRollback을 호출해야 반영이 완료된다.

• 다른 API와 달리 dbmExecuteStmt로 수행된 결과에 결과 집합이 없을 경우에는 NOT_FOUND 오류를 반환하지 않으므로 dbmGetRowCount를 통해 결과 개수를 확인해야 한다.

• API는 TableName을 이용하거나 dbmTableHandle을 이용하는 두 가지 유형이 있으므로 API 상세 spec을 참고하여 적절한 유형을 사용해야 한다.

dbmInitHandle

기능

API 사용을 위한 handle 초기화 작업을 수행한다. 모든 API를 사용하기 위해 반드시 선행되어 호출되어야 한다. dbmInitHandle 내에서는 아래의 과정을 내부적으로 수행한 후 성공/실패를 반환한다.

• Process 정보 저장

• Undo space 할당

• Dictionary 준비

• 트랜잭션 처리를 위한 내부 공간 할당

인자

int dbmInitHandle( dbmHandle     ** aHandle,
                   char           * aInstanceName )

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    int            rc;

    rc = dbmInitHandle( &sHandle, "demo" );
}

dbmFreeHandle

기능

dbmInitHandle에 의해 할당된 자원을 모두 해제한다. 
만일 변경 트랜잭션을 commit 하지 않은 상태에서 dbmFreeHandle이 호출되면 자동으로 rollback을 먼저 수행한다.
dbmFreeHandle을 호출하지 않고 프로그램을 종료할 수 있지만  dbmFreeHandle 없이 dbmInitHandle를 계속 호출하면 메모리가 증가하며 동시에 접속 가능한 공간이 부족한 오류가 발생할 수 있다.

인자

int dbmFreeHandle( dbmHandle     ** aHandle )

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    int            rc;

    rc = dbmInitHandle( &sHandle, "demo" );

    // 사용자코드 

    rc = dbmFreeHandle( &sHandle );
}

dbmPrepareTable

기능

사용자가 수행할 table을 handle에 준비시킨다. (Shared memory attach 등을 수행)

인자

int dbmPrepareTable( dbmHandle       * aHandle,
                     char            * aTableName );

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    int            rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareTable( sHandle,
                          "table1" );
}

dbmPrepareTableHandle

기능

사용자가 DML/ SELECT를 수행할 table에 대한 TableHandle을 생성하여 반환한다. (Shared memory attach 등을 수행한다.)

인자

int dbmPrepareTableHandle( dbmHandle         * aHandle,
                           const char        * aTableName,
                           dbmTableHandle   ** aTableHandle );

사용 예

main()
{
    dbmHandle      * sHandle = NULL;
    dbmTableHandle * sTableHandle = NULL;
    int            rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareTableHandle( sHandle,
                                "table1",
                                &sTableHandle );
}

dbmPrepareStmt

기능

사용자가 수행할 SQL을 실행 직전 단계로 만든다.

• 구문 분석

• Object 정합성 등의 validation 수행

• DDL/ DML을 모두 사용할 수 있다. (단, commit/ rollback 구문은 지원하지 않는다.)

인자

int dbmPrepareStmt( dbmHandle       * aHandle,
                    char            * aSQLString,
                    dbmStmt        ** aStmt )

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    dbmStmt      * sStmt   = NULL;
    int            rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareStmt( sHandle,
                         "select * from t1 where c1 = :v1",
                         & sStmt );
}

Procedure는 다음과 같은 방식으로 호출한다. Procedure를 호출할 때는 out mode parameter인 경우에도 BindParamById와 같은 BindParam 함수를 사용해야 한다.

rc = dbmPrepareStmt( sHandle, "exec proc1(?, ?, ?, ?)", &sStmt );
    TEST_ERR( sHandle, rc, "prepareStmt" );

    rc = dbmBindParamById( sHandle, sStmt, 1, DBM_BIND_DATA_TYPE_INT, &sData.c1, NULL );
    TEST_ERR( sHandle, rc, "bindParam1" );

    rc = dbmBindParamById( sHandle, sStmt, 2, DBM_BIND_DATA_TYPE_INT, &sData.c2, NULL );
    TEST_ERR( sHandle, rc, "bindParam2" );

    rc = dbmBindParamById( sHandle, sStmt, 3, DBM_BIND_DATA_TYPE_INT, &sData.c3, NULL );
    TEST_ERR( sHandle, rc, "bindParam3" );

    rc = dbmBindParamById( sHandle, sStmt, 4, DBM_BIND_DATA_TYPE_INT, &sData.c4, NULL );
    TEST_ERR( sHandle, rc, "bindParam4" );


    for( i = 0 ; i < 10 ; i ++ )
    {
        sData.c1 = i;
        sData.c2 = i;
        sData.c3 = i;

        rc = dbmExecuteStmt( sHandle, sStmt );
        TEST_ERR( sHandle, rc, "executeStmt" );

        fprintf( stdout, "c4=%d\n", sData.c4 );
    }

dbmFreeStmt

기능

사용자가 dbmPrepareStmt를 통해 할당 dbmStmt Handle의 메모리를 해제시킨다.

인자

int dbmFreeStmt( dbmHandle       * aHandle,
                 dbmStmt        ** aStmt )

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    dbmStmt      * sStmt   = NULL;
    int            rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareStmt( sHandle,
                         "select * from t1 where c1 = :v1",
                         & sStmt );
    // ....

    rc = dbmFreeStmt( sHandle, &sStmt );
}

dbmBindParamById

기능

dbmPrepareStmt에서 사용된 사용자 parameter marker (?)에 대응되는 변수를 순서대로 binding 한다.

• 사용자 변수는 input mode로만 사용할 수 있다.

• Binding 되는 변수의 pointer를 지정해야 하며 dbmPrepareStmt와 dbmExecuteStmt 사이에 호출한다.

• 길이 정보를 포함하는 변수를 지정하지 않을 경우, CHAR 타입은 실행 시점에 바인딩 된 변수의 string length를 구해 실행한다. 따라서 NULL을 포함하지 않는 변수일 경우 알 수 없는 오류가 발생할 수 있다. 그 외의 타입은 NULL로 지정할 수 있다.

인자

int dbmBindParamById( dbmHandle           * aHandle,
                      dbmStmt             * aStmt,
                      int                   aBindId,
                      dbmBindDataType       aBindType,
                      void                * aData,
                      long                * aSizePtr );

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    dbmStmt      * sStmt   = NULL;
    int            sVar;
    int            rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareStmt( sHandle,
                         "select * from t1 where c1 = ?",
                         & sStmt );

    rc = dbmBindParamById( sHandle,
                           sStmt,
                           1,
                           DBM_BIND_DATA_TYPE_INT,
                           & sVar,
                           NULL );
}

JSON Object 예제

다음은 json에 대해 dbmBindParamById를 사용하는 예이다.

dbmStmt * sStmt = NULL;
int sC1;

• 일반 int 변수 bind

sRc = dbmPrepareStmt( aHandle,
           "select c1, json_value(c2, '$.key1') from t1 where c1 = ?",
           &sStmt );
PRT_ERROR( sRc );

sRc = dbmBindParamById( aHandle,
                        sStmt,
                        1,
                        DBM_BIND_DATA_TYPE_INT,
                        &sC1,
                        NULL );
PRT_ERROR( sRc );

dbmStmt * sStmt = NULL;
int sC1;
char * sPath;

// json path bind
sRc = dbmPrepareStmt( aHandle,
           "select c1, json_query(c2, ?) from t1 where c1 = ?",
           &sStmt );
PRT_ERROR( sRc );

sRc = dbmBindParamById( aHandle,
                        sStmt,
                        1,
                        DBM_BIND_DATA_TYPE_CHAR,
                        &sPath,
                        NULL );
PRT_ERROR( sRc );

sRc = dbmBindParamById( aHandle,
                        sStmt,
                        2,
                        DBM_BIND_DATA_TYPE_INT,
                        &sC1,
                        NULL );
PRT_ERROR( sRc );

sPath = "$.key1";

dbmStmt * sStmt = NULL;
char * sSelectPath;
char * sWherePath;

// json path bind
sRc = dbmPrepareStmt( aHandle,
                      "select c1, json_query(c2, ?) from t1 "
                      "where json_value(c2, ?) = ?",
                      &sStmt );
PRT_ERROR( sRc );

sRc = dbmBindParamById( aHandle,
                        sStmt,
                        1,
                        DBM_BIND_DATA_TYPE_CHAR,
                        &sSelectPath,
                        NULL );
PRT_ERROR( sRc );

sRc = dbmBindParamById( aHandle,
                        sStmt,
                        2,
                        DBM_BIND_DATA_TYPE_CHAR,
                        &sWherePath,
                        NULL );
PRT_ERROR( sRc );

sSelectPath = "$.key2";
sWherePath = "$.key1";

dbmBindParamByName

기능

dbmPrepareStmt에서 사용자가 기술한 변수 이름을 기반으로 사용자 변수를 binding 한다.

• 사용자 변수는 input mode로만 사용할 수 있다.

• Binding 되는 변수의 pointer를 지정해야 하며 dbmPrepareStmt와 dbmExecuteStmt 사이에 호출한다.

인자

int dbmBindParamByName( dbmHandle           * aHandle,
                        dbmStmt             * aStmt,
                        char                * aVarName,
                        dbmBindDataType       aBindType,
                        void                * aData,
                        long                * aSizePtr );

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    dbmStmt      * sStmt   = NULL;
    int            sVar;
    int            rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareStmt( sHandle,
                         "select * from t1 where c1 = :v1",
                         & sStmt );

    rc = dbmBindParamByName( sHandle,
                             sStmt,
                             "v1",
                             DBM_BIND_DATA_TYPE_INT,
                             & sVar,
                             NULL );
}

dbmBindCol

기능

Select 구문에 의해 수행된 결과를 저장하기 위한 사용자 변수와 매핑하는 역할을 수행한다.

• dbmExecuteStmt에 의해 수행된 질의가 select 구문이어야 한다.

• 실제 select target 절의 데이터 크기와 사용자 변수의 크기가 다르므로 결과를 복사할 때 오류가 발생하지 않도록 주의해야 한다.

인자

int dbmBindCol( dbmHandle           * aHandle,
                dbmStmt             * aStmt,
                int                   aBindIndex,
                dbmBindDataType       aBindDataType,
                void                * aData,
                int                   aMaxSize,
                long                * aSizePtr )

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    dbmStmt      * sStmt   = NULL;
    int            sVar;
    int            sCol1;
    int            sCol2;
    int            rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareStmt( sHandle,
                         "select c1, c2 from t1 where c1 = :v1",
                         & sStmt );

    rc = dbmBindParamByName( sHandle,
                             sStmt,
                             "v1",
                             DBM_BIND_DATA_TYPE_INT,
                             & sVar,
                             NULL );

    rc = dbmBindCol( sHandle,
                     sStmt,
                     1,
                     DBM_BIND_DATA_TYPE_INT,
                     & sCol1,
                     sizeof(int),
                     NULL );
 
    rc = dbmBindCol( sHandle,
                     sStmt,
                     2,
                     DBM_BIND_DATA_TYPE_INT,                     
                     & sCol2,
                     sizeof(int),                     
                     NULL );
}

dbmBindColStruct

기능

Select 구문에 의해 수행된 결과를 저장하기 위해 사용자 변수와 매핑한다는 점에서 dbmBindCol과 동일하다. 다만 사용자가 정의한 구조체 변수로 반환받고자 할 때 사용한다는 차이가 있다.

• dbmExecuteStmt에 의해 수행된 질의가 select 구문이어야 한다.

• 구조체를 한 개만 binding 할 수 있고 dbmBindCol과 혼용하여 사용할 수 없다.

• 실제 select target 절의 데이터 크기와 사용자 변수의 크기가 다른 경우 메모리 침범등의 오류가 발생할 수 있으므로 target 절이 모두 column이거나 구조체가 반환되는 target 절의 크기와 일치하는 경우에 사용할 수 있다.

인자

int dbmBindColStruct( dbmHandle           * aHandle,
                      dbmStmt             * aStmt,
                      void                * aData )

사용 예

typedef struct
{
    int c1;
    int c2;
    int c3;
} DATA;

int main( int argc, char *argv[] )
{
    dbmHandle    * sHandle = NULL;
    dbmStmt      * sStmt = NULL;
    DATA           sData;
    char           sErrMsg[1024];
    int c1;
    int rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    TEST_ERR( sHandle, rc, "initHandle" );

• Prepare select stmt

c1 = 10;
    rc = dbmPrepareStmt( sHandle,
                         "select * from t1 where c1 = ?",
                         & sStmt );
    TEST_ERR( sHandle, rc, "prepareStmt" );

• 조건절 binding

rc = dbmBindParamById( sHandle,
                           sStmt,
                           1,
                           DBM_BIND_DATA_TYPE_INT,
                           &c1,
                           NULL );

TEST_ERR( sHandle, rc, "selectBindParam" );

• Target binding

rc = dbmBindColStruct( sHandle,
                       sStmt,
                       &sData );
    TEST_ERR( sHandle, rc, "selectTargetBind" );

    rc = dbmExecuteStmt( sHandle, sStmt );
    if( rc )
    {
        dbmGetErrorData( sHandle, &rc, sErrMsg, sizeof(sErrMsg) );
        printf("ERR-%d] %s\n", rc, sErrMsg );
    }

    rc = dbmFetchStmt( sHandle, sStmt );
    TEST_ERR( sHandle, rc, "fetchStmt" );

    printf( "Out c1=%d, c2=%d, c3=%d\n", sData.c1, sData.c2, sData.c3 );

    rc = dbmFreeStmt( sHandle, &sStmt );
    TEST_ERR( sHandle, rc, "FreeStmtInsert" );

    return 0;
}

dbmExecuteStmt

기능

dbmPrepareStmt에 의해 처리된 statement를 실행한다.

인자

int dbmExecuteStmt( dbmHandle           * aHandle,
                    dbmStmt             * aStmt )

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    dbmStmt      * sStmt   = NULL;
    int            sVar;
    int            sCol1;
    int            sCol2;
    int            rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareStmt( sHandle,
                         "select c1, c2 from t1 where c1 = :v1",
                         & sStmt );

    rc = dbmBindParamByName( sHandle,
                             sStmt,
                             "v1",
                             DBM_BIND_DATA_TYPE_INT,
                             & sVar,
                             NULL );

    rc = dbmBindCol( sHandle,
                     sStmt,
                     1,
                     DBM_BIND_DATA_TYPE_INT,  
                     & sCol1,
                     sizeof(int),
                     NULL ); 
    rc = dbmBindCol( sHandle,
                     sStmt,
                     2,
                     DBM_BIND_DATA_TYPE_INT,
                     & sCol2,
                     sizeof(int),
                     NULL );
    rc = dbmExecuteStmt( sHandle,
                         sStmt );
}

dbmFetchStmt

기능

dbmExecuteStmt에 의해 수행된 select 문 조회 결과를 한 건씩 가지고 온다.

• Select 문이 아닌데 호출될 경우 오류가 발생한다.

• dbmBindCol에 의해 미리 사용자 변수가 지정되어야 하며 잘못 설정된 경우 오류가 발생한다.

인자

int dbmFetchStmt( dbmHandle           * aHandle,
                  dbmStmt             * aStmt )

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    dbmStmt      * sStmt   = NULL;
    int            sVar;
    int            sCol1;
    int            sCol2;
    int            rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareStmt( sHandle,
                         "select c1, c2 from t1 where c1 = :v1",
                         & sStmt );

    rc = dbmBindParamByName( sHandle,
                             sStmt,
                             "v1",
                             DBM_BIND_DATA_TYPE_INT,
                             & sVar,
                             NULL );

    rc = dbmBindCol( sHandle,
                     sStmt,
                     1,
                     DBM_BIND_DATA_TYPE_INT,                     
                     & sCol1,
                     sizeof(int),
                     NULL );

    rc = dbmBindCol( sHandle,
                     sStmt,
                     2,
                     DBM_BIND_DATA_TYPE_INT,                     
                     & sCol2,
                     sizeof(int),
                     NULL );

    rc = dbmExecuteStmt( sHandle,
                         sStmt );

    rc = dbmFetchStmt( sHandle,
                       sStmt );
}

dbmFetchStmt2Json

기능

dbmExecuteStmt가 select 문을 조회한 결과를 한 건씩 JSON format text로 가져온다.

• Select 문이 아닌데 호출될 경우 오류가 발생한다.

• 입력된 버퍼의 크기는 충분히 크게 할당하여 사용해야 한다.

인자

int dbmFetchStmt2Json( dbmHandle           * aHandle,
                       dbmStmt             * aStmt,
                       char                * aDataPtr )

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    dbmStmt      * sStmt   = NULL;
    char           sText[1024];
    int            sVar;  
    int            rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareStmt( sHandle,
                         "select c1, c2 from t1 where c1 = :v1",
                         & sStmt );

    rc = dbmBindParamByName( sHandle,
                             sStmt,
                             "v1",
                             DBM_BIND_DATA_TYPE_INT,
                             & sVar,
                             NULL );

    while( dbmFetchStmt2Json( sHandle, sStmt, sText ) == 0 )
    {
        fprintf( stdout, "%s\n", sText );
    }
}

dbmInsertRow

기능

한 개의 사용자 데이터를 지정된 테이블에 추가한다.

인자

int dbmInsertRow( dbmHandle           * aHandle,
                  char                * aTableName,
                  void                * aUserData,
                  int                   aDataSize )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    sData.c1 = 1;
    sData.c2 = 100;
    rc = dbmInsertRow( sHandle, 
                       "t1",
                       & sData,
                       sizeof(DATA) );
}

dbmInsertRowExpired

기능

지정된 시간이 경과하면 expired 될 record를 삽입한다. 입력된 시간이 경과하면 데이터는 제거된다. 0을 입력하면 데이터는 유지되고 시간 (초 단위)을 지정하면 해당 시간이 경과된 후에 제거된다.

인자

int dbmInsertRow( dbmHandle           * aHandle,
                  char                * aTableName,
                  void                * aUserData,
                  int                   aDataSize,
                  int                   aSecond )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    sData.c1 = 1;
    sData.c2 = 100;
    rc = dbmInsertRowExpired( sHandle, 
                              "t1",
                              & sData,
                              sizeof(DATA),
                              600 );         // 10분 후 제거됨.
}

dbmInsert

기능

한 개의 사용자 데이터를 table handle에 지정된 테이블에 추가하고 row의 slot ID를 반환한다.

인자

int dbmInsert( dbmHandle       * aHandle,
               dbmTableHandle  * aTableHandle,
               void            * aUserData,
               int               aDataSize,
               long            * aSlotId );

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle      * sHandle = NULL;
    dbmTableHandle * sTableHandle = NULL;
    DATA             sData;
    long             sSlotId;

    rc = dbmInitHandle( &sHandle, "demo" );

    rc = dbmPrepareTableHandle( sHandle,
                                "t1",
                                &sTableHandle );    

    sData.c1 = 1;
    sData.c2 = 100;
    rc = dbmInsertRow( sHandle, 
                       sTableHandle,
                       & sData,
                       sizeof(DATA),
                       & sSlotId );
}

dbmUpdateRow

기능

한 건 이상의 사용자 데이터를 갱신한다.

• Key를 갱신하지 않고 데이터만 갱신할 경우에 빠르게 처리하기 위해 호출한다.

• Before/ after의 update로 인해 key column의 값이 갱신될 경우, dbmPrepareStmt/ dbmExecuteStmt를 통해 수행해야 한다.

인자

int dbmUpdateRow( dbmHandle           * aHandle,
                  char                * aTableName,
                  void                * aUserData,
                  int                 * aAffectedCount )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;
    int            sRowCount = 0;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    sData.c1 = 1;
    sData.c2 = 100;
    rc = dbmUpdateRow( sHandle, 
                       "t1",
                       & sData,
                       & sRowCount );
}

dbmUpdate

기능

지정된 table handle의 테이블에서 주어진 데이터에 해당하는 key를 가진 데이터를 변경하며, 필요한 경우 변경 전의 data를 반환한다.

aSlotID 인자가 -1 이 아닌 경우, 해당 slot의 데이터를 변경한다.

인자

int dbmUpdate( dbmHandle      * aHandle,
               dbmTableHandle * aTableHandle,
               void           * aUserData,
               long             aSlotId,
               int            * aRowCount,
               void           * aReturnOldData );

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle      * sHandle = NULL;
    dbmTableHandle * sTableHandle = NULL;
    DATA             sData;
    DATA             sOldData;
    int              sRowCount = 0;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareTableHandle( sHandle,
                                "t1",
                                & sTableHandle );    

    sData.c1 = 1;
    sData.c2 = 100;
    rc = dbmUpdate( sHandle, 
                    sTableHandle,
                    & sData,
                    -1,
                    & sRowCount,
                    & sOldData );
}

dbmUpsert

기능

지정된 table handle의 테이블에서 주어진 데이터에 해당하는 key를 가진 데이터가 있으면 변경하고 없으면 insert를 수행한다. Update 되었을 때 필요한 경우 변경되기 전의 data를 반환한다.

변경 전의 data가 필요 없으면 aReturnOldData를 NULL로 설정해야 하지만, aInsertCnt는 NULL이 아닌 경우 insert로 동작이 성공하면 1을 반환하고 update로 성공하면 0을 반환한다.

변경 전의 data가 필요하면 aReturnOldData를 NULL이 아닌 값으로 설정해야 하고, 해당 변수값은 update 일 때만 유효하므로 이 변수가 유효한지 여부를 판단하기 위해 aInsertCnt도 NULL이 아닌 값으로 설정해야 한다.

인자

int dbmUpsert( dbmHandle        * aHandle,
               dbmTableHandle   * aTableHandle,
               void             * aUserData,
               int                aDataSize,
               void             * aReturnOldData,
               int              * aInsertCnt );

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle      * sHandle = NULL;
    dbmTableHandle * sTableHandle = NULL;
    DATA             sData;
    DATA             sOldData;
    int              sInsertCnt = 0;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareTableHandle( sHandle,
                                "t1",
                                & sTableHandle );    

    sData.c1 = 1;
    sData.c2 = 100;
    rc = dbmUpsert( sHandle, 
                    sTableHandle,
                    & sData,
                    sizeof(DATA),
                    & sOldData,
                    & sInsertCnt);
}

dbmDeleteRow

기능

한 건 이상의 사용자 데이터를 삭제한다.

인자

int dbmDeleteRow( dbmHandle           * aHandle,
                  char                * aTableName,
                  void                * aUserData,
                  int                 * aAffectedCount )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;
    int            sRowCount = 0;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    sData.c1 = 1;
    sData.c2 = 100;
    rc = dbmDeleteRow( sHandle, 
                       "t1",
                       & sData,
                       & sRowCount );
}

dbmDelete

기능

주어진 table handle의 테이블에서 한 건 이상의 사용자 데이터를 삭제한다.

인자

int dbmDelete( dbmHandle      * aHandle,
               dbmTableHandle * aTableHandle,
               void           * aUserData,
               long             aSlotId,
               int            * aRowCount,
               void           * aReturnOldData );

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle      * sHandle = NULL;
    dbmTableHandle * sTableHandle = NULL;
    DATA             sData;
    DATA             sOldData;
    int              sRowCount = 0;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareTableHandle( sHandle,
                                "t1",
                                & sTableHandle );    

    sData.c1 = 1;
    sData.c2 = 100;
    rc = dbmDeleteRow( sHandle, 
                       sTableHandle,
                       & sData,
                       -1,
                       & sRowCount,
                       & sOldData );
}

dbmBindColumn

기능

dbmUpdateRowByCols를 호출할 때 특정 column에 사용자 데이터를 저장하기 위해 사용한다.
dbmBindColumn을 수행하는 시점에 내부 임시 버퍼에 사용자 데이터가 복제된다. 따라서 execution하기 전에 반드시 dbmBindColumn을 호출해야 한다.
동일한 column을 대상으로 반복적으로 dbmBindColumn을 호출할 경우 마지막에 호출한 값이 저장되며 존재하지 않는 column에 대해 수행할 경우 오류가 발생한다.

인자

int dbmBindColumn( dbmHandle     * aHandle,
                   const char    * aTableName,
                   const char    * aColumnName,
                   void          * aUserData,
                   int             aDataSize );

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    char           sData[1024];



    rc = dbmInitHandle( &sHandle, "demo" );

    rc = dbmBindColumn( sHandle,
                        "t1",
                        "col1",
                        sData,
                        sizeof(sData) );    
}

dbmClearBind

기능

dbmBindColumn을 수행한 정보를 삭제한다. 특정 column만 지정할 수 있으며 column을 명시하지 않고 NULL로 지정할 경우 이전에 binding 된 모든 정보를 삭제한다.

인자

int dbmClearBind( dbmHandle    * aHandle,
                  const char   * aTableName,
                  const char   * aColumnName );

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    char           sData[1024];



    rc = dbmInitHandle( &sHandle, "demo" );

    rc = dbmClearBind( sHandle,
                       "t1",
                       "col1" );    


    rc = dbmClearBind( sHandle,
                       "t1",
                       NULL );
}

dbmUpdateRowByCols

기능

특정 column만 갱신하고자 할 경우에 사용한다.  호출하기 전에 미리 dbmBindColumn API를 이용하여 key value를 포함하여 갱신하려는 column에 값을 설정해야 한다.

인자

int dbmUpdateRowByCols( dbmHandle      * aHandle,
                        const char     * aTableName,
                        int            * aRowCount );

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    char           sData[1024];
    int            sRowCount;



    rc = dbmInitHandle( &sHandle, "demo" );

    rc = dbmBindColumn( sHandle,
                        "t1",
                        "col1",
                        sData,
                        sizeof(sData) );    

    rc = dbmUpdateRowByCols( sHandle,
                             "t1",
                             &sRowCount );
}

dbmSelectRow

기능

한 건의 사용자 데이터를 조회하고 fetch 한다.
여러 건이 조회되더라도 첫 번째 한 건만 가지고오는데 다음 건을 가져와야 할 경우, dbmFetchNext 계열의 API를 사용해야 한다.

인자

int dbmSelectRow( dbmHandle           * aHandle,
                  char                * aTableName,
                  void                * aUserData )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;
    int            sRowCount = 0;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    sData.c1 = 1;
    rc = dbmSelectRow( sHandle, 
                       "t1",
                       & sData );
}

Date 타입을 반환받아야 할 경우에는 사용자가 unsigned long long 형태의 8 byte 변수를 지정하여 값을 저장할 수 있다.

다음 예제를 참고한다.

#include <stdio.h>
#include <string.h>
#include <unistd.h>
#include <sys/time.h>
#include <time.h>
#include <dbmUserAPI.h>


typedef struct
{
    int c1;
    long long c2;
} DATA;

main()
{
    dbmHandle *sHandle = NULL;
    struct timeval ss;
    time_t now;
    struct tm *nowtm;
    char buf[200];
    DATA sData;
    int sRowCount;
    int rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    if( rc )
    {
        printf( "test fail1\n" );
    }

    sData.c1 = 1;
    rc = dbmSelectRow( sHandle, "t1", &sData );
    if( rc )
    {
        printf( "test fail2\n" );
    }

• Date 값을 string format으로 변환한다.

ss.tv_sec = sData.c2 / 1000000.0;
ss.tv_usec = sData.c2 % 1000000;
now = ss.tv_sec;
nowtm = localtime(&now);
strftime( buf, sizeof(buf), "%Y-%m-%d %H:%M:%S", nowtm);
printf( "c1=%d, c2=%s.%ld\n", sData.c1, buf, ss.tv_usec );

• 현재 시각으로 변경할 경우

gettimeofday( &ss, NULL );
sData.c2 = ss.tv_sec * 1000000LL + ss.tv_usec;
rc = dbmUpdateRow( sHandle, "t1", &sData, &sRowCount );
if( rc )
{
    printf( "test fail3\n" );
}

rc = dbmSelectRow( sHandle, "t1", &sData );
if( rc )
{
    printf( "test fail4\n" );
}
ss.tv_sec = sData.c2 / 1000000.0;
ss.tv_usec = sData.c2 % 1000000;

now = ss.tv_sec;
nowtm = localtime(&now);
strftime( buf, sizeof(buf), "%Y-%m-%d %H:%M:%S", nowtm);
printf( "c1=%d, c2=%s.%ld\n", sData.c1, buf, ss.tv_usec );

dbmCommit( sHandle );
}

================================
== Test
================================
shellPrompt> ./testPgm
c1=1, c2=2020-12-23 17:48:38.913314
c1=1, c2=2020-12-23 17:49:33.214220

API에 의해 변경된 시간정보가 table에도 동일하게 반영되어 있다는 것을 확인할 수 있다.

dbmMetaManager(DEMO)> select * from t1;
---------------------------------------------------------------------------------
C1                   : 1
C2                   : 2020/12/23 17:49:33.214220
---------------------------------------------------------------------------------

1 row selected
dbmMetaManager(DEMO)>

dbmSelect

기능

주어진 table handle의 테이블에서 주어진 조건에 맞는 사용자 데이터를 조회하기 시작하고 fetch 한다.
한 건 이상의 데이터를 조회하려면 계속해서 dbmFetch 함수를 사용해야 한다.

인자

int dbmSelect( dbmHandle         * aHandle,
               dbmTableHandle    * aTableHandle,
               void              * aUserData,
               void              * aUntilData,
               dbmScanDirection    aScanDir,
               dbmScanType         aScanType );

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle      * sHandle = NULL;
    dbmTableHandle * sTableHandle = NULL;
    DATA             sData;
    int              sRowCount = 0;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareTableHandle( sHandle,
                                "t1",
                                & sTableHandle );    

    sData.c1 = 1;
    rc = dbmSelect( sHandle, 
                    sTableHandle,
                    & sData,
                    NULL,
                    DBM_SCAN_DIR_EQUAL,
                    DBM_SCAN_TYPE_RDONLY );
}

dbmFetch

기능

주어진 table handle의 테이블에서 수행한 이전 검색에 이어서 다음 데이터를 조회한다.

반드시 dbmSelect가 먼저 호출된 이후에 사용해야 한다.

인자

int dbmFetch( dbmHandle         * aHandle,
              dbmTableHandle    * aTableHandle,
              void              * aUserData,
              void              * aUntilData,
              dbmScanDirection    aScanDir,
              dbmScanType         aScanType );

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle      * sHandle = NULL;
    dbmTableHandle * sTableHandle = NULL;
    DATA             sData;
    DATA             sUntilData;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareTableHandle( sHandle,
                                "t1",
                                & sTableHandle );    

    sData.c1 = 10;
    sUntilData.c1 = 100;


    rc = dbmSelect( sHandle, 
                    sTableHandle,
                    & sData,
                    & sUntilData,
                    DBM_SCAN_DIR_FORWARD,
                    DBM_SCAN_TYPE_RDONLY );
   while( 1 )
   {
       rc = dbmFetch( sHandle,
                      sTableHandle,
                      & sData,
                      & sUntilData,
                      DBM_SCAN_DIR_FORWARD,
                      DBM_SCAN_TYPE_RDONLY );
       if( rc != 0 ) break; 
   }
}

dbmSelectMax

기능

주어진 table handle의 direct 테이블에 대해서만 key로 설정된 데이터 중 최대값을 조회한다.

테이블이 가진 segment들 중에 데이터가 하나라도 들어간 마지막 segment를 찾아서 이진 탐색을 통해 최대값을 가진 데이터를 반환한다.

이진 탐색 중에 데이터가 들어 있지 않은 slot을 발견할 경우, 잘못된 결과를 반환할 수 있다.

인자

int dbmSelectMax( dbmHandle      * aHandle,
                  dbmTableHandle * aTableHandle,
                  void           * aUserData );

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle      * sHandle = NULL;
    dbmTableHandle * sTableHandle = NULL;
    DATA             sData;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    rc = dbmPrepareTableHandle( sHandle,
                                "t1",
                                & sTableHandle );    

    sData.c1 = 1;
    rc = dbmSelectMax( sHandle, 
                       sTableHandle,
                       & sData );
}

dbmSelectCount

기능

입력된 데이터와 일치하는 레코드의 개수를 반환한다.

인자

int dbmSelectRow( dbmHandle           * aHandle,
                  char                * aTableName,
                  void                * aUserData,
                  int                 * aRetCount )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;
    int            sRowCount = 0;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    sData.c1 = 1;
    rc = dbmSelectCount( sHandle, 
                         "t1",
                         & sData,
                         & sRowCount );
}

dbmSelectRowGT

기능

입력된 데이터의 key 값보다 큰 데이터를 조회한다.

인자

int dbmSelectRowGT( dbmHandle           * aHandle,
                    char                * aTableName,
                    void                * aUserData )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;


    rc = dbmInitHandle( &sHandle, "demo" );
    
    sData.c1 = 1;
    rc = dbmSelectRowGT( sHandle, 
                         "t1",
                         & sData );
}

dbmSelectRowLT

기능

입력된 데이터의 key 값보다 작은 데이터를 조회한다.

인자

int dbmSelectRowLT( dbmHandle           * aHandle,
                    char                * aTableName,
                    void                * aUserData )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;


    rc = dbmInitHandle( &sHandle, "demo" );
    
    sData.c1 = 10;
    rc = dbmSelectRowLT( sHandle, 
                         "t1",
                         & sData );
}

dbmFetchNext

기능

입력된 데이터의 key 값과 동일한 다음 데이터를 조회한다.
Non-unique index에 여러 건의 데이터가 존재하는 까닭에 동일한 key 값을 갖는 여러 레코드를 가져오기 위해 dbmSelectRow와 조합하여 fetch를 수행해야 할 경우에 사용한다.

인자

int dbmFetchNext( dbmHandle           * aHandle,
                  char                * aTableName,
                  void                * aUserData )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    sData.c1 = 10;
    rc = dbmSelectRow( sHandle, 
                       "t1",
                       & sData );

   while( 1 )
   {
       rc = dbmFetchNext( sHandle,
                          "t1",
                          &sData );

       if( rc != 0 ) break; 
   }
}

dbmFetchNextGT

기능

입력된 데이터의 key 값보다 큰 데이터를 조회한다. dbmSelectRow 또는 dbmSelectRowGT에서 시작된 값을 기준으로 조회한다.

인자

int dbmFetchNextGT( dbmHandle           * aHandle,
                    char                * aTableName,
                    void                * aUserData )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    sData.c1 = 10;
    rc = dbmSelectRow( sHandle, 
                       "t1",
                       & sData );

   while( 1 )
   {
       rc = dbmFetchNextGT( sHandle,
                            "t1",
                            &sData );

       if( rc != 0 ) break; 
   }
}

dbmFetchNextLT

기능

입력된 데이터의 key 값보다 작은 데이터를 조회한다.

인자

int dbmFetchNextLT( dbmHandle           * aHandle,
                    char                * aTableName,
                    void                * aUserData )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    sData.c1 = 10;
    rc = dbmSelectRow( sHandle, 
                       "t1",
                       & sData );

   while( 1 )
   {
       rc = dbmFetchNextLT( sHandle,
                            "t1",
                            &sData );

       if( rc != 0 ) break; 
   }
}

dbmSelectForUpdateRow

기능

dbmSelectRow와 동일하며 조회된 레코드를 LOCK 한다.

인자

int dbmSelectForUpdateRow( dbmHandle           * aHandle,
                           char                * aTableName,
                           void                * aUserData )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;

    rc = dbmInitHandle( &sHandle, "demo" );
    
    sData.c1 = 10;
    rc = dbmSelectForUpdateRow( sHandle, 
                                "t1",
                                & sData );

}

레코드 lock을 유지하는 API 종류는 다음과 같다.

• dbmSelectForUpdateRowGT

• dbmSelectForUpdateRowLT

• dbmFetchNextUpdateRowGT

• dbmFetchNextUpdateRowLT

dbmInsertArray

기능

N 개의 레코드를 삽입할 때 사용한다. N 개의 operation 중에 오류가 한 건 이상 발생하면 에러를 반환하는데 오류가 발생한 경우에도 operation은 진행되며 모든 operation이 완료된 후에 결과가 반환된다.

인자

int dbmInsertArray( dbmHandle           * aHandle,
                    char                * aTableName,
                    void                * aUserData,
                    int                   aDataSingleSize,
                    int                   aDataCount, 
                    int                   aRetArr[] )

사용 예

typedef struct
{
    int c1;
    int c2;
    int c3;
} DATA;

int main( int argc, char *argv[] )
{
    dbmHandle    * sHandle = NULL;
    DATA           sData[10];
    int sErrCode[10];
    int i;
    int rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    if( rc ) exit(-1);

    for( i = 0; i < 10; i ++ )
    {
        sData[i].c1 = i;
        sData[i].c2 = i;
        sData[i].c3 = i;
    }

• 정상 처리

rc = dbmInsertArray( sHandle, "t1", sData, sizeof(DATA), 10, sErrCode );
    if( rc ) exit(-1);

    rc = dbmCommit( sHandle );
    if( rc ) exit(-1);

• 에러 처리

rc = dbmInsertArray( sHandle, "t1", sData, sizeof(DATA), 10, sErrCode );
    for( i = 0 ; i < 10; i ++ )
    {
        printf( "%d] retCode = %d\n", i, sErrCode[i] );
    }

    dbmFreeHandle( &sHandle );
    return 0;
}

dbmUpdateArray

기능

N 개의 레코드를 변경할 때 사용한다. N 개의 operation 중에 오류가 한 건 이상 발생하면 에러를 반환하는데 오류가 발생한 경우에도 operation은 진행되며 모든 operation이 완료된 후에 결과가 반환된다.

인자

int dbmUpdateArray( dbmHandle           * aHandle,
                    char                * aTableName,
                    void                * aUserData,
                    int                   aDataCount, 
                    int                 * aAffectedRowCount,
                    int                   aRetArr[] )

사용 예

typedef struct
{
    int c1;
    int c2;
    int c3;
} DATA;

int main( int argc, char *argv[] )
{
    dbmHandle    * sHandle = NULL;
    DATA           sData[10];
    int sErrCode[10], sRowCount;
    int i;
    int rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    if( rc ) exit(-1);

    for( i = 0; i < 10; i ++ )
    {
        sData[i].c1 = i;
        sData[i].c2 = i;
        sData[i].c3 = i;
    }

    rc = dbmInsertArray( sHandle, "t1", sData, sizeof(DATA), 10, sErrCode );
    if( rc ) exit(-1);

    rc = dbmCommit( sHandle );
    if( rc ) exit(-1);

    for( i = 0; i < 10; i ++ )
    {
        sData[i].c1 = i;
        sData[i].c2 = i*10;
        sData[i].c3 = i*20;
    }

    rc = dbmUpdateArray( sHandle, "t1", sData, 10, &sRowCount, sErrCode );
    if( rc ) exit(-1);

    printf( "AffectedRow = %d\n", sRowCount );

    rc = dbmCommit( sHandle );
    if( rc ) exit(-1);


    dbmFreeHandle( &sHandle );
    return 0;
}

dbmSelectArray

기능

N 개의 레코드를 조회할 때 사용한다. N 개의 operation 중에 오류가 한 건 이상 발생하면 에러를 반환하는데 오류가 발생한 경우에도 operation은 진행되며 모든 operation이 완료된 후에 결과가 반환된다.

인자

int dbmSelectArray( dbmHandle           * aHandle,
                    char                * aTableName,
                    void                * aUserData,
                    int                   aDataCount, 
                    int                 * aAffectedRowCount,
                    int                   aRetArr[] )

사용 예

typedef struct
{
    int c1;
    int c2;
    int c3;
} DATA;

int main( int argc, char *argv[] )
{
    dbmHandle    * sHandle = NULL;
    DATA           sData[10];
    int sErrCode[10], sRowCount;
    int i;
    int rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    if( rc ) exit(-1);

    for( i = 0; i < 10; i ++ )
    {
        sData[i].c1 = i;
        sData[i].c2 = i;
        sData[i].c3 = i;
    }

    rc = dbmInsertArray( sHandle, "t1", sData, sizeof(DATA), 10, sErrCode );
    if( rc ) exit(-1);

    rc = dbmCommit( sHandle );
    if( rc ) exit(-1);

    for( i = 0; i < 10; i ++ )
    {
        sData[i].c1 = i;
    }

    rc = dbmSelectArray( sHandle, "t1", sData, 10, &sRowCount, sErrCode );
    if( rc ) exit(-1);

    printf( "AffectedRow = %d\n", sRowCount );

    dbmFreeHandle( &sHandle );
    return 0;
}

dbmDeleteArray

기능

N 개의 레코드를 삭제할 때 사용한다. N 개의 operation 중에 오류가 한 건 이상 발생하면 에러를 반환하는데 오류가 발생한 경우에도 operation은 진행되며 모든 operation이 완료된 후에 결과가 반환된다.

인자

int dbmDeleteArray( dbmHandle           * aHandle,
                    char                * aTableName,
                    void                * aUserData,
                    int                   aDataCount, 
                    int                 * aAffectedRowCount,
                    int                   aRetArr[] )

사용 예

typedef struct
{
    int c1;
    int c2;
    int c3;
} DATA;

int main( int argc, char *argv[] )
{
    dbmHandle    * sHandle = NULL;
    DATA           sData[10];
    int sErrCode[10], sRowCount;
    int i;
    int rc;

    rc = dbmInitHandle( &sHandle, "demo" );
    if( rc ) exit(-1);

    for( i = 0; i < 10; i ++ )
    {
        sData[i].c1 = i;
        sData[i].c2 = i;
        sData[i].c3 = i;
    }

    rc = dbmInsertArray( sHandle, "t1", sData, sizeof(DATA), 10, sErrCode );
    if( rc ) exit(-1);

    rc = dbmCommit( sHandle );
    if( rc ) exit(-1);

    for( i = 0; i < 10; i ++ )
    {
        sData[i].c1 = i;
    }

    rc = dbmDeleteArray( sHandle, "t1", sData, 10, &sRowCount, sErrCode );
    if( rc ) exit(-1);

    printf( "AffectedRow = %d\n", sRowCount );

    rc = dbmCommit( sHandle );
    if( rc ) exit(-1);


    dbmFreeHandle( &sHandle );
    return 0;
}

dbmEnqueue

기능

사용자 데이터를 queue 형식의 테이블에 삽입한다.

• 한 개의 테이블에 여러 형태의 메시지를 이용하려면 msg-type을 임의의 숫자로 지정한다.

• Priority가 더 낮을 수록 우선순위가 높다.

• Msg-type 이나 priority 등이 설정되지 않은 경우에는 모두 0으로 설정된다.

인자

int dbmEnqueue( dbmHandle           * aHandle,
                char                * aTableName,
                int                   aMsgType,
                int                   aPriority,
                char                * aUserData,
                int                   aDataSize )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;


    rc = dbmInitHandle( &sHandle, "demo" );
    
    sData.c1 = 10;
    sData.c2 = 100;

    rc = dbmEnqueue( sHandle, 
                     "que1",
                     101,
                     1,
                     & sData,
                     sizeof(DATA) );

   
}

dbmDequeue

기능

Queue table로부터 한 건의 사용자 데이터를 추출한다. 
(MsgType, Priority)를 지정할 경우, 해당 조건에 맞는 데이터를 dequeue 한다. 조건없이 가져오려면 두 개의 필드를 모두 (-1, -1)로 설정하면 된다.
Dequeue 된 데이터는 자동으로 삭제되며 rollback이 호출된 경우 원본 데이터 형태로 그대로 삽입된다. (MsgType과 priority가 모두 유지되고 삽입 시간만 rollback time으로 변경된다.)

인자

int dbmDequeue( dbmHandle           * aHandle,
                char                * aTableName,
                int                   aInMsgType,
                int                   aInPriority,
                int                 * aOutMsgType,
                int                 * aOutPriority,
                char                * aUserData,
                int                 * aDataSize,
                int                   aTimeout )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;
    int            sDataSize = 0;
    int            sMsgType;
    int            sPriority;


    rc = dbmInitHandle( &sHandle, "demo" );

    rc = dbmDequeue( sHandle, 
                     "que1",
                     101,
                     1,
                     &sMsgType,
                     &sPriority,
                     & sData,
                     & sDataSize,
                     1000 );

   
}

dbmGetCurrVal

기능

미리 생성되어 있는 sequence 객체의 현재값을 반환한다.

인자

int dbmGetCurrVal( dbmHandle           * aHandle,
                   char                * aSequenceName,
                   long long           * aCurrVal )

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    long long      sCurrVal;
    int            sDataSize = 0;


    rc = dbmInitHandle( &sHandle, "demo" );

    rc = dbmGetCurrVal( sHandle,
                        "seq1",
                        & sCurrVal );   
}

dbmGetNextVal

기능

미리 생성되어 있는 sequence 객체의 다음 값을 반환한다.

인자

int dbmGetNextVal( dbmHandle           * aHandle,
                   char                * aSequenceName,
                   long long           * aNextVal )

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    long long      sNextVal;
    int            sDataSize = 0;


    rc = dbmInitHandle( &sHandle, "demo" );

    rc = dbmGetNextVal( sHandle,
                        "seq1",
                        & sNextVal);   
}

dbmCommit

기능

사용자가 수행한 모든 트랜잭션을 영구적으로 반영한다.

인자

int dbmCommit( dbmHandle           * aHandle )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;
    int            sRowCount = 0;


    rc = dbmInitHandle( &sHandle, "demo" );

    sData.c1 = 10;
    sData.c2 = 100;
    rc = dbmInsertRow( sHandle, "t1", &sData, sizeof(DATA) );

    sData.c1 = 10;
    sData.c2 = 200;
    rc = dbmUpdateRow( sHandle, "t1", &sData, &sRowCount );

    rc = dbmCommit( sHandle );
}

dbmRollback

기능

사용자가 수행한 트랜잭션을 모두 rollback 한다.

인자

int dbmRollback( dbmHandle           * aHandle )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;
    int            sRowCount = 0;


    rc = dbmInitHandle( &sHandle, "demo" );

    sData.c1 = 10;
    sData.c2 = 100;
    rc = dbmInsertRow( sHandle, "t1", &sData, sizeof(DATA) );

    sData.c1 = 10;
    sData.c2 = 200;
    rc = dbmUpdateRow( sHandle, "t1", &sData, &sRowCount );

    rc = dbmRollback( sHandle );
}

dbmRefineSystem

기능

사용자로 하여금 instance-level, table-level에서 table/index lock을 해제하거나 index를 재구축하는 복구 기능을 실행하도록 한다.

인자

int dbmRefineSystem( const char    * aInstName,
                     const char    * aTableName )

• Instance 이름은 필수이다.

• TableName을 지정하면 대상 테이블만 복구하고, NULL을 입력하면 instance와 관련된 모든 테이블을 복구한다.

사용 예

if( argc > 1 )
    {
        if( dbmRefineSystem( "demo", NULL ) != 0 )
        {
            printf( "failed to refine all\n" );
            exit(-1);
        }
    else
    {
        if( dbmRefineSystem( "demo", "t1" ) != 0 )
        {
            printf( "failed to refine t1\n" );
            exit(-1);
        }
    }

dbmGetRowCount

기능

UPDATE/ DELETE/ SELECT 기능을 prepare/ execute 한 후에 대상 row의 개수를 계산한다.

인자

int dbmGetRowCount( dbmHandle           * aHandle,
                    dbmStmt             * aStmt,
                    int                 * aRowCount )

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    dbmStmt      * sStmt = NULL;
    int            sRowCount;

    rc = dbmInitHandle( &sHandle, "demo" );

    rc = dbmPrepareStmt( sHandle, "...", &sStmt );
    rc = dbmExecuteStmt( sHandle, sStmt );
    
    rc = dbmGetRowCount( sHandle, sStmt, &sRowCount );

}

dbmGetRowSize

기능

입력한 테이블이 생성된 시점의 row size를 반환한다.

인자

int dbmGetRowSize( dbmHandle           * aHandle,
                   char                * aObjectName,
                   int                 * aRowSize )

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    int            sRowSize;

    rc = dbmInitHandle( &sHandle, "demo" );

    rc = dbmGetRowSize( sHandle, "Table1", &sRowSize );

}

dbmGetTableName

기능

입력된 테이블 핸들로부터 table name을 반환한다.

인자

const char * dbmGetTableName( dbmTableHandle           * aHandle )

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    dbmTableHandle * sTableHandle = NULL;
    char  * sTableName;

    rc = dbmInitHandle( &sHandle, "demo" );
    rc = dbmPrepareTableHandle( &sHandle, "t1", &sTableHandle );

    sTableName = dbmGetTableHandle ( sTableHandle );
}

dbmGetTableType

기능

입력된 테이블 핸들로부터 table type을 반환한다.

인자

dbmTableType  dbmGetTableType( dbmTableHandle           * aHandle )

dbmTableType의 정의는 아래와 같다.
typedef enum
{
    DBM_TABLE_TYPE_INVALID = 0,
    DBM_TABLE_TYPE_TABLE,                  // BTree Index Table
    DBM_TABLE_TYPE_QUEUE,                  // N/A
    DBM_TABLE_TYPE_SEQUENCE,               // Sequence Object
    DBM_TABLE_TYPE_DIRECT_TABLE,           // Direct Table
    DBM_TABLE_TYPE_DIRECT_QUEUE,           // N/A
    DBM_TABLE_TYPE_SPLAY_TABLE,            // Splay Index Table
    DBM_TABLE_TYPE_LIST_TABLE,             // N/A
    DBM_TABLE_TYPE_HASH_TABLE,             // Hash Table
    DBM_TABLE_TYPE_PERF_VIEW,
    DBM_TABLE_TYPE_MAX
} dbmTableType;

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    dbmTableHandle * sTableHandle = NULL;
    dbmTableType  sTableType;

    rc = dbmInitHandle( &sHandle, "demo" );
    rc = dbmPrepareTableHandle( &sHandle, "t1", &sTableHandle );

    sTableType = dbmGetTableType ( sTableHandle );
}

dbmSetSplayMode4DML

기능

Splay table handle인 경우, 입력된 option에 따라 insert 할 때 tree를 splay 할 지 여부를 설정한다.
0 으로 설정하면 splay 하지 않는다.

인자

int dbmSetSplayMode4DML( dbmTableHandle           * aHandle,
                         int                        aMode )

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    dbmTableHandle * sTableHandle = NULL;

    rc = dbmInitHandle( &sHandle, "demo" );
    rc = dbmPrepareTableHandle( &sHandle, "t1", &sTableHandle );
    dbmSetSplayMode4DML( sTableHandle, 1 );
}

dbmGetErrorData

기능

API 호출로 발생한 각 오류 코드에 대한 상세 에러 메시지를 확인한다.
DBM 내에는 에러가 stack 형태로 축적되어 있기 때문에 에러가 날 때까지 호출하면 최초 오류부터 발생 원인을 추적할 수 있다.

인자

int dbmGetErrorData( dbmHandle           * aHandle,
                     int                 * aErrorCode,
                     char                * aErrorMsg )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;
    int            sErrCode;
    char           sErrMsg[1024];


    rc = dbmInitHandle( &sHandle, "demo" );

    sData.c1 = 10;
    sData.c2 = 100;
    rc = dbmInsertRow( sHandle, "t1", &sData, sizeof(DATA) );
    if( rc )
    {
        while( dbmGetErrorData( sHandle, &sErrCode, sErrMsg ) == 0 )
        {
             fprintf( stdout, "ERR-%d] %s\n", sErrCode, sErrMsg );
        }
    }

}

dbmGetErrorMsg

기능

API 호출로 발생한 각 오류 코드에 대한 상세 에러 메시지를 확인한다.
에러 stack에 저장된 에러의 원본 유형을 출력하기 때문에 상세한 부가 오류사항은 출력되지 않는다.

인자

void dbmGetErrorMsg( int         aErrorCode,
                     char      * aErrorMsg,
                     int         aErrorMsgSize )

사용 예

typedef struct
{
    int c1;
    int c2;
} DATA;

main()
{
    dbmHandle    * sHandle = NULL;
    DATA           sData;
    int            sErrCode;
    char           sErrMsg[1024];


    rc = dbmInitHandle( &sHandle, "demo" );

    sData.c1 = 10;
    sData.c2 = 100;
    rc = dbmInsertRow( sHandle, "t1", &sData, sizeof(DATA) );
    if( rc )
    {
        dbmGetErrorMsg( rc, sErrMsg, sizeof(sErrMsg) );
    }

}

dbmGetTableUsage

기능

특정 테이블의 segment 정보를 반환한다.

인자

int dbmGetTableUsage( dbmHandle       * aHandle,
                      const char      * aTableName,
                      long            * aMaxSize,
                      long            * aTotalSize,
                      long            * aUsedSize,
                      long            * aFreeSize )

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    long           sTotal;
    long           sMax;
    long           sUsed;
    long           sFree;
    int            rc;

    rc = dbmInitHandle( &sHandle, 
                        "demo" );

    rc = dbmGetTableUsage( sHandle, 
                           "t1", 
                           &sMax, 
                           &sTotal, 
                           &sUsed, 
                           &sFree );
}

dbmGetTableUsageByHandle

기능

주어진 table handle에 해당하는 테이블의 segment 정보를 반환한다.

Direct 테이블의 경우, 각 segment 별로 데이터를 가진 최대 slot ID를 구하여 계산되므로 중간에 빈 slot이 있을 경우에도 사용 중인 slot으로 계산될 수도 있다.

인자

int dbmGetTableUsageByHandle( dbmHandle       * aHandle,
                              dbmTableHandle  * aTableHandle,
                              long            * aMaxSize,
                              long            * aTotalSize,
                              long            * aUsedSize,
                              long            * aFreeSize );

사용 예

main()
{
    dbmHandle      * sHandle = NULL;
    dbmTableHandle * sTableHandle = NULL;
    long             sTotal;
    long             sMax;
    long             sUsed;
    long             sFree;
    int              rc;

    rc = dbmInitHandle( &sHandle, 
                        "demo" );

    rc = dbmPrepareTableHandle( sHandle,
                                "t1",
                                & sTableHandle );

    rc = dbmGetTableUsage( sHandle, 
                           sTableHandle, 
                           &sMax, 
                           &sTotal, 
                           &sUsed, 
                           &sFree );
}

dbmExtendTable

기능

주어진 table handle에 해당하는 테이블에 새 segment를 추가한다.
새 segment의 크기는 CREATE TABLE 시 지정된 extend size 이다.

인자

int dbmExtendTable( dbmHandle       * aHandle,
                    dbmTableHandle  * aTableHandle );

사용 예

main()
{
    dbmHandle      * sHandle = NULL;
    dbmTableHandle * sTableHandle = NULL;

    rc = dbmInitHandle( &sHandle, 
                        "demo" );

    rc = dbmPrepareTableHandle( sHandle,
                                "t1",
                                & sTableHandle );

    rc = dbmExtendTable( sHandle, 
                         sTableHandle );
}

dbmExistDataInQue

기능

지정된 queue table에 데이터가 존재하는지 여부를 반환한다.

인자

int dbmExistDataInQue( dbmHandle       * aHandle,
                       const char      * aTableName,
                       int             * aExists );

사용 예

main()
{
    dbmHandle    * sHandle = NULL;
    int            i;


    rc = dbmInitHandle( &sHandle, "demo" );

    rc = dbmExistDataInQue( sHandle, "que1", &i );
}

dbmNow

기능

현재 시각을 반환한다.

인자

unsigned long dbmNow( void )

사용 예

#include <dbmUserAPI.h>
#include <common.h>




typedef struct
{
    int c1;
    unsigned long c2;
} DATA;


int main()
{
    DATA   sData;

    
    sData.c1 = 1;
    sData.c2 = dbmNow();
    rc = dbmInsertRow( sHandle, "t1", &sData, sizeof(sData) );
    TEST_ERR( sHandle, rc, "InsertFail" );


    sData.c1 = 1;
    rc = dbmSelectRow( sHandle, "t1", &sData );
    TEST_ERR( sHandle, rc, "SelectFail" );


    tt =sTimeVal.tv_sec;
    nowtm = localtime( &tt );
    strftime( buf, sizeof(buf), "%Y-%m-%d %H:%M:%S", nowtm);

    printf( "fetchData: c1=%d, c2=%s.%06ld\n", sData.c1, buf, sTimeVal.tv_usec );
}

Error Message

GOLDILOCKS LITE에 정의된 에러 메시지는 다음 표와 같다.