4. Log Analysis API#

This chapter describes how to use the Log Analysis API component of the Altibase Log Analyzer. The Log Analysis API is an API that is invoked by a client application. It provides functions for receiving XLogs from an XLog Sender and analyzing them. In the following function descriptions, any argument whose name begins with "aOut" is an output argument. All of the Log Analysis API functions, which are intended for use in the C and C++ languages, are described in detail in this chapter.

ALA_InitializeAPI#

Syntax#

ALA_RC ALA_InitializeAPI(
      ALA_BOOL       aUseAltibaseODBCDriver,
      ALA_ErrorMgr * aOutErrorMgr);

Arguments#

Argument	Description
aUseAltibaseODBCDriver	This indicates whether the ODBC driver of Altibase is being used.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This creates an environment in which the Log Analysis API can be invoked.

Considerations#

With the exception of ALA_ClearErrorMgr(), no other Log Analyzer API functions can be called before this function.
If execution of this function fails, it will be impossible to use the Log Analysis API.
When using the ODBC Driver of Altibase, it is necessary to call SQLAllocEnv() before calling this function.

ALA_DestroyAPI

Example#

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

/* When the Altibase ODBC driver is not used */
void testAPIEnvironment1()
{
/* Create Log Analysis API Environment */
(void)ALA_InitializeAPI(ALA_FALSE, NULL);
/* Invoke Log Analysis API */

...

/* Remove Log Analysis API Environment */
(void)ALA_DestroyAPI(ALA_FALSE, NULL);
}
/* When the Altibase ODBC driver is used */
void testAPIEnvironment2(ALA_BOOL aUseAltibaseODBCDriver)
{
SQLHENV sEnv = NULL;

/* Create Altibase ODBC Environment */
(void)SQLAllocEnv(&sEnv);
/* Create Log Analysis API Environment */
(void)ALA_InitializeAPI(ALA_TRUE, NULL);
/* Invoke Altibase ODBC API and Log Analysis API */

...

/* Remove Log Analysis API Environment */
(void)ALA_DestroyAPI(ALA_TRUE, NULL);
/* Remove Altibase ODBC Environment */
(void)SQLFreeEnv(sEnv);
}

ALA_DestroyAPI#

Syntax#

ALA_RC ALA_DestroyAPI(
        ALA_BOOL      aUseAltibaseODBCDriver,
        ALA_ErrorMgr * aOutErrorMgr);

Arguments#

Argument	Description
aUseAltibaseODBCDriver	This indicates whether the ODBC driver of Altibase was being used.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function terminates the environment that was created by calling ALA_InitializeAPI.

Considerations#

Regardless of the result value, it will be impossible to call any of the Log Analysis API functions after this function has been called.
When using the ODBC Driver of Altibase, this function must be called before SQLFreeEnv() is called, which is the last step in terminating the Log Analysis API environment.

ALA_InitializeAPI

Example#

Refer to ALA_InitializeAPI.

ALA_EnableLogging#

Syntax#

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

Argument#

Argument	Description
aLogDirectory	This is the log directory.
aLogFileName	This is the name of the log file.
aFileSize	This is the size of each log file.
aMaxFileNumber	This is the maximum number of completed log files.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function enables logging for help in tracking the cause of problems.

If this function is not called, logging will not be performed.

If there is no log file having the specified name, a new log file is created. If a log file having the specified name already exists, logs will be appended to the end of this log file.

If the size of this log file reaches aFileSize, the log file is renamed and a new log file having the specified name is created. The header of each log file contains a number ranging from 1 to aMaxFileNumber. The log file is renamed with reference to this number. For example, if the header of a log file named "analysis.log" contains the number 1 and the size of the log file reaches the size specified in aFileSize, the name of the log file is changed from "analysis.log" to "analysis.log-1", and a new log file, named "analysis.log" and having the number 2 in the header, is created.

The numbers in the log file headers start at 1 and are incremented by 1. If this number reaches aMaxFileNumber, the numbering restarts at 1. As a result, only the log file that is currently in use and the most recent aMaxFileNumber log files are kept.

Considerations#

The maximum length of the log directory and file name (including NULL character) is 1024bytes.
If logging has already been enabled, calling this function will result in an error.
Calling another Log Analysis API function while execution of this function is underway will cause unexpected behavior.
If the contents of the log file header are abnormal or unexpected, the log file is deleted and created again.
Setting the value of aFileSize to 0 will allow the log file to grow infinitely large, depending on system resources.

ALA_DisableLogging

Example#

#include <alaAPI.h>
...

void testLogging()
{
/*  Create Log Analysis API Environment  */
        (void)ALA_InitializeAPI(ALA_FALSE, NULL);

    /* Enable logging
     * Log Directory            : The current directory
     * Log File Name            : analysis.log
     * The Size of Log File Size   : 10 MB
     * The Max. Number of Previous Log Files : 10
 */
        (void)ALA_EnableLogging(".",
                               "analysis.log",
                                10 * 1024 * 1024,
                                10,
                                NULL);

    /* Invoke Log Analysis API  */
        ...

    /* Disable logging */
        (void)ALA_DisableLogging(NULL);

    /* Remove Log Analysis API Environment */
        (void)ALA_DestroyAPI(ALA_FALSE, NULL);
}

ALA_DisableLogging#

Syntax#

ALA_RC ALA_DisableLogging(  
      ALA_ErrorMgr * aOutErrorMgr);

Argument#

Argument	Description
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function disables logging.

Considerations#

If logging has not been enabled, calling this function will result in an error.
Calling another Log Analysis API function while execution of this function is underway will cause unexpected behavior.

ALA_EnableLogging

Example#

Please refer to ALA_EnableLogging.

ALA_CreateXLogCollector#

Syntax#

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

Arguments#

