Navigation

CUBRID CCI (CCI Client Interface) driver implements an interface to enable access from C-based application to CUBRID database server through broker. It is also used as back-end infrastructure for creating tools (PHP, ODBC, etc.) which use the CAS application servers. In this environment, the CUBRID broker sends queries received from applications to a database and transfers the result to applications.

It is automatically installed upon CUBRID installation and can be found in the $CUBRID/lib directory. A header file as well as library files is required to use the driver.

Windows

UNIX/Linux

C header file

include/cas_cci.h

include/cas_cci.h

Static library

lib/cascci.lib

lib/libcascci.a

Dynamic library

bin/cascci.dll

lib/libcascci.so

Because CUBRID CCI driver is connected through the CUBRID broker, you can manage it the same way as other interfaces such as JDBC, PHP, ODBC, etc. In fact, CCI provides back-end infrastructure to implement PHP, ODBC, Python, and Ruby interfaces.

The applications using CCI interact with CUBRID in the process of connecting to CAS, preparing queries, executing queries, handling response, and disconnecting. In each process, CCI communicates with applications through connection handle, query handle, and response handle.

The default value of auto-commit mode can be configured by using CCI_DEFAULT_AUTOCOMMIT (which is a broker parameter). If it is omitted, the default value is set to ON. To change auto-commit mode within applications, you should use the cci_set_autocommit() function. If auto-commit mode is OFF, you should explicitly commit or roll back transactions by using the cci_end_tran() function.

General process for writing applications is as follows. For using the prepared statement, additional step binding data to a variable is required; the examples 1 and 2 show the way to implement this.

If you want to compile the CCI application on Windows, "WINDOWS" should be defined. Therefore, "-DWINDOWS" option should be defined on the compiler.

The database connection in thread-based programming must be used independently each other.

In autocommit mode, the transaction is not committed if all results are not fetched after running the SELECT statement. Therefore, although in autocommit mode, you should end the transaction by calling cci_end_tran() if some error occurs during fetching for the resultset.

Example 1

//Example to execute a simple query#include <stdio.h>#include "cas_cci.h"#define BUFSIZE (1024)intmain(void){intcon=0,req=0,col_count=0,i,ind;interror;char*data;T_CCI_ERRORcci_error;T_CCI_COL_INFO*col_info;T_CCI_CUBRID_STMTstmt_type;char*query="select * from code";//getting a connection handle for a connection with a servercon=cci_connect("localhost",33000,"demodb","dba","");if(con<0){printf("cannot connect to database\n");return1;}//preparing the SQL statementreq=cci_prepare(con,query,0,&cci_error);if(req<0){printf("prepare error: %d, %s\n",cci_error.err_code,cci_error.err_msg);gotohandle_error;}//getting column information when the prepared statement is the SELECT querycol_info=cci_get_result_info(req,&stmt_type,&col_count);if(col_info==NULL){printf("get_result_info error: %d, %s\n",cci_error.err_code,cci_error.err_msg);gotohandle_error;}//Executing the prepared SQL statementerror=cci_execute(req,0,0,&cci_error);if(error<0){printf("execute error: %d, %s\n",cci_error.err_code,cci_error.err_msg);gotohandle_error;}while(1){//Moving the cursor to access a specific tuple of resultserror=cci_cursor(req,1,CCI_CURSOR_CURRENT,&cci_error);if(error==CCI_ER_NO_MORE_DATA){break;}if(error<0){printf("cursor error: %d, %s\n",cci_error.err_code,cci_error.err_msg);gotohandle_error;}//Fetching the query result into a client buffererror=cci_fetch(req,&cci_error);if(error<0){printf("fetch error: %d, %s\n",cci_error.err_code,cci_error.err_msg);gotohandle_error;}for(i=1;i<=col_count;i++){//Getting data from the fetched resulterror=cci_get_data(req,i,CCI_A_TYPE_STR,&data,&ind);if(error<0){printf("get_data error: %d, %d\n",error,i);gotohandle_error;}printf("%s\t|",data);}printf("\n");}//Closing the request handleerror=cci_close_req_handle(req);if(error<0){printf("close_req_handle error: %d, %s\n",cci_error.err_code,cci_error.err_msg);gotohandle_error;}//Disconnecting with the servererror=cci_disconnect(con,&cci_error);if(error<0){printf("error: %d, %s\n",cci_error.err_code,cci_error.err_msg);gotohandle_error;}return0;handle_error:if(req>0)cci_close_req_handle(req);if(con>0)cci_disconnect(con,&cci_error);return1;}

Example 2

//Example to execute a query with a bind variablechar*query="select * from nation where name = ?";charnamebuf[128];//getting a connection handle for a connection with a servercon=cci_connect("localhost",33000,"demodb","dba","");if(con<0){printf("cannot connect to database ");return1;}//preparing the SQL statementreq=cci_prepare(con,query,0,&cci_error);if(req<0){printf("prepare error: %d, %s ",cci_error.err_code,cci_error.err_msg);gotohandle_error;}//Binding date into a valuestrcpy(namebuf,"Korea");error=cci_bind_param(req,1,CCI_A_TYPE_STR,namebuf,CCI_U_TYPE_STRING,CCI_BIND_PTR);if(error<0){printf("bind_param error: %d ",error);gotohandle_error;}

Once you have written applications using CCI, you should decide, according to its features, whether to execute CCI as static or dynamic link before you build it. See the table in CCI Overview to decide which library will be used.

The following is an example of Makefile, which makes a link by using the dynamic library on UNIX/Linux.

You can retrieve LOB data by using the following functions in CCI applications. Note that if you enter data in the LOB type column, the actual LOB data is stored in the file located in external storage and Locator value is stored in the LOB type column. Thus, to retrieve the LOB data stored in the file, you should call the cci_blob_read() function but the cci_get_data() function.

