Build a C application

This topic describes how to build a C application with OceanBase Database and OBCI.

Prerequisites

• You have set up the basic database development environment.

• You have a hardware environment that meets the following requirements:

  • Hardware platform: x86_64

  • Operating system: Linux distribution of CentOS/Redhat 7.2

  • Compiler: GCC 4.8

• Contact the technical support team to request the RPM installation packages of OBCI and LibOBClient.

Step 1: Obtain a database connection string

Obtain a database connection string from OceanBase deployment engineer or administrator. For example:

obclient  -h100.88.xx.xx -usys@oracle -p****** -P2881

The database connection string contains parameters required for accessing the database. Before you create an application, you can log in to the database using the database connection string to verify that the parameters are correct.

The parameters are described as follows:

• -h: the IP address for connecting to OceanBase Database, which is sometimes the IP address of an ODP.

• -u: the username for connecting to a tenant, in the format of username@tenant name#cluster name. The default username for the administrator in Oracle mode is sys. The cluster name is not required when you directly connect to the database, but is required when you connect to the database through an ODP.

• -p: the user password.

• -P: the port for connecting to OceanBase Database, which is also the listening port of the ODP.

Step 2: Install the C driver

After you obtain the RPM package, run the following command as the root user in the command-line tool to install the OBCI driver:

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

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

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

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

Step 3: Write an application

This topic describes how a C application interacts with an OBServer node in the Oracle mode of OceanBase Database. It uses a concrete example to illustrate the basic approach.

1. Initialize the OBCI environment and the current thread.

   /*Initialize the OBCI program environment*/
   OCIInitialize(OCI_DEFAULT, NULL, NULL, NULL, NULL)
   
   /*Initialize the environment handle*/
   OCIEnvInit(&envhp, OCI_DEFAULT, 0, 0)
   

2. Allocate necessary handles and data structures.

   /*Service context handle*/
   OCIHandleAlloc(envhp, (dvoid **)&svchp, OCI_HTYPE_SVCCTX, 0, 0)
   
   /*Server handle*/
   OCIHandleAlloc(envhp, (dvoid **)&srvhp, OCI_HTYPE_SERVER, 0, 0)
   
   /*Session handle*/
   OCIHandleAlloc(envhp, (dvoid **)&authp, OCI_HTYPE_SESSION, 0, 0)
   
   /*Error handle*/
   OCIHandleAlloc(envhp, (dvoid **)&errhp, OCI_HTYPE_ERROR, 0, 0)
   
   /*Describe handle*/
   OCIHandleAlloc(envhp, (dvoid **)&dschp, OCI_HTYPE_DESCRIBE, 0, 0)
   

3. Establish a connection to the 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 OceanBase Server through SQL statements, and then process the data. The execution steps of an SQL statement in an OBCI application are as follows:

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

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

   2. Call the OCIBindByPos() or OCIBindByName() function to bind the addresses of input variables to the placeholders in 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 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 retrieve the result set of a query.

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

5. End the user session and disconnect from the database.

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

6. Deallocate the handles that are allocated in the program.

   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)