Argument	Description
aXLogSenderName	This is the name of the corresponding XLog Sender. (length: 1 - 40)
aSocketInfo	This is the socket type (TCP, UNIX Domain)
aXLogPoolSize	This is the maximum size of the XLog Pool. (unit: the number of XLogs; range: from 1 upwards)
aUseCommittedTxBuffer	This indicates whether to obtain transaction XLogs in the order in which they were committed.
aACKPerXLogCount	This is the actual number of XLogs for which ACK will be sent. (range: from 1 upwards)
aOutHandle	This is the handle for the XLog Collector.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function creates an XLog Collector that corresponds to the specified XLog Sender.

The name of the XLog Sender can be a duplicate name, that is, it can be the same name specified when another XLog collector was created.

aSocketInfo is a string having the format "SOCKET=socket_type;IP_STACK=xlog_ip_stack;PEER_IP=xlog_sender_ip;MY_PORT=listen_port", whereby:

socket_type can only be set to one of "TCP" or "UNIX." If it is set to "UNIX," a socket file having the path and name "$ALTIBASE_HOME/trc/rp-replication_name" is automatically created
xlog_sender_ip must be specified when socket_type is set to "TCP". The valid length is in the range from 1 to 39 bytes. This is the IP address of the XLog Sender. This information is required in order to authenticate the XLog Sender.
xlog_ip_stack can be specified when socket_type is set to "TCP". This indicates the kind of Internet Protocol Stack to be used.
If it is set to 0, an Internet Protocol Stack that supports only IPv4 will be used. If it is set to 1, a dual stack (i.e. an Internet Protocol Stack that supports both IPv4 and IPv6) will be used.
If the value is specified as 1, the Internet Protocol Stack, which supports only IPv6, is used.

aACKPerXLogCount is used when ALA_SendACK() is called.

Considerations#

The following must be taken into consideration when the transaction XLogs are obtained in the order in which transactions were committed:

Because XLogs for a given transaction accumulate in the transaction table until the corresponding COMMIT XLog arrives, the size of the XLog Pool must be set sufficiently large. In other words, more memory space is required.
No XLogs for a transaction can be obtained until after the corresponding COMMIT XLog has been received. In other words, the time interval between the time that an XLog arrives and the time that it is actually processed increases. This means that a decrease in performance is highly likely in situations in which individual transactions are used for batch processing.

If the number of XLogs for which ACK is to be sent out is set to a number greater than 1 (one), ACK may not be sent to the XLog Sender, even when ALA_SendACK() is called.

When the socket type is set to "TCP", the listen port must not be being used by any other process.

When the socket type is set to "UNIX", the value of the ALTIBASE_HOME environment variable must be set the same as in the Altibase database to which the XLog Sender belongs. Additionally, since the maximum allowable length of the socket filename varies depending on the operating system, be sure to check, and avoid exceeding, the maximum allowable length on your system.

ALA_AddAuthInfo

ALA_RemoveAuthInfo

ALA_DestroyXLogCollector

ALA_SetXLogPoolSize

Example#

#include <alaAPI.h>
…

