Skip to content
≡

Administrator

Developer

Tools

External Tools

1. Introduction to Altibase C Interface#

This chapter introduces the Altibase C interface and explains its basic usage.

What is the Altibase C Interface?#

The Altibase C Interface (ACI) is a mechanism for interacting with a computer operating system or software to perform specific tasks. ACI facilitates easier communication between applications and databases. More specifically, ACI allows applications to access data from a variety of database management systems, and provides calling level interfaces to access database servers and execute SQL statements.

ACI is designed to be independent of programming languages, database systems, and operating systems. Thus, any application can use ACI to query data from a database, regardless of the platform it is on or the database it uses.

ACI vs CLI#

ACI is used to type commands, whereas CLI is used to perform various functions. However, the user should make fewer function calls with fewer arguments (than CLI) when using ACI to ensure successful execution. It is easier for the user to customize ACI, than CLI.

Using ACI#

This chapter explains how to develop application programs using ACI.

Basic Usages#

ACI application program generally consists of following three parts:

  • initializing handles
  • Processing transactions
  • Release handles

In addition to the above steps, in case of an error, a step of checking a diagnostic message may be added.

Initializing Handles#

This part allocates and initializes environment and connection handles. A handle is a memory pointer that stores information about the execution result of a previous phase. Transition from phases is made through the transmission of handles.

The following handle types are provided:

ALTIBASE Handle#

The ALTIBASE handle is a memory pointer that stores information related to connections managed by ACI. This information includes connection status and transaction status. The application must create and initialize an ALTIBASE handle for each connection, which can be used to connect to Altibase. You can also use this handle to execute SQL statements in Altibase.

ALTIBASE_STMT Handle#

To execute SQL statements in the Prepare-Execution method, the ALTIBASE_STMT handle must be used. A maximum of 1024 ALTIBASE_STMT handles can be allocated to one connection handle.

Processing of Transactions#

The following figure is a general procedure of calling functions to processing a transaction.

Releasing Handle#

This step is for releasing the handles and meory allocated by an application, and finishing an application

Managing Diagnosis Messages#

Diagnosis is to handle the warning or error status occurred in an application. When calling function, the user recieve return value and then can know whether function works successfully or not. For details of return value for each function, refer to Chapter3: Function Descriptions.

If function fails to work successfully, diagnosis messages are usually created. If you want to get more information from them in detail, you can do by using other functions as follows. Following functions are grouped depending on what handle to be used for calling functions previously.

Handle Type ALTIBASE ALTIBASE_STMT Description
Function altibase_errno() altibase_stmt_errno() Error code
altibase_error() altibase_stmt_error() Error message
altibase_sqlstate() altibase_stmt_sqlstate() SQLSTATE message

The diagnosis messages are returned except the case of SQL_SUCCESS, SQL_NO_DATA_FOUND, SQL_INVALID_HANDLE. To check the diagnosis message, call SQLGetDiagRec(), SQLGetDiagField().

Diagnosis Messages#

The diagnosis message is a five-bytes alphanumeric character string. The heading two characters refer to the class, and the next three character refer to the sub class. ACI diagnosis messages follow the standard of X/Open SQL CAE specifications.

Restrictions#

  • When writing multithreaded programs, an environment handle and connection handle must be allocated for each thread.

  • Altibase client library doesn't use signal processor. Therefore, if access to network terminates due to external factors, application can be shut down compulsorily by receiving signal of SIGPIPE.
    To prevent this forced termination, the SIGPIPE signal must be handled by the user application. Calling the Altibase client library function from within a function that handles SIGPIPE signal processing can cause the program to hang, so be careful about writing signal processing functions. However, after signal processing, it is possible to call Altibase client library functions.

Building Client Applications#

This section describes the header and library files needed to build client applications.

The Header Files#

The header file to build ACI applications is "alticapi.h" and located in $ALTIBASE_HOME/include/. For GCC, using following option will set the directory searchable by the compiler:

-I$ALTIBASE_HOME/include

The Library Files#

The ACI library file and ODBC library file must be linked by the compiler to build ACI applications. Below is the list of the ACI library and ODBC library files that can be found under $ALTIBASE_HOME/lib directory:

  • libalticapi.a

  • libodbccli.a

For GCC, using following option will help compilers to locate the library files:

-L$ALTIBASE_HOME/lib -lalticapi -lodbccli