4. Log Analysis API#

Log Analyzer의 구성요소 중의 하나인 Log Analysis API의 사용법을 설명한다.

Log Analysis API는 사용자의 애플리케이션에서 호출하는 API이며, XLog Sender에서 XLog를 받고 이를 분석하는 기능을 제공한다.

각 API의 설명에서 이름이 aOut으로 시작하는 인자는 출력 인자이다.

Log Analysis API는 C/C++ 언어에서 사용할 수 있다.

ALA_InitializeAPI#

구문#

ALA_RC ALA_InitializeAPI(
      ALA_BOOL       aUseAltibaseODBCDriver,
      ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aUseAltibaseODBCDriver	Altibase ODBC Driver의 사용 여부
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

Log Analysis API를 호출할 수 있는 환경을 생성한다.

주의사항#

ALA_ClearErrorMgr()외에 다른 Log Analyzer API를 먼저 호출하면 안 된다.
이 함수 호출을 실패한 경우, Log Analysis API를 사용하면 안 된다.
사용자 애플리케이션에서 Altibase ODBC Driver를 사용할 경우, 이 함수 호출전에 SQLAllocEnv()를 호출해야 한다.

예제#

#include <sqlcli.h>
#include <alaAPI.h>
...

/* Altibase ODBC Drive를 사용하지 않을 경우 */
void testAPIEnvironment1()
{
    /* Log Analysis API 환경 생성 */
    (void)ALA_InitializeAPI(ALA_FALSE, NULL);

    /* Log Analysis API를 호출 */
    ...

    /* Log Analysis API 환경 제거 */
    (void)ALA_DestroyAPI(ALA_FALSE, NULL);
}

/* Altibase ODBC Drive를 사용할 경우 */
void testAPIEnvironment2(ALA_BOOL aUseAltibaseODBCDriver)
{
    SQLHENV sEnv = NULL;

    /* Altibase ODBC 사용 환경 생성 */
    (void)SQLAllocEnv(&sEnv);

    /* Log Analysis API 환경 생성 */
    (void)ALA_InitializeAPI(ALA_TRUE, NULL);

    /* Altibase ODBC API 및 Log Analysis API를 호출 */
    ...

    /* Log Analysis API 환경 제거 */
    (void)ALA_DestroyAPI(ALA_TRUE, NULL);

    /* Altibase ODBC 사용 환경 제거 */
    (void)SQLFreeEnv(sEnv);
}

ALA_DestroyAPI#

구문#

ALA_RC ALA_DestroyAPI(
        ALA_BOOL      aUseAltibaseODBCDriver,
        ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aUseAltibaseODBCDriver	Altibase ODBC Driver의 사용 여부
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

ALA_InitializeAPI 호출로 생성한 환경을 제거한다.

주의사항#

결과에 관계 없이, 이 함수 호출 후 다른 Log Analyzer API를 사용하면 안 된다.
Altibase ODBC Driver를 사용할 경우, SQLFreeEnv()를 호출하기 전에 이 함수를 호출해야 한다.

예제#

ALA_InitializeAPI를 참고한다.

ALA_EnableLogging#

구문#

ALA_RC ALA_EnableLogging(
      const SChar  * aLogDirectory,
      const SChar  * aLogFileName,
      UInt           aFileSize,
      UInt           aMaxFileNumber,
      ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aLogDirectory	로그 디렉토리
aLogFileName	로그 파일의 이름
aFileSize	로그 파일의 크기
aMaxFileNumber	유지하는 로그 파일 최대 개수 (현재 사용중인 로그 파일 제외)
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

이 함수는 Problem Tracking을 위해 Logging을 활성화한다.

이 함수를 호출하지 않으면, Logging을 수행하지 않는다.

지정한 이름의 로그 파일이 없으면 로그 파일을 생성하고, 이미 있으면 그 로그 파일의 마지막에 로그를 추가한다.

로그 파일의 크기가 aFileSize에 도달하면 로그 파일의 이름을 바꾸고, 지정한 이름의 새로운 로그 파일을 생성한다. 로그 파일의 헤더에는 1에서 aMaxFileNumber사이의 번호가 있어서, 이 번호를 참고하여 로그 파일의 이름을 바꾼다. 예를 들면, 'analysis.log'라는 로그 파일의 헤더에 1이라는 번호가 있고 로그 파일의 크기가 aFileSize에 도달하면, 'analysis.log' 로그 파일의 이름을 'analysis.log-1'으로 바꾸고 헤더에 2라는 번호가 있는 새로운 'analysis.log' 로그 파일을 생성한다.

로그 파일 헤더의 번호는 1부터 시작하며, 하나씩 증가하다가 aMaxFileNumber에 도달하면 다시 1부터 시작한다. 따라서, 현재 사용 중인 로그 파일과 마지막으로 기록된 aMaxFileNumber 개의 로그 파일만 유지된다.

주의사항#

로그 디렉토리와 로그 파일을 합친 스트링의 길이는 최대 1024바이트까지 가능하다. (NULL 포함)
이미 Logging이 활성화된 상태에서 이 함수를 또 호출하면 에러가 발생한다.
이 함수가 실행중인 상태에서 다른 Log Analysis API를 호출하면 원하지 않은 결과가 나올 수 있다.
로그 파일의 헤더가 비정상적이면, 로그 파일을 삭제하고 다시 생성한다.
aFileSize가 0이면, 시스템 자원에 따라서 로그 파일이 무한히 커질 수 있다.

예제#

#include <alaAPI.h>
...

void testLogging()
{
    /* Log Analysis API 환경 생성 */
    (void)ALA_InitializeAPI(ALA_FALSE, NULL);

    /* Logging 활성화
     * 로그 디렉토리            : 현재 디렉토리
     * 로그 파일명              : analysis.log
     * 로그 파일의 크기         : 10 MB
     * 최대 이전 로그 파일의 수 : 10 개
     */
     (void)ALA_EnableLogging(".",
                             "analysis.log",
                             10 * 1024 * 1024,
                             10,
                             NULL);

    /* Log Analysis API를 호출 */
        ...

    /* Logging 비활성화 */
    (void)ALA_DisableLogging(NULL);

    /* Log Analysis API 환경 제거 */
    (void)ALA_DestroyAPI(ALA_FALSE, NULL);
}

ALA_DisableLogging#

구문#

ALA_RC ALA_DisableLogging(  
      ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

로깅을 비활성화한다.

주의사항#

로깅을 활성화하지 않고 호출하면 에러가 발생한다.
이 함수가 실행중인 상태에서 다른 Log Analysis API를 호출하면 원하지 않은 결과가 나올 수 있다.

예제#

ALA_EnableLogging을 참고한다.

ALA_CreateXLogCollector#

구문#

ALA_RC ALA_CreateXLogCollector(
     const SChar  * aXLogSenderName,
     const SChar  * aSocketInfo,
     SInt           aXLogPoolSize,
     ALA_BOOL       aUseCommittedTxBuffer,
     UInt           aACKPerXLogCount,
     ALA_Handle   * aOutHandle,
     ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aXLogSenderName	대응하는 XLog Sender의 이름 (길이 : 1 ~ 40)
aSocketInfo	Socket 타입 (TCP, UNIX Domain)
aXLogPoolSize	XLog Pool의 최대 크기 (단위: XLog의 개수, 범위 : 1 ~ )
aUseCommittedTxBuffer	Commit 순서로 Transaction의 XLog 얻기 여부
aACKPerXLogCount	실제로 ACK를 보낼 기준 XLog 수 (범위 : 1 ~ )
aOutHandle	XLog Collector 핸들
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

XLog Sender에 대응하는 XLog Collector를 생성한다.

XLog Sender의 이름은 중복될 수 있다. 즉, 다른 XLog Collector를 생성할 때 같은 XLog Sender를 지정할 수 있다.

aSocketInfo는 "SOCKET=socket_type;IP_STACK=xlog_ip_stack;PEER_IP=xlog_sender_ip;MY_PORT=listen_port" 형식의 문자열이다.

socket_type은 "TCP" 또는 "UNIX" 중에서 하나만 지정할 수 있다. 'UNIX'로 지정한 경우, Socket 파일명은 "$ALTIBASE_HOME/trc/rp-replication_name"으로 자동 생성된다.
xlog_sender_ip는 socket_type이 TCP일 때 지정해야 하며, 길이는 1 ~ 39 bytes 이다. XLog Sender가 실행되어 있는 IP주소이며, XLog Sender를 인증하기 위한 정보이다.
listen_port는 socket_type이 TCP일 때 지정해야 하며, 가능한 값의 범위는 1024 ~ 65535(0xFFFF) 이다. 이것은 XLog Sender가 접속할 포트 번호IP이며, ALA_Handshake()에서 사용된다.xlog_ip_stack은 socket_type이 TCP일 때 지정할 수 있으며, 사용할 Internet Protocol Stack의 종류를 가리킨다.
지정되어 있지 않을 경우, IPv4만 지원하는 Internet Protocol Stack이 사용된다.
값이 0으로 지정된 경우, Dual Stack (즉 IPv4와 IPv6 모두 지원하는 Internet Protocol Stack)이 사용된다.
값이 1로 지정된 경우, IPv6만 지원하는 Internet Protocol Stack이 사용된다.

ALA_SendACK()를 호출할 때, aACKPerXLogCount가 적용된다.

주의사항#

Commit 순서로 Transaction의 XLog를 얻을 경우, 아래의 사항을 고려해야 한다.

COMMIT XLog가 올 때까지 Transaction Table에 해당 트랜잭션의 모든 XLog가 쌓이기 때문에, XLog Pool의 크기를 크게 설정해야 한다. 즉, 메모리 부담이 커진다.
COMMIT XLog가 수신된 후에야 해당 트랜잭션의 XLog들을 얻을 수 있다. 즉, XLog가 도착한 시점과 실제로 처리하는 시점 사이의 간격이 커진다. Transaction이 배치 처리성 작업인 경우, 성능이 저하될 가능성이 매우 높다.

실제로 ACK를 보낼 기준 XLog 수를 1 보다 크게 설정하면, ALA_SendACK()를 호출해도 ACK를 XLog Sender에 전송하지 않을 수도 있다.

Socket Type이 TCP인 경우, 접속 대기 포트 번호는 다른 프로세스에서 사용 중인 것을 사용할 수 없다.

Socket Type이 UNIX Domain인 경우, XLog Sender가 있는 DBMS와 동일한 '$ALTIBASE_HOME' 환경 변수를 설정해야 한다. 그리고, OS마다 Socket 파일명의 최대 길이가 다르므로, 이를 확인하여 최대 길이를 초과하지 않도록 한다.

예제#

#include <alaAPI.h>
…

void testXLogCollectorTCP()
{
    ALA_Handle sHandle;

    /* TCP를 사용하는 XLog Collector 생성
    * XLog Sender의 이름                    : log_analysis
    * XLog Sender의 인증 정보               : IP=127.0.0.1
    * 접속 대기 PORT                        : 30300
    * XLog Pool의 최대 크기                 : 10000
    * Commit 순서로 Transaction의 XLog 얻기 : 미지정
    * 실제로 ACK를 보낼 기준 XLog 수        : 100
    */
    (void)ALA_CreateXLogCollector("log_analysis",
                "SOCKET=TCP;PEER_IP=127.0.0.1;MY_PORT=30300",
                10000,
                ALA_FALSE,
                100,
                &sHandle,
                NULL);

    /* XLog Sender 인증 정보 추가 */
    (void) ALA_AddAuthInfo(sHandle, "PEER_IP=127.0.0.2", NULL);

    /* XLog Sender 인증 정보 제거 */
    (void)ALA_RemoveAuthInfo(sHandle, "PEER_IP=127.0.0.2", NULL);

    /* Log Analysis API를 호출 */
    …

    /* XLog Collector 제거 */
    (void)ALA_DestroyXLogCollector(sHandle, NULL);
}

void testXLogCollectorUNIX()
{
    ALA_Handle sHandle;

    /* UNIX Domain을 사용하는 XLog Collector 생성
    * XLog Sender의 이름                    : log_analysis
    * XLog Pool의 최대 크기                 : 20000
    * Commit 순서로 Transaction의 XLog 얻기 : 지정
    * 실제로 ACK를 보낼 기준 XLog 수        : 50
    */
    (void)ALA_CreateXLogCollector("log_analysis",
                "SOCKET=UNIX",
                20000,
                ALA_TRUE,
                50,
                &sHandle,
                NULL);

    /* Log Analysis API를 호출 */
    …

    /* XLog Collector 제거 */
    (void)ALA_DestroyXLogCollector(sHandle, NULL);
}

ALA_AddAuthInfo#

구문#

ALA_RC ALA_AddAuthInfo(
     ALA_Handle     aHandle,
     const SChar  * aAuthInfo,
     ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aHandle	XLog Collector 핸들
aAuthInfo	XLog Sender 인증 정보
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

XLog Sender 인증 정보를 추가한다.

접속 소켓 타입이 TCP인 경우, aAuthInfo는 "PEER_IP=xlog_sender_ip" 형식의 문자열이다. xlog_sender_ip의 허용 길이는 1 ~ 39 bytes이다.

주의사항#

Socket Type을 TCP로 지정한 경우에만 사용할 수 있다.
XLog Sender 인증 정보는 32개까지 지정할 수 있다.

예제#

ALA_CreateXLogCollector를 참고한다.

ALA_RemoveAuthInfo#

구문#

ALA_RC ALA_RemoveAuthInfo(
     ALA_Handle     aHandle,
     const SChar  * aAuthInfo,
     ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aHandle	XLog Collector 핸들
aAuthInfo	XLog Sender 인증 정보
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

XLog Sender 인증 정보를 제거한다.

접속 소켓 타입이 TCP인 경우, aAuthInfo는 "PEER_IP=xlog_sender_ip" 형식의 문자열이다. xlog_sender_ip의 허용 길이는 1 ~ 39 이다.

주의사항#

Socket Type을 TCP로 지정한 경우에만 사용할 수 있다.
XLog Sender 인증 정보는 최소 하나가 필요하다.

예제#

ALA_CreateXLogCollector를 참고한다.

ALA_SetHandshakeTimeout#

구문#

ALA_RC ALA_SetHandshakeTimeout(
     ALA_Handle     aHandle,
     UInt           aSecond,
     ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aHandle	XLog Collector 핸들
aSecond	Handshake Timeout (단위 : 초, 범위 : 1 ~ 0xFFFFFFFE)
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

Handshake의 Timeout을 지정한다.

ALA_Handshake()를 호출할 때, Handshake Timeout이 적용된다. Handshake Timeout의 기본값은 600초이다.

예제#

ALA_Handshake를 참고한다.

ALA_SetReceiveXLogTimeout#

구문#

ALA_RC ALA_SetReceiveXLogTimeout(
     ALA_Handle      aHandle,
     UInt              aSecond,
     ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aHandle	XLog Collector 핸들
aSecond	XLog 수신 Timeout (단위 : 초, 범위 : 1 ~ 0xFFFFFFFE)
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

XLog 수신 Timeout을 지정한다.

ALA_ReceiveXLog()를 호출할 때, XLog 수신 Timeout이 적용된다. XLog 수신 Timeout의 기본값은 10초이다.

예제#

ALA_Handshake를 참고한다.

ALA_SetXLogPoolSize#

구문#

ALA_RC ALA_SetXLogPoolSize (
     ALA_Handle      aHandle,
     SInt              aXLogPoolSize,
     ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aHandle	XLog Collector 핸들
aXLogPoolSize	XLog Pool의 크기
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

XLog Collector가 가지고 있는 XLog Pool의 크기를 변경한다.

예제#

#include <alaAPI.h>
…

int main()
{
    ALA_Handle sHandle;
    ALA_XLog * sXLog = NULL;
    ALA_XLogHeader * sXLogHeader = NULL;
    ALA_XLogCollectorStatus sXLogCollectorStatus;
    ALA_BOOL sInsertXLogInQueue = ALA_FALSE;
    ALA_BOOL sExitFlag = ALA_FALSE;


    /* TCP를 사용하는 XLog Collector 생성
    * XLog Sender의 이름                    : log_analysis
    * XLog Sender의 인증 정보               : IP=127.0.0.1
    * 접속 대기 PORT                        : 30300
    * XLog Pool의 최대 크기                 : 10000
    * Commit 순서로 Transaction의 XLog 얻기 : 미지정
    * 실제로 ACK를 보낼 기준 XLog 수        : 100
    */
    (void)ALA_CreateXLogCollector("log_analysis",
                "SOCKET=TCP;PEER_IP=127.0.0.1;MY_PORT=30300",
                10000,
                ALA_FALSE,
                100,
                &sHandle,
                NULL);

    ...    

    /* XLog Sender가 종료될 때까지 XLog 수신 */
    while(sExitFlag != ALA_TRUE)
    {
        /* XLog 수신 및 XLog Queue에 추가 */
        sInsertXLogInQueue = ALA_FALSE;
        while(sInsertXLogInQueue != ALA_TRUE)
        {
            if(ALA_ReceiveXLog(aHandle, &sInsertXLogInQueue, NULL) != ALA_SUCCESS)
            {
                if(sErrorCode == 0x52033)   /* XLog Pool Empty */
                {
                    if(ALA_SetXLogPoolSize(aHandle,
                                20000, /* Increase XLog Pool Size */
                                aErrorMgr)
                                != ALA_SUCCESS)
                    {
                        return -1;
                    }
                    continue;
                }
            }
        }
        /* XLog Queue에서 XLog 얻기
        * 로그 레코드가 기록된 순서로 Transaction의 XLog 얻는 경우를 가정
        */
        (void)ALA_GetXLog(aHandle, &sXLog, NULL);

        /* XLog 분석 및 처리 */
        (void)ALA_GetXLogHeader(sXLog, &sXLogHeader, NULL);
        if(sXLogHeader->mType == XLOG_TYPE_REPL_STOP)
        {
            sExitFlag = ALA_TRUE;
        }
        ...

        /* XLog Sender에게 ACK 전송 */
        (void)ALA_SendACK(aHandle, NULL);

        /* XLog를 XLog Pool에 반환 */
        (void)ALA_FreeXLog(aHandle, sXLog, NULL);

        /* XLog Collector의 상태 얻기 */
        (void)ALA_GetXLogCollectorStatus(aHandle,
                    &sXLogCollectorStatus,
                    NULL);
    }
    ...
    /* XLog Collector 제거 */
    (void)ALA_DestroyXLogCollector(sHandle, NULL);

    return 0;
}

ALA_Handshake#

구문#

ALA_RC ALA_Handshake(
     ALA_Handle      aHandle,
     ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aHandle	XLog Collector 핸들
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

XLog Sender의 접속을 대기하고, Handshake를 수행한다.

사용자 설정 정보와 XLog Pool을 제외한, 모든 XLog Collector 내의 데이터를 초기화한다.

대상 테이블들의 메타 정보를 수신하고 내부에 저장한다.

주의사항#

TCP를 사용할 경우, 일치하는 인증 정보가 없으면 실패한다.
접속한 Peer가 XLog Sender가 아니면 실패한다.
Handshake Timeout 동안 XLog Sender가 접속하지 않으면, Timeout이 발생한다.
Handshake가 완료되기 전에 ALA_ReceiveXLog(), ALA_GetXLog(), ALA_SendACK()을 호출하면 안 된다.
Handshake를 시작하기 전에 ALA_GetXLog()로 얻은 모든 XLog에 대해 ALA_FreeXLog()를 수행하여, XLog Pool이 고갈되지 않도록 해야 한다.

예제#

#include <alaAPI.h>
…

void testXLogCollector(ALA_Handle aHandle)
{
    ALA_XLog                * sXLog                = NULL;
    ALA_XLogHeader          * sXLogHeader          = NULL;
    ALA_XLogCollectorStatus   sXLogCollectorStatus;
    ALA_BOOL                  sInsertXLogInQueue   = ALA_FALSE;
    ALA_BOOL                  sExitFlag            = ALA_FALSE;

    /* Handshake Timeout 설정 : 600 초 */
    (void)ALA_SetHandshakeTimeout(aHandle, 600, NULL);

    /* XLog 수신 Timeout 설정 : 10 초 */
    (void)ALA_SetReceiveXLogTimeout(aHandle, 10, NULL);

    /* XLog Sender 접속 대기 및 Handshake */
    (void)ALA_Handshake(aHandle, NULL);

    /* XLog Sender가 종료될 때까지 XLog 수신 */
    while(sExitFlag != ALA_TRUE)
    {
        /* XLog 수신 및 XLog Queue에 추가 */
        sInsertXLogInQueue = ALA_FALSE;
        while(sInsertXLogInQueue != ALA_TRUE)
        {
            (void)ALA_ReceiveXLog(aHandle, &sInsertXLogInQueue, NULL);
        }

        /* XLog Queue에서 XLog 얻기
        * 로그 레코드가 기록된 순서로 Transaction의 XLog 얻는 경우를 가정
        */
        (void)ALA_GetXLog(aHandle, &sXLog, NULL);

        /* XLog 분석 및 처리 */
        (void)ALA_GetXLogHeader(sXLog, &sXLogHeader, NULL);
        if(sXLogHeader->mType == XLOG_TYPE_REPL_STOP)
        {
            sExitFlag = ALA_TRUE;
        }
        …

        /* XLog Sender에게 ACK 전송 */
        (void)ALA_SendACK(aHandle, NULL);

        /* XLog를 XLog Pool에 반환 */
        (void)ALA_FreeXLog(aHandle, sXLog, NULL);

        /* XLog Collector의 상태 얻기 */
        (void)ALA_GetXLogCollectorStatus(aHandle,
                                        &sXLogCollectorStatus,
                                            NULL);
    }
}

ALA_ReceiveXLog#

구문#

ALA_RC ALA_ReceiveXLog(  
     ALA_Handle aHandle,  
     ALA_BOOL * aOutInsertXLogInQueue,  
     ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aHandle	XLog Collector 핸들
aOutInsertXLogInQueue	수신한 XLog가 XLog Queue에 추가되었는지 여부를 알려줌
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

XLog를 수신하여 XLog Queue에 XLog를 추가한다.

XLog를 저장할 메모리는 XLog Pool에서 얻는다.

Commit 순서로 Transaction의 XLog를 얻을 경우, Transaction 관련 XLog는 COMMIT XLog가 수신될 때까지 Transaction Table에 보관된다.

ALA_GetXLog()와 동시에 호출할 수 있다.

주의사항#

ALA_Handshake()를 먼저 호출해야 하며, ALA_Handshake() 성공 후에 네트워크 에러가 발생하면, 이 함수 호출은 실패한다.
XLog 수신 Timeout 동안 XLog가 수신되지 않으면, Timeout이 발생한다.
XLog Pool에 가용한 XLog가 없으면 실패한다.
Commit 순서로 Transaction의 XLog를 얻을 경우, XLog가 수신되어도 XLog Queue에 추가되지 않을 수 있다.
네트워크 에러가 발생하거나 REPL_STOP XLog을 수신한 경우, 이전에 수신해서 대상 데이터베이스에 적용은 했으나 Commit하지 않은 Transaciton을 Rollback해야 한다.
aOutInsertXLogInQueue의 메모리는 미리 할당해야 한다.

예제#

ALA_Handshake를 참고한다.

ALA_GetXLog#

구문#

ALA_RC ALA_GetXLog(
        ALA_Handle          aHandle,
        const ALA_XLog ** aOutXLog,
        ALA_ErrorMgr     * aOutErrorMgr);

인자#

인 자	설 명
aHandle	XLog Collector 핸들
aOutXLog	XLog Queue에서 얻은 XLog
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

XLog Queue에서 XLog를 얻는다.

ALA_ReceiveXLog()와 동시에 호출할 수 있다.

XLog Queue에 XLog가 없으면, aOutXLog는 NULL이다.

주의사항#

ALA_FreeXLog()를 호출하기 전까지 XLog는 사용자 애플리케이션에서 관리해야 한다.

예제#

ALA_Handshake를 참고한다.

ALA_SendACK#

구문#

ALA_RC ALA_SendACK(
        ALA_Handle      aHandle,
        ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aHandle	XLog Collector 핸들
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

ACK를 XLog Sender에게 전송한다.

이 함수를 호출할 때 바로 ACK를 XLog Sender에게 보내는 것이 아니라, 실제로 ACK를 보낼 기준 XLog 수 이상의 ALA_GetXLog()가 성공하거나, KEEP_ALIVE 또는 REPL_STOP XLog가 수신된 기록이 있을 때, ACK를 XLog Sender에게 전송한다.

REPL_STOP XLog가 수신된 기록이 있으면, 네트워크 연결을 종료한다.

ACK메시지에는 Restart SN이 포함되어 있다. Restart SN은 아래의 SN 중에서 최소 값으로 결정된다.

마지막으로 ALA_GetXLog()를 호출한 시점에서 확인된 Active Transaction들 중 최소 XLog SN
Active Transaction이 하나도 없는 경우, ALA_GetXLog()로 얻은 마지막 XLog의 SN
Commit 순서로 Transaction의 XLog를 얻는 경우, Transaction Table 내부에 보관 중인 Commit되지 않은 Transaction들 중 최소 XLog SN

주의사항#

XLog Sender의 Meta Table, Flush 등에 영향을 준다. XLog Sender의 REPLICATION_RECEIVE_TIMEOUT 프라퍼티로 지정한 시간이 지나도록 ACK를 전송하지 않으면, XLog Sender는 네트워크 연결을 끊는다. 또한, 장기간 ACK를 전송하지 않으면, XLog Sender가 XLog 전송을 포기한 후 Restart SN을 가장 최근에 기록된 로그 레코드의 SN으로 갱신하고 다시 시작할 수 있다.
XLog Sender에서 ACK을 받으면 XLog Sender의 Restart SN이 갱신될 수 있기 때문에, ALA_SendACK()를 호출하기 전에 ALA_GetXLog()로 얻은 XLog를 모두 처리해야 한다.
네트워크 에러가 발생한 경우, XLog Sender는 Handshake를 주기적으로 시도하고, Handshake가 성공하면 XLog를 Restart SN부터 다시 전송한다.

예제#

ALA_Handshake를 참고한다.

ALA_FreeXLog#

구문#

ALA_RC ALA_FreeXLog(
     ALA_Handle      aHandle,
     ALA_XLog      * aXLog,
     ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aHandle	XLog Collector 핸들
aXLog	XLog Pool에 반환할 XLog
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

XLog를 XLog Pool에 반환한다.

주의사항#

ALA_GetXLog()에서 얻은 XLog를 장기간 반환하지 않으면, XLog Pool이 고갈될 수 있다.

예제#

ALA_Handshake를 참고 한다.

ALA_DestroyXLogCollector#

구문#

ALA_RC ALA_DestroyXLogCollector(
        ALA_Handle      aHandle,
        ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aHandle	XLog Collector 핸들
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

XLog Collector를 제거한다.

주의사항#

호출하기 전에 ALA_GetXLog()에서 얻은 모든 XLog에 대해 ALA_FreeXLog()를 수행해야 한다.

결과에 관계 없이, 해당 XLog Collector을 인자로 써서 Log Analysis API를 호출하면 안 된다.

예제#

ALA_CreateXLogCollector를 참고한다.

ALA_GetXLogCollectorStatus#

구문#

ALA_RC ALA_GetXLogCollectorStatus(
       ALA_Handle                     aHandle,
       ALA_XLogCollectorStatus * aOutXLogCollectorStatus,
       ALA_ErrorMgr                * aOutErrorMgr);

인자#

인 자	설 명
aHandle	XLog Collector 핸들
aOutXLogCollectorStatus	XLog Collector의 상태를 저장하는 구조체
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

XLog Collector의 상태를 얻는다.

XLog Collector의 상태를 저장하는 구조체는 아래와 같이 정의된다.

typedef struct ALA_XLogCollectorStatus
{
    SChar       mMyIP[ALA_IP_LEN];
    SInt        mMyPort;
    SChar       mPeerIP[ALA_IP_LEN];
    SInt        mPeerPort;
    SChar       mSocketFile[ALA_SOCKET_FILENAME_LEN];
    UInt        mXLogCountInPool;
    ALA_SN      mLastArrivedSN;
    ALA_SN      mLastProcessedSN;
    ALA_BOOL    mNetworkValid;
} ALA_XLogCollectorStatus;

구조체 멤버	설 명
mMyIP	[TCP] XLog Collector의 IP 주소
mMyPort	[TCP] XLog Collector의 Port 번호
mPeerIP	[TCP] XLog Sender의 IP 주소
mPeerPort	[TCP] XLog Sender의 Port 번호
mSocketFile	[UNIX Domain] Socket 파일 이름
mXLogCountInPool	XLog Pool에 남은 XLog의 수
mLastArrivedSN	마지막으로 수신한 XLog의 SN
mLastProcessedSN	마지막으로 처리한 XLog의 SN
mNetworkValid	네트워크 연결의 유효 여부

이 구조체에 포함된 상태값들은 Log Analyzer 내부에서 따로 관리되며, 이 함수를 호출할 때 저장하고 있던 상태값을 반환한다.

mMyIP, mMyPort, mPeerIP, mPeerPort, mSocketFile에 해당하는 내부 상태값은 ALA_Handshake()에서 갱신된다.

mXLogCountInPool에 해당하는 내부 상태값은 ALA_ReceiveXLog()에서 증가 (ROLLBACK XLog를 수신했을 때) 또는 감소하고, ALA_FreeXLog()에서 증가한다.

mLastArrivedSN 은 ALA_ReceiveXLog()으로 수신한 마지막 XLog의 SN이고, mLastProcessedSN은 ALA_GetXLog()로 얻은 마지막 XLog의 SN이다.

mNetworkValid 에 해당하는 내부 상태값은 ALA_Handshake(), ALA_ReceiveXLog(), ALA_SendACK() 등을 호출할 때 변경될 수 있다.

주의사항#

aOutXLogCollectorStatus의 메모리는 이 함수 호출 전에 할당되어야 한다.

예제#

ALA_Handshake를 참고한다.

ALA_GetXLogHeader#

구문#

ALA_RC ALA_GetXLogHeader(
        const ALA_XLog          * aXLog,
        const ALA_XLogHeader ** aOutXLogHeader,
        ALA_ErrorMgr             * aOutErrorMgr);

인자#

인 자	설 명
aXLog	Header를 얻어 올 XLog
aOutXLogHeader	aXLog의 XLog eader
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

주어진 XLog에서 XLog Header를 얻는다.

예제#

#include <alaAPI.h>
…

void testXLogGetPart(const ALA_XLog * aXLog)
{
    ALA_XLogHeader     * sXLogHeader     = NULL;
    ALA_XLogPrimaryKey * sXLogPrimaryKey = NULL;
    ALA_XLogColumn     * sXLogColumn     = NULL;
    ALA_XLogSavepoint  * sXLogSavepoint  = NULL;
    ALA_XLogLOB        * sXLogLOB        = NULL;

    /* XLog Header 얻기 */
    (void)ALA_GetXLogHeader(aXLog, &sXLogHeader, NULL);

    /* XLog Primary Key 얻기 */
    (void)ALA_GetXLogPrimaryKey(aXLog, &sXLogPrimaryKey, NULL);

    /* XLog Column 얻기 */
    (void)ALA_GetXLogColumn(aXLog, &sXLogColumn, NULL);

    /* XLog Savepoint 얻기 */
    (void)ALA_GetXLogSavepoint(aXLog, &sXLogSavepoint, NULL);

    /* XLog LOB 얻기 */
    (void)ALA_GetXLogLOB(aXLog, &sXLogLOB, NULL);
}

ALA_GetXLogPrimaryKey#

구문#

ALA_RC ALA_GetXLogPrimaryKey(
        const ALA_XLog               * aXLog,
        const ALA_XLogPrimaryKey    ** aOutXLogPrimaryKey,
        ALA_ErrorMgr                 * aOutErrorMgr);

인자#

인 자	설 명
aXLog	XLog Primary Key를 얻어 올 XLog
aOutXLogPrimaryKey	aXLog의 XLog Primary Key
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

주어딘 XLog에서 XLog Primary Key를 얻는다.

예제#

ALA_GetXLogHeader를 참고한다.

ALA_GetXLogColumn#

구문#

ALA_RC ALA_GetXLogColumn(
        const ALA_XLog        * aXLog,
        const ALA_XLogColumn ** aOutXLogColumn,
        ALA_ErrorMgr          * aOutErrorMgr);

인자#

인 자	설 명
aXLog	XLog Column을 얻어 올 XLog
aOutXLogColumn	aXLog의 XLog Column
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

주어진 XLog에서 XLog Column를 얻는다.

예제#

ALA_GetXLogHeader를 참고한다.

ALA_GetXLogSavepoint#

구문#

ALA_RC ALA_GetXLogSavepoint(
        const ALA_XLog           * aXLog,
        const ALA_XLogSavepoint ** aOutXLogSavepoint,
        ALA_ErrorMgr             * aOutErrorMgr);

인자#

인 자	설 명
aXLog	XLog Savepoint를 얻어 올 XLog
aOutXLogSavepoint	aXLog의 XLog Savepoint
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

주어진 XLog에서 XLog Savepoint를 얻는다.

예제#

ALA_GetXLogHeader를 참고한다.

ALA_GetXLogLOB#

구문#

ALA_RC ALA_GetXLogLOB(
        const ALA_XLog       * aXLog,
        const ALA_XLogLOB   ** aOutXLogLOB,
        ALA_ErrorMgr         * aOutErrorMgr);

인자#

인 자	설 명
aXLog	XLog LOB을 얻어 올 XLog
aOutXLogLOB	aXLog의 XLog LOB
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

주어진 XLog에서 XLog LOB를 얻는다.

예제#

ALA_GetXLogHeader를 참고한다.

ALA_GetProtocolVersion#

구문#

ALA_RC ALA_GetProtocolVersion(
         const ALA_ProtocolVersion * aOutProtocolVersion,
         ALA_ErrorMgr              * aOutErrorMgr);

인자#

인 자	설 명
aOutProtocolVersion	Protocol Version 구조체
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

Log Analysis API의 Protocol Version을 얻는다.

Handshake와 관계없이 Protocol Version을 얻을 수 있다.

주의사항#

aOutProtocolVersion의 메모리를 함수 호출전에 할당해야 한다.

예제#

#include <alaAPI.h>
…

void testProtocolVersion()
{
    ALA_ProtocolVersion sProtocolVersion;

    /* Protocol Version 정보 얻기 */
    (void)ALA_GetProtocolVersion(&sProtocolVersion, NULL);
}

ALA_GetReplicationInfo#

구문#

ALA_RC ALA_GetReplicationInfo(
        ALA_Handle                 aHandle,
        const ALA_Replication   ** aOutReplication,
        ALA_ErrorMgr             * aOutErrorMgr);

인자#

인 자	설 명
aHandle	XLog Collector 핸들
aOutReplication	Replication 정보
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

이중화에 대한 정보를 얻는다.

주의사항#

주어진 이중화에 대한 메타 정보가 없으면, aOutReplication 인자로 NULL을 반환한다.
Handshake 전에 얻은 메타 정보를 계속 사용하면 안 된다.

예제#

#include <alaAPI.h>
…

void testMetaInformation(ALA_Handle aHandle)
{
    ALA_Replication * sReplication     = NULL;
    ALA_Table       * sTable           = NULL;
    ALA_Table       * sTableByTableOID = NULL;
    ALA_Table       * sTableByName     = NULL;
    ALA_Column      * sPKColumn        = NULL;
    ALA_Column      * sColumn          = NULL;
    ALA_Index       * sIndex           = NULL;
    UInt              sTablePos;
    UInt              sPKColumnPos;
    UInt              sColumnPos;
    UInt              sIndexPos;

    /* Replication 정보 얻기 */
    (void)ALA_GetReplicationInfo(aHandle, &sReplication, NULL);

    for(sTablePos = 0; sTablePos < sReplication->mTableCount; sTablePos++)
    {
        sTable = &(sReplication->mTableArray[sTablePos]);

        /* Table OID로 Table 정보 얻기 */
        (void)ALA_GetTableInfo(aHandle,
            sTable->mTableOID,
            &sTableByTableOID,
            NULL);

        if(sTableByTableOID != sTable)
        {
            /* 치명적인 오류 : Log Analysis API에 문제가 있음 */
            break;
        }

        /* 이름으로 Table 정보 얻기 */
        (void)ALA_GetTableInfoByName(aHandle,
            sTable->mFromUserName,
            sTable->mFromTableName,
            &sTableByName,
            NULL);

        if(sTableByName != sTable)
        {
            /* 치명적인 오류 : Log Analysis API에 문제가 있음 */
            break;
        }

        /* Primary Key Column 처리 */
        for(sPKColumnPos = 0; sPKColumnPos < sTable->mPKColumnCount; sPKColumnPos++)
        {         /* Primary Key Column ID로 Primary Key Column 정보 얻기 */

            (void)ALA_GetColumnInfo(sTable,
                sTable->mPKColumnArray[sPKColumnPos]->mColumnID,
                &sPKColumn,
                NULL);

            if(sPKColumn != sTable->mPKColumnArray[sPKColumnPos])
            {    /* 치명적인 오류 : Log Analysis API에 문제가 있음 */
                break;
            }

           /* Primary Key Column 처리 */
            …
        }

        /* Column 처리 */

        for(sColumnPos = 0; sColumnPos < sTable->mColumnCount; sColumnPos++)
        {        /* Column ID로 Column 정보 얻기 */
            (void)ALA_GetColumnInfo(sTable,
                sTable->mColumnArray[sColumnPos].mColumnID,
                &sColumn,
                NULL);

            if(sColumn != &(sTable->mColumnArray[sColumnPos]))
            {      /* 치명적인 오류 : Log Analysis API에 문제가 있음 */
                break;
            }

            /* Column 처리 */
            …
        }

        /* Index 처리 */
        for(sIndexPos = 0; sIndexPos < sTable->mIndexCount; sIndexPos++)
        {        /* Index ID로 Index 정보 얻기 */
            (void)ALA_GetIndexInfo(sTable,
                sTable->mIndexArray[sIndexPos].mIndexID,
                &sIndex,
                NULL);

            if(sIndex != &(sTable->mIndexArray[sIndexPos]))
            {        /* 치명적인 오류 : Log Analysis API에 문제가 있음 */
                break;
            }

            /* Index 처리 */
            …
        }
    }
}

ALA_GetTableInfo#

구문#

ALA_RC ALA_GetTableInfo(
        ALA_Handle            aHandle,
        ULong                  aTableOID,
        const ALA_Table  ** aOutTable,
        ALA_ErrorMgr       * aOutErrorMgr);

인자#

인 자	설 명
aHandle	XLog Collector 핸들
aTableOID	정보를 검색할 Table의 OID
aOutTable	Table 정보
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

주어진 Table OID로 Table 정보를 검색한다.

주의사항#

주어진 테이블의 메타 정보가 없으면, aOutTable 인자로 NULL을 반환한다.
Handshake 전에 얻은 메타 정보를 계속 사용하면 안 된다.

예제#

ALA_GetReplicationInfo를 참고한다.

ALA_GetTableInfoByName#

구문#

ALA_RC ALA_GetTableInfoByName(
      ALA_Handle            aHandle,
      const SChar        * aFromUserName,
      const SChar        * aFromTableName,
      const ALA_Table   ** aOutTable,
      ALA_ErrorMgr       * aOutErrorMgr);

인자#

인 자	설 명
aHandle	XLog Collector 핸들
aFromUserName	정보를 검색할 테이블의 소유자 이름
aFromTableName	정보를 검색할 테이블 이름
aOutTable	Table 정보
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

주어진 사용자 이름과 테이블 이름으로 테이블 정보를 검색한다.

주의사항#

해당 테이블의 메타 정보가 없으면, aOutTable 인자로 NULL을 반환한다.
Handshake 전에 얻은 메타 정보를 계속 사용하면 안 된다.

예제#

ALA_GetReplicationInfo를 참고한다.

ALA_GetColumnInfo#

구문#

ALA_RC ALA_GetColumnInfo(
       const ALA_Table    * aTable,
       UInt                 aColumnID,
       const ALA_Column  ** aOutColumn,
       ALA_ErrorMgr       * aOutErrorMgr);

인자#

인 자	설 명
aTable	검색할 칼럼이 속해 있는 테이블의 메타 정보
aColumnID	정보를 검색할 칼럼의 Column ID
aOutColumn	Column 정보
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

Column ID로 테이블에서 컬럼 정보를 검색한다.

주의사항#

해당 칼럼의 메타 정보가 없으면, aOutColumn 인자로 NULL을 반환한다.
Handshake 전에 얻은 메타 정보를 계속 사용할 수 없다.

예제#

ALA_GetReplicationInfo를 참고한다.

ALA_GetIndexInfo#

구문#

ALA_RC ALA_GetIndexInfo(
        const ALA_Table  * aTable,
        UInt               aIndexID,
        const ALA_Index ** aOutIndex,
        ALA_ErrorMgr     * aOutErrorMgr);

인자#

인 자	설 명
aTable	검색할 인덱스를 포함하는 테이블의 메타 정보
aIndexID	검색할 인덱스의 Index ID
aOutIndex	Index 정보
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

주어진 Index ID로 테이블에서 인덱스 정보를 검색한다.

주의사항#

해당 인덱스의 메타 정보가 없으면, aOutIndex 인자로 NULL을 반환한다.
Handshake 전에 얻은 Meta 정보를 계속 사용하면 안 된다.

예제#

ALA_GetReplicationInfo를 참고한다.

ALA_IsHiddenColumn#

구문#

ALA_RC ALA_GetReplicationInfo(
     ALA_Column   * aColumn,
     ALA_BOOL     * aIsHiddenColumn,
     ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aColumn	Column 정보
aIsHiddenColumn	HiddenColumn 여부
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

Column ID로 검색한 컬럼이 숨겨진 컬럼인지 아닌지를 알아낸다.

주의사항#

Handshake 전에 얻은 메타 정보를 계속 사용하면 안된다.

예제#

#include <alaAPI.h>
…

void testColumnInformation(ALA_Handle aHandle)
 {
     ALA_Replication * sReplication = NULL;
     ALA_Table * sTable = NULL;
     ALA_Column * sColumn = NULL;
     ALA_BOOL    sIsHiddenColumn = ALA_FALSE;
     UInt sColumnPos;


     /* Replication 정보 얻기 */
     (void)ALA_GetReplicationInfo(aHandle, &sReplication, NULL);
     for(sTablePos = 0; sTablePos < sReplication->mTableCount; sTablePos++)
     {
         sTable = &(sReplication->mTableArray[sTablePos]);
         /* Table OID로 Table 정보 얻기 */
         (void)ALA_GetTableInfo( aHandle,
                             sTable->mTableOID,
                             &sTableByTableOID,
                             NULL);
         if(sTableByTableOID != sTable)
         {
             /* 치명적인 오류 : Log Analysis API에 문제가 있음 */
             break;
         }

         /* 이름으로 Table 정보 얻기 */
         (void)ALA_GetTableInfoByName(aHandle,
                         sTable->mFromUserName,
                         sTable->mFromTableName,
                         &sTableByName,
                         NULL);
         if(sTableByName != sTable)
         {
             /* 치명적인 오류 : Log Analysis API에 문제가 있음 */
             break;
         }

         /* Column 처리 */
         for(sColumnPos = 0; sColumnPos < sTable->mColumnCount; sColumnPos++)
         { /* Column ID로 Column 정보 얻기 */
             (void)ALA_GetColumnInfo(sTable,
                             sTable->mColumnArray[sColumnPos].mColumnID,
                             &sColumn,
                             NULL);
             if( sColumn != &(sTable->mColumnArray[sColumnPos]) )
             { /* 치명적인 오류 : Log Analysis API에 문제가 있음 */
                 break;
             }
             /* Column 처리 */
             (void)ALA_IsHiddenColumn( sColumn, &sIsHiddenColumn, NULL );
             if( sIsHiddenColumn != ALA_TRUE )
             {
                 /* Column 처리 */
             }
             else
             {
                 /* Hidden Column 처리 */
             }
         }

         ...
     }
}

ALA_GetInternalNumericInfo#

구문#

ALA_RC ALA_GetInternalNumericInfo(
        ALA_Column  * aColumn,
        ALA_Value    * aAltibaseValue,
        SInt           * aOutSign,
        SInt           * aOutExponent,
        ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aColumn	칼럼의 메타 정보
aAltibaseValue	Altibase 내부 포맷으로 저장된 데이터
aOutSign	부호
aOutExponent	지수
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

Altibase 내부 포맷으로 저장된 FLOAT, NUMERIC 타입 데이터의 부호와 지수를 얻는다.

aOutSign이 1이면 양수를 나타내고, 0이면 음수를 나타낸다.

aOutExponent는 밑수가 10진수인 수에 대한 지수이다.

예제#

#include <alaAPI.h>
…

void testInternalNumeric(ALA_Column * aColumn, ALA_Value * aAltibaseValue)
{
    SInt sNumericSign;
    SInt sNumericExponent;

    /* 내부 Numeric 정보 얻기 */
    (void)ALA_GetInternalNumericInfo(aColumn,
                                     aAltibaseValue,
                                     &sNumericSign,
                                     &sNumericExponent,
                                     NULL);
}

ALA_GetAltibaseText#

구문#

ALA_RC ALA_GetAltibaseText(
        ALA_Column   * aColumn,
        ALA_Value    * aValue,
        UInt           aBufferSize,
        SChar        * aOutBuffer,
        ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aColumn	칼럼의 메타 정보
aValue	Altibase 내부 포맷으로 저장된 데이터
aBufferSize	aOutBuffer 버퍼의 크기
aOutBuffer	문자열을 반환할 버퍼
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

Altibase 내부 포맷으로 저장된 데이터를 문자열로 변환한다.

시간/날짜의 경우, 반환되는 문자열의 포맷은 "YYYY-MM-DD HH:MI:SS.SSSSSS"이다.

BIT타입 데이터는 BIT'value' 형식으로 변환하고, VARBIT타입 데이터는 VARBIT'value' 형식으로 변환한다.

NCHAR 또는 NVARCHAR타입의 데이터는 무조건 UCS-2(UTF-16) Character Set으로 변환한다.

주의사항#

NCHAR 또는 NVARCHAR타입의 데이터를 사용할 경우, 분석 서버(XLog Collector측)의 ALTIBASE_ALA_NCHARSET 환경 변수를 로그 분석 대상 서버(XLog Sender 측)의 국가 문자 집합(National Character Set)과 같은 값으로 설정해야 한다. 이는 분석 서버(XLog Collector측)에서 Character encoding변환 시 필요하다.

예를 들어, 대상 서버(XLog Sender 측)의 문자 집합이 UTF8이면, 분석 서버(XLog Collector측)의 환경 변수를 아래처럼 설정한다.

export ALTIBASE_ALA_NCHARSET=UTF8;

NCHAR, NVARCHAR타입 데이터에 대한 ALA_GetAltibaseText호출 시, aOutBuffer에는 UCS-2(UTF-16) character set으로 변환되어서 반환된다.

예:

\\0031\\0020\\0020\\0020

BLOB, CLOB, GEOMETRY 타입의 데이터는 지원하지 않는다.

예제#

#include <alaAPI.h>
…

void testAltibaseText(ALA_Table * aTable, ALA_XLog * aXLog)
{
    SChar        sBuffer[1024];

    /* Altibase SQL 얻기 */
    (void)ALA_GetAltibaseSQL(aTable,
                             aXLog,
                             1024,
                             sBuffer,
                             NULL);
}

ALA_GetAltibaseSQL#

구문#

ALA_RC ALA_GetAltibaseSQL(
        ALA_Table     * aTable,
        ALA_XLog      * aXLog,
        UInt            aBufferSize,
        SChar         * aOutBuffer,
        ALA_ErrorMgr  * aOutErrorMgr);

인자#

인 자	설 명
aTable	XLog와 관련된 테이블 정보
aXLog	XLog
aBufferSize	버퍼 크기
aOutBuffer	버퍼
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

XLog를 Altibase SQL 문자열로 변환한다.

시간/날짜의 경우, 반환되는 문자열의 포맷은 'YYYY-MM-DD HH:MI:SS.SSSSSS'이다.

BIT타입 데이터는 BIT'value' 형식으로 변환하고, VARBIT타입 데이터는 VARBIT'value' 형식으로 변환한다.

NCHAR, NVARCHAR타입 데이터는 UNISTR('value') 형식으로 변환한다.

XLog로부터 Insert, Update, Delete SQL구문을 생성할 때, aTable의 mToUserName과 mToTableName을 참조하여 SQL 문 내의 대상 Table을 지정한다.

주의사항#

BLOB, CLOB, GEOMETRY 타입 데이터는 지원하지 않는다.
이 함수가 생성한 SQL 문은 다른 DBMS의 SQL과 호환되지 않을 수도 있다.

예제#

#include <alaAPI.h>
…

void testAltibaseSQL(ALA_Table * aTable, ALA_XLog * aXLog)
{
    ALA_Column * sColumn;
    SChar        sBuffer[1024];
    UInt         sPKColumnPos;
    UInt         sColumnPos;

    /* Primary Key Column 처리 */
    for(sPKColumnPos = 0;
        sPKColumnPos < aXLog->mPrimaryKey.mPKColCnt;
        sPKColumnPos++)
    {
        /* XLog의 Primary Key 순서와 Table의 Primary Key 순서는 동일 */
        sColumn = aTable->mPKColumnArray[sPKColumnPos];

        /* Altibase Text 얻기 */
        (void)ALA_GetAltibaseText(sColumn,
                                  &(aXLog->mPrimaryKey.mPKColArray[sPKColumnPos]),
                                  1024,
                                  sBuffer,
                                  NULL);
    }

    /* Column 처리 */
    for(sColumnPos = 0; sColumnPos < aXLog->mColumn.mColCnt; sColumnPos++)
    {
        /* Column 정보 얻기 */
        (void)ALA_GetColumnInfo(aTable,
                                aXLog->mColumn.mCIDArray[sColumnPos],
                                &sColumn,
                                NULL);

        /* Before Image의 Altibase Text 얻기 */
        (void)ALA_GetAltibaseText(sColumn,
                                  &(aXLog->mColumn.mBColArray[sColumnPos]),
                                  1024,
                                  sBuffer,
                                  NULL);

        /* After Image의 Altibase Text 얻기 */
        (void)ALA_GetAltibaseText(sColumn,
                                 &(aXLog->mColumn.mAColArray[sColumnPos]),
                                 1024,
                                 sBuffer,
                                 NULL);
    }
}

ALA_GetODBCCValue#

구문#

ALA_RC ALA_GetODBCCValue(
        ALA_Column   * aColumn,
        ALA_Value    * aAltibaseValue,
        SInt           aODBCCTypeID,
        UInt           aODBCCValueBufferSize,
        void         * aOutODBCCValueBuffer,
        ALA_BOOL     * aOutIsNull,
        UInt         * aOutODBCCValueSize,
        ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aColumn	칼럼의 메타 정보
aAltibaseValue	Altibase 내부 포맷으로 저장된 데이터
aODBCCTypeID	변환할 ODBC C Type
aODBCCValueBufferSize	결과 버퍼의 크기
aOutODBCCValueBuffer	결과 버퍼
aOutIsNull	변환할 데이터가 NULL인지 여부
aOutODBCCValueSize	변환된 ODBC C 값의 크기
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

Altibase 내부 포맷으로 저장된 데이터를 ODBC C 값으로 변환한다. 아래표는 지원하는 타입 변환을 보여준다.

Altibase Data(우) ODBC C Value(하)	SQL_C_CHAR	SQL_C_NUMERIC	SQL_C_BIT	SQL_C_STINYINT SQL_C_UTINYINT	SQL_C_SSHORT SQL_C_USHORT	SQL_C_SLONG SQL_C_ULONG	SQL_C_SBIGINT SQL_C_UBIGINT	SQL_C_FLOAT	SQL_C_DOUBLE	SQL_C_BINARY	SQL_C_TYPE_DATE SQL_C_TYPE_TIME SQL_C_TYPE_TIMESTAMP
FLOAT	○	○	○	○	○	○	○	○	○	○
NUMERIC	○	○	○	○	○	○	○	○	○	○
DOUBLE	○	○	○	○	○	○	○	○	○	○
REAL	○	○	○	○	○	○	○	○	○	○
BIGINT	○	○	○	○	○	○	○	○	○	○
INTEGER	○	○	○	○	○	○	○	○	○	○
SMALLINT	○	○	○	○	○	○	○	○	○	○
DATE	○									○	○
CHAR	○	○	○	○	○	○	○	○	○	○	○
VARCHAR	○	○	○	○	○	○	○	○	○	○	○
NCHAR	○	○	○	○	○	○	○	○	○	○	○
NVARCHAR	○	○	○	○	○	○	○	○	○	○	○
BYTE	○									○
NIBBLE	○									○
BIT	○	○	○	○	○	○	○	○	○	○
VARBIT	○	○	○	○	○	○	○	○	○	○

[표 4‑1] ODBC C Conversion

주의사항#

BLOB, CLOB, GEOMETRY 타입의 변환은 지원하지 않는다
ODBC 3.0 이후를 지원한다.

예제#

#include <alaAPI.h>
…

void testODBCCConversion(ALA_Table * aTable, ALA_XLog * aXLog)
{
    ALA_Column * sColumn;
    SChar        sBuffer[1024];
    ALA_BOOL     sIsNull;
    UInt         sODBCCValueSize;
    UInt         sPKColumnPos;

    /* Primary Key를 SQL_C_CHAR로 변환 */
    for(sPKColumnPos = 0;
        sPKColumnPos < aXLog->mPrimaryKey.mPKColCnt;
        sPKColumnPos++)
    {
        /* XLog의 Primary Key 순서와 Table의 Primary Key 순서는 동일 */
        sColumn = aTable->mPKColumnArray[sPKColumnPos];

        /* 내부 데이터를 SQL_C_CHAR로 변환 */
        (void)ALA_GetODBCCValue(sColumn,
                                &(aXLog->mPrimaryKey.mPKColArray[sPKColumnPos],
                                SQL_C_CHAR,
                                1024,
                                sBuffer,
                                &sIsNull,
                                &sODBCCValueSize,
                                NULL);
    }
}

ALA_IsNullValue#

구문#

ALA_RC ALA_IsNullValue(
        ALA_Column     * aColumn,
        ALA_Value      * aValue,
        ALA_BOOL       * aOutIsNull,
        ALA_ErrorMgr   * aOutErrorMgr );

인자#

인 자	설 명
aColumn	칼럼의 메타 정보
aValue	칼럼의 값
aOutIsNull	칼럼의 값이 NULL인지 판단한 결과
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

컬럼의 값이 NULL인지 판단한다.

주의 사항#

XLog로 넘어온 NULL값은 Altibase 내부에서 사용되는 포맷이어서 직접 해석이 불가능하므로, NULL여부를 알기 위해서는 이 함수를 사용해야 한다.

예제#

#include <alaAPI.h>
…

ALA_BOOL isAlaValueNull(  ALA_Column *aColumn,
                          ALA_Value  *aAlaValue,
                          ALA_BOOL   *aNullFlag)
{
    ALA_RC   sAlaRC  = ALA_SUCCESS;
    ALA_BOOL sIsNull = ALA_FALSE;
    /* TODO: ALA_GetIsNullValue() is not released. */
    sAlaRC= ALA_IsNullValue(aColumn,
                            aAlaValue,
                            &sIsNull,
                            NULL);
    if(sAlaRC != ALA_SUCCESSE)
    {
        return ALA_FAILURE;
    }
    if (sIsNull == ALA_TRUE)
    {
        *aNullFlag = ACP_TRUE;
    }
    else
    {
        *aNullFlag = ACP_FALSE;
    }
    return ALA_SUCCESS;
}

ALA_ClearErrorMgr#

구문#

ALA_RC ALA_ClearErrorMgr(
         ALA_ErrorMgr * aOutErrorMgr);

인자#

인 자	설 명
aOutErrorMgr	오류 관리자의 구조체

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

오류 관리자를 초기화한다.

주의사항#

해당 오류 관리자를 처음 사용하기 전에, 오류 관리자를 초기화해야 한다.

예제#

#include <alaAPI.h>
…

void testErrorHandling()
{
    ALA_ErrorMgr     sErrorMgr
    UInt             sErrorCode;
    ALA_ErrorLevel   sErrorLevel;
    SChar          * sErrorMessage;

    /* 오류 관리자 초기화 */
    (void)ALA_ClearErrorMgr(&sErrorMgr);

    /* Log Analysis API 호출 실패 */
    …

    /* Error Code 얻기 */
    (void)ALA_GetErrorCode(&sErrorMgr, &sErrorCode);

    /* Error Level 얻기 */
    (void)ALA_GetErrorLevel(&sErrorMgr, &sErrorLevel);

    /* Error Message 얻기 */
    (void)ALA_GetErrorMessage(&sErrorMgr, &sErrorMessage);
}

ALA_GetErrorCode#

구문#

ALA_RC ALA_GetErrorCode(
        const ALA_ErrorMgr * aErrorMgr,
        UInt                   * aOutErrorCode);

인자#

인 자	설 명
aErrorMgr	오류 관리자
aOutErrorCode	에러 코드

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

Error Code를 얻는다.

Error Code는 어떤 종류의 오류가 발생했는지를 판단할 수 있는 유일한 숫자 값이다.

주의사항#

aOutErrorCode 메모리는 함수 호출 전에 할당해야 한다.
ALA_ErrorMgr 구조체의 mErrorCode는 내부적으로 사용되는 값이므로, ALA_GetErrorCode()를 통해 Error Code를 얻어야 한다.

예제#

ALA_ClearErrorMgr를 참고한다.

ALA_GetErrorLevel#

구문#

ALA_RC ALA_GetErrorLevel(
        const ALA_ErrorMgr   * aErrorMgr,
        ALA_ErrorLevel       * aOutErrorLevel);

인자#

인 자	설 명
aErrorMgr	오류 관리자
aOutErrorLevel	Error Level

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

aErrorMgr 로부터 Error Level을 얻는다.

ALA_ERROR_FATAL은 치명적인 오류이므로, ALA_DestroyXLogCollector()를 호출하여 해당 XLog Collector를 종료해야 한다.

ALA_ERROR_ABORT는 XLog Collector가 비정상적인 상태임을 나타내므로, ALA_Handshake()를 호출하여 해당 XLog Collector의 Handshake를 다시 수행해야 한다.

ALA_ERROR_INFO는 Log Analysis API 호출이 실패했음을 나타낸다. Error Code에 따라 적절한 조치를 해야 한다.

주의사항#

aOutErrorLevel 메모리는 이 함수 호출 전에 할당해야 한다.

예제#

ALA_ClearErrorMgr를 참고한다.

ALA_GetErrorMessage#

구문#

ALA_RC ALA_GetErrorMessage(
        const ALA_ErrorMgr  * aErrorMgr,
        const SChar         ** aOutErrorMessage);

인자#

인 자	설 명
aErrorMgr	오류 관리자
aOutErrorMessage	Error Message

결과#

ALA_SUCCESS

ALA_FAILURE

설명#

aErrorMgr로부터 구체적인 Error Message를 얻는다.

주의사항#

aOutErrorMessage에는 Error Message의 포인터가 대입되므로, aOutErrorMessage 메모리를 할당할 필요가 없다.

예제#

ALA_ClearErrorMgr를 참고한다.

4. Log Analysis API#

ALA_InitializeAPI#

구문#

인자#

결과#

설명#

주의사항#

관련 함수#

예제#

ALA_DestroyAPI#

구문#

인자#

결과#

설명#

주의사항#

관련 함수#

예제#

ALA_EnableLogging#

구문#

인자#

결과#

설명#

주의사항#

관련 함수#

예제#

ALA_DisableLogging#

구문#

인자#

결과#

설명#

주의사항#

관련 함수#

예제#

ALA_CreateXLogCollector#

구문#

인자#

결과#

설명#

주의사항#

관련 함수#

예제#

ALA_AddAuthInfo#

구문#

인자#

결과#

설명#

주의사항#

관련 함수#

예제#

ALA_RemoveAuthInfo#

구문#

인자#

결과#

설명#

주의사항#

관련 함수#

예제#

ALA_SetHandshakeTimeout#

구문#

인자#

결과#

설명#

관련 함수#

예제#

ALA_SetReceiveXLogTimeout#

구문#

인자#

결과#

설명#

관련 함수#

예제#

ALA_SetXLogPoolSize#

구문#

인자#

결과#

설명#

관련 함수#

예제#

ALA_Handshake#

구문#