2. Data Type

This chapter describes the data types used with the Altibase C interface.

ACI Data Types

This section describes the data structures of the Altibase C interface. These data structures will be used with ACI functions when writing the application. The data structures are broadly classified as follows:

• Handle types

• Structure types

• Other data types

Altibase Handles

There are three ACI handles:

• ALTIBASE

• ALTIBASE_STMT

• ALTIBASE_RES

ALTIBASE

ALTIBASE is a connection handle to a database. Connection handles are used for most ACI functions. The user must initialize this handle with altibase_init () and release it with altibase_close ().

The connection handle returns and manages only one result set handle (ALTIBASE_RES). In other words, to use one result set and get a handle to another, the user must first release the result set handle in use.

ALTIBASE_STMT

This data type is a handle for a prepared statement. If a statement contains parameter markers or you want to get data by using the bind operation, you must use the prepared statement. The user must initialize the handle with altibase_stmt_init() and close it with altibase_stmt_close().

ALTIBASE_RES

This data type represents the result of a query that returns rows. The information returned from a query is called the result set in the remainder of this chapter. The result set can be used to process total number of columns and individual column information.

The user must call altibase_use_result() or altibase_store_result() for every statement that successfully produces a result set. You must also call altibase_free_result() after you are done with the result set.

Data Structures

The data structures that can be used with ACI are:

• struct ALTIBASE_BIND

• struct ALTIBASE_CHARSET_INFO

• struct ALTIBASE_FIELD

• struct ALTIBASE_NUMERIC

• struct ALTIBASE_TIMESTAMP

struct ALTIBASE_BIND

This structure is used to bind input and output variables, and the user specifies binding information here. altibase_stmt_bind_param () binds a buffer for input parameters Function. altibase_stmt_bind_result () is a function that binds a buffer to get column data of the retrieved result set.

This structure contains the following members:

Member	Type	Description
buffer_type	ALTIBASE_BIND_TYPE	This indicates the data type. For more details, see enum ALTIBASE_BIND_TYPE.
buffer	void *	This indicates a pointer to be used for data transfer. For input, buffer is a pointer to the variable in which you store the data value for a statement parameter. For output, buffer is a pointer to the variable in which to return a result set column value.
buffer_length	ALTIBASE_LONG	This indicates the actual size of buffer. You do not have to define data types whose lengths are fixed across platforms as follows for the binding operation. To achieve this, their lengths must be set to 0 after initialization. ALTIBASE_BIND_SMALLINT, ALTIBASE_BIND_INTEGER, ALTIBASE_BIND_BIGINT, ALTIBASE_BIND_REAL, ALTIBASE_BIND_DOUBLE, ALTIBASE_BIND_DATE The user must set buffer_length to a valid value when binding a string variable by specifying a data type such as ALTIBASE_BIND_STRING whose length is not fixed. If the size of actual data is greater than a value of buffer_length, data can be buffered only as much as you set a value. For example, if you specify buffer_length as 2, 2bytes from the starting are buffered in the value of int. You must set buffer_length to a valid value to return a valid result.
length	ALTIBASE_LONG *	This indicates the actual number of bytes of data. You do not have to define data types such as short and int whose lengths are variable across platforms. You must define character string or binary data as a valid value because the sizes of character string and binary data may be smaller than that of buffer. The user can use ALTIBASE_NULL_DATA to fetch data. This indicates the return value is null.
is_null	ALTIBASE_BOOL *	This member points to an ALTIBASE_BOOL* variable that is ALTIBASE_TRUE if a value is null. It is recommended to check if a value is null by using this variable before using a value.
error	int	This member points to an int variable to have information for the parameter stored after the binding operation. When the binding operation fails, the user can check what argument fails specifically by using this variable. A value is returned by calling altibase_errno(). For more details, see 3.8 altibase_errno()

struct ALTIBASE_CHARSET_INFO

Structure that contains character set information. When the altibase_get_charset_info () function is called, this structure returns information about the character set.

This structure contains the following members:

