제7장 유틸리티 API

내용 목차

7.1. 헤더 파일
7.2. 구조체
7.3. 유틸리티 API 목록
7.3.1. TBConnect
7.3.2. TBDisconnect
7.3.3. TBExport
7.3.4. TBImport

Tibero에서는 유틸리티와 관련된 C와 C++ 함수를 제공하고 있다. 애플리케이션 프로그램 개발자는 유틸리티 API를 사용하여 기존에 명령 프롬프트에서 수행하던 유틸리티를 애플리케이션 프로그램에서 호출할 수 있다.

다음은 유틸리티 API가 사용하는 헤더 파일이다.

헤더 파일명설명
tbutil.h

유틸리티 API를 선언하고 이와 관련된 구조체를 정의한다.

정의할 구조체는 다음과 같다.

  • struct sqlstr

  • struct TBExpImpMeta

  • struct TBExportIn

  • struct TBExportOut

  • struct TBExportStruct

  • struct TBImportIn

  • struct TBImportOut

  • struct TBImportStruct

sqlca.h

유틸리티 내부에서 발생한 에러 정보를 애플리케이션 프로그램에 전달하는 구조체를 선언한다.

선언할 구조체는 다음과 같다.

  • struct sqlca

sqlcli.hODBC 표준인 헤더 파일이며, 표준 API와 매크로를 정의한다.

다음은 유틸리티 API에서 정의할 수 있는 구조체이다.

다음은 유틸리티 API 목록이다.

함수 타입함수헤더 파일
데이터베이스 연결TBConnecttbutil.h
데이터베이스 연결해제TBDisconnecttbutil.h
데이터 추출TBExporttbutil.h
데이터 로드TBImporttbutil.h

데이터베이스에 존재하는 데이터를 외부 파일로 추출하는 함수이다. 외부 파일은 추출된 데이터를 텍스트 형태로 표시하며, 컬럼 구분자와 레코드 구분자를 이용하여 컬럼과 레코드를 추출한다. 이렇게 추출된 외부 파일은 tbLoader 유틸리티의 데이터 파일 형태를 취한다. 사용자는 SELECT 문을 이용하여 추출할 데이터를 선정할 수 있다. 단, 대상 테이블 또는 뷰의 SELECT 권한이 있어야 한다.

