3. ACI Functions Description#
This chapter describes the specifications of ACI functions used with Altibase handle. For each ACI functions, the following information are described.
- Name of the function and purpose of use
- Arguments list of the function
- Return Values
- Usages of function and notes
- Diagnosis message that can be displayed when an error occurrs in function
- Example source codes
altibase_affected_rows()#
altibase_affected_rows() may be called immediately after executing a statement. It returns the number of rows changed, deleted, or inserted by the last statement if it was an UPDATE, DELETE, or INSERT.
Syntax#
ALTIBASE_LONG altibase_affected_rows (
ALTIBASE altibase );
Example#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Values#
| Return Value | Description |
|---|---|
| Greater than 0 | An integer indicates the number of rows affected or retrieved |
| 0 | Zeo indicates that no rows were updated or that no query has yet been executed |
| ALTIBASE_INVALID_AFFECTEDROW | Error during UPDATE, DELETE, or INSERT |
Description#
This function returns the following values, depending on the type of the last SQL statement executed:
- UPDATE statement: Number of records changed
- DELETE statement: Number of records deleted
- INSERT statement: Number of records added
If the last SQL statement executed was a SELECT statement, this function will return 0. To get the number of records selected by the SELECT statement, use altibase_num_rows() should be used.
Example#
#define QSTR "UPDATE employees SET salary = salary * 1.1 WHERE group = 1"
rc = altibase_query(altibase, QSTR);
/* ... check return value ... */
printf("%ld updated\n", altibase_affected_rows(altibase));
altibase_client_version()#
altibase_client_version() returns a constant that represents the client library version.
Syntax#
int altibase_client_version( void );
Return Values#
altibase_client_version() returns the client library version in a numeric format.
Description#
altibase_client_version() returns the client library information as a constant. The value has the format MMmmttSSpp whose specific meaning is as follows.
| Format | Meaning | Remarks |
|---|---|---|
| MM | Where MM is the major version. | |
| mm | Where mm is the minor version. | When you assign a value to mm, if the value is shorter than the declared length of this, Altibase pads 0 to the rest space. |
| tt | Where tt is the term | If the value is shorter than 2, Altibase pads 0 to the rest space. |
| SS | Where SS is the patch set. | If the value is shorter than 2, Altibase pads 0 to the rest space. |
| pp | Where pp is the patch. | If the value is shorter than 2, Altibase pads 0 to the rest space. |
For example, if the returned value of this function is 605010309, the the client library version of 7.1.0.3.9.
altibase_client_verstr()#
altibase_client_verstr() returns a string that represents the client library version.
Syntax#
const char * altibase_client_verstr ( void );
Return Value#
altibase_client_verstr() returns a string that represents the client library version.
Description#
altibase_client_verstr() returns a string that represents the client library version. The value has the format x.x.x.x and each x represents the main version, minor version, term, patch set, patch in order.
The memory pointed to by the char pointer returned by this function is managed inside the library and should never be changed or released by the user.
altibase_close()#
altibase_close() closes a previously opened connection.
Syntax#
int altibase_close (
ALTIBASE altibase );
Argument#
| Data Type | Argument | In/Out | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Value#
altibase_close() returns ALTIBASE_SUCCESS on success or ALTIBASE_ERROR on failure.
Description#
This function closes the connection to the server and frees all resources allocated for the connection handle.
All statement handles belonging to the connection handle passed as arguments when this function is called Processing of SQL statements related to (ALTIBASE_STMT) is aborted, the results are discarded, and all resources associated with these statement handles are freed.
If you have a result set handle returned using a connection handle, you must first call the altibase_free_result() function to free the result set handle before executing this function. do.
Example#
altibase = altibase_init();
if (altibase == NULL)
{
return 1;
}
/* ... omit ... */
rc = altibase_close(altibase);
/* ... check return value ... */
altibase_commit()#
altibase_commit() commits the current trasnaction.
Syntax#
int altibase_commit (
ALTIBASE altibase );
Argument#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Value#
The function returns ALTIBASE_SUCCESS if successful or ALTIBASE_ERROR if unsuccessful.
Description#
This function commits a transaction running in the currently connected session. If the session is not in AUTOCOMMIT mode, a new transaction is automatically started at the next SQL statement execution after executing this function.
Example#
Refer to the example in altibase_set_autocommit().
altibase_connect()#
altibase_connect() attempts to establish a connection to an Altibase database engine running on host by using connection string.
Syntax#
int altibase_connect (
ALTIBASE altibase,
const char* connstr );
Arguments#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
| const char* | connstr | Input | Connection string |
Return Values#
The function returns ALTIBASE_SUCCESS if successful, or ALTIBASE_ERROR if an error occurred.
Description#
Connection string is used to send each value of more than one parameter such as DSN, PORT_NO, UID, PWD, CONNTYPE or NLS_USE. For more detailed information, please refer to CLI User' Manual.
The connection attribute string must be a NULL terminated string.
Example#
#define CONNSTR "DSN=127.0.0.1;PORT_NO=20300;UID=sys;PWD=manager"
ALTIBASE altibase;
altibase = altibase_init();
/* ... check return value ... */
rc = altibase_set_option(altibase, ALTIBASE_APP_INFO, "your_app_name");
/* ... check return value ... */
rc = altibase_connect(altibase, CONNSTR);
if (ALTIBASE_NOT_SUCCEEDED(rc))
{
fprintf(stderr, "Failed to connect : %s\n", altibase_error(altibase));
}
altibase_data_seek()#
altibase_data_seek() seeks to an arbitrary row in a query result set and changes the pointer location of the resource.
Syntax#
int altibase_data_seek (
ALTIBASE_RES result,
ALTIBASE_LONG offset );
Arguments#
| Data Type | Argument | In/Output | Descriptions |
|---|---|---|---|
| ALTIBASE_RES | result | Input | Result handle |
| ALTIBASE_LONG | offset | Input | The offset value is a row number and should be in the range from 0. |
Return Values#
The function returns ALTIBASE_SUCCESS if successful or ALTIBASE_ERROR if an error occurred.
Description#
altibase_data_seek() moves the internal row pointer of the result associated with the specified result indentifier to point to the specified row number. The offset value is a row number and should be in the range from 0 to altibase_num_rows(result) - 1.
altibase_data_seek() may be used only in conjunction with altibase_store_result().
Example#
#define QSTR "SELECT last_name, first_name FROM friends"
rc = altibase_query(altibase, QSTR);
/* ... check return value ... */
result = altibase_store_result(altibase);
/* ... check return value ... */
row_count = altibase_num_rows(result);
for (i = 0; i < row_count; i++)
{
rc = altibase_data_seek(result, i);
if (ALTIBASE_NOT_SUCCEEDED(rc))
{
printf("ERR : %d : ", i, altibase_error());
continue;
}
/* ... omit ... */
}
rc = altibase_free_result(result);
/* ... check return value ... */
altibase_errno()#
For the connection specified by Altibase, altibase_errno() returns the error code for the most recently invoked API function that can succeed or fail.
Syntax#
unsigned int altibase_errno (
ALTIBASE altibase );
Argument#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Values#
0 means no error occurred. An error code value for the last altibase_errno() call is returned if it failed.
Description#
altibase_errno() returns the numerical value of the error code from previous function. All functuins do not return error codes. Error codes are returned by queries for their operation. Errors are listed at Error Message Refrence in detail.
If an error occurs while executing a function, if another function is called without immediately checking the error, the error information disappears. Therefore, when an error occurs, this function should be used to check the error information.
The value returned by altibase_errno() is an Altibase self-defined error code is different from the SQLSTATE defined in the ODBC standard specification. To get SQLSTATE, altibase_sqlstate() is used. Generally, it is not recommended to write an error handling routine by checking the return value of altibase_errno().
Example#
rc = altibase_query(altibase, QSTR);
if (ALTIBASE_NOT_SUCCEEDED(rc))
{
printf("error no : %05X\n", altibase_errno(altibase));
printf("error msg : %s\n", altibase_error(altibase));
printf("sqlstate : %s\n", altibase_sqlstate(altibase));
return 1;
}
/* ... omit ... */
altibase_error()#
For the connection specified by Altibase, altibase_error() returns error message for the most recently invoked API function.
Syntax#
const char * altibase_error (
ALTIBASE altibase );
Argument#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Values#
altibase_error() returns the error text from the last function, or an empty string if no error occurred.
Description#
This function returns an error message indicating the reason for the failure if the previously executed function failed.
If an error occurs while executing a function, calling the other function without checking the error immediately removes the information about the error. Therefore, when an error occurs, you should use this function to check the error information.
The memory pointed to by the char pointer returned by this function is managed inside the library and should never be changed or released by the user.
Example#
Refer to the example in altibase_errno().
altibase_fetch_lengths()#
altibase_fetch_lengths() returns the lengths of the columns of the current row within a result set.
Syntax#
ALTIBASE_LONG * altibase_fetch_lengths (
ALTIBASE_RES result );
Argument#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE_RES | result | Input | Result handle |
Result Values#
altibase_fetch_lengths() returns an array of unsigned long integer representing the size of each column on success, or null if an error occurred.
Description#
This function returns the data length of each column constituting the current row as an array. You can use the return value of this function to determine the size of the buffer to hold the data for each column.
If the column data is a string, the length is returned without the NULL terminator.
If the column data is NULL, the length returned is ALTIBASE_NULL_DATA.
Altibase_fetch_row() must be executed more than once on the result set handle before calling this function. This function returns NULL before executing altibase_fetch_row() or when there are no more rows to return in the result set.
Since the data obtained by altibase_fetch_row() may contain binary data, you should not estimate the length of the data using the strlen() function. The user must check the length of the data to be returned using the altibase_fetch_lengths() function.
The memory pointed to by the pointer returned by this function is managed inside the library and must never be changed or released by the user.
Example#
ALTIBASE_LONG *lengths;
int num_fields;
int i;
/* ... omit ... */
num_fields = altibase_num_fields(result);
row = altibase_fetch_row(result);
if (row != NULL)
{
lengths = altibase_fetch_lengths(result);
for (i = 0; i < num_fields; i++)
{
printf("Column length %d : %ld\n", i, lengths[i]);
}
}
/* ... omit ... */
altibase_fetch_row()#
altibase_fetch_row() retrieves a row of a result set.
Syntax#
ALTIBASE_ROW altibase_fetch_row (
ALTIBASE_RES result );
Argument#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE_RES | result | Input | Result handle |
Return Values#
altibase_fetch_row() returns data in a row on success, or null if error occurs or no rows are left.
Description#
altibase_fetch_row() fetches one row of data from the result set. The function returns null if error occurs or no rows are left. When used after altibase_store_result(), altibase_fetch_row() returns null when there are no more rows to retrieve.
A numerical array corresponds to a fetched row. The offset value is a column number and should be in the range from 0 to altibase_num_fields(result) - 1.
The value can contain a character string or binary data because this is type-safe representation of one row of data. If you want to treat a value as a number, the user must convert the string yourself. For more details, refer to chapter 2: ALTIBASE_ROW.
If a value has null, null values are represented by null pointers in the ALTIBASE_ROW array. The lengths of the values in the row may be obtained by calling altibase_fetch_lengths(). The user must not get string length by calling strlen() because their lengths returned by altibase_fetch_row() can contain binary data.
The user must use the lengths of the values by calling altibase_fetch_lengths(). altibase_fetch_row() returns data storing the lengths of each result column in a row. Therefore, there can be insufficient memory if result set contains large amounts of data such as LOB or geometry. In case like that, it is more convenient to use a parepared statement for sending SQL statements to the database with separating data. Prepared statements are designed in a more secure and efficient manner. If you want to execute a statement many times, it normally reduces execution time to use a prepared statement instead.
The value returned by altibase_fetch_row() is valid only before calling altibase_fetch_row() again. You must store the value in the row variable of application to remember. The user must not change or release it as you please because it is manged within procedure.
Example#
Refer to the example in altibase_query().
altibase_field()#
altibase_field() returns the definition of one column of a result set.
Syntax#
ALTIBASE_FIELD * altibase_field (
ALTIBASE_RES result,
int fieldnr );
Arguments#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE_RES | result | Input | Result handle |
| int | fieldnr | Input | This is a column number which starts at 0. |
Return Values#
altibase_field() returns the pointer to the definition of a specified column on success, or null if error occurs or no columns are left.
Description#
This function returns information about the specified column as an ALTIBASE_FIELD pointer. Possible column numbers are values from 0 (altibase_num_fields (result) -1).
The memory pointed to by the pointer returned by this function is managed internally by the library. It should never be changed or released by the user.
Example#
ALTIBASE_FIELD *field;
int num_fields;
int i;
num_fields = altibase_num_fields(result);
for (i = 0; i < num_fields; i++)
{
field = altibase_field(result, i);
printf("%d : %s\n", i, field->name);
}
altibase_field_count()#
altibase_field_count() returns the number of columns for the most recent query on the connection.
Syntax#
int altibase_field_count (
ALTIBASE altibase );
Arguments#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Values#
| Return Value | Description |
|---|---|
| Greater than 0 | An integer indicates the number of columns in result set. |
| 0 | Zeo indicates that no result sets are left. |
| ALTIBASE_INVALID_FIELDCOUNT | Error occurs. |
Description#
altibase_field_count() returns the number of columns for the most recent query. This enables the client program to take proper action with returning 0 if the query was a SELECT statement.
Example#
/* ... omit ... */
rc = altibase_query(altibase, qstr);
/* ... check return value ... */
printf("field count = %d\n", altibase_field_count(altibase));
altibase_free_result()#
altibase_free_result() frees the memory allocated for a result set.
Syntax#
int altibase_free_result (
ALTIBASE_RES result );
Argument#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE_RES | result | Input | Result handle |
Return Values#
The function returns ALTIBASE_SUCCESS if successful or ALTIBASE_ERROR if unsuccessful.
Description#
This function returns the memory allocated to the system to store the result set.
Once the user have a handle to the result set using the following function, the user must call altibase_free_result() to free the allocated memory after the result set handle has been used.
-
altibase_store_result()
-
altibase_use_result()
-
altibase_list_fields()
-
altibase_list_tables()
After a handle is released, it must not be used to call ACI functions.
When the user got a result set handle using a connection handle, the user should release the result set handle first by calling the altibase_free_result() function before reusing the handle or calling altibase_close() function. Also when you got a result set handle using the command handle, the user should call the altiibase_free_result() function before calling altibase_stmt_close() function.
Example#
Refer to the example in altibase_query().
altibase_get_charset()#
altibase_get_charset() returns character set name for the current connection.
Syntax#
const char * altibase_get_charset (
ALTIBASE altibase );
Argument#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Values#
altibase_get_charset() returns the name of character set derived from NLS_USE environment variable.
Description#
altibase_get_charset() returns character set name for the current connection. It can be derived from NLS_USE environment variable or connection string, or can be defined by using altibase_set_charset() before sending data from and to the database server. If it is not set, it returns the default character set.
The memory pointed to by the char pointer returned by this function is managed internally by the library. It should never be changed or released by the user.
Example#
rc = altibase_set_charset(altibase, "KO16KSC5601");
/* ... check return value ... */
printf("NLS_USE = %s\n", altibase_get_charset(altibase));
altibase_get_charset_info()#
This function is not currently supported.
altibase_host_info()#
This function is not currently supported.
altibase_init()#
altibase_init() allocates or initializes an Altibase object as a connection handle.
Syntax#
ALTIBASE altibase_init ( void );
Argument#
| Data Type | Argument | In/Out | Descriptiion |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Result Values#
altibase_init() returns an initialized Altibase connection handle on success, or null if it failed.
Description#
altibase_init() allocates an Altibase object as a connection handle suitable for altibase_connect(). If altibase_init() allocates a new object as a connection handle, it is freed when altibase_close() is called to close the connection.
Example#
altibase = altibase_init();
if (altibase == NULL)
{
return 1;
}
/* ... omit ... */
rc = altibase_close(altibase);
/* ... check return value ... */
altibase_list_fields()#
altibase_list_fields() returns a result set consisting of field names in the given table.
Syntax#
ALTIBASE_RES altibase_list_fields (
ALTIBASE altibase,
const char * conditions[] );
Arguments#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
| const char ** | conditions | Input | This works as a restriction, and denotes a string containing 3 array elements. |
Return Values#
altibase_list_fields() returns result set for success, or null if an error occurred.
Description#
altibase_list_fields() returns result set consisting of field names applied to requests that meet the coditions. A string should contain 3 array elements. If there are more than 3 array elements, the rest are ignored execept 3 array elements from the first. The following array elements work as a restriction.
| Index | Condition | Meaning |
|---|---|---|
| 0 | User name | This is the LIKE condition which allows you to retrieve information of user name. If a user name argument is set to null or ALTIBASE_ALL_USERS, all privileges are granted on a user name argument. |
| 1 | Table name | This is the LIKE condition which allows you to retrieve information of table name. If a table name argument is set to null or ALTIBASE_ALL_TABLES, all privileges are granted on a table name argument. |
| 2 | Column name | This is the LIKE condition which allows you to retrieve information of column name. If a column name argument is set to null or ALTIBASE_ALL_COLUMNS, all privileges are granted on a column name argument. |
The value specified by the constraint means a pattern. The format of the pattern is the same as that specified in the LIKE condition of an SQL statement. For more information, please refer to SQL Reference.
Do not enter NULL as the second argument of this function. One of the array elements, i.e. at least one of the constraints, must be a valid value.
This function should not be called while executing another query, or execute another query while using the result set returned by executing this function.
The columns in the result set returned by this function are:
| Column Number | Column Name | Data Type | Description |
|---|---|---|---|
| 1 | TABLE_CAT | VARCHAR | This field contains the catalog name of the table, and always returns null. |
| 2 | TABLE_SCHEM | VARCHAR | This field contains the schema name of the table. If this is not appropriate for database, this returns null. |
| 3 | TABLE_NAME | VARCHAR (NOT NULL) | This field contains the name of the table. |
| 4 | COLUMN_NAME | VARCHAR (NOT NULL) | This field contains the name of the column. If column is not defined, it returns an empty string, |
| 5 | DATA_TYPE | VARCHAR (NOT NULL) | This field contains SQL data type. |
| 6 | TYPE_NAME | VARCHAR (NOT NULL) | This field contains a character string which represents the name of the data type corresponding to DATA_TYPE. |
| 7 | COLUMN_SIZE | INTEGER | This field contains the size of the column. If this is not appropriate for database, this returns null |
| 8 | BUFFER_LENGTH | INTEGER | This field denotes maximum buffer length to store the data. |
| 9 | DECIMAL_DIGITS | SMALLINT | This field denotes number of decimal digits stored in the column. If this cannot be applied to data type, this returns null. |
| 10 | NUM_PREC_RADIX | SMALLINT | If the column has a decimal numeric type and NUM_PREC_RADIX has the value 10, COLUMN_SIZE and DECIMAL_DIGITS have values which are decimal numbers allowed in the columnn. For example, a DECIMAL value is defined as DECIMAL(12, 5), this indicates that NUM_PREC_RADIX has the value 10, COLUMN_SIZE has the value 12, and DECIMAL_DIGITS has the value 5. |
| 11 | NULLABLE | SMALLINT (NOT NULL) | This field indicates if null values can be ever supported. If they can, this returns 1. Otherwise, this returns 0. |
| 12 | REMARKS | VARCHAR | This field contains a description of the column in the table. |
| 13 | COLUMN_DEF | VARCHAR | This field indicates default value of the column, and can be used to initialize the table. |
| 14 | SQL_DATA_TYPE | SMALLINT (NOT NULL) | This field contains SQL data type. |
| 15 | SQL_DATETIME_SUB | SMALLINT | This field returns an integer value representing a datetime subtype code, or null for SQL data types to which this does not apply. |
| 16 | CHAR_OCTET_LENGTH | INTEGER | This field returns maximum number of digits for character or binary string, or null for other data types. |
| 17 | ORDINAL_POSITION | INTEGER (NOT NULL) | This fiedl indicates column order of the table. The column number starts at offset 1. |
| 18 | IS_NULLABLE | VARCHAR | NO : nulls are not included in the column. YES : nulls are included in the column. |
| 19 | STORE_TYPE | CHAR(1) | This field determines the type of column to store. V: A column is stored in variable length format. F: A column is stored in fixed length format. L: A column is stored in LOB format. |
The results are aligned by using TABLE_CAT, TABLE_SCHEM, TABLE_NAME and ORDINAL_POSITION. 반환된다.
The results are aligned by using TABLE_CAT, TABLE_SCHEM, TABLE_NAME and ORDINAL_POSITION. altibase_list_fields() cannot be used with the functions such as altibase_use_result() and altibase_list_tables() which return result set. You must free current result set handle with altibase_free_result() to obtain other one.
altibase_list_tables()#
altibase_list_tables() returns a result set consisting of table names in the current database.
Syntax#
ALTIBASE_RES altibase_list_tables (
ALTIBASE altibase,
const char * conditions[] );
Arguments#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
| const char ** | conditions | Input | This works as a restriction, and denotes a string containing 3 array elements. |
Return Values#
altibase_list_tables() returns result set for success, or null if an error occurred.
Description#
altibase_list_tables() returns a result set consisting of table names applied to requests that meet the conditions. A string should contain 3 array elements. If there are more than 3 array elements, the rest are ignored except 3 array elements from the first. The following array elements work as a restriction
| Index | Condition | Description |
|---|---|---|
| 0 | User name | This is the LIKE condition which allows you to retrieve information of user name. If a user name argument is set to null or ALTIBASE_ALL_USERS, all privileges are granted on a user name argument. |
| 1 | Table name | This is the LIKE condition which allows you to retrieve information of table name. If a table name argument is set to null or ALTIBASE_ALL_TABLES, all privileges are granted on a table name argument. |
| 2 | Table type | This is the LIKE condition which allows you to retrieve information of column name. If a column name argument is set to null or ALTIBASE_ALL_TABLE_TYPES, all privileges are granted on a column name argument. |
The value specified by the constraint means a pattern. The format of the pattern is the same as that specified in the LIKE condition of an SQL statement. For more information, please refer to SQL Reference.
Do not enter NULL as the second argument of this function. One of the array elements, i.e. at least one of the constraints, must be a valid value.
This function should not be called while executing another query, or execute another query while using the result set returned by executing this function.
The columns in the result set returned by this function are:
| Column Number | Column Name | Data Type | Description |
|---|---|---|---|
| 1 | TABLE_CAT | VARCHAR | This field contains the catalog name of the table, and always returns null. |
| 2 | TABLE_SCHEM | VARCHAR | This field contains the schema name of the table. If this is not appropriate for database, this returns null. |
| 3 | TABLE_NAME | VARCHAR (NOT NULL) | This field contains the name of the table. |
| 4 | TABLE_TYPE | VARCHAR | This field denotes the table type. (Only TABLE exists in Altibase.) |
| 5 | REMARKS | VARCHAR | This field is not enabled. |
| 6 | MAXROW | BIGINT | This field represents the maximum number of rows a result set can contain. If this is set to 0, the number of rows is not limited. |
| 7 | TABLESPACE_NAME | VARCHAR | This field represents the name of the tablespace. |
| 8 | TABLESPACE_TYPE | INTEGER | This field represents the type of the tablespace. |
| 9 | PCTFREE | INTEGER | PCTFREE value set in the table. For a description of PCTFREE, refer to the CREATE TABLE statement in SQL Reference. |
| 10 | PCTUSED | INTEGER | PCTUSED value set in the table. For a description of PCTUSED, refer to the CREATE TABLE statement in SQL Reference. |
The results are aligned by using TABLE_TYPE, TABLE_CAT, TABLE_SCHEM and TABLE_NAME. altibase_list_tables() cannot be used with the functions such as altibase_use_result() and altibase_list_tables() which return result set. The user must free current result set handle with altibase_free_result() to obtain other one.
altibase_next_result()#
altibase_next_result() moves the cursor position on the next result set to read.
Syntax#
int altibase_next_result (
ALTIBASE altibase );
Arguments#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Values#
| Return Value | Description |
|---|---|
| ALTIBASE_SUCCESS | Successful and there are more result sets |
| ALTIBASE_NO_DATA | Successful and there are no more result sets |
| ALTIBASE_ERROR | An error occurred. |
Description#
This function is used to access the next result set when users execute store procedures, which can return multiple result sets.
If there is a previously retrieved result set, it must be freed using altibase_free_result() before calling altibase_next_result().
Executing this function puts the statement in the same state as if altibase_query() had been called. This means that users can call altibase_store_result() and altibase_affected_rows().
Example#
#define QSTR "EXEC PROC_RESULTSET"
ALTIBASE altibase;
ALTIBASE_RES result;
int num_fields;
int rc;
/* ... omit ... */
rc = altibase_query(altibase, QSTR);
/* ... check return value ... */
while (1)
{
result = altibase_use_result(altibase);
/* ... check return value ... */
num_fields = altibase_field_count(altibase);
process_result_set(result, num_fields );
altibase_free_result(result);
if ((rc = altibase_next_result(altibase)) == ALTIBASE_NO_DATA)
break;
/* ... check return value ... */
}
altibase_close(altibase);
altibase_num_fields()#
altibase_num_fields() returns the number of columns in a result set.
Syntax#
int altibase_num_fields (
ALTIBASE_RES result );
Arguments#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE_RES | result | Input | Result handle |
Return Values#
altibase_num_fields() returns the number of columns in a result set for success, or ALTIBASE_INVALID_FIELDCOUNT if an error occurred.
Description#
This function returns the number of columns in the result set:
The number of columns can be obtained using the result set handle or the connection handle. If previous NULL returned by altibase_store_result() or altibase_use_result() calls, the connection handle must be used.
The altibase_field_count() function should be used to get the number of columns by the connection handle.
altibase_num_rows()#
altibase_num_rows() returns the number of rows in the result set.
Syntax#
ALTIBASE_LONG altibase_num_rows (
ALTIBASE_RES result );
Argument#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE_RES | result | Input | Result handle |
Return Values#
altibase_num_rows() returns the number of rows in the result set.
Description#
altibase_num_rows() retrives the number of rows from a result set. The use of altibase_num_rows() depends on whether you use altibase_store_result() or altibase_use_result() to return the result set.
If the user uses altibase_store_result(), altibase_num_rows() returns the correct value. However, if the user uses altibase_num_rows(), altibase_num_rows() does not return the correct value until all the rows in the result set have been retrieved.
altibase_num_rows() is intended to use with statements that return a result set such as SELECT. For statements such as INSERT, UPDATE and DELETE, the number of affected rows can be obtained with altibase_affected_rows().
altibase_proto_version()#
altibase_proto_version() returns a constant representing the protocol version used by the current connection.
Syntax#
int altibase_proto_version (
ALTIBASE altibase );
Arguments#
| Data Type | Argument | In/Out | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Values#
altibase_proto_version() returns the protocol version used by the current connection as a constant on success, or ALTIBASE_INVALID_VERSION if connection handle is not valid or connection is closed.
Description#
altibase_proto_version() returns a constant representing the protocol version used by the current connection. The value has the format MMmmttSSpp whose specific meaning is as follows.
| Format | Meaning | Remarks |
|---|---|---|
| MM | Where MM is the major version. | |
| mm | Where mm is the minor version | If the value is shorter than 2, Altibase pads 0 to the rest space. |
| tt | Where tt is the term | Altibase always pads 0 and return the value. |
| SS | Where SS is the patch set | Altibase always pads 0 and return the value. |
| pp | Where pp is the patch | If the value is shorter than 2, Altibase pads 0 to the rest space. |
For example, if the returned value of this function is 605000001, the the protocol version is 7.1.0
altibase_proto_verstr()#
altibase_proto_verstr() returns a string representing the protocol version used by the current connection.
Syntax#
const char * altibase_proto_verstr (
ALTIBASE altibase );
Argument#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Values#
altibase_proto_verstr() returns the protocol version used by the current connection as a string on success, or null if connection handle for a string is not valid or connection is closed.
Description#
altibase_proto_verstr() returns a string that represents the client library version. The value has the format x.x.0.0.x. and each x represents the main version, minor version and patch in order.
The memory pointed to by the char pointer returned by this function is managed inside the library and should never be changed or released by the user.
altibase_query()#
altibase_query() executes the SQL statement.
Syntax#
int altibase_query (
ALTIBASE altibase,
const char * qstr );
Arguments#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
| const char * | qstr | Input | The SQL statement pointed to by the null-terminated string |
Return Values#
altibase_query() returns ALTIBASE_SUCCESS if the statement was successful. The function returns ALTIBASE_ERROR if an error occurred.
Description#
If altibase_query() sends a query to Altibase, the SQL statement must be pointed by the null-terminated string which should consist of a single SQL statement. Multiple-statement execution has not been enabled. The string cannot contain several statements separated by semicolons. Enabling multiple-statement execution with this function need to permit processing of stored procedures.
Example#
#define QSTR "SELECT last_name, first_name FROM friends"
ALTIBASE altibase;
ALTIBASE_RES result;
ALTIBASE_ROW row;
ALTIBASE_LONG *lengths;
int num_fields;
int rc;
int i;
/* ... omit ... */
rc = altibase_query(altibase, QSTR);
/* ... check return value ... */
result = altibase_use_result(altibase);
/* ... check return value ... */
num_fields = altibase_num_fields(result);
while ((row = altibase_fetch_row(result)) != NULL)
{
lengths = altibase_fetch_lengths(result);
for (i = 0; i < num_fields; i++)
{
printf("(%ld) %s", lengths[i], (row[i] == NULL ? "null" : row[i]));
}
printf("\n");
}
rc = altibase_free_result(result);
/* ... check return value ... */
/* ... omit ... */
altibase_rollback()#
altibase_rollback() rolls back the current transaction. In other words, the function aborts the queries you have sent before and reverts them to the old values in the database.
Syntax#
int altibase_rollback (
ALTIBASE altibase );
Arguments#
| Data Type | Argument | In/Out | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Values#
The function returns ALTIBASE_SUCCESS if successful or ALTIBASE_ERROR if an error occurred.
Description#
This function cancels (rolls back) a transaction currently running in the connected session. If the session is not in AUTOCOMMIT mode, a new transaction is automatically started at the next SQL statement execution after executing this function.
Example#
Refer to the xample in altibase_set_autocommit().
altibase_server_version()#
altibase_server_version() returns the version number of the server.
Syntax#
int altibase_server_version (
ALTIBASE altibase );
Argument#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Values#
altibase_server_version() returns the number that represents the Altibase server version on success, or ALTIBASE_INVALID_VERSION if connection handle is not valid, connection is closed or the function fails to return the value.
Description#
altibase_server_version() returns a constant representing the protocol version used by the current connection. The value has the format MMmmttSSpp whose specific meaning is as follows.
| Format | Meaning | Remarks |
|---|---|---|
| MM | When MM is the major version | |
| mm | Where mm is the minor version | If the value is shorter than 2, Altibase pads 0 to the rest space. |
| tt | Where tt is the term | Altibase always pads 0 and return the value. |
| SS | Where SS is the patch set | Altibase always pads 0 and return the value. |
| pp | Where pp is the patch | If the value is shorter than 2, Altibase pads 0 to the rest space. |
For example, if the returned value of this function is 605010309, the the protocol version is 7.1.0.3.9.
altibase_server_verstr()#
altibase_server_verstr() returns a string that represents the server version number.
Syntax#
const char * altibase_server_verstr (
ALTIBASE altibase );
Arguments#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Values#
altibase_server_verstr() returns a character string that represents the server version number on success, or null if connection handle is not valid, connection is closed, or the function fails to return the value.
Description#
This function returns a string that represents the client library version. The value has the format x.x.x.x.x and each x represents the main version, minor version, term version, patch set, patch version in order.
The memory pointed to by the char pointer returned by this function is managed inside the library and should never be changed or released by the user.
altibase_set_charset()#
altibase_set_charset() is used to set the character set for the current connection.
Syntax#
int altibase_set_charset (
ALTIBASE altibase,
const char * charset );
Arguments#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
| const char * | charset | Input | Character set name |
Return Values#
altibase_set_charset() returns ALTIBASE_SUCCESS for success, or ALTIBASE_ERROR if an error occurred.
Description#
altibase_set_charset() is used to set the character set for the current connection. The character set must be set before connecting to the server.
In addition to this function, the character set can also be set using the ALTIBASE_NLS_USE environment variable or the connection string attribute when connecting to the server. Character set settings are given priority in order of the altibase_set_charset() function, the connection attribute string, and the ALTIBASE_NLS_USE environment variable.
Example#
ALTIBASE altibase;
altibase = altibase_init();
/* ... check return value ... */
rc = altibase_set_charset(altibase, "KO16KSC5601"));
if (ALTIBASE_NOT_SUCCEEDED(rc))
{
/* ... error handling ... */
}
rc = altibase_connect(altibase, CONNSTR);
/* ... check return value ... */
altibase_set_autocommit()#
altibase_set_autocommit() sets the autocommit mode to on.
Syntax#
int altibase_set_autocommit (
ALTIBASE altibase,
int mode );
Arguments#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
| int | mode | Input | This determines whether the autocommit mode is set to on. |
Return Values#
The function returns ALTIBASE_SUCCESS if successful or ALTIBASE_ERROR if an error occurred.
Description#
The value of the autocommit mode can be ALTIBASE_AUTOCOMMIT_ON or ALTIBASE_AUTOCOMMIT_OFF. If it cannot, error occurs. altibase_set_autocommit() enables the autocommit mode if ALTIBASE_AUTOCOMMIT_ON is set, or disables it if ALTIBASE_AUTOCOMMIT_OFF is set. By default, autocommit is enabled.
Example#
rc = altibase_set_autocommit(altibase, ALTIBASE_AUTOCOMMIT_OFF);
/* ... check return value ... */
/* ... omit ... */
rc = (error_exist) ? altibase_rollback(altibase) : altibase_commit(altibase);
if (ALTIBASE_NOT_SUCCEEDED(rc))
{
/* ... error handling ... */
}
rc = altibase_set_autocommit(altibase, ALTIBASE_AUTOCOMMIT_ON);
/* ... check return value ... */
altibase_set_failover_callback()#
altibase_set_failover_callback() registers failover callbcaks for the failover to happen in Altibase.
Syntax#
int altibase_set_failover_callback (
ALTIBASE altibase,
ALTIBASE_FAILOVER_CALLBACK callback,
void * app_context );
Arguments#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
| ALTIBASE_FAILOVER_CALLBACK | callback | Input | This denotes failover callback for registeration. If this is set to null, you can cancel the registeration. |
| void * | app_context | Input | This denotes user context. This is also function pointer used by callback to store an address of a function. |
Return Values#
altibase_set_failover_callback() returns ALTIBASE_SUCCESS for success, or ALTIBASE_ERROR if an error occurred.
Description#
altibase_set_failover_callback() need to be called to register failover callbcaks for communication with user application only at the time of STF(Service Time Failover). If the user wants to cancel the registeration, the callback argument should be set to null.
The user must register failover callbacks after calling altibase_connect() successfully.
Example#
Refer to the example in chapter 4. Fail-Over of Replication Manual.
altibase_set_option()#
altibase_set_option() enables or disables an option for the connection.
Syntax#
int altibase_set_option (
ALTIBASE altibase,
ALTIBASE_OPTION option,
const void * arg );
Argument#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
| ALTIBASE_OPTION | option | Input | Option type |
| const void * | arg | Input | Option value |
Return Values#
altibase_set_option() returns ALTIBASE_SUCCESS for success, or ALTIBASE_ERROR if an error occurred.
Description#
altibase_set_option() enables or disables an option for the connection. The user can call this function many times when enabling several options.
altibase_set_option() can be used after calling altibase_init() and before calling altibase_connect(). For details about an option for connection, refer to enum ALTIBASE_OPTION.
Example#
ALTIBASE altibase;
altibase = altibase_init();
/* ... check return value ... */
rc = altibase_set_option(altibase, ALTIBASE_APP_INFO, "myapp");
/* ... check return value ... */
rc = altibase_set_option(altibase, ALTIBASE_NLS_USE, "KO16KSC5601");
/* ... check return value ... */
rc = altibase_connect(altibase, CONNSTR);
if (ALTIBASE_NOT_SUCCEEDED(rc))
{
fprintf(stderr, "Failed to connect: %s\n", altibase_error(altibase));
}
altibase_sqlstate()#
altibase_sqlstate() returns a null-terminated string containing the SQLSTATE error code for the most recently executed SQL statement.
Syntax#
const char * altibase_sqlstate (
ALTIBASE altibase );
Arguments#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Values#
altibase_sqlstate() returns a null-terminated string containing the SQLSTATE error code.
Description#
altibase_sqlstate() returns a null-terminated string containing the SQLSTATE error code for the most recently executed SQL statement. The error code consists of five characters. '00000' means "no error". For a list of possible values of SQLSTATE, refer to Altibase Error Message Reference.
SQLSTATE values returned by altibase_sqlstate() differ from Altibase-specific error numbers returned by altibase_errno(). It is recommanded not to check the values returned by altibase_errno() but those of SQLSTATE if you need error code.
Not all Altibase error numbers returned by altibase_errno() are mapped to SQLSTATE error codes. Therefore, you cannot know the values of SQLSTATE by checking thoses returned by altibase_errno(), or you cannot know the values returned by altibase_errno() by checking those of SQLSTATE exactly.
Make sure you check the value before calling another function because it is initialized or new one is created instead if you call another function. You must not change or cancel it as you please because it is managed within procedure.
Example#
Refer to the example in altibase_errno().
altibase_store_result()#
The statement can produce a result set successfully by calling altibase_store_result().
Syntax#
ALTIBASE_RES altibase_store_result (
ALTIBASE altibase );
Arguments#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Values#
altibase_store_result() returns an ALTIBASE_RES result structure with the results for success, or null if an error occurred.
Description#
altibase_store_result() returns the contents of one cell from an Altibase result set of a query.
If the user calls altibase_store_result(), the function reads the entire result of a query to the client and allocates a ALTIBASE_RES structure. And then the function places the result into this structure. It is not neccessary to communicate with the client when you call () because entire result is already stored. Therefore, altibase_fetch_row() returns the values which are already placed by altibase_store_result().
Great attention should be paid to call altibase_store_result() because there can be insufficient memory if result set contaions large amounts of data such as LOB or geometry. An empty result set is returned instead of null if there are no row returned. Therefore, if you have called altibase_store_result() and gotten back a result that is a null pointer for a SELECT statement, the user can know error occurs. If calling altibase_store_result() instead of altibase_use_result(), the user can use the followings additionally.
-
altibase_num_rows()
-
altibase_data_seek()
altibase_store_result() cannot be used with the functions such as altibase_use_result() and altibase_list_tables() which return result set. The user must call altibase_free_result() to free current result set handle and obtain other one after you are done with the result set.
After using it, The result set obtained with this function must be releases by using altibase_free_result().
Example#
Refer to the examples in altibase_data_seek() and altibase_query().
altibase_use_result()#
altibase_use_results gets the result set for query execution.
Syntax#
ALTIBASE_RES altibase_use_result (
ALTIBASE altibase );
Argument#
| Data Type | Argument | In/Output | Description |
|---|---|---|---|
| ALTIBASE | altibase | Input | Connection handle |
Return Values#
altibase_use_result() returns an ALTIBASE_RES result structure for success, or null if an error occurred
Description#
altibase_use_result() returns result set of a query.
This function does not actually read the result set into the client like altibase_store_result() does. Instead, each row must be retrieved individually by making calls to altibase_fetch_row(). This reads the result of a query directly from the server without storing it in a temporary table or local buffer.
altibase_use_result() returns an empty result set instead of NULL even when there are no query results. If NULL is returned by a call to altibase_use_result(), the result set failed to be read.
altibase_use_result() cannot be mixed with other functions that return a result set, such as altibase_store_result() and altibase_list_tables(). That is, for functions that return a result set, first release the result set returned by one function and then the user can use functions to get different result sets.
The user must call altibase_free_result() to free current result set handle and obtain other one after done with the result set.
Example#
Refer to the example in altibase_query().