Skip to end of metadata
Go to start of metadata

In this chapter, detailed explanations are given with the source of development examples. When converting other DBMS, convert it by referring to this document.

How to use APRE*C/C++

Altibase Precompiler is called APRE*C/C++ and the executable file is "apre". The user should develop the source with ".sc" as the extension. The following is how to use it.

When compiled normally, a file called sample.cpp is created in the corresponding directory, and the prompt returns without any error. For detailed options related to apre, refer to "Altibase APRE(SEC)C makefile".

If  C++ needs a "*.c" file as a C compiler, precompile it with "-t c" instead of "-t cpp".

Basic Makefile

The basic header file and library for Altibase development are located below.



Header file




The part to be added in the library is "-lapre –lodbccli". With this reference, a simple Makefile that compiles can be written as follows.

In addition to the ALTIBASE library, a system library is required for compilation. For a list of system libraries required for each platform and an example of a makefile, use the list defined in the "LIBS" tag in the $ALTIBASE_HOME/install/ file.

One more point to consider is that if the user uses a C compiler other than a C++ compiler, the ALTIBASE library is provided in C++, so the C++ system library must be linked for compatibility. For details, refer to the "Altibase APRE(SES)C makefile".

Host Variables

When coding using SQL statements on the source, all variables used to control I/O for data to the DBMS are referred to as host variables. Prior to ALTIBASE version 5.3.3, all host variables could be used only those declared in the “EXEC SQL BEGIN DECLARE SECTION” and “EXEC SQL END DECLARE SECTION” clauses.

However, starting from version 5.3.3 or later, it is possible to recognize general variables as host variables through the apre option. (apre -parse full option)

In the process of development, there may be a case where it is necessary to write a host variable in the Target clause of the SELECT statement. From ALTIBASE version 5, it is supported in the following form with an operator called CAST.


Sqlca Structure

ALTIBASE returns an error with the sqlca structure. The user can check the error code and error message with the following.





When an error occurs


When processed normally



When it has been processed but the user confirmation is required



When there is no target data


Contain an error message



In the case of modified DML, it has the number of processed records, and in the case of the select statement, when the host variable is an array, it only has the number of arrays (not cumulative) of variables containing the currently fetched records.


Contain error codes defined in ALTIBASE



Contain CLI standard error codes (ex) 08S01

Since the above code values are already defined in the source in the precompile stage, the developer does not need to redefine or include it in the header.


ALTIBASE does not have the same configuration as a separate listener and is implemented in a form that directly connects to the thread inside the DBMS. Therefore, the connection is made by directly entering the IP and PORT number of the server to be connected. The following is a basic example code for connecting to ALTIBASE.


Connection type

The type of connection method is the setting value of the CONNTYPE property, and one of three types can be selected: TCP/IP, unix domain, and IPC.





Communication between the program and DBMS is performed in the TCP/IP method


Communication between the program and DBMS is performed in the unix domain method


Communication between the program and DBMS is performed in the IPC method

CONNTYPE=2, 3 methods can be used only if the program is located in the same equipment as the DBMS server. Since both methods do not incur communication costs up to the hardware level, it is recommended if achieving faster performance than TCP/IP is required. When selecting the IPC connection method, the IPC_CHANNEL_COUNT in the ALTIBASE_HOME/conf/ file must be adjusted to a value of 1 or larger. This setting can be used only by restarting the DB, and kernel settings related to IPC must be sufficiently adjusted in advance.

Connection Name

It is possible to give an explicit name at the time of connection, but it is performed as follows.


It can be processed by saving it as an explicit name or host variable.

Connection close

The method of disconnecting the connection is as follows. If abnormal connection termination occurs, be sure to perform "EXEC SQL FREE" before attempting to reconnect.

Please note that ALTIBASE DISCONNECT is operated in NonAuto-Commit mode, but it should be noted that the changed transaction normally processed immediately before DISCONNECT by the user is committed. (If the user does not want to reflect it, the user must explicitly perform rollback and then disconnect.)



Commit/Rollback can be executed as follows.

Example of executing DML


In the case of ALTIBASE, the INTO clause of the SELECT clause cannot be omitted. For other transactional DML, the user can use SQL as it is.


A cursor is generally used as follows.

FAC(Fetch Across Commit) Error 

In a non-autocommit environment, it is not recommending to fetch the cursor by record unit after opening the cursor and commit/rollback during fetching in the ANSI standard. Altibase complies with ANSI standards, and errors occur in FAC by default. However, starting from Altibase version 6.3.1 or later, the FAC function is supported with the option of opening the cursor.

Example of code which the error occurs


In the above code, an error check is performed at the point after the fetch, and the following errors may occur during the execution. (Based on ALTIBASE version 5.3)