void testXLogCollectorTCP()
{
    ALA_Handle sHandle;

    /* Create XLog Collector that uses TCP
    * XLog Sender Name : log_analysis
    * XLog Sender Authentication Information : IP=127.0.0.1
    * Listening Port : 30300
    * The max. size of XLog Pool : 10000
    * Obtain transaction XLog in the order of commit : Disabled
    * The reference number of XLog for which ACK will be sent out : 100
    */
    (void)ALA_CreateXLogCollector("log_analysis",
                "SOCKET=TCP;PEER_IP=127.0.0.1;MY_PORT=30300",
                10000,
                ALA_FALSE,
                100,
                &sHandle,
                NULL);

   /* Adde XLog Sender Authentication Information */
 (void) ALA_AddAuthInfo(sHandle, "PEER_IP=127.0.0.2", NULL);

    /* Remove XLog Sender Authentication Information */
 (void)ALA_RemoveAuthInfo(sHandle, "PEER_IP=127.0.0.2", NULL);

 /* Invoke Log Analysis API */

 …

 /* Remove XLog Collector */
 (void)ALA_DestroyXLogCollector(sHandle, NULL);

void testXLogCollectorUNIX()
{
    ALA_Handle sHandle;

    /* Create XLog Collector that uses a UNIX domain
    * XLog Sender Name : log_analysis
    * The max. size of XLog Pool : 20000
    * Obtain transaction XLog in the order of commit : Enabled
    * The reference number of XLog for which ACK will be sent out : 50
    */
    (void)ALA_CreateXLogCollector("log_analysis",
                "SOCKET=UNIX",
                20000,
                ALA_TRUE,
                50,
                &sHandle,
                NULL);

    /* Invoke Log Analysis API */
    …

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

ALA_AddAuthInfo#

Syntax#

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

Arguments#

Argument	Description
aHandle	THis is the handle of the XLog Collector.
aAuthInfo	This is the XLog Sender authentication information.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function adds authentication information for the XLog Sender.

When the connection type is TCP, aAuthInfo is a string having the format "PEER_IP=xlog_sender_ip". The valid length of xlog_sender_ip is from 1 to 39 bytes.

Considerations#

This function can only be called when the socket type is set to "TCP".
Up to 32 different pieces of XLog Sender authentication information can be specified.

ALA_CreateXLogCollector

ALA_RemoveAuthInfo

ALA_Handshake

Example#

Refer to ALA_CreateXLogCollector.

ALA_RemoveAuthInfo#

Syntax#

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

Arguments#

Argument	Description
aHandle	This is the handle of the XLog Collector
aAuthInfo	This is the XLog Sender authentication information.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function removes the specified XLog Sender authentication information.

When the connection type is TCP, aAuthInfo is a string having the format "PEER_IP=xlog_sender_ip". The valid length of xlog_sender_ip is from 1 to 39 bytes.

Considerations#

This function can only be called when the socket type is set to "TCP".
At least one piece of XLog Sender authentication information is required.

ALA_CreateXLogCollector

ALA_AddAuthInfo

ALA_Handshake

Example#

Refer to ALA_CreateXLogCollector.

ALA_SetHandshakeTimeout#

Syntax#

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

Arguments#

Argument	Description
aHandle	This is the handle of the XLog Collector.
aSecond	This is the handshake timeout. (unit: seconds, range: 1- 0xFFFFFFFE)
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function sets the handshake timeout.

The handshake timeout is used when ALA_Handshake() is called.

The default handshake timeout is 600 seconds.

ALA_Handshake

Example#

Refer to ALA_Handshake.

ALA_SetReceiveXLogTimeout#

Syntax#

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

Arguments#

Argument	Description
aHandle	This is the handle of the XLog Collector.
aSecond	This is the reception timeout. (unit: seconds, range: 1 - 0xFFFFFFFE)
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function sets the XLog reception timeout.

The XLog reception timeout is used when ALA_ReceiveXLog() is called. The default XLog reception timeout is 10 seconds.

ALA_ReceiveXLog

Example#

Please refer to ALA_Handshake.

ALA_SetXLogPoolSize#

Syntax#

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

Arguments#

Argument	Description
aHandle	This is the handle of the XLog Collector
aXLogPoolSize	This is the size of the XLog Pool.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This functions changes the size of XLog Pool which XLog Collector has.

ALA_CreateXLogCollector

Example#

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


    /* Create XLog Collector that uses TCP
    * XLog Sender Name                   : log_analysis
    * XLog Sender Authentication Information               : IP=127.0.0.1
    * Listening Port                        : 30300
    * The max. size of XLog Pool                  : 10000
    * Obtain transaction XLog in the order of commit : Disable
    * The reference number of XLog for which ACK will be sent out        : 100
    */
    (void)ALA_CreateXLogCollector("log_analysis",
                "SOCKET=TCP;PEER_IP=127.0.0.1;MY_PORT=30300",
                10000,
                ALA_FALSE,
                100,
                &sHandle,
                NULL);

    ...    

    /* Receiving XLog until the XLog Sender terminates */
    while(sExitFlag != ALA_TRUE)
    {
        /* Receive XLog and Add to 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;
                }
            }
        }
        /* Retrieve XLog from XLog Queue
        * Assume that retrieve XLog of Transaction in the order that log record is recorded
        */
        (void)ALA_GetXLog(aHandle, &sXLog, NULL);

        /* XLog Analysis and Processing */
        (void)ALA_GetXLogHeader(sXLog, &sXLogHeader, NULL);
        if(sXLogHeader->mType == XLOG_TYPE_REPL_STOP)
        {
            sExitFlag = ALA_TRUE;
        }
        ...

        /* Send ACK to XLog Sender */
        (void)ALA_SendACK(aHandle, NULL);

        /* Return XLog to XLog Pool */
        (void)ALA_FreeXLog(aHandle, sXLog, NULL);

        /* Retrieve status of XLog Collector */
        (void)ALA_GetXLogCollectorStatus(aHandle,
                    &sXLogCollectorStatus,
                    NULL);
    }
    ...
    /* Terminate XLog Collector */
    (void)ALA_DestroyXLogCollector(sHandle, NULL);

    return 0;
}

ALA_Handshake#

Syntax#

ALA_RC ALA_Handshake(
     ALA_Handle      aHandle,
     ALA_ErrorMgr * aOutErrorMgr);

Arguments#

Argument	Description
aHandle	This is the handle of the XLog Collector.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to tell the XLog Collector to listen for the XLog Sender and perform handshaking.

With the exception of user settings and the XLog Pool, all of the data in the XLog Collector are initialized. Meta data about the target tables are received and stored internally.

Considerations#

When the connection type is TCP and the authentication information does not match, handshaking will fail.
If the peer being connected to is not an XLog Sender, handshaking will fail.
If a connection with an XLog Sender is not established within the specified handshaking timeout period, a timeout event will occur.
ALA_ReceiveXLog(), ALA_GetXLog() and ALA_SendACK() must not be called before handshaking is completed.
Before commencing handshaking, ALA_FreeXLog() must be executed for all XLogs that were obtained using ALA_GetXLog(), in order to ensure that the XLog Pool is not depleted.

ALA_AddAuthInfo

ALA_RemoveAuthInfo

ALA_SetHandshakeTimeout

ALA_ReceiveXLog

ALA_SendACK

ALA_GetReplicationInfo

ALA_GetTableInfo

ALA_GetColumnInfo

ALA_GetIndexInfo

Example#

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

/* Set Handshake Timeout : 600 seconds */
(void)ALA_SetHandshakeTimeout(aHandle, 600, NULL);

/* Set XLog Receive Timeout : 10 seconds */
(void)ALA_SetReceiveXLogTimeout(aHandle, 10, NULL);

/* Listen for XLog Sender and Handshake */
(void)ALA_Handshake(aHandle, NULL);

/* Receive XLog until XLog Sender ends */
while(sExitFlag != ALA_TRUE)
{
//* Receive XLog and add it to XLog Queue */
sInsertXLogInQueue = ALA_FALSE;
while(sInsertXLogInQueue != ALA_TRUE)
{
    (void)ALA_ReceiveXLog(aHandle, &sInsertXLogInQueue, NULL);
}

/* Obtain XLog from XLog Queue
 * Assuming that transaction XLog is obtained in the order in which records are logged
 */
(void)ALA_GetXLog(aHandle, &sXLog, NULL);

/* Analyze and Process XLog */
(void)ALA_GetXLogHeader(sXLog, &sXLogHeader, NULL);
if(sXLogHeader->mType == XLOG_TYPE_REPL_STOP)
{
sExitFlag = ALA_TRUE;
}
…

/*  Send ACK to XLog Sender */
(void)ALA_SendACK(aHandle, NULL);

/*  Return XLog to XLog Pool */
(void)ALA_FreeXLog(aHandle, sXLog, NULL);

/* Obtain the Status of XLog Collector */
(void)ALA_GetXLogCollectorStatus(aHandle,
                                 &sXLogCollectorStatus,
NULL);
}
}

ALA_ReceiveXLog#

