In an application, you can call library functions provided by OceanBase Call Interface (OBCI) to manipulate OceanBase Database. To be compatible with Oracle, all OBCI functions are prefixed with OCI and have the same names as Oracle OCI functions. This allows you to manipulate OceanBase Database in existing Oracle applications by calling the same OCI functions, without the need to modify a single line of code.
Basic structure of an OBCI application
The following content describes the basic structure of an OBCI application:
Initialize the OBCI environment and threads.
Allocate necessary handles and data structures.
Establish a connection to the database and create a user session.
Exchange data with the OceanBase server by using SQL statements, and then perform data processing.
End the user session and disconnect from the database.
Release the allocated handles.
Development procedure of an OBCI application
The following figure shows the basic development procedure of an OBCI application. For more information about the code, see Development examples.
Process SQL statements
One of the most common tasks of an OBCI application is to receive and process SQL statements. This section describes how to process SQL statements by using an OBCI application.
The following figure shows the steps of executing an SQL statement in an OBCI application and the functions called in each step.
Call the OCIStmtPrepare() or OCIStmtPrepare2() function to prepare an SQL statement.
Bind the SQL statement with variables that need to be passed to the SQL statement. For a DML statement that has input variables, you can call one or more functions, such as OCIBindByPos() and OCIBindByName(), to bind the address of each input variable to the placeholder in the DML statement.
Call the OCIStmrExecute() function to execute the SQL statement. For a DDL statement, its execution ends at this step.
Describe the output data of the SQL statement.
If necessary, you can call the OCIParamGet() and OCIAttGet() functions to obtain the following attributes of the record read: the number of fields, the data types of the fields, and the maximum length defined for the field data.
Define the output variables.
If necessary, you can call the OCIDefineByPos() function to define output variables for the data output items of the SQL statement.
Notice
Do not define output variables by calling the OCIDefineByPos() function in an anonymous PL/SQL block. This is because you have completed this step during data binding.
Obtain data.
If necessary, you can call the OCIStmtFetch() function to obtain the result set of a query.
Example
This example describes how OBCI calls functions on a Linux system.
This example shows how to create, delete, insert, update, and query data in the person table.
The oci.h header file of OBCI is used during the compilation, and the libobci.so or libobci.a library file is used in the linking phase.
Notice
If you are creating a dynamic link to libobci.so, you also need to manually install the OBClient RPM package. If you are creating a static link to libobci.a, the OBClient RPM package is not required.
Sample statement:
Static link:
gcc example.c -I/u01/obclient/include -I/usr/include/oracle/11.2/client64/ /u01/obclient/lib/libobci.a -L/usr/local/lib64 -lstdc++ -lpthread -ldl -lm -g -o example
Dynamic link:
gcc example.c -I/u01/obclient/include -I/usr/include/oracle/11.2/client64/ -L/u01/obclient/lib/ -L/usr/local/lib64 -lobci -lobclnt -g -o example
Note
We recommend that you use the header files of the oracle-11.2 client. You can adjust the header files to use based on the path of the
includedirectory in your environment.
Execution output:
export LD_LIBRARY_PATH=/u01/obclient/lib:$LD_LIBRARY_PATH
$./example
PERSONID NAME EMAIL
finish fetch data
finish insert tables
PERSONID NAME EMAIL
1 obtest t@ob.com
finish fetch data
PERSONID NAME EMAIL
1 test test@mail
finish fetch data
PERSONID NAME EMAIL
finish fetch data