At this point, there are more actual records, but this error occurs because cursor1 that was previously opened at the time of committing has been internally terminated and there are no more result sets to fetch. (This error may be somewhat ambiguous to judge because it is the same as when there is no actual data, but this situation can be considered if such an error occurs below the expected number.)

Therefore, when a separate change transaction needs to be created in the process of fetching using a cursor, the session must be executed in auto-commit, or a separate connection object must be created and processed with the session.

FAC Error Message

Depending on the version of Altibase, the FAC error message is displayed slightly differently.

Error Code
Error Message
 Altibase 4.3.9ERR-4103C Request of fetching data to an unprepared SQL statement.
Altibase 5.3.3 ~ 6.1.1 100   
Altibase 6.3.1 or laterERR-410D2  Request of fetching data to an unprepared SQL statement.

Example of performing FAC by creating a separate connection


In the case of using a separate connection, the user must consider that the entire execution flow must be tied to one transaction. When using a separate connection object, some are committed due to an error during execution and some cannot be processed. If it is to be processed in the form of All or Nothing in one transaction,  the commit/rollback statement must be used outside the fetch-loop.

Use "WITH HOLD" statement when declaring cursor

Starting from Altibase version 6.3.1 or later, if the cursor declared with "WITH HOLD" is opened, the cursor is not closed even after the transaction is completed after Commit/Rollback is executed. This is valid only when the session is in non-autocommit mode. For more detailed information, please refer to "ALTIBASE CLI User's Manual" and "ALTIBASE Precompiler Manual".


Dynamic SQL 

Two examples of change transaction and inquiry transaction are described as follow.


Example of query transaction


This is a method of creating an SQL statement in a separate char* type variable and dynamically using the SQL statement when the table name is not specified or the column or search condition needs to be changed.

Starting from ALTIBASE 5.1 or later,  the execution plan executed by all sessions is internally shared in the area called Plan-Cache. However, if the query statement is changed each time like Dynamic SQL, the execution plan already created in Plan-Cache is not used, and the query performance is inevitably slower than that of static SQL statements because it operates in Prepare/Execute form again.

Call Function

This describes an example of how to call a user-created or DBMS built-in function.

Example of calling DBMS built-in function


Example of calling user function


It doesn't always have to be from dual, and it is fine if the user designates an arbitrary table as needed. (The user should be cautious about the function when char/varchar is returned in the return clause, the returned length must be specified. If not specified, only 1 byte is returned, so the following exception occurs in most functions: “Invalid length of the data type”)

Call Procedure

Unlike other functions, procedures are executed with the separate calling method. Please note that functions can also be used in the same way.

WHENEVER Statement

The WHENEVER statement of ALTIBASE provides such as do/goto/continue/stop. This statement must be declared before executing the embedded SQL statement. The following form is possible in the condition statement of the WHENEVER statement.




When sqlca.sqlcode is SQL_NO_DATA



When sqlca.sqlcode is SQL_ERROR


The processing part is possible as follows.




Ignore the error and continue


DO [사용자 함수]

Execute a user-defined function



Exit the loop. It is only valid within a loop.



Move to the first position in the loop. This statement is only valid within loops.


GOTO [Label]

Execute GOTO to the designated by the user



Disconnect and close the program

Examples are as follows.


Session Failover function and Checking current connection

In ALTIBASE, there isn't any way to actively return the status of the connection object, but the developer can detect that the connection has been terminated by checking the status of SQLSTATE after executing a query.

One of the possible methods is to put the following example source into a common function.

Example of Session Failover by User Code

Starting from ALTIBASE Version 5.3.3 or later, the Session FailOver function of the concept called CTP (Connection Time Failover) and STF (Service Time FailOver) are provided. CTF means FailOver tries to connect when the program first start, and STF means FailOver occurs in the process of executing a query after the connection.

Since this function does not support transaction FailOver, the user must consider reprocessing the business logic after the Session FailOver. The example is as follows.

Example of using Altibase FailOver function



The meaning of each input item of the connection string is as follows.




The target servers to FailOver are listed in the form of IP:PORT in order based on comma (,).



The number of connection attempts to one target serer


After sleep for this interval (in seconds), retry the connection



Determine whether to use the SessionFailOver function during the service time. In other words, this specifies whether to automatically connect to the server in the AlternateServers list when an SQL error occurs. (on/off)


When turned on, the server and AlternateServers list specified in the DSB are randomly selected at the time of initial connection. If turned off, the DSN is selected first, and then the connection is attempted in the order described in the AlternateServers list.

If an error occurs at the time of cursor opening and needs to be reprocessed, the cursor must be reprocessed after executing the cursor until close release before reprocessing. 




For more detailed information on CTF/STF, please refer to the "Altibase UL FailOver Guide".


  • No labels