Syntax#

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

Arguments#

Argument	Description
aHandle	This is the handle of the XLog Collector
aOutInsertXLogInQueue	This indicates whether the received XLog was added to the XLog Queue.
aOutErrorMgr	This is an Error Manager structure

Ruturn Value#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to receive an XLog and add it to the XLog Queue.

The memory for an XLog is obtained from the XLog Pool.

When transaction XLogs are obtained in the order in which transactions are committed, all of the XLogs pertaining to a given transaction are stored in the transaction table until the corresponding COMMIT XLog is received.

This function can be called at the same time as ALA_GetXLog().

Considerations#

ALA_Handshake() must be called before this function. If a network error occurs after a successful call to ALA_Handshake(), the call to this function will fail.
If no XLogs are received within the XLog reception timeout period, a timeout event will occur.
If there are no XLogs available in the XLog Pool, the call to this function will fail.
When transaction XLogs are obtained in the order in which transactions are committed, XLogs that are received are not necessarily added to the XLog Queue.
If a network error occurs or a REPL_STOP XLog is received, it will be necessary to roll back any uncommitted transactions for which XLogs have been obtained, and in connection with which the database contents have been changed.
Memory for aOutInsertXLogInQueue must be allocated in advance.

ALA_SetReceiveXLogTimeout

ALA_Handshake

ALA_GetXLog

ALA_SendACK

ALA_FreeXLog

Example#

Refer to ALA_Handshake.

ALA_GetXLog#

Syntax#

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

Arguments#

Argument	Description
aHandle	This is the handle of the XLog Collector.
aOutXLog	This is an XLog obtained from the XLog Queue.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to obtain an XLog from the XLog Queue.

It can be called at the same time as ALA_ReceiveXLog().

If there are no XLogs in the XLog Queue, the value of aOutXLog will be NULL.

Consideration#

XLogs must be managed by the client application until ALA_FreeXLog() is called.

ALA_ReceiveXLog

ALA_FreeXLog

ALA_GetXLogHeader

ALA_GetXLogPrimaryKey

ALA_GetXLogColumn

ALA_GetXLogSavepoint

ALA_GetXLogLOB

Example#

Refer to ALA_Handshake.

ALA_SendACK#

Syntax#

ALA_RC ALA_SendACK(
        ALA_Handle      aHandle,
        ALA_ErrorMgr * aOutErrorMgr);

Arguments#

Argument	Description
aHandle	This is the handle of the XLog Collector.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function sends ACK to the XLog Sender.

ACK is not sent to the XLog Sender immediately at the time that this function is called. Rather, ACK is sent to the XLog Sender some time after this function is called, when the number of successful calls to ALA_GetXLog() exceeds the number of XLogs for which ACK is to be sent out, or when a KEEP_ALIVE or REPL_STOP XLog is received.

When a REPL_STOP XLog is received, the network connection is disconnected.

The ACK message contains the so-called "Restart SN". The Restart SN is the SN having the lowest value among the following SNs:

The lowest XLog SN for active transactions that were checked at the time point at which ALA_GetXLog() was most recently called
If there are no active transactions, the SN of the last XLog that was obtained using ALA_GetXLog()
When transaction XLogs are obtained in the order in which transactions are committed, the lowest XLog SN for uncommitted transactions that are currently stored in the transaction table.

Considerations#

ACK has an influence on the XLog Sender's meta table and on flushing. If ACK is not sent within the time period specified in the REPLICATION_RECEIVE_TIMEOUT property on the XLog Sender, the XLog Sender drops the network connection. Moreover, if ACK is not sent for a long time, the XLog Sender may stop sending XLogs, update the Restart SN with the SN for the most recently recorded log, and resume attempting to send XLogs.
Because the restart SN on the XLog Sender can be updated after the XLog Sender receives ACK, it is necessary to process all of the XLogs obtained by calling ALA_GetXLog() before calling ALA_SendACK().
If a network error occurs, the XLog Sender will periodically attempt handshaking. When handshaking succeeds, the XLog Sender will resume sending XLogs, beginning with the XLog having the Restart SN.

ALA_Handshake

ALA_ReceiveXLog

Example#

Refer to ALA_Handshake.

ALA_FreeXLog#

Syntax#

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

Arguments#

Argument	Description
aHandle	This is the handle of the XLog Collector.
aXLog	THisis an XLog that will be returned to the XLog Pool.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function returns an XLog to the XLog Pool.

Consideration#

If XLogs obtained using ALA_GetXLog() are not returned to the XLog Pool for an excessively long period of time, the XLog Pool may become depleted.

ALA_ReceiveXLog

ALA_GetXLog

Example#

Refer to ALA_Handshake.

ALA_DestroyXLogCollector#

Syntax#

ALA_RC ALA_DestroyXLogCollector(
        ALA_Handle      aHandle,
        ALA_ErrorMgr * aOutErrorMgr);

Arguments#

Argument	Description
aHandle	This is the handle of the XLog Collector.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function terminates an XLog Collector.

Considerations#

Before this function is called, ALA_FreeXLog() must be executed for all XLogs that were obtained by calling ALA_GetXLog().

Regardless of the result value, any subsequent calls to the Log Analysis API functions in relation to the corresponding XLog Collector will fail.

ALA_CreateXLogCollector

Example#

Refer to ALA_CreateXLogCollector.

ALA_GetXLogCollectorStatus#

Syntax#

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

Arguments#

Argument	Description
aHandle	This is the handle of the XLog Collector
aOutXLogCollectorStatus	This is a structure in which information about the status of the XLog Collector is stored.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to check the status of the XLog Collector.

The structure for storing information about the status of the XLog Collector is defined as follows:

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;