TBExport 함수의 세부 내용은 다음과 같다.

  • 문법

    SQLRETURN SQL_API
    TBExport(SQLINTEGER versionNumber, TBExportStruct *pParamStruct,
             struct sqlca *pSqlca);
  • 파라미터

    파라미터용도설명
    versionNumber입력

    유틸리티 라이브러리의 버전번호이다. 이 파라미터는 유틸리티 라이브러리가 변경될 것에 대비하여 하위 버전과의 호환성을 위해 존재한다.

    현재 버전번호는 1이다.

    pParamStruct입출력이 파라미터를 사용하여 추출할 대상 정보를 명시하고, 추출 후에는 결과정보를 받는다. 자세한 정보는 TBExportStruct 구조체를 참고한다.
    pSqlca출력반환 코드가 SQL_SUCCESS가 아닌 경우 유틸리티 내부에서 발생한 에러 정보를 포함한다.
  • 반환 코드

    반환 코드설명
    SQL_SUCCESS함수가 성공적으로 완료된 상태
    SQL_SUCCESS_WITH_INFO함수가 성공적으로 완료되었으나, 경고 메시지가 있는 상태
    SQL_ERROR치명적인 에러가 발생한 상태
  • 예제

    #include "tbutil.h"
    
    #define DNS_NAME  "DEFAULT"
    #define USER_NAME "SYS"
    #define PWD       "tibero"
    
    int main(int argc, char *argv[]) {
        SQLRETURN      rc = SQL_SUCCESS;
        SQLINTEGER     versionNumber = 1;
        SQLCHAR        dataFileName[256];
        SQLCHAR        actionString[256];
        SQLCHAR        msgFileName[256];
        SQLCHAR        fieldTerm[5];
        SQLCHAR        lineTerm[5];
        SQLCHAR        enclStart[5];
        SQLCHAR        enclEnd[5];
    
        struct sqlca   ca           = {"\0", 0, 0, {0, "\0"}, "\0",
                                       {0, 0, 0, 0, 0, 0}, "\0", "\0"};
        TBExportStruct exportStruct = {NULL, 0, NULL, NULL, NULL, 0, NULL,
                                       0, NULL, NULL};
        TBExportIn     exportIn     = {{NULL, 0, NULL, 0, NULL, 0, NULL, 0, NULL, 0}};
        TBExportOut    exportOut    = {0};
    
        rc= TBConnect((SQLCHAR *)DNS_NAME, (SQLCHAR *)USER_NAME, (SQLCHAR *)PWD, &ca);
        
        if (rc != SQL_SUCCESS) return -1;
    
        strcpy((char *)dataFileName, "./all_tables.dat");
        strcpy((char *)actionString, "select * from all_tables");
        strcpy((char *)msgFileName, "./all_tables.log");
        strcpy((char *)fieldTerm, ",");
        strcpy((char *)lineTerm, "\n");
        strcpy((char *)enclStart, "\"");
        strcpy((char *)enclEnd, "\"");
    
        /* setting data file name */
        exportStruct.piDataFileName   = dataFileName;
        exportStruct.iDataFileNameLen = strlen((char *)dataFileName);
    
        /* setting action String */
        exportStruct.piActionString = calloc(1, sizeof(sqlstr));
        exportStruct.piActionString->data   = actionString;
        exportStruct.piActionString->length = strlen((char *)actionString);
    
        /* setting file type */
        exportStruct.iFileType = SQL_DEL;
    
        /* setting message file name */
        exportStruct.piMsgFileName   = msgFileName;
        exportStruct.iMsgFileNameLen = strlen((char *)msgFileName);
    
        /* setting field term, line term etc.. */
        exportIn.iMeta.fieldTerm    = fieldTerm;
        exportIn.iMeta.fieldTermLen = strlen((char *)fieldTerm);
        exportIn.iMeta.lineTerm     = lineTerm;
        exportIn.iMeta.lineTermLen  = strlen((char *)lineTerm);
        exportIn.iMeta.enclStart    = enclStart;
        exportIn.iMeta.enclStartLen = strlen((char *)enclStart);
        exportIn.iMeta.enclEnd      = enclEnd;
        exportIn.iMeta.enclEndLen   = strlen((char *)enclEnd);
    
        /* setting export input, output information */
        exportStruct.piExportInfoIn  = &exportIn;
        exportStruct.poExportInfoOut = &exportOut;
    
        /* setting file type */
        rc = TBExport(versionNumber, &exportStruct, &ca);
        if (rc != SQL_SUCCESS) return -1;
    
        /* disconnect */
        rc= TBDisconnect((SQLCHAR *)DNS_NAME, &ca);
        if (rc != SQL_SUCCESS) return -1;
    
        return 1;
    }

외부 파일에 존재하는 데이터를 데이터베이스에 로드하는 함수이다. 여기서 외부 파일은 tbLoader 유틸리티가 지원하는 고정된 레코드 형태와 분리된 레코드 형태를 지원한다. 단, 대상 테이블 또는 뷰의 INSERT 권한이 있어야 한다.