If the value of error code is between -20002 and -20999, it is caused by CCI API functions. You can output CCI error messages which CCI error codes represent by using the cci_get_err_msg() function.

If the value of error code is between -10000 and -10999, it is caused by CAS and transferred by CCI API functions.

If the value of error code is between -11000 and -11999, it is caused by broker server and transferred by CCI API functions.

If the value of error code is CCI_ER_DBMS (-20001), it is caused by database server. You can check server error codes in err_buf.err_code of the database error buffer (err_buf).

Warning

If an error occurs in server, the value of CCI_ER_DBMS, which is error code returned by a function may be different from the value of the err_buf.err_code. Except server errors, every error code stored in err_buf is identical to that returned by a function.

Note

In the earlier version of CUBRID 9.0, the CCI and CAS error codes had values which w different in the version of CUBRID 9.0 or later. Therefore, the users who developed the applications by using the error code names must recompile them and the users who developed them by directly assigning error code numbers must recompile them after changing the number values.

The database error buffer (err_buf) is a struct variable of T_CCI_ERROR defined in the cas_cci.h header file. For how to use it, see the example below.

CCI error codes which starting with CCI_ER are defined in enum called T_CCI_ERROR_CODE under the $CUBRID/include/cas_cci.h file. Therefore, to use this error code name in program code, you should include a header file in the upper side of code by entering #include "cas_cci.h".

The following example shows how to display error messages. In the example, the error code value (req) returned by cci_prepare() is CCI_ER_DBMS. -493 (server error code) is stored in cci_error.err_code
and the error message, 'Syntax: Unknown class "notable". select * from notable' is stored in cci_error.err_msg of the database error buffer.

The sample program shows how to write a CCI application by using the demodb database which is included with the CUBRID installation package. You can practice the ways to connect to CAS, prepare queries, execute queries, handle response, disconnect from CAS, etc. by following sample program below. In the sample program, the dynamic link on Linux environment is used.

The code below shows information about olympic table schema in the demodb database which is used for sample program.

Make sure that the demodb database and the broker are running before you execute the sample program. You can start the demodb database and the broker by executing the cubrid utility. The code below shows how to run a database server and broker by executing the cubrid utility.

With the program source and the Makefile prepared, executing make will create an executable file named test. If you use a static library, there is no need to deploy additional files and the execution will be faster. However, it increases the program size and memory usage. If you use a dynamic library, there will be some performance overhead but the program size and memory usage can be optimized.

The code below a command line that makes a test program build by using a dynamic library instead of using make on Linux.

The cci_bind_param function binds data in the bind variable of prepared statement. This function converts value of the given a_type to an actual binding type and stores it. Subsequently, whenever cci_execute() is called, the stored data is sent to the server. If cci_bind_param () is called multiple times for the same index, the latest configured value is valid.

Parameters:

req_handle -- (IN) Request handle of a prepared statement

index -- (IN) Location of binding; it starts with 1.

a_type -- (IN) Data type of value

value -- (IN) Data value to bind

u_type -- (IN) Data type to be applied to the database

flag -- (IN) bind_flag(CCI_BIND_PTR).

Returns:

Error code (0: success)

CCI_ER_REQ_HANDLE

CCI_ER_TYPE_CONVERSION

CCI_ER_BIND_INDEX

CCI_ER_ATYPE

CCI_ER_NO_MORE_MEMORY

If NULL is bound to the database, there can be two scenarios.

When the value of value is a NULL pointer

When the value of u_type is CCI_U_TYPE_NULL

If CCI_BIND_PTR is configured for flag, the pointer of value variable is copied (shallow copy), but no value is copied. If it is not configured for flag, the value of value variable is copied (deep copy) by allocating memory. If multiple columns are bound by using the same memory buffer, CCI_BIND_PTR must not be configured for the flag.

T_CCI_A_TYPE is a C language type that is used in CCI applications for data binding, and consists of primitive types such as int and float, and user-defined types defined by CCI such as T_CCI_BIT and T_CCI_DATE. The identifier for each type is defined as shown in the table below.

a_type

value type

CCI_A_TYPE_STR

char *

CCI_A_TYPE_INT

int *

CCI_A_TYPE_FLOAT

float *

CCI_A_TYPE_DOUBLE

double *

CCI_A_TYPE_BIT

T_CCI_BIT *

CCI_A_TYPE_SET

T_CCI_SET *

CCI_A_TYPE_DATE

T_CCI_DATE *

CCI_A_TYPE_BIGINT

int64_t *
(For Windows: __int64 *)

CCI_A_TYPE_BLOB

T_CCI_BLOB

CCI_A_TYPE_CLOB

T_CCI_CLOB

T_CCI_U_TYPE is a column type of database and data bound though the value argument is converted into this type. The cci_bind_param () function uses two kinds of types to send information which is used to convert U-type data from A-type data; the U-type data can be interpreted by database language and the A-type data can be interpreted by C language.

There are various A-type data that are allowed by U-type data. For example, CCI_U_TYPE_INT can receive CCI_A_TYPE_STR as A-type data including CCI_A_TYPE_INT. For information on type conversion, see "CUBRID SQL Guide > Data Types > Implicit Type Conversion > Rules."

Both T_CCI_A_TYPE and T_CCI_U_TYPE enum(s) are defined in the cas_cci.h file. The definition of each identifier is described in the table below.

u_type

Corresponding a_type (default)

CCI_U_TYPE_CHAR

CCI_A_TYPE_STR

CCI_U_TYPE_STRING

CCI_A_TYPE_STR

CCI_U_TYPE_BIT

CCI_A_TYPE_BIT