Structure Member	Description
mMyIP	[TCP] This is the IP address of the XLog Collector.
mMyPort	[TCP] This is the port number being used on the XLog Collector.
mPeerIP	[TCP] This is the IP address of the XLog Sender.
mPeerPort	[TCP] This is the port number being used on the XLog Sender.
mSocketFile	[UNIX Domain] This is the name of the socket file.
mXLogCountInPool	This is the number of XLogs remaining in the XLog Pool.
mLastArrivedSN	This is the SN of the most recently received XLog.
mLastProcessedSN	This is the SN of the most recently processed XLog.
mNetworkValid	This indicates whether the network connection is valid.

These status values are maintained internally by the Log Analyzer, and the values are returned in the structure when this function is called.

The internal values corresponding to mMyIP, mMyPort, mPeerIP, mPeerPort and mSocketFile are updated when ALA_Handshake() is called.

When ALA_ReceiveXLog() is called, the value that is returned in mXLogCountInPool is incremented if a ROLLBACK XLog is received and decremented when other kinds of XLogs are received. It is incremented when ALA_FreeXLog() is called.

mLastArrivedSN is the SN of the XLog that was most recently received by calling ALA_ReceiveXLog(). mLastProcessedSN is the SN of the XLog that was most recently obtained by calling ALA_GetXLog().

The status value corresponding to mNetworkValid might change when ALA_Handshake(), ALA_ReceiveXLog() or ALA_SendACK() is called.

Consideration#

Memory for aOutXLogCollectorStatus must be allocated before this function is called.

ALA_Handshake

ALA_ReceiveXLog

ALA_GetXLog

ALA_SendACK

ALA_FreeXLog

Example#

Refer to ALA_Handshake.

ALA_GetXLogHeader#

Syntax#

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

Arguments#

Argument	Description
aXLog	This is the XLog for which to retrieve the header.
aOutXLogHeader	The XLog header of aXLog is returned in this argument.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to obtain the XLog header for the specified XLog.

ALA_GetXLog

ALA_GetXLogPrimaryKey

ALA_GetXLogColumn

ALA_GetXLogSavepoint

ALA_GetXLogLOB

Example#

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

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

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

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

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

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

ALA_GetXLogPrimaryKey#

Syntax#

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

Arguments#

Argument	Description
aXLog	This is the XLog for which to retrieve the primary key.
aOutXLogPrimaryKey	The XLog primary key of aXLog is returned in this argument.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to obtain the XLog primary key for the specified XLog.

ALA_GetXLog

ALA_GetXLogHeader

ALA_GetXLogColumn

ALA_GetXLogSavepoint

ALA_GetXLogLOB

Example#

Refer to ALA_GetXLogHeader.

ALA_GetXLogColumn#

Syntax#

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

Arguments#

Argument	Description
aXLog	This is the XLog for which to retrieve the column.
aOutXLogColumn	The XLog column of aXLog is returned in this argument.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to obtain the XLog column for the specified XLog.

ALA_GetXLog

ALA_GetXLogHeader

ALA_GetXLogPrimaryKey

ALA_GetXLogSavepoint

ALA_GetXLogLOB

Example#

Refer to ALA_GetXLogHeader.

ALA_GetXLogSavepoint#

Syntax#

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

Arguments#

Argument	Description
aXLog	This is the XLog for which to retrieve the savepoint.
aOutXLogSavepoint	THe XLog savepoint information of a XLog is returned in this argument.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to obtain the XLog savepoint information for the specified XLog.

ALA_GetXLog

ALA_GetXLogHeader

ALA_GetXLogPrimaryKey

ALA_GetXLogColumn

ALA_GetXLogLOB

Example#

Please refer to ALA_GetXLogHeader.

ALA_GetXLogLOB#

Syntax#

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

Arguments#

Argument	Description
aXLog	This is the XLog for which to retrieve the XLog LOB information.
aOutXLogLOB	The XLog LOB information of aXLog is returned in this argument.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to obtain the XLog LOB information for the specified XLog.

ALA_GetXLog

ALA_GetXLogHeader

ALA_GetXLogPrimaryKey

ALA_GetXLogColumn

ALA_GetXLogSavepoint

Example#

Refer to ALA_GetXLogHeader.

ALA_GetProtocolVersion#

Syntax#

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

Arguments#

Argument	Description
aOutProtocolVersion	This is a Protocol Version structure.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to check the protocol version that is being used by the Log Analysis API.

The protocol version can be checked regardless of whether handshaking has been performed.

Consideration#

Before this function is executed, it is first necessary to allocated memory to hold the aOutProtocolVersion structure.

Example#

#include <alaAPI.h>
…

void testProtocolVersion()
{
ALA_ProtocolVersion sProtocolVersion;

/* Obtain Protocol Version */
(void)ALA_GetProtocolVersion(&sProtocolVersion, NULL);
}

ALA_GetReplicationInfo#

Syntax#

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

Arguments#

Argument	Description
aHandle	This is the handle of the XLog Collector.
aOutReplication	This is information about Replication
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to obtain information about Replication.

Considerations#

If there are no meta data pertaining to replication, this function returns NULL for the aOutReplication argument.
Any meta data that were obtained using this function before handshaking was performed should not be used again after handshaking, as the information might be out of date.

ALA_Handshake

ALA_GetTableInfo

ALA_GetTableInfoByName

ALA_GetColumnInfo

ALA_GetIndexInfo

