OceanBase Call Interface (OBCI) is an API developed based on C for OceanBase Database. OBCI provides features that are fully compatible with Oracle Call Interface (OCI).
Overview
OCI is a client-side API provided by Oracle. You can call OCI to access Oracle database servers and manage database operations by using SQL statements. OCI supports all SQL data definition, data manipulation, query, and transaction management operations. It also supports the data types, call methods, syntax, and semantics of C and C++. OCI provides a set of interface subroutines, also known as functions, that have access to Oracle databases. OBCI is an API that is compatible with Oracle and is developed based on the standards of OCI and features of OceanBase Database. OBCI supports the interface capabilities and user behavior processing of OCI. OBCI allows developers to quickly access OceanBase clusters in Oracle mode from clients such as Oracle Template Library (OTL), Tuxedo, and OceanBase Embedded SQL in C (ECOB).
The basic concepts of OBCI and OCI are described as follows:
OBCI: an API that can be used by clients to access OceanBase Database.
OCI: an API that can be used by clients to access Oracle databases.
libobclient/libobclnt: an API that can be used by clients to manage databases. This API serves as an OBCI dependency.
Oracle mode: a processing mode of OceanBase Database that is compatible with Oracle syntax.
Features
OBCI allows you to access and manage data in OceanBase Database in Oracle mode by using the C language. OBCI provides standard database access and index features in the form of dynamic link libraries (OCI libraries). Applications can connect to these libraries and use the features provided in the libraries.
OBCI provides the following main features:
Serves as a standard API that can be used to access and process OceanBase Database data in Oracle mode. OBCI provides features such as data definition, data management, data query and processing, and transaction control.
Supports the development of scalable and multi-threaded applications.
Supports SQL access functions that you can use to manage database access, process SQL statements, and manipulate objects retrieved from OBServers.
Supports data type mapping and manipulation functions that allow you to manipulate OceanBase data type attributes.
Benefits
Compared with access to OceanBase Database by directly using a database protocol or calling a C interface, OBCI has the following benefits:
Encapsulates database access operations and simplifies the business implementation logic.
Supports third-party framework capabilities, such as Tuxedo and OTL.
Allows you to use connection pools and statement cache to improve program scalability.
Supports dynamic parameter binding and the processing of result callback functions. This allows programs to process parameters and outputs in an efficient manner.
Provides interfaces to query metadata.
Provides capabilities to access and manage complex data such as arrays by using DML statements such as INSERT, UPDATE, and DELETE.
Supports the prefetch feature, which reduces the interactions with the backend.
Ensures thread security and reduces the use of mutex by services.
Supported SQL statements
DDL statements
Control statements:
Transaction control
Session control
System control
DML statements
Query statements
PL/SQL statements and the NOLOCK hint
Data types
OBCI supports internal data types in Oracle mode in OceanBase Database and external data types that are compatible with OCI and defined in <oci.h> by using C.
Internal data types
Internal data types are data types that can be used in Oracle mode in OceanBase Database.
The following table describes the general internal data types that are supported by OBCI.
| Data type | Description | Limit |
|---|---|---|
| char | A character string that has a fixed length. | Maximum length: 2000 |
| varchar2 | A character string that has a variable length. | Maximum length: 32767 |
| number | A numeric value. | Range of precision: 1 to 38 Range of scale: -84 to 127 |
| int | An integer. | Maximum number of digits: 38 |
| binary_float | A 32-bit floating-point number. | Minimum value: 1.17549E-38F Maximum value: 3.40282E+38F |
| binary_double | A 64-bit floating-point number. | Minimum value: 2.22507485850720E-308 Maximum value: 1.79769313486231E+308 |
| date | A date. | Format: YYYY-MM-DD HH:MI:SS |
| timestamp | A time value. | Format: YYYY-MM-DD HH:MI:SS [.FFFFFFFFF] |
External data types
External data types specify the types of data in host variables. When you import data to OceanBase Database, OBCI converts the external data types of the input host variables to the corresponding internal data types. When you export data to an external program, OBCI converts the internal data types of the database table to the corresponding external data types of the host variables.
The following table describes the general external data types that are supported by OBCI, and the data type mappings.
| External data types | Code | Data type of host variable | OBCI type |
|---|---|---|---|
| VARCHAR2 | 1 | char[n] | SQLT_CHR |
| NUMBER | 2 | unsigned char[21] | SQLT_NUM |
| 8-bit signed INTEGER | 3 | signed char | SQLT_INT |
| 16-bit signed INTEGER | 3 | signed short, signed int | SQLT_INT |
| 32-bit signed INTEGER | 3 | signed int, signed long | SQLT_INT |
| FLOAT | 4 | float, double | SQLT_FLT |
| LONG | 8 | char[n] | SQLT_LNG |
| NULL-terminated STRING | 5 | char[n+1] | SQLT_STR |
| LONG | 8 | char[n] | SQLT_LNG |
| VARCHAR | 9 | char[n+sizeof(short integer)] SQLT_VCS | VARCHAR |
| DATE | 12 | unsigned char[n] | SQLT_BIN |
| RAW | 23 | char[7] | SQLT_DAT |
| CHAR | 96 | char[n] | SQLT_AFC |
| REF | 110 | OCIRef | SQLT_REF |
| Character LOB descriptor | 112 | OCILobLocator (see note 2) | SQLT_CLOB |
| Binary LOB descriptor | 113 | OCILobLocator (see note 2) | SQLT_BLOB |
| ANSI DATE descriptor | 184 | OCIDateTime * | SQLT_DATE |
| TIMESTAMP descriptor | 187 | OCIDateTime * | SQLT_TIMESTAMP |
| TIMESTAMP WITH TIME ZONEdescriptor | 188 | OCIDateTime * | SQLT_TIMESTAMP_TZ |
| TIMESTAMP WITH LOCAL TIME ZONEdescriptor | 232 | OCIDateTime * | SQLT_TIMESTAMP_LTZ |
Data type conversion
In OBCI, host variables use external data types. Data type conversion is required for data that is read from OceanBase Database to external variables, or for external data that is stored in OceanBase Database.
The following table lists the supported conversion operations.
| VARCHAR2/CHAR | INT | NUMBER | FLOAT | BINARY_FLOAT | BINARY_DOUBLE | DATE | TIMESTAMP | |
|---|---|---|---|---|---|---|---|---|
| CHAR/UNSIGNED CHAR | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| INT/UNSIGNED INT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| LONG/UNSIGNED LONG | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| LONG LONG/UNSIGNED LONG LONG | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| FLOAT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| DOUBLE | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| CHAR[n]/VARCHAR[n]/CHAR* | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN |
Note
- The table does not include possible errors during the conversion. For example, errors such as overflows and invalid numbers may occur when OBCI converts
VARCHAR2intoCHARin C.- IN indicates the conversion from a C language variable to an internal data type of OceanBase Database during data writes. OUT indicates the conversion from an internal data type of OceanBase Database to a C language variable during data reads.
Objects and functions
OBCI objects
The following table describes the general internal objects of OCI that are supported by OBCI.
| Object | Description |
|---|---|
| OCIEnv | An OCI environment handle. |
| OCIError | An OCI error processing handle, which is used to obtain error information. |
| OCISvcCtx | An OCI service context, such as memory and connection. |
| OCIStmt | An OCI statement processing object. |
| OCIBind | An OCI bind variable. |
| OCIDefine | An OCI result variable. |
| OCIDescribe | An OCI definition type. |
| OCIServer | An OCI backend OBServer. |
| OCISession | OCI session information. |
| OCITrans | An OCI transaction. |
| OCICPool | An OCI connection pool. |
| OCIAuthInfo | Information about OCI connection authentication. |
| OCILobLocator | An OCI large object (LOB) locator, which is used for LOB function processing. |
| OCIParam | An OCI parameter, which is used to obtain metadata. |
| OCIRowid | An OCI ROWID value. |
| OCIDate | An OCI date. |
| OCIDateTime | An OCI timestamp. |
| OCIInterval | An OCI time interval. |
| OCINumber | An OCI high-precision numeric value. |
| OCIString | An OCI string. |
OBCI functions
Initialization-related functions
The following table describes the functions that are used for processing initialization and connection authentication.
| Function | Description |
|---|---|
| OCIEnvCreate | Creates and initializes an environment handle. |
| OCIEnvNlsCreate | Creates and initializes an environment handle based on which OCI functions work. It serves as an enhanced version of the OCIEnvCreate() function. |
| OCIEnvInit | Initializes and allocates an environment handle. |
| OCIInitialize | Initializes the OCI application environment. OCI initializes internal global variables and loads some configuration information by calling this function. |
| OCILogoff | Closes a connection to the server that is established by calling the OCILogon() or OCILogon2() function. |
| OCILogon | Establishes a connection to a specified database server by using a username and a password, and initializes the related context handle. |
| OCILogon2 | Establishes a connection to a specified database server by using a username and a password, and initializes the related context handle. This function supports connection pools. |
| OCIServerAttach | Attaches a database server to a specified connection handle. |
| OCIServerDetach | Detaches a connection handle from a database server. |
| OCISessionBegin | Creates a session with a specified database server on a specified context handle based on the logon credentials. |
| OCISessionEnd | Releases the session with the database server that is created by calling the OCISessionBegin() function on the context handle. |
| OCIPing | Checks whether the connection and server are active. A call to this function succeeds only when the server is active and the connection exists. |
| OCITerminal | Terminates the thread processing. |
Object initialization-related functions
The following table describes the functions that are related to handles and descriptors.
| Function | Description |
|---|---|
| OCIAttrGet | Obtains an attribute value of a handle. |
| OCIAttrSet | Sets an attribute for a handle. |
| OCIDescriptorAlloc | Allocates storage to store descriptors. |
| OCIDescriptorFree | Releases a descriptor allocated by calling the OCIDescriptorAlloc() function. |
| OCIHandleAlloc | Allocates and initializes handles. |
| OCIHandleFree | Releases handles allocated by calling the OCIHandleAlloc() function. |
| OCIParamGet | Obtains a descriptor handle at a specified position. |
Functions related to parameter binding and result data processing
The following table describes the functions that are related to the Bind, Define, and Describe operations.
| Function | Description |
|---|---|
| OCIBindArrayOfStruct | Binds parameters as arrays. |
| OCIBindByName | Binds a parameter to a placeholder in an SQL statement by parameter name. Same parameters are bound for only once. |
| OCIBindByPos | Binds a parameter to a placeholder in an SQL statement by parameter position. |
| OCIDefineArrayOfStruct | Binds a column in a return value set as an array. |
| OCIDefineByPos | Binds the value range of each column in a return value set by the position of value. |
Statement processing-related functions
The following table describes the functions that are related to statement processing.
| Function | Description |
|---|---|
| OCIStmtPrepare | Prepares an SQL statement, initializes an Stmtp object, and then calls the OCIStmtExecute() function to execute the statement. |
| OCIStmtExecute | Executes the prepared SQL statement. |
| OCIStmtFetch | Fetches rows from the result set of an SQL statement. After an SQL statement is executed, this function can be called multiple times to return all rows of the result set until the function returns OCI_NO_DATA. |
| OCIStmtRelease | Releases the statement handles fetched by calling the OCIStmtPrepare2() function. |
Transaction processing-related functions
The following table describes the functions that are related to transaction processing.
| Function | Description |
|---|---|
| OCITransStart | Starts a transaction. |
| OCITransCommit | Commits an SQL execution task. |
| OCITransRollback | Rolls back an SQL execution task. |
Data type-related functions The following table describes the functions that are related to different data types.
| Data object | Function | Description |
|---|---|---|
| OCIString | OCIStringAllocSize | Obtains the allocated size of string memory in bytes or code points (Unicode). |
| OCIString | OCIStringAssign | Assigns a string to another string. |
| OCIString | OCIStringAssignText | Assigns a string to another string. |
| OCIString | OCIStringPtr | Obtains the pointer to a specified string. |
| OCIString | OCIStringSize | Obtains the size of a specified string. |
| OCIString | OCIStringResize | Obtains the size of a specified string. |
| OCILoblocator | OCILobGetLength | Returns the length of the LOB, in bytes. |
| OCILoblocator | OCILobRead | Reads the content of a specified length from a LOB. |
| OCILoblocator | OCILobWrite | Continuously writes content to a LOB. |
| OCILoblocator | OCILobLocatorIsInit | Checks whether a specified LOB or BFILE locator is initialized. |
| OCILoblocator | OCILobOpen | Opens a LOB or a BFILE object. |
| OCILoblocator | OCILobClose | Closes a LOB or a BFILE object. |
| OCILoblocator | OCILobIsOpen | Tests whether a LOB or a FILE object is open. |
| OCILoblocator | OCILobTrim | Truncates a LOB value. |
| OCILoblocator | OCILobTrim2 | Truncates a LOB value. This function can be used only for LOBs that are not greater than 48 MB in size in OceanBase Database. |
| OCIDate | OCIDateSysDate | Obtains the current system date and time of a client. |
| OCIDate | OCIDateToText | Converts a date into a string of a specified format. |
| OCIDate | OCIDateFromText | Converts a string into a date in a specified format. |
| OCIDateTime | OCIDateTimeToText | Converts a datetime value into a string in a specified format. |
| OCIDateTime | OCIDateTimeFromText | Converts a datetime value into a string in a specified format. |
| OCIDateTime | OCIDateTimeConstruct | Constructs a datetime value. |
| OCIDateTime | OCIDateTimeGetTime | Obtains the time, including the values for the hour, minute, second, and fractional second, from a datetime value. |
| OCIDateTime | OCIDateTimeGetDate | Obtains the date, including values for the year, month, and day, from a datetime value. |
| OCIDateTime | OCIDateTimeGetTimeZoneOffset | Obtains the time zone, including values for the hour and minute, from a datetime value. |
| OCINumber | OCINumberToInt | Converts a value of the Oracle NUMBER type to an integer. |
| OCINumber | OCINumberToReal | Converts a value of the Oracle NUMBER type to a real number. |
| OCINumber | OCINumberToText | Converts a value of the Oracle NUMBER type to a string in a specified format. |
| OCINumber | OCINumberIsInt | Tests whether an OCINumber value is an integer. |
| OCINumber | OCINumberFromText | Converts a string into a value of the Oracle NUMBER type. |
Other functions
The following table describes some other general functions.
| Function | Description |
|---|---|
| OCIBreak | Performs an immediate (asynchronous) termination on the current OBCI function that is associated with a server. |
| OCIClientVersion | Returns the version of the OCI client during runtime. |
| OCIServerVersion | Returns the version of the OCI server during runtime. |
| OCIErrorGet | Returns an error message and an OceanBase error code to the provided buffer. |
| OCIPasswordChange | Changes the password of an account. |
| OCIPing | Makes a round trip call to a server to check whether the connection and the server are active. |
More information
For more information about OBCI, see OBCI.