CCI_U_TYPE_VARBIT

CCI_A_TYPE_BIT

CCI_U_TYPE_NUMERIC

CCI_A_TYPE_STR

CCI_U_TYPE_INT

CCI_A_TYPE_INT

CCI_U_TYPE_SHORT

CCI_A_TYPE_INT

CCI_U_TYPE_MONETARY

CCI_A_TYPE_DOUBLE

CCI_U_TYPE_FLOAT

CCI_A_TYPE_FLOAT

CCI_U_TYPE_DOUBLE

CCI_A_TYPE_DOUBLE

CCI_U_TYPE_DATE

CCI_A_TYPE_DATE

CCI_U_TYPE_TIME

CCI_A_TYPE_DATE

CCI_U_TYPE_TIMESTAMP

CCI_A_TYPE_DATE

CCI_U_TYPE_OBJECT

CCI_A_TYPE_STR

CCI_U_TYPE_BIGINT

CCI_A_TYPE_BIGINT

CCI_U_TYPE_DATETIME

CCI_A_TYPE_DATE

CCI_U_TYPE_BLOB

CCI_A_TYPE_BLOB

CCI_U_TYPE_CLOB

CCI_A_TYPE_CLOB

CCI_U_TYPE_ENUM

CCI_A_TYPE_STR

When the string including the date is used as an input parameter of DATE, DATETIME, or TIMESTAMP, only "YYYY/MM/DD" is allowed for the date string type. Therefore, "2012/01/31" is valid, but "01/31/2012" or "2012-01-31" is invalid. The following is an example of having the string that includes the date as an input parameter of the date type.

The cci_bind_param_array function binds a parameter array for a prepared cci_execute_array() occurs, data is sent to the server by the stored value pointer. If cci_bind_param_array () is called multiple times for the same index, the last configured value is valid. If NULL is bound to the data, a non-zero value is configured in null_ind. If value is a NULL pointer, or u_type is CCI_U_TYPE_NULL, all data are bound to NULL and the data buffer used by value cannot be reused. For the data type of value for a_type, see the cci_bind_param() function description.

The cci_col_seq_insert function inserts one member at the index-th (base: 1) position of the sequence attribute values. The following example shows how to insert "a" at the first position of the sequence attribute values.

The cci_col_seq_put function replaces the index-th (base: 1) member of the sequence attribute values with a new value. The following example shows how to replace the first member of the sequence attributes values with "a".

The cci_connect_ex function returns CCI_ER_DBMS error and checks the error details in the database error buffer (err_buf) at the same time. In that point, it is different from cci_connect() and the others are the same as the cci_connect() function.

Parameters:

ip -- (IN) A string that represents the IP address of the server (host name)

The cci_connect_with_url function connects a database by using connection information passed with a url argument. If broker's HA feature is used in CCI, you must specify the connection information of the standby broker server with altHosts property, which is used for the failover, in the url argument of this function. It returns the ID of a connection handle on success; it returns an error code on failure. For details about HA features of broker, see Duplexing Brokers.

Parameters:

url -- (IN) A string that contains server connection information.

db_user -- (IN) Database user name. If it is NULL or an empty string, it becomes <db_user> in url. If both of this value and <db_user> in url are not specified, DB user name becomes PUBLIC.

db_passwd -- (IN) Database user password. If it is NULL or an empty string, use <db_password> in url. If both of this value and <db_password> in url are not specified, DB password becomes NULL.

altHosts is the property related to connection target and loginTimeout, queryTimeout, and disconnectOnQueryTimeout are the properties related to timeout; logSlowQueries, logTraceApi, and logTraceNetwork are the properties related to log information configuration for debugging.

Note that a property name which is a value to be entered in the url argument is not case sensitive.

host : A host name or IP address of the master database

port : A port number

db_name : A name of the database

db_user : A name of the database user

db_password : A database user password

altHosts = standby_broker1_host, standby_broker2_host, . . .: Specifies the broker information of the standby server, which is used for failover when it is impossible to connect to the active server. You can specify multiple brokers for failover, and the connection to the brokers is attempted in the order listed in alhosts.

rcTime : After the failure occurred on the first connected broker, the application connects to the broker specified by altHosts(broker failover). Then it attempts to reconnect to the first connected broker at every rcTime(default value: 600 seconds).

loadBalance : When this value is true, the applications try to connect to the main host and alternative hosts specified with the altHosts property as a random order. (default value: false).

query_timeout | queryTimeout : If time specified in these properties has expired when calling cci_prepare(), cci_execute(), etc. a cancellation message for query request which was sent to a server will be delivered and called function returns a CCI_ER_QUERY_TIMEOUT (-39) error. The value returned upon timeout may vary depending on a value specified in disconnect_on_query_timeout. For details, see disconnect_on_query_timeout.

disconnect_on_query_timeout | disconnectOnQueryTimeout : Whether to disconnect socket immediately after time for query request has expired. It determines whether to terminate a socket connection immediately or wait for server response after sending cancellation message for query request to a server when calling cci_prepare(), cci_execute(), etc. The default value is false, meaning that it will wait for server response. It this value is true, a socket will be closed immediately after sending a cancellation message to a server upon timeout and returns the CCI_ER_QUERY_TIMEOUT (-39) error. (If an error occurs on database server side, not on broker side, it returns -1. If you want to view error details, see error codes in "database error buffer." You can get information how to check error codes in CCI Error Codes and Error Messages.) In this case, you must explicitly close the database connection handle by using the cci_disconnect() function. Please note that there is a possibility that a database server does not get a cancellation message and execute a query even after an error is returned.

logFile : A log file name for debugging (default value: cci_ <handle_id> .log). <handle_id> indicates the ID of a connection handle returned by this function.