TBImport 함수의 세부 내용은 다음과 같다.

  • 문법

    SQLRETURN SQL_API TBImport(SQLINTEGER versionNumber,
                               TBImportStruct *pParamStruct,
                               struct sqlca *pSqlca);
  • 파라미터

    파라미터용도설명
    versionNumber입력

    유틸리티 라이브러리의 버전번호이다. 이 파라미터는 유틸리티 라이브러리가 변경될 것에 대비하여 하위 버전과의 호환성을 위해 존재한다.

    현재 버전번호는 1이다.

    pParamStruct입출력이 파라미터를 사용하여 로드할 대상 정보를 명시하고, 로드 후에는 결과정보를 받는다. 자세한 정보는 TBImportStruct 구조체를 참고한다.
    pSqlca출력반환 코드가 SQL_SUCCESS가 아닌 경우 유틸리티 내부에서 발생한 에러 정보를 포함한다.
  • 반환 코드

    반환 코드설명
    SQL_SUCCESS함수가 성공적으로 완료된 상태
    SQL_SUCCESS_WITH_INFO함수가 성공적으로 완료되었으나, 경고 메시지가 있는 상태
    SQL_ERROR치명적인 에러가 발생한 상태
  • 예제

    #include "tbutil.h"
    
    #define DNS_NAME  "DEFAULT"
    #define USER_NAME "SYS"
    #define PWD       "tibero"
    
    int main(int argc, char *argv[]) {
     SQLRETURN      rc = SQL_SUCCESS;
     SQLINTEGER     versionNumber = 1;
     SQLCHAR        dataFileName[256];
     SQLCHAR        actionString[256];
     SQLCHAR        msgFileName[256];
     SQLCHAR        badFileName[256];
     SQLCHAR        fieldTerm[5];
     SQLCHAR        lineTerm[5];
     SQLCHAR        enclStart[5];
     SQLCHAR        enclEnd[5];
     SQLCHAR        escape[5];
    
     struct sqlca   ca           = {"\0", 0, 0, {0, "\0"}, "\0",
                                   {0, 0, 0, 0, 0, 0}, "\0", "\0"};
     TBImportStruct importStruct = {NULL, 0, NULL, NULL, NULL, 0, NULL,
                                    0, NULL, 0, 0, NULL, NULL};
     TBImportIn     importIn     = {{NULL, 0, NULL, 0, NULL, 0, NULL, 0, NULL, 0},
                                    0, 0, 0, 0};
     TBImportOut    importOut    = {0, 0, 0, 0, 0, 0};
    
     rc= TBConnect((SQLCHAR *)DNS_NAME, (SQLCHAR *)USER_NAME, (SQLCHAR *)PWD, &ca);
     if (rc != SQL_SUCCESS) return -1;
    
     strcpy((char *)actionString, "LOAD DATA "
                                "APPEND "
                                "INTO TABLE DEPT "
                                "MULTI INSERT INDEXES "
                                "(position, deptno, dname CONSTANT \"co dep\", loc)");
     strcpy((char *)dataFileName, "./test.dat");
     strcpy((char *)msgFileName, "./test.log");
     strcpy((char *)badFileName, "./test.bad");
     strcpy((char *)fieldTerm,   ",b");
     strcpy((char *)lineTerm,    "abbb\n");
     strcpy((char *)enclStart,   "{$");
     strcpy((char *)enclEnd,     "$}");
     strcpy((char *)escape,      "XX");
    
     /* setting data file name */
     importStruct.piDataFileName   = dataFileName;
     importStruct.iDataFileNameLen = strlen((char *)dataFileName);
    
     /* setting action String */
     importStruct.piActionString = calloc(1, sizeof(sqlstr));
     importStruct.piActionString->data   = actionString;
     importStruct.piActionString->length = strlen((char *)actionString);
    
     /* setting file type */
     importStruct.iFileType = SQL_DEL;
    
     /* setting message file name */
     importStruct.piMsgFileName   = msgFileName;
     importStruct.iMsgFileNameLen = strlen((char *)msgFileName);
    
     /* setting bad data file name */
     importStruct.piBadFileName   = badFileName;
     importStruct.iBadFileNameLen = strlen((char *)badFileName);
    
     /* turn on DPL mode */
     importStruct.iDPL            = 2;
    
     /* setting field term, line term etc.. */
     importIn.iMeta.fieldTerm    = fieldTerm;
     importIn.iMeta.fieldTermLen = strlen((char *)fieldTerm);
     importIn.iMeta.lineTerm     = lineTerm;
     importIn.iMeta.lineTermLen  = strlen((char *)lineTerm);
     importIn.iMeta.enclStart    = enclStart;
     importIn.iMeta.enclStartLen = strlen((char *)enclStart);
     importIn.iMeta.enclEnd      = enclEnd;
     importIn.iMeta.enclEndLen   = strlen((char *)enclEnd);
     importIn.iMeta.escape       = escape;
     importIn.iMeta.escapeLen    = strlen((char *)escape);
    
     importIn.iRowcount          = 0;
     importIn.iSkipcount         = 0;
     importIn.iCommitcount       = 2;
     importIn.iErrorcount        = 50;
    
     /* setting export input, output information */
     importStruct.piImportInfoIn  = &importIn;
     importStruct.poImportInfoOut = &importOut;
    
     /* setting file type */
     rc = TBImport(versionNumber, &importStruct, &ca);
     if (rc != SQL_SUCCESS) return -1;    
    
       fprintf(stdout, "oRowsRead[%ld]", importOut.oRowsRead);
       fprintf(stdout, "oRowsSkipped[%ld]", importOut.oRowsSkipped);
       fprintf(stdout, "oRowsInserted[%ld]", importOut.oRowsInserted);
       fprintf(stdout, "oRowsUpdated[%ld]", importOut.oRowsUpdated);
       fprintf(stdout, "oRowsRejected[%ld]", importOut.oRowsRejected);
       fprintf(stdout, "oRowsCommitted[%ld]", importOut.oRowsCommitted);
    
       /* disconnect */
       rc= TBDisconnect((SQLCHAR *)DNS_NAME, &ca);
       if (rc != SQL_SUCCESS) return -1;
    
       return 1;
    }