Connect C applications to OceanBase Database

This topic describes how to connect C applications to OceanBase Database.

Prerequisites

• A basic database development environment is deployed.

• The following hardware and software versions are used:

  • Architecture: x86_64

  • Operating system: CentOS/Red Hat Linux 7.2

  • Compiler: GNU Compiler Collection (GCC) 4.8

• The RPM installation package for OBCI is available. You can contact OceanBase Technical Support to obtain the package.

Install OceanBase Connector/C

After you obtain the RPM package, run the following command in the CLI as the root user:

rpm -ivh obci-<version>.x86_64.rpm

By default, the programs and files in the package are installed in the following directories:

• The header files are installed in the /u01/obclient/include directory.

• The library files are installed in the /u01/obclient/lib directory.

Procedure

Steps of connecting C applications to OBServer of OceanBase Database in Oracle mode through OBCI:

1. Initialize the OBCI environment and threads.

   /*Initialize the OBCI environment.*/
   OCIInitialize(OCI_DEFAULT, NULL, NULL, NULL, NULL)
   
   /*Initialize the OCI process environment.*/
   OCIEnvInit(&envhp, OCI_DEFAULT, 0, 0)
   

2. Allocate necessary handles and data structures.

   /*Allocate and initialize an OCI environment handle.*/
    OCIHandleAlloc(envhp, (dvoid **)&svchp, OCI_HTYPE_SVCCTX, 0, 0)
   
   /*Server environment handle.*/
    OCIHandleAlloc(envhp, (dvoid **)&srvhp, OCI_HTYPE_SERVER, 0, 0)
   
   /*Server handle.*/
    OCIHandleAlloc(envhp, (dvoid **)&authp, OCI_HTYPE_SESSION, 0, 0)
   
   /*Session handle.*/
    OCIHandleAlloc(envhp, (dvoid **)&errhp, OCI_HTYPE_ERROR, 0, 0)
   
   /*Error handle.*/
    OCIHandleAlloc(envhp, (dvoid **)&dschp, OCI_HTYPE_DESCRIBE, 0, 0)
   

3. Establish a connection to OceanBase Database and create a user session.

   /*Set the username and password.*/
    OCIAttrSet(authp, OCI_HTYPE_SESSION, (text *)strUserName,
   (ub4)strlen(strUserName), OCI_ATTR_USERNAME, errhp)
    OCIAttrSet(authp, OCI_HTYPE_SESSION, (text *)strPassword,
   (ub4)strlen(strPassword), OCI_ATTR_PASSWORD, errhp)
   
   /*Set the attributes of the server environment handle.*/
     OCIAttrSet((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX,(dvoid *)srvhp, (ub4)0, OCI_ATTR_SERVER, errhp)
     OCIAttrSet(svchp, OCI_HTYPE_SVCCTX, (dvoid *)authp,0, OCI_ATTR_SESSION, errhp)
   
   /*Create and start a user session.*/
     OCISessionBegin(svchp, errhp, authp, OCI_CRED_RDBMS, OCI_DEFAULT)
     OCIHandleAlloc(envhp, (dvoid **)&stmthp, OCI_HTYPE_STMT, 0, 0)
   

4. Exchange data with the OBServer by using SQL statements, and then perform data processing. Steps of executing an SQL statement in the OBCI application:

   1. Call the OCIStmtPrepare() or OCIStmtPrepare2() function to prepare an SQL statement.

      OCIStmtPrepare(stmthp, errhp, (text *)sql, strlen(sql), OCI_NTV_SYNTAX,OCI_DEFAULT))
      

   2. Call one or multiple functions, such as OCIBindByPos() or OCIBindByName(), to bind the address in the input variable to the placeholder of the DML statement.

      OCIBindByPos(stmthp, &bidhp[0], errhp, 1, &szpersonid,
                       sizeof(szpersonid), SQLT_INT, NULL, NULL, NULL, 0, NULL, 0)
      
      OCIBindByName(stmthp, &bidhp[0], errhp, (const OraText*)":personid", 9, &szpersonid,
                        sizeof(szpersonid), SQLT_INT, NULL, NULL, NULL, 0, NULL, 0)
      

   3. Call the OCIStmrExecute() function to execute the SQL statement.

      OCIStmtExecute(svchp, stmthp, errhp, (ub4)1, (ub4)0, (CONST OCISnapshot *)0,
      (OCISnapshot *)0, (ub4)OCI_DEFAULT)
      

   4. Call the OCIDefineByPos() function to define output variables for the data output items of the SQL statement.

      OCIDefineByPos(stmthp, &defhp[0], errhp, 1, &szpersonid,
      sizeof(szpersonid), SQLT_INT, &ind[0], 0, 0, OCI_DEFAULT)
      

   5. Call the OCIStmtFetch() function to obtain the result set of the query.

      OCIStmtFetch(stmthp, errhp, 1, OCI_FETCH_NEXT, OCI_DEFAULT)
      

5. End the user session and disconnect from OceanBase Database.

   /*End the session.*/
     OCISessionEnd(svchp, errhp, authp, (ub4)0)
   
   /*Disconnect from OceanBase Database.*/
     OCIServerDetach(srvhp, errhp, OCI_DEFAULT)
   

6. Release the allocated handles.

   OCIHandleFree((dvoid *)dschp, OCI_HTYPE_DESCRIBE)
   OCIHandleFree((dvoid *)stmthp, OCI_HTYPE_STMT)
   OCIHandleFree((dvoid *)errhp, OCI_HTYPE_ERROR)
   OCIHandleFree((dvoid *)authp, OCI_HTYPE_SESSION)
   OCIHandleFree((dvoid *)svchp, OCI_HTYPE_SVCCTX)
   OCIHandleFree((dvoid *)srvhp, OCI_HTYPE_SERVER)
   

For more information about the installation and use of OBCI, see OBCI.