logBaseDir : A directory where a debug log file is created. The file name including the path will be logBaseDir/logFile, and the relative path is possible.

The cci_connect_with_url_ex function returns CCI_ER_DBMS error and checks the error details in the database error buffer (err_buf) at the same time. In that point, it is different from cci_connect_with_url() and the others are the same as the cci_connect_with_url() function.

Parameters:

url -- (IN) A string that contains server connection information

db_user -- (IN) Database user name. If it is NULL or an empty string, use <db_user> in url.

db_passwd -- (IN) Database user password. If it is NULL or an empty string, use <db_password> in url.

The cci_cursor function moves the cursor specified in the request handle to access the specific record in the query result executed by cci_execute(). The position of cursor is moved by the values specified in the origin and offset values. If the position to be moved is not valid, CCI_ER_NO_MORE_DATA is returned.

Parameters:

req_handle -- (IN) Request handle

offset -- (IN) Offset to be moved

origin -- (IN) Variable to represent a position. The type is T_CCI_CURSOR_POS. T_CCI_CURSOR_POS enum consists of CCI_CURSOR_FIRST, CCI_CURSOR_CURRENT and CCI_CURSOR_LAST.

err_buf -- (OUT) Database error buffer

Returns:

Error code (0: success)

CCI_ER_REQ_HANDLE

CCI_ER_NO_MORE_DATA

CCI_ER_COMMUNICATION

Example

//the cursor moves to the first recordcci_cursor(req,1,CCI_CURSOR_FIRST,&err_buf);//the cursor moves to the next recordcci_cursor(req,1,CCI_CURSOR_CURRENT,&err_buf);//the cursor moves to the last recordcci_cursor(req,1,CCI_CURSOR_LAST,&err_buf);//the cursor moves to the previous recordcci_cursor(req,-1,CCI_CURSOR_CURRENT,&err_buf);

The cci_cursor_update function updates cursor_pos from the value of the index -th column to value. If the database is updated to NULL, value becomes NULL. For update conditions, see cci_prepare(). The data types of value for a_type are shown in the table below.

The cci_end_tran function performs commit or rollback on the current transaction. At this point, all open request handles are terminated and the connection to the database server is disabled. However, even after the connection to the server is disabled, the connection handle remains valid.

Parameters:

conn_handle -- (IN) Connection handle

type -- (IN) CCI_TRAN_COMMIT or CCI_TRAN_ROLLBACK

err_buf -- (OUT) Database error buffer

Returns:

Error code (0: success)

CCI_ER_CON_HANDLE

CCI_ER_DBMS

CCI_ER_COMMUNICATION

CCI_ER_TRAN_TYPE

You can configure the default value of auto-commit mode by using CCI_DEFAULT_AUTOCOMMIT (broker parameter) upon startup of an application. If configuration on broker parameter is omitted, the default value is ON; use the cci_set_autocommit() function to change auto-commit mode within an application. If auto-commit mode is OFF, you must explicitly commit or roll back transaction by using the cci_end_tran() function.

Converts the input string to a string that can be used in the CUBRID query. The following parameters are specified in this function: connection handle or no_backslash_escapes setting value, output string pointer, input string pointer, the length of the input string, and the address of the T_CCI_ERROR struct variable.

Parameters:

conn_handle -- (IN) connection handle or no_backslash_escapes setting value. When a connection handle is given, the no_backslash_escapes parameter value is read to determine how to convert. Instead of the connection handle, CCI_NO_BACKSLASH_ESCAPES_TRUE or CCI_NO_BACKSLASH_ESCAPES_FALSE value can be sent to determine how to convert.

to -- (OUT) Result string

from -- (IN) Input string

length -- (IN) Maximum byte length of the input string

err_buf -- (OUT) Database error buffer

Returns:

Success: Byte length of the changed string, Failure: Error Code

CCI_ER_CON_HANDLE

CCI_ER_COMMUNICATION

When the system parameter no_backslash_escapes is yes (default) or when the CCI_NO_BACKSLASH_ESCAPES_TRUE value is sent to the connection handle location, the string is converted to the following characters.

' (single quote) => ' + ' (escaped single quote)

When the system parameter no_backslash_escapes is no or when the CCI_NO_BACKSLASH_ESCAPES_FALSE value is sent to the connection handle location, the string is converted to the following characters:

\n (new line character, ASCII 10) => \ + n (backslash + Alphabet n)

\r (carriage return, ASCII 13) => \ + r (backslash + Alphabet r)