Example#

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

    /* Obtain replication information */
    (void)ALA_GetReplicationInfo(aHandle, &sReplication, NULL);

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

        /* Obtain table information by table OID */
        (void)ALA_GetTableInfo(aHandle,
            sTable->mTableOID,
            &sTableByTableOID,
            NULL);

        if(sTableByTableOID != sTable)
        {
            /* Fatal Error : Error in Log Analysis API */
            break;
        }

        /* Obtain table information by name */
        (void)ALA_GetTableInfoByName(aHandle,
            sTable->mFromUserName,
            sTable->mFromTableName,
            &sTableByName,
            NULL);

        if(sTableByName != sTable)
        {
            /*  Fatal Error : Error in Log Analysis API */
            break;
        }

        /* Process primary key column */
        for(sPKColumnPos = 0; sPKColumnPos < sTable->mPKColumnCount; sPKColumnPos++)
        {         /* Obtain the primary key column information by primary key column ID */

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

            if(sPKColumn != sTable->mPKColumnArray[sPKColumnPos])
            {    /* Fatal Error : Error in Log Analysis API */
                break;
            }

           /* Process primary key column */
            …
        }

        /* Process column */

        for(sColumnPos = 0; sColumnPos < sTable->mColumnCount; sColumnPos++)
        {        /*  Obtain column information by column ID */
            (void)ALA_GetColumnInfo(sTable,
                sTable->mColumnArray[sColumnPos].mColumnID,
                &sColumn,
                NULL);

            if(sColumn != &(sTable->mColumnArray[sColumnPos]))
            {      /*  Fatal Error : Error in Log Analysis API  */
                break;
            }

            /* Process column */
            …
        }

        /* Process Index */
        for(sIndexPos = 0; sIndexPos < sTable->mIndexCount; sIndexPos++)
        {        /* Obtain index information by index ID */
            (void)ALA_GetIndexInfo(sTable,
                sTable->mIndexArray[sIndexPos].mIndexID,
                &sIndex,
                NULL);

            if(sIndex != &(sTable->mIndexArray[sIndexPos]))
            {        /* Fatal Error : Error in Log Analysis API  */
                break;
            }

            /* Process index */
            …
        }
    }
}

ALA_GetTableInfo#

Syntax#

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

Arguments#

Argument	Description
aHandle	This is the handle of the XLog Collector.
aTableOID	This is the OID of the table for which to retrieve the information.
aOutTable	This is information about the table
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function retrieves information about the table identified by the specified table OID.

Considerations#

If there are no meta data corresponding to the specified table, or if the specified table could not be found, this function returns NULL for the aOutTable argument.
Any meta data that were obtained using this function before handshaking was performed should not be used again after handshaking, as the information might be out of date.

ALA_Handshake

ALA_GetReplicationInfo

ALA_GetTableInfoByName

ALA_GetColumnInfo

ALA_GetIndexInfo

Example#

Please refer to ALA_GetReplicationInfo.

ALA_GetTableInfoByName#

Syntax#

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

Arguments#

Argument	Description
aHandle	This is the handle of the XLog Collector.
aFromUserName	This is the name of the owner of the table for which to retrieve the information.
aFromTableName	This is the name of the table for which to retrieve the information.
aOutTable	The table information is returned in this argument.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function retrieves information about the table identified by the specified user (table owner) name and table name.

Considerations#

If there are no meta data corresponding to the specified table, or if no table corresponding to the specified user name and table name could be found, this function returns NULL for the aOutTable argument.
Any meta data that were obtained using this function before handshaking was performed should not be used again after handshaking, as the information might be out of date.

ALA_Handshake

ALA_GetReplicationInfo

ALA_GetTableInfo

ALA_GetColumnInfo

ALA_GetIndexInfo

Example#

Refer to ALA_GetReplicationInfo.

ALA_GetColumnInfo#

Syntax#

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

Arguments#

Argument	Description
aTable	This is the meta information about the table containing the column for which to retrieve the information.
aColumnID	This is the ID of the column for which to retrieve the information.
aOutColumn	The column information is returned in this argument.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function retrieves the information about the column identified by the specified Column ID in the specified table.

Considerations#

If there are no meta data corresponding to the specified column or the specified table, this function returns NULL for the aOutColumn argument.
Any meta data that were obtained using this function before handshaking was performed should not be used again after handshaking, as the information might be out of date.

ALA_Handshake

ALA_GetReplicationInfo

ALA_GetTableInfo

ALA_GetTableInfoByName

ALA_GetIndexInfo

Example#

Refer to ALA_GetReplicationInfo.

ALA_GetIndexInfo#

Syntax#

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

Arguments#

Argument	Description
aTable	This is the meta information about the table containing the index for which to retrieve the information.
aIndexID	This is the ID of the index for which to retrieve the information.
aOutIndex	The index information is returned in this argument.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function retrieves the information about the index identified by the specified Index ID in the specified table.

Considerations#

If there are no meta data corresponding to the specified index, or if the specified table or index could not be found, this function returns NULL for the aOutIndex argument.
Any meta data that were obtained using this function before handshaking was performed should not be used again after handshaking, as the information might be out of date.

ALA_Handshake

ALA_GetReplicationInfo

ALA_GetTableInfo

ALA_GetTableInfoByName

ALA_GetColumnInfo

Example#

Refer to ALA_GetReplicationInfo.

ALA_IsHiddenColumn#

Syntax#

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

Arguments#

Argument	Description
aColumn	This is information of the column.
aIsHiddenColumn	Whether or not the column is a hidden column.
aOutErrorMgr	This is an Error Manager structure.

Result Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function determines whether the column selected by the Column ID is a hidden column.

Consideration#

Any meta data that were obtained using this function before handshaking was performed should not be used again after handshaking, as the information might be out of date.

ALA_GetColumnInfo

Example#

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


     /* Obtain replication information */
     (void)ALA_GetReplicationInfo(aHandle, &sReplication, NULL);
     for(sTablePos = 0; sTablePos < sReplication->mTableCount; sTablePos++)
     {
         sTable = &(sReplication->mTableArray[sTablePos]);
         /* Getting Table Information by Table OID */
         (void)ALA_GetTableInfo( aHandle,
                             sTable->mTableOID,
                             &sTableByTableOID,
                             NULL);
         if(sTableByTableOID != sTable)
         {
             /* Fatal Error : Error in Log Analysis API */
             break;
         }

         /* Obtain table information by name */
         (void)ALA_GetTableInfoByName(aHandle,
                         sTable->mFromUserName,
                         sTable->mFromTableName,
                         &sTableByName,
                         NULL);
         if(sTableByName != sTable)
         {
             /* Fatal Error : Error in Log Analysis API */
             break;
         }

         /*  Process column */
         for(sColumnPos = 0; sColumnPos < sTable->mColumnCount; sColumnPos++)
         { /* Obtain column information by column ID */
             (void)ALA_GetColumnInfo(sTable,
                             sTable->mColumnArray[sColumnPos].mColumnID,
                             &sColumn,
                             NULL);
             if( sColumn != &(sTable->mColumnArray[sColumnPos]) )
             { /* Fatal Error : Error in Log Analysis API */
                 break;
             }
             /* Process column */
             (void)ALA_IsHiddenColumn( sColumn, &sIsHiddenColumn, NULL );
             if( sIsHiddenColumn != ALA_TRUE )
             {
                 /* Process column */
             }
             else
             {
                 /* Process hidden column */
             }
         }

         ...
     }
}