Member	Type	Description
id	unsigned int	The identification of character set
name	void *	The name of character set encoded as UTF8
name_length	int	The name length of chaset
mbmaxlen	int	The maximum length of one character (Unit: Byte)

struct ALTIBASE_FIELD

Structure that contains column information of the result set retrieved by a SELECT statement. Column information can be obtained from this structure type using the altibase_field () or altibase_fields () functions. The value of the memory pointed to by the structure pointer thus obtained is managed internally by the ACI, so the user should not change or free it.

This structure contains the following members.

Member	Type	Description
type	ALTIBASE_FIELD_TYPE	The type of the filed
name	char [ALTIBASE_MAX_FIELD_NAME_LEN]	Name of the column. If an alias was given to the column in the query, this value will be the given alias.
name_length	int	The length of field name
org_name	char [ALTIBASE_MAX_FIELD_NAME_LEN]	The name of the original field
org_name_length	int	The length of org_name
table	char [ALTIBASE_MAX_TABLE_NAME_LEN]	Name of the table that contains this column. If the query gave an alias to a table, this value will be the given alias.
table_length	int	The length of table name
org_table	char [ALTIBASE_MAX_TABLE_NAME_LEN]	The name of the original table
org_table_length	int	The length of org_table
size	int	The size or precision of the field
scale	int	The numerical scale

struct ALTIBASE_NUMERIC

The struct ALTIBASE_NUMERIC is used to send and receive numerical data to and from the server.

This structure contains the following members.

Member	Type
precision	unsigned char
scale	unsigned char
sign	char
val	unsigned char [ALTIBASE_MAX_NUMERIC_LEN]

struct ALTIBASE_TIMESTAMP

The struct ALTIBASE_TIMESTAMP is used to send and receive date data to and from the server.

This structure contains the following members.

Member	Member Type	Description
year	short	Year
month	unsigned short	Month
day	unsigned short	Day
hour	unsigned short	Hour
minute	unsigned short	Minute
second	unsigned short	Seceond
fraction	int	One over one hundred thousand second

Other Data Types

In addition to the handles and structures described above, the following types can be used:

• ALTIBASE_ROW

• ALTIBASE_LONG

• ALTIBASE_NTS

• enum ALTIBASE_BIND_TYPE

• enum ALTIBASE_FAILOVER_EVENT

• enum ALTIBASE_FIELD_TYPE

• enum ALTIBASE_OPTION

• enum ALTIBASE_STMT_ATTR_TYPE

ALTIBASE_ROW

This is a type-safe representation of one row of data. Rows are obtained by calling altibase_fetch_row() when altibase_query() is used with a statement such as SELECT which returns a reuslt set.

A field value contains binary data or character string. If fields have data types such as BLOB, BYTE, NIBBLE, BIT, VARBIT or GEOMETRY, fields are encoded as binary data. Otherwise, fields are encoded as character string.

The NIBBLE, BIT and VARBIT are all based on binary logic in special form. A NIBBLE is a four-bit aggregation and a BIT is the basic unit of information. To obtain these easily, database effectively performs the required macro substitutions by using GET_NIBBLE_VALUE() and GET_BIT_VALUE().

The user must not change or release their values as you please because they are managed within procedure.

ALTIBASE_LONG

This can be defined as a 32-bit integer or a 64-bit integer. This works similarly to SQLLEN defined by the Altibase ODBC driver. This is used to get row number or the number of rows.

ALTIBASE_NTS

This is a macro used to indicate that the data is a null terminated string. When input binding a string, the user can set the data length to this value instead of the actual length.

If ALTIBASE_NTS is set to data length when input binding non-string binary data, the value of buffer_length is used as the data length.

enum ALTIBASE_BIND_TYPE

This gets the data type of the bind variable as follows.

The elements of this enum type are:

enum Value	Description
ALTIBASE_BIND_NULL	This is used to input NULL data into a column. Equivalent to setting the is_null member variable of the ALTIBASE_BIND structure to ALTIBASE_TRUE. Can only be used when binding parameters.
ALTIBASE_BIND_BINARY	This is used for binary data whose type is BYTE, NIBBLE, BIT, VARBIT, BLOB or GEOMETRY.
ALTIBASE_BIND_STRING	This is used for character strings such as CHAR, VARCHAR, NCHAR and NVARCHAR.
ALTIBASE_BIND_WSTRING	This is used for unicode character.
ALTIBASE_BIND_SMALLINT	This is used for the SMALLINT type which is a 16 bit sized signed integer.
ALTIBASE_BIND_INTEGER	This is used for the INTEGER type which is a 32 bit sized signed integer.
ALTIBASE_BIND_BIGINT	This is used for the BIGINT type which is a 64 bit sized signed integer.
ALTIBASE_BIND_REAL	This is used for the REAL type which is a single prcision floating-point number.
ALTIBASE_BIND_DOUBLE	This is used to represent the DOUBLE type which is a double prefloating-point number.
ALTIBASE_BIND_NUMERIC	This is used to store numeric data types such as NUMERIC, DECIMAL NUMBER and FLOAT.
ALTIBASE_BIND_DATE	This is used to represent DATE type storing date and time values.

enum ALTIBASE_FAILOVER_EVENT

This is an enumeration that represents a Failover event. Ifthe failover callback functionis registered, the failover callback function is notified of values returned by the failover events. They are used when the failover callback function determines its advance to the next step. For more details, refer to Chapter6: Using Failover.

Enum Value	Description
ALTIBASE_FO_BEGIN	This notifies the start of STF (Service Time Failover).
ALTIBASE_FO_END	This notifies the success of STF.
ALTIBASE_FO_ABORT	This notifies the failure of STF.
ALTIBASE_FO_GO	FailOverCallback sends this so that STF can advance to the next step.
ALTIBASE_FO_QUIT	FailOverCallback sends this to prevent STF from advancing to the next step.

enum ALTIBASE_FIELD_TYPE

This is an enumeration that contains the data types of the columns.

the IS_NUM_TYPE () macro can be used to check that it is a numeric type. In numeric type There are SMALLINT, INTEGER, BIGINT, REAL, DOUBLE, FLOAT, and NUMERIC.

You can use the IS_BIN_TYPE () macro to check for a binary type. Binary Types include BYTE, BLOB, NIBBLE, BIT, VARBIT, and GEOMETRY.

Refer to the alticapi.h header file for definitions of the IS_NUM_TYPE () and IS_BIN_TYPE () macros.

The elements of this enum type are:

enum Value	Data Type
ALTIBASE_TYPE_CHAR	CHAR
ALTIBASE_TYPE_VARCHAR	VARCHAR
ALTIBASE_TYPE_NCHAR	NCHAR
ALTIBASE_TYPE_NVARCHAR	NVARCHAR
ALTIBASE_TYPE_SMALLINT	SMALLINT
ALTIBASE_TYPE_INTEGER	INTEGER
ALTIBASE_TYPE_BIGINT	BIGINT
ALTIBASE_TYPE_REAL	REAL
ALTIBASE_TYPE_DOUBLE	DOUBLE
ALTIBASE_TYPE_FLOAT	FLOAT
ALTIBASE_TYPE_NUMERIC	NUMERIC
ALTIBASE_TYPE_DATE	DATE
ALTIBASE_TYPE_BLOB	BLOB
ALTIBASE_TYPE_CLOB	CLOB
ALTIBASE_TYPE_BYTE	BYTE
ALTIBASE_TYPE_NIBBLE	NIBBLE
ALTIBASE_TYPE_BIT	BIT
ALTIBASE_TYPE_VARBIT	VARBIT
ALTIBASE_TYPE_GEOMETRY	GEOMETRY

enum ALTIBASE_OPTION

It is recommended to use altibase_set_autocommit() when you want to set ALTIBASE_AUTOCOMMIT.

The elements of this enum type (that is, the connection attributes) and the types and maximum sizes of values that can be specified for each attribute are as follows:

enum Value	Data Type	Maximum Size	Description
ALTIBASE_AUTOCOMMIT	int	sizeof(int)	This is used to set connect options and affect behavior for a connection. This represents a 32 bit. ALTIBASE_AUTOCOMMIT_ON: each individual SQL statement is automatically committed right after it is executed. ALTIBASE_AUTOCOMMIT_OFF: each individual SQL statement is not automatically committed right after it is executed.
ALTIBASE_CONNECTION_TIMEOUT	int	sizeof(int)	This is used to set the value of timeout to make a connection to the database server in a nonblocking manner. Blocking can be caused by using the select() or poll() when network is unstable.
ALTIBASE_PORT	int	sizeof(int)	This is used to define server port.
ALTIBASE_TXN_ISOLATION	int	sizeof(int)	This is used to determine the transaction isolation level for current connection.
ALTIBASE_APP_INFO	char *	ALTIBASE_MAX_APP_INFO_LEN	The client uses the application ID retrieved using ALTIBASE_APP_INFO. The user can know speinformation of user's session by using this because ALTIBASE_APP_INFO runs consent in the session.
ALTIBASE_DATE_FORMAT	char *	ALTIBASE_MAX_DATE_FORMAT_LEN	This is used to display date data in formats. The default is YYYY/MM/DD HH:MI:SS.
ALTIBASE_NLS_USE	char *	ALTIBASE_MAX_NLS_USE_LEN	This determines whether to check national character set data by parsing a SQL statement.
ALTIBASE_NLS_NCHAR_LITERAL_REPLACE	int	sizeof(int)	This is used to select language. (US7ASCII : English character set, KO16KSC5601 : Korean chaset)
ALTIBASE_IPC_FILEPATH	char *	ALTIBASE_MAX_IPC_FILEPATH_LEN	The UNIX domain can be used to communicate between processes on IPC. One process usually acts as a server and the other process is the client. The UNIX domain provides a socket address space on IPC. Communicating processes connect through addresses In the UNIX domain, a connection is usually composed of one path name as ALTIBASE_HOME. The server binds its socket to a previously agreed path or address. However, if two processes connect through different paths of ALTIBASE_HOME respectively, you cannot establish a connection between them because a socket domain also provides different addressing structures. At this time, if you use ALTIBASE_HOME/trc/cm-ipc file, the Unix domain is available. Therefore, you can pass data retrieved from a shared memory between processes.

enum ALTIBASE_STMT_ATTR_TYPE

This is an enumeration used to set properties for a statement handle.

The elements of this enum type are:

Enum Value	Data Type	Maximum Size	Description
ALTIBASE_STMT_ATTR_ATOMIC_ARRAY	int	sizeof(int)	This specifies whether all of the rows should be inserted as an atomic operation or not. ARRAY INSERT inserts a single data into a given array separately and independently. In comparison, the multiple inserts are processed as a single statement when you use the ATOMIC ARRAY INSERT. You can set ALTIBASE_ATOMIC_ARRAY_ON or ALTIBASE_ATOMIC_ARRAY_OFF. If other value is set except them, error occurs during the execution of an insert. If you set ALTIBASE_ATOMIC_ARRAY_ON, ATOMIC ARRAY INSERT is in effect. Array size effects in performance. Therefore, you should declare right size of array. You would realize the performance improvements with using ATOMI ARRAY INSERT rather than ARRAY INSERT. When a_stmt_status() and altibase_stmt_processed() returns the result, only the first value of the result is valid because multiple inserts are processed as a single statement by using the ATOMIC ARRAY INSERT.

Relationship Between Data Types

The following figure illustrates the relationships among Altibase handles and other data types

In the above relationship, the ALTIBASE_RES obtained using the ALTIBASE_STMT handle is Notice that the ALTIBASE_ROW cannot be obtained (indicated by the dashed line). ALTIBASE_ROW can be obtained only through the altibase_query () related function that executes SQL statements directly without binding. Refer to description of each function for details.