\0 (ASCII 0) => \ + 0 (backslash + 0(ASCII 48)

\ (backslash) => \ + \

You can assign the space where the result string will be saved by using the length parameter. It will take as much as the byte length of the maximum input string * 2 + 1.

The cci_execute function executes the SQL statement (prepared statement) that has executed cci_prepare(). A request handle, flag, the maximum length of a column to be fetched, and the address of a T_CCI_ERROR construct variable in which error information being stored are specified as arguments.

Parameters:

req_handle -- (IN) Request handle of the prepared statement

flag -- (IN) exec flag ( CCI_EXEC_ASYNC or CCI_EXEC_QUERY_ALL )

max_col_size -- (IN) The maximum length of a column to be fetched when it is a string data type in bytes. If this value is 0, full length is fetched.

err_buf -- (OUT) Database error buffer

Returns:

SELECT : Returns the number of results in sync mode. Returns 0 in async mode.

INSERT, UPDATE : Returns the number of rows reflected.

Others queries : 0

Failure : Error code

CCI_ER_REQ_HANDLE

CCI_ER_BIND

CCI_ER_DBMS

CCI_ER_COMMUNICATION

CCI_ER_QUERY_TIMEOUT

CCI_ER_LOGIN_TIMEOUT

The function of retrieving the query result from the server by configuring flag can be classified as synchronous or asynchronous. Or it can be determined whether to execute multiple queries or one query. If the flag is set to CCI_EXEC_QUERY_ALL, a synchronous mode (sync_mode) is used to retrieve query results immediately after executing prepared queries if it is set to CCI_EXEC_ASYNC, an asynchronous mode (async_mode) is used to retrieve the result immediately each time a query result is created. The flag is set to CCI_EXEC_QUERY_ALL by default, and in such cases the following rules are applied.

Through a flag, the behavior of retrieving the query result from the server can be set as synchronous or asynchronous, and the way of query execution can be set as all queries or the first one.

If the flag is set as CCI_EXEC_ASYNC, an asynchronous mode is used to retrieve the result immediately each time a query result is created. If not, a synchronous mode is used to retrieve query results after executing prepared queries all.

If the flag is set to CCI_EXEC_QUERY_ALL, all prepared queries(separated by semicolon) are executed. If not, only the first query is executed.

If the flag is set to CCI_EXEC_QUERY_ALL, the following rules are applied.

The return value is the result of the first query.

If an error occurs in any query, the execution is processed as a failure.

For a query composed of in a query composed of q1; q2; q3, even if an error occurs in q2 after q1 succeeds the execution, the result of q1 remains valid. That is, the previous successful query executions are not rolled back when an error occurs.

If a query is executed successfully, the result of the second query can be obtained using cci_next_result().

max_col_size is a value that is used to determine the maximum length of a column to be sent to a client when the columns of the prepared statement are CHAR, VARCHAR, BIT or VARBIT. If this value is 0, full length is fetched.

If autocommit mode is on, each query in the array is committed after executing.

Note

In the previous version of 2008 R4.3, if the autocommit mode is on, all queries in the array were committed after all of them are executed. From 2008 R4.3 version, the transaction is committed every time when a query is executed.

In autocommit mode off, if the general error occurs during executing one of the queries in the array on the cci_execute_array function which does a batch processing of the queries, the query with an error is ignored and the next query is executed continuously. But if the deadlock occurs, the error occurs as rolling back the transaction.

In CCI, multiple jobs can be processed simultaneously when using DML queries such as INSERT / UPDATE / DELETE. CCI_QUERY_RESULT_RESULT and cci_execute_batch() functions can be used to execute such batch jobs. Note that prepared statements cannot be used in the cci_execute_batch() function. The query result will be stored on the array of T_CCI_QUERY_RESULT structure.

Note that the validity check is not performed for each parameter entered in the macro.

After using the query_result variable, you must delete the query result by using the cci_query_result_free() function.

If autocommit mode is on, each query in the array is committed after executing.

Note

In the previous version of 2008 R4.3, if the autocommit is on, all queries in the array were committed after all of them are executed. From 2008 R4.3 version, each query in the array is committed right after each running.

If autocommit mode is off, after the general error occurs during executing one of the queries in the array on the cci_execute_batch function which does a batch processing of the queries, the query with an error is ignored and the next query is executed. But if the deadlock occurs, the error occurs as rolling back the transaction.

The cci_fetch function fetches the query result executed by cci_execute() from the server-side CAS and stores it to the client buffer. The cci_get_data() function can be used to identify the data of a specific column from the fetched query result.

The cci_fetch_sensitive function sends changed values for sensitive column when the SELECT query result is delivered. If the results by req_handle are not sensitive, they are same as the ones by :c:func`cci_fetch`. The return value of CCI_ER_DELETED_TUPLE means that the given row has been deleted.

Parameters:

req_handle -- (IN) Request handle

err_buf -- (OUT) Database error buffer

Returns:

Error code (0: success)

CCI_ER_REQ_HANDLE

CCI_ER_NO_MORE_DATA

CCI_ER_COMMUNICATION

CCI_ER_DBMS

CCI_ER_DELETED_TUPLE

sensitive column means the item that can provide updated value in the SELECT list when you re-request the results. For example, if a column is directly used as an item of the SELECT list without aggregation operation, this column can be called a sensitive column.

When you fetch the result again, the sensitive result receive the data from the server, not from the client buffer.

The cci_get_bind_num function gets the number of input bindings. If the SQL statement used during preparation is composed of multiple queries, it represents the number of input bindings used in all queries.

The cci_get_class_num_objs function gets the number of objects of the class_name class and the number of pages being used. If the flag is configured to 1, an approximate value is fetched; if it is configured to 0, an exact value is fetched.

If type is CCI_A_TYPE_STR : -1 is returned in case of NULL; the length of string stored in value is returned, otherwise.

If type is not CCI_A_TYPE_STR : -1 is returned in case of NULL, 0 is returned, otherwise.

Returns:

Error code (0: success)

CCI_ER_REQ_HANDLE

CCI_ER_TYPE_CONVERSION

CCI_ER_COLUMN_INDEX

CCI_ER_ATYPE

The type of the value variable is determined based on the given type argument, and the value or the pointer is copied to the value variable accordingly. For a value to be copied, the memory for the address to be transferred to the value variable must have been previously assigned. Note that if a pointer is copied, a pointer in the application client library is returned, so the value becomes invalid next time the cci_get_data() function is called.

In addition, the pointer returned by the pointer copy must not be freed. However, if the type is CCI_A_TYPE_SET, the memory must be freed by using the cci_set_free() function after using the set because the set is returned after the T_CCI_SET type memory is allocated. The following table shows the summary of type arguments and data types of their corresponding value values.

type

value Type

Meaning

CCI_A_TYPE_STR

char **

pointer copy

CCI_A_TYPE_INT

int *

value copy

CCI_A_TYPE_FLOAT

float *

value copy

CCI_A_TYPE_DOUBLE

double *

value copy

CCI_A_TYPE_BIT

T_CCI_BIT *

value copy (pointer copy for each member)

CCI_A_TYPE_SET

T_CCI_SET *

memory allocation and value copy

CCI_A_TYPE_DATE

T_CCI_DATE *

value copy

CCI_A_TYPE_BIGINT

int64_t *
(For Windows: __int64 *)

value copy

CCI_A_TYPE_BLOB

T_CCI_BLOB

memory allocation and value copy

CCI_A_TYPE_CLOB

T_CCI_CLOB

memory allocation and value copy

Remark

For LOB type, if the cci_get_data() function is called, meta data with the LOB type column (Locator) is displayed. To call data of the LOB type column, the cci_blob_read() function should be called.

Saves the error messages corresponding to the CCI error codes in the message buffer. If the value of CCI error code is CCI_ER_DBMS, the database error buffer (err_buf) receives the error message sent from the data server and saves it in the message buffer. For details on error codes and messages, see CCI Error Codes and Error Messages.

Returns the cursor holdability setting value about the result set from the connection handle. When it is 1, the connection is disconnected or the cursor is holdable until the result set is intentionally closed regardless of commit. When it is 0, the result set is closed when committed and the cursor is not holdable. For more details on cursor holdability, see Cursor Holdability.

Saves the query plan to the result buffer; the query plan about the request handle which the cci_prepare function returned.

You can call this function whether to call the cci_execute function or not.

After calling the cci_get_query_plan function, if the use of a result buffer ends, you should call the cci_query_info_free() function to release the result buffer created by cci_get_query_plan function.

If the prepared statement is SELECT, the T_CCI_COL_INFO struct that stores the column information about the execution result can be obtained by using this function. If it is not SELECT, NULL is returned and the num value becomes 0.

Parameters:

req_handle -- (IN) Request handle for the prepared statement

stmt_type -- (OUT) Command type

num -- (OUT) he number of columns in the SELECT statement (if stmt_type is CUBRID_STMT_SELECT)

Returns:

Success: Result info pointer, Failure: NULL

You can access the T_CCI_COL_INFO struct directly to get the column information from the struct, but you can also use a macro to get the information, which is defined as follows. The address of the T_CCI_COL_INFO struct and the column index are specified as parameters for each macro. The macro can be called only for the SELECT query. Note that the validity check is not performed for each parameter entered in each macro. If the return type of the macro is char*, do not free the memory pointer.

The CCI_GET_RESULT_INFO_ATTR_NAME macro gets the actual attribute name of the index-th column of a prepared SELECT list. If there is no name for the attribute (constant, function, etc), " " (empty string) is returned. It does not check whether the specified argument, res_info, is NULL and whether index is valid. You cannot delete the returned memory pointer with free ().

The CCI_GET_RESULT_INFO_CLASS_NAME macro gets the index-th column's class name of a prepared SELECT list. It does not check whether the specified argument, res_info, is NULL and whether index is valid. You cannot delete the returned memory pointer with free (). The return value can be NULL.

The CCI_GET_RESULT_INFO_IS_NON_NULL macro gets a value indicating whether the index-th column of a prepared SELECT list is nullable. It does not check whether the specified argument, res_info, is NULL and whether index is valid.

The CCI_GET_RESULT_INFO_NAME macro gets the index-th column's name of a prepared SELECT list. It does not check whether the specified argument, res_info, is NULL and whether index is valid. You cannot delete the returned memory pointer with free ().

Gets the primary key of the INSERT statement which executed at the last time.

Parameters:

conn_handle -- (IN) Request handle

value -- (OUT) The pointer of the result buffer pointer(char **). It stores the last primary key of INSERT statement executed on the last time. The memory which this pointer indicates doesn't need to be released, because it is the fixed buffer inside the connection handle.

The cci_next_result function gets results of next query if CCI_EXEC_QUERY_ALLflag is set upon cci_execute(). The information about the query fetched by next_result can be obtained with cci_get_result_info(). If next_result is executed successfully, the database is updated with the information of the current query.

Parameters:

req_handle -- (IN) Request handle of a prepared statement

err_buf -- (OUT) Database error buffer

Returns:

SELECT (sync mode) : The number of results, (async mode) : 0

INSERT, UPDATE : The number of records reflected

Others : 0

Failure : Error code

CCI_ER_REQ_HANDLE

CCI_ER_DBMS

CCI_ER_COMMUNICATION

The error code CAS_ER_NO_MORE_RESULT_SET means that no more result set exists.

The cci_oid_get function gets the attribute values of the given oid. attr_name is an array of the attributes, and it must end with NULL. If attr_name is NULL, the information of all attributes is fetched. The request handle has the same form as when the SQL statement "SELECT attr_name FROM oid_class WHERE oid_class = oid" is executed.

The cci_oid_put function configures the attr_name attribute values of the given oid to new_val_str. The last value of attr_name must be NULL. Any value of any type must be represented as a string. The value represented as a string is applied to the database after being converted depending on the attribute type on the server. To insert a NULL value, configure the value of new_val_str [i] to NULL.

The cci_prepare() function prepares SQL execution by acquiring request handle for SQL statements. If a SQL statement consists of multiple queries, the preparation is performed only for the first query. With the parameter of this function, an address to T_CCI_ERROR where connection handle, SQL statement, flag, and error information are stored.

CCI_PREPARE_UPDATABLE, CCI_PREPARE_INCLUDE_OID, or CCI_PREPARE_HOLDABLE can be configured in flag. If CCI_PREPARE_UPDATABLE is configured, updatable resultset is created and CCI_PREPARE_INCLUDE_OID is automatically configured. CCI_PREPARE_UPDATABLE and CCI_PREPARE_HOLDABLE cannot be used simultaneously in flag.
If you want to call the Java Stored Procedure, specify CCI_PREPARE_CALL flag into the cci_prepare function. You can see an related example on c:func:cci_register_out_param.

The default value of whether to keep result set after commit is cursor holdability. Thus, if you want to configure CCI_PREPARE_UPDATABLE in flag of cci_prepare(), you should call cci_set_holdable() first before calling cci_prepare() so that cursor cannot be maintained.

However, not all updatable resultsets are created even though CCI_PREPARE_UPDATABLE is configured. So you need to check if the results are updatable by using cci_is_updatable() after preparation. You can use cci_oid_put() or cci_oid_put2() to update result sets.

The conditions of updatable queries are as follows:

Must be SELECT.

OID can be included in the query result.

The column to be updated must be the one that belongs to the table specified in the FROM clause.

If CCI_PREPARE_HOLDABLE is set, a cursor is holded as long as result set is closed or connection is disconnected after the statement is committed(see Cursor Holdability).

The cci_prepare_and_execute function executes the SQL statement immediately and returns a request handle for the SQL statement. A request handle, SQL statement, the maximum length of a column to be fetched, error code, and the address of a T_CCI_ERROR construct variable in which error information being stored are specified as arguments. max_col_size is a value to configure the maximum length of a column to be sent to a client when the column of a SQL statement is CHAR, VARCHAR, BIT, or VARBIT. If this value is 0, full length is fetched.

Parameters:

conn_handle -- (IN) Connection handle

sql_stmt -- (IN) SQL statement

max_col_size -- (IN) The maximum length of a column to be fetched when it is a string data type in bytes. If this value is 0, full length is fetched.

If the number of prepared statements exceeds max_open_prepared_statement value, the oldest prepared statement is released from the statement pool. If you reuse it later, it is added to the statement pool again.

If you configure default_autocommit, default_isolation, or default_lock_timeout value, connection for autocommit, isolation, or lock_timeout based on current configured value is returned when cci_datasource_borrow is called. If you do not configure it, connection for autocommit, isolation, or lock_timeout is returned with keeping the value that a user changed before.

The CCI_QUERY_RESULT_ERR_MSG macro gets error messages about query results executed by cci_execute_batch(), cci_execute_array() or cci_execute_result() function. If there is no error message, this macro returns ""(empty string). It does not check whether the specified argument, query_result, is NULL, and whether index is valid.

The cci_register_out_param function is used to bind the parameters as outbind in Java Stored Procedure. The index value begins from 1.
To call this function, CCI_PREPARE_CALL flag of cci_prepare function should be specified.

The following shows to print out "Hello, CUBRID" string with Java Stored Procedure.

To use Java Stored Procedure, firstly specify java_stored_procedure parameter in cubrid.conf as yes, then start the database.

The cci_savepoint function configures savepoint or performs transaction rollback to a specified savepoint. If cmd is set to CCI_SP_SET, it configures savepoint and if it is set to CCI_SP_ROLLBACK, it rolls back transaction to specified savepoint.

The cci_schema_info function gets schema information. If it is performed successfully, the results are managed by the request handle and can be fetched by fetch and getdata. If you want to retrieve a class_name and attr_name by using pattern matching of the LIKE statement, you should configure flag.

Two types of flag s, CCI_CLASS_NAME_PATTERN_MATCH, and CCI_ATTR_NAME_PATTERN_MATCH, are used for pattern matching; you can configure these two flag s by using the OR operator ( | ). To use pattern matching, search by using the LIKE statement. For example, to search the information on a column of which class_name is "athlete" and attr_name is "code," you can enter as follows (in the example, "%code" is entered in the value of attr_name).

When the attribute of the CCI_SCH_CLASS_ATTRIBUTE column is INSTANCE or SHARED,
the order and the name values are identical to those of the column of CCI_SCH_ATTRIBUTE.

CCI_SCH_CLASS_METHOD

1

NAME

char *

2

RET_DOMAIN

int

3

ARG_DOMAIN

char *

CCI_SCH_METHOD_FILE

1

METHOD_FILE

char *

CCI_SCH_SUPERCLASS

1

CLASS_NAME

char *

2

TYPE

short

CCI_SCH_SUBCLASS

1

CLASS_NAME

char *

2

TYPE

short

CCI_SCH_CONSTRAINT

1

TYPE
0 : unique
1 : index
2 : reverse unique
3 : reverse index

int

2

NAME

char *

3

ATTR_NAME

char *

4

NUM_PAGES

int

5

NUM_KEYS

int

6

PRIMARY_KEY
1 : primary key

short

7

KEY_ORDER

short
base : 1

CCI_SCH_TRIGGER

1

NAME

char *

2

STATUS

char *

3

EVENT

char *

4

TARGET_CLASS

char *

5

TARGET_ATTR

char *

6

ACTION_TIME

char *

7

ACTION

char *

8

PRIORITY

float

9

CONDITION_TIME

char *

10

CONDITION

char *

CCI_SCH_CLASS_PRIVILEGE

1

CLASS_NAME

char *

2

PRIVELEGE

char *

3

GRANTABLE

char *

CCI_SCH_ATTR_PRIVILEGE

1

ATTR_NAME

char *

2

PRIVILEGE

char *

3

GRANTABLE

char *

CCI_SCH_DIRECT_SUPER_CLASS

1

CLASS_NAME

char *

2

SUPER_CLASS_NAME

char *

CCI_SCH_PRIMARY_KEY

1

CLASS_NAME

char *

2

ATTR_NAME

char *

3

KEY_SEQ

short
base : 1

4

KEY_NAME

char *

CCI_SCH_IMPORTED_KEYS

Used to retrieve primary key columns that are referred by a foreign key column in a given table.
The results are sorted by PKTABLE_NAME and KEY_SEQ.

If this type is specified as a parameter, a foreign key table is specified for
class_name
, and
NULL
is specified for
attr_name.

1

PKTABLE_NAME

char **

2

PKCOLUMN_NAME

char **

3

FKTABLE_NAME

char **

4

FKCOLUMN_NAME

char **

5

KEY_SEQ

char **

6

UPDATE_ACTION
cascade=0
restrict=1
no action=2
set null=3

int *

7

DELETE_ACTION
cascade=0
restrict=1
no action=2
set null=3

int *

8

FK_NAME

char **

9

PK_NAME

char **

CCI_SCH_EXPORTED_KEYS

Used to retrieve primary key columns that are referred by all foreign key columns.
The results are sorted by FKTABLE_NAME and KEY_SEQ.
If this type is specified as a parameter, a primary key table is specified for
class_name
, and
NULL
is specified for
attr_name.

1

PKTABLE_NAME

char **

2

PKCOLUMN_NAME

char **

3

FKTABLE_NAME

char **

4

FKCOLUMN_NAME

char **

5

KEY_SEQ

char **

6

UPDATE_ACTION
cascade=0
restrict=1
no action=2
set null=3

int *

7

DELETE_ACTION
cascade=0
restrict=1
no action=2
set null=3

int *

8

FK_NAME

char **

9

PK_NAME

char **

CCI_SCH_CROSS_REFERENCE

Used to retrieve foreign key information when primary keys and foreign keys in a given table are cross referenced.
The results are sorted by FKTABLE_NAME and KEY_SEQ.

If this type is specified as a parameter, a primary key is specified for
class_name
, and a foreign key table is specified for
attr_name.

1

PKTABLE_NAME

char **

2

PKCOLUMN_NAME

char **

3

FKTABLE_NAME

char **

4

FKCOLUMN_NAME

char **

5

KEY_SEQ

char **

6

UPDATE_ACTION
cascade=0
restrict=1
no action=2
set null=3

int *

7

DELETE_ACTION
cascade=0
restrict=1
no action=2
set null=3

int *

8

FK_NAME

char **

9

PK_NAME

char **

In the cci_schema_info function, the type argument supports the pattern matching of the LIKE statement for the class_name and attr_name.

The cci_set_allocators function registers the memory allocation/release functions used by users. By executing this function, you can use user-defined functions for every memory allocation/release jobs being processed in CCI API. If you do not use this function, system functions (malloc, free, realloc, and calloc) are used.

Note

This function can be used only on Linux, so cannot be used on Windows.

The cci_set_autocommit function configures the auto-commit mode of current database connection. It is only used to turn ON/OFF of auto-commit mode. When this function is called, every transaction being processed is committed regardless of configured mode.

Parameters:

conn_handle -- (IN) Connection handle

autocommit_mode -- (IN) Configures the auto-commit mode. It has one of the following value: CCI_AUTOCOMMIT_FALSE or CCI_AUTOCOMMIT_TRUE

Returns:

Error code (0: success)

Note that CCI_DEFAULT_AUTOCOMMIT, broker parameter configured in the cubrid_broker.conf file, determines whether it is in auto-commit mode upon program startup.

The cci_set_free function releases the memory allocated to the type value of T_CCI_SET fetched by CCI_A_TYPE_SET with cci_get_data(). The T_CCI_SET type value can be created through fetching cci_get_data() or cci_set_make() function.

Sets whether to enable or disable cursor holdability of the result set from the connection level. When it is 1, the connection is disconnected or the cursor is holdable until the result set is intentionally closed regardless of commit. When it is 0, the result set is closed when committed and the cursor is not holdable. For more details on cursor holdability, see Cursor Holdability.

The cci_set_isolation_level function sets the transaction isolation level of connections. All further transactions for the given connections work as new_isolation_level.

Parameters:

conn_handle -- (IN) Connection handle

new_isolation_level -- (IN) Transaction isolation level

err_buf -- (OUT) Database error buffer

Returns:

Error code

CCI_ER_CON_HANDLE

CCI_ER_CONNECT

CCI_ER_ISOLATION_LEVEL

CCI_ER_DBMS

Note If the transaction isolation level is set by cci_set_db_parameter(), only the current transaction is affected. When the transaction is complete, the transaction isolation level returns to the one set by CAS. You must use cci_set_isolation_level () to set the isolation level for the entire connection.

The cci_set_lock_timeout function specifies the connection lock timeout as milliseconds.
This is the same with calling cci_set_db_parameter (conn_id, CCI_PARAM_LOCK_TIMEOUT, &val, err_buf). See cci_set_db_parameter().

The cci_set_make function makes a set of a new CCI_A_TYPE_SET type. The created set is sent to the server as CCI_A_TYPE_SET by cci_bind_param(). The memory for the set created by cci_set_make() must be freed by cci_set_free(). The type of value for u_type is shown in the table below.

The cci_set_max_row function configures the maximum number of records for the results of the SELECT statement executed by :c:func`cci_execute`. If the max value is 0, it is the same as not setting the value.

These functions can return the CCI_ER_LOGIN_TIMEOUT error if login_timeout is configured in the connection URL, which is an argument of cci_connect_with_url() function; this means that login timeout happens between application client and CAS during re-connection.

It is going through the process of re-connection between application client and CAS when an application restarts or it is re-scheduled. Re-scheduling is a process that CAS chooses an application client, and starts and stops connection in the unit of transaction. If KEEP_CONNECTION, broker parameter, is OFF, it always happens; if AUTO, it can happen depending on its situation. For details, see the description of KEEP_CONNECTION in the Parameter by Broker