ALA_GetInternalNumericInfo#

Syntax#

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

Arguments#

Argument	Description
aColumn	This is the meta information about the column.
aAltibaseValue	This is the actual Altibase numeric data.
aOutSign	This is the sign of the numeric data.
aOutExponent	This is the exponent of the numeric data.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to determine the sign and exponent of a FLOAT or NUMERIC type number.

An aOutSign value of 1 represents a positive number, whereas an aOutSign value of 0 represents a negative number.

aOutExponent is a base 10 exponent.

Example#

#include <alaAPI.h>
…

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

    /* Obtain the internal numeric information */
    (void)ALA_GetInternalNumericInfo(aColumn,
        aAltibaseValue,
        &sNumericSign,
        &sNumericExponent,
        NULL);
}

ALA_GetAltibaseText#

Syntax#

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

Arguments#

Argument	Description
aColumn	This is the meta information about the column.
aValue	This is the actual data of Altibase to convert to a string.
aBufferSize	This is the size of the buffer in which the output string will be stored.
aOutBuffer	This is the buffer containing the actual output string.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function converts Altibase data into string form. For date/time type data, the output string format is "YYYY-MM-DD HH:MI:SS.SSSSSS".

BIT type data are converted to the BIT'value' format, and VARBIT type data are converted to the VARBIT'value' format.

NCHAR or NVARCHAR type data are always converted to the UCS-2 (UTF-16) character set

Considerations#

In order to convert NCHAR or NVARCHAR type data between different character sets, it is necessary to set the value of the ALTIBASE_ALA_NCHARSET environment variable on the server on which the logs will be analyzed (i.e. on the XLog Collector side) to the value of the national character set on the server from which the data originate (i.e. on the XLog Sender side).

For example, if the character set for NCHAR and NVARCHAR type data is set to UTF8 on the server acting as the data source, execute the following on the server on which the logs will be analyzed:

export ALTIBASE_ALA_NCHARSET=UTF8;

Then, when the ALA_GetAltibaseText function is executed on NCHAR or NVARCHAR type data, the data written to aOutBuffer are in UCS-2(UTF-16) form.

Example:

\0031\\0020\\0020\\0020

This function cannot be used with BLOB, CLOB, or GEOMETRY type data.

ALA_GetAltibaseSQL

Example#

#include <alaAPI.h>
…

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

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

ALA_GetAltibaseSQL#

Syntax#

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

Arguments#

Argument	Description
aTable	The table information for XLog
aXLog	XLog
aBufferSize	Buffer Size
aOutBuffer	Buffer
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to convert information in an XLog into a SQL string of Altibase.

For date/time type data, the output string format is "YYYY-MM-DD HH:MI:SS.SSSSSS".

BIT type data are converted to the BIT'value' format, and VARBIT type data are converted to the VARBIT'value' format. NCHAR and NVARCHAR type data are converted to the UNISTR('value') format.

NCHAR and NVARCHAR type data is converted to UNISTR ('value') format.

When an INSERT, UPDATE or DELETE SQL statement is reconstructed from XLogs, the target table in the SQL string is specified using the mToUserName and mToTableName elements of the aTable structure.

Considerations#

This function cannot be used with BLOB, CLOB or GEOMETRY type data.
This function may generate SQL that is incompatible with other DBMS products.

ALA_GetAltibaseText

Example#

#include <alaAPI.h>
…

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

/*  Process the primary key column */
for(sPKColumnPos = 0;
sPKColumnPos < aXLog->mPrimaryKey.mPKColCnt;
sPKColumnPos++)
{
/* The primary key sequence for the XLog and the primary key sequence for the table are the same */
sColumn = aTable->mPKColumnArray[sPKColumnPos];

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

/* Process the column */
for(sColumnPos = 0; sColumnPos < aXLog->mColumn.mColCnt; sColumnPos++)
{
/* Obtain the column information */
(void)ALA_GetColumnInfo(aTable,
aXLog->mColumn.mCIDArray[sColumnPos],
&sColumn,
NULL);

/* Obtain the Altibase text for the Before Image */
(void)ALA_GetAltibaseText(sColumn,
&(aXLog->mColumn.mBColArray[sColumnPos]),
1024,
sBuffer,
NULL);

/* Obtain the Altibase text for the After Image */
(void)ALA_GetAltibaseText(sColumn,
&(aXLog->mColumn.mAColArray[sColumnPos]),
1024,
sBuffer,
NULL);
}
}

ALA_GetODBCCValue#

Syntax#

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

Arguments#

Argument	Description
aColumn	This is meta information about the column in which aAltibaseValue is stored.
aAltibaseValue	This is the data in the internal format of Altibase.
aODBCCTypeID	This is the ODBC C type into which the data are to be converted.
aODBCCValueBufferSize	This is the size of the buffer in which to store the results.
aOutODBCCValueBuffer	This is the buffer in which to store the results.
aOutIsNull	This indicates whether the data to be converted are NULL.
aOutODBCCValueSize	This is the size of the ODBC C value resulting from the conversion.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to convert a value in an internal format of Altibase to an ODBC C type.The type conversions that are supported are shown in the following table:

Altibase Data(Right) ODBC C Value(Bottom)	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	○	○	○	○	○	○	○	○	○	○

[Table 4-1] ODBC C Conversion

Considerations#

The BLOB, CLOB and GEOMETRY types cannot be converted using this function.
This function supports ODBC 3.0 and subsequent versions.

Example#

#include <alaAPI.h>
…

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

/* Convert the primary key to SQL_C_CHAR */
for(sPKColumnPos = 0;
sPKColumnPos < aXLog->mPrimaryKey.mPKColCnt;
sPKColumnPos++)
{
/* The primary key sequence for XLog and the primary key sequence for the table are the same */
sColumn = aTable->mPKColumnArray[sPKColumnPos];

/* Convert the internal data to SQL_C_CHAR */
(void)ALA_GetODBCCValue(sColumn,
&(aXLog->mPrimaryKey.mPKColArray[sPKColumnPos],
SQL_C_CHAR,
1024,
sBuffer,
&sIsNull,
&sODBCCValueSize,
NULL);
}
}

ALA_ IsNullValue#

Syntax#

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

Arguments#

Argument	Description
aColumn	This is the meta information about the column in which aValue is stored.
aValue	This is a column value.
aOutIsNull	This returns the result of a determination of whether aValue is NULL.
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to determine whether a column value is NULL.

Considerations#

Because the NULL value that is passed as an XLog is in an internally used Altibase format that cannot be interpreted directly, this function must be used to determine whether a value is NULL.

Example#

#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#

Syntax#

ALA_RC ALA_ClearErrorMgr(
         ALA_ErrorMgr * aOutErrorMgr);

Argument#

Argument	Description
aOutErrorMgr	This is an Error Manager structure.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function initializes the Error Manager.

Consideration#

Before an Error Manager is used for the first time, it must be initialized using this function.

ALA_GetErrorCode

ALA_GetErrorLevel

ALA_GetErrorMessage

Example#

#include <alaAPI.h>
…

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

/* Initialize Error Manager */
(void)ALA_ClearErrorMgr(&sErrorMgr);

/* Invoking of Log Analysis API fails */
…

/* Obtain the error code */
(void)ALA_GetErrorCode(&sErrorMgr, &sErrorCode);

/* Obtain the error level */
(void)ALA_GetErrorLevel(&sErrorMgr, &sErrorLevel);

/* Obtain the error message */
(void)ALA_GetErrorMessage(&sErrorMgr, &sErrorMessage);
}

ALA_GetErrorCode#

Syntax#

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

Arguments#

Argument	Description
aErrorMgr	This is an Error Manager structure.
aOutErrorCode	This is the Error Code.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to obtain an error code.

An error code is a unique numerical value that identifies the kind of error that has occurred.

Considerations#

It is necessary to allocate memory in which to store aOutErrorCode before calling this function.
Because the mErrorCode element of the ALA_ErrorMgr structure contains information that is internally used and thus not easy to parse or understand, it is necessary to use the ALA_GetErrorCode() function in order to obtain the error code.

ALA_ClearErrorMgr

ALA_GetErrorLevel

ALA_GetErrorMessage

Example#

Refer to ALA_ClearErrorMgr.

ALA_GetErrorLevel#

Syntax#

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

Arguments#

Argument	Description
aErrorMgr	This is an Error Manager structure
aOutErrorLevel	This is the error level.

Return Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to determine the error level from aErrorMgr.

Because the ALA_ERROR_FATAL error level indicates a fatal error, if this error level is returned, the corresponding XLog Collector must be terminated. This is accomplished using the ALA_DestroyXLogCollector() function.

The ALA_ERROR_ABORT error level indicates that the state of the XLog Collector is abnormal. If this error level is returned, it will be necessary to call ALA_Handshake() for the corresponding XLog Collector in order to perform handshaking with the XLog Sender again.

An error level of ALA_ERROR_INFO indicates failure to invoke the Log Analysis API. The action that is appropriate to take in response to this error level is determined based on the error code.

Consideration#

It will be necessary to allocate memory in which to store aOutErrorLevel before calling this function.

ALA_ClearErrorMgr

ALA_GetErrorCode

ALA_GetErrorMessage

Example#

Refer to ALA_ClearErrorMgr.

ALA_GetErrorMessage#

Syntax#

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

Arguments#

Argument	Description
aErrorMgr	This is an Error Manager structure.
aOutErrorMessage	The error message is returned in this argument.

Retun Values#

ALA_SUCCESS

ALA_FAILURE

Description#

This function is used to obtain the actual error message from an Error Manager.

Consideration#

Since only a pointer to the actual error message is returned in aOutErrorMessage, there is no need to allocate memory in which to store aOutErrorMessage.

ALA_ClearErrorMgr

ALA_GetErrorCode

ALA_GetErrorLevel

Example#

Refer to ALA_ClearErrorMgr.

4. Log Analysis API#

ALA_InitializeAPI#

Syntax#

Arguments#

Return Values#

Description#

Considerations#

Related Function#

Example#

ALA_DestroyAPI#

Syntax#

Arguments#

Return Values#

Description#

Considerations#

Related Function#

Example#

ALA_EnableLogging#

Syntax#

Argument#

Return Values#

Description#

Considerations#

Related Function#

Example#

ALA_DisableLogging#

Syntax#

Argument#

Return Values#

Description#

Considerations#

Related Function#

Example#

ALA_CreateXLogCollector#

Syntax#

Arguments#

Return Values#

Description#

Considerations#

Related Functions#

Example#

ALA_AddAuthInfo#

Syntax#

Arguments#

Return Values#

Description#

Considerations#

Related Functions#

Example#

ALA_RemoveAuthInfo#

Syntax#

Arguments#

Return Values#

Description#

Considerations#

Related Functions#

Example#

ALA_SetHandshakeTimeout#

Syntax#

Arguments#

Return Values#

Description#

Related Function#

Example#

ALA_SetReceiveXLogTimeout#

Syntax#

Arguments#

Return Values#

Description#

Related Function#

Example#

ALA_SetXLogPoolSize#

Syntax#

Arguments#

Return Values#

Description#

Related Function#

Example#

ALA_Handshake#

Syntax#