GBase 8s GCI Usage Guide

In enterprise-level database application development, efficient access to and operation of the database is key to enhancing application performance. The GBase 8s database system offers the GCI (GBase Client Interface), a programming interface that allows developers to conveniently access and manipulate the database using the C language. This article provides a detailed guide on how to use GCI, including environment setup, program compilation, and how to run GCI programs, to help developers quickly master client-side development for the GBase database.

1. Introduction to IDS and GCI Installation Locations

• Install IDS and CSDK (assuming they are installed together) at a location like /home/gbase.

• Extract the GCI package (the location is not critical), for example, /home/gci.

• Go to the etc directory and modify the client.ksh file:
  

cd /home/gci/etc
vim client.ksh

Make the following changes:

GCICLIENTDIR=/home/gci  # Path to GCI

GBASEDBTCSDK=/home/gbase # Path to CSDK

GBASEDBTSERVER=ol_gbasedbt # Instance name

2. Environment Variables and Their Meanings for Compiling GCI Programs

1) Set the database connection username and password:

   export DBUSER=gbasedbt 
   export DBPWD=Big4ifmx

(If DBUSER and DBPWD are not used in the code, these do not need to be configured.)

2) Set the installation path of CSDK:

   export GBASEDBTDIR=/home/gbase

Additional Environment Variables (Optional)

1) Set the date format:

   export DBDATE=Y4MD-

2) Set character encoding:

   export DB_LOCALE=ZH_CN.UTF8 
   export CLIENT_LOCALE=ZH_CN.UTF8

3) Set the paths for the libraries needed for compilation:

   export LD_LIBRARY_PATH=${GBASEDBTDIR}/lib:${GBASEDBTDIR}/lib/esql:${GBASEDBTDIR}/lib/cli

3. CMakeList Configuration

To add a new example in the demo directory under GCI, the CMakeList needs to be modified. For example, to add a case named test.c:

cd /home/gci/demo
vim CMakeList.txt

Add the following content to CMakeList.txt:

# Compile the source file test.c to generate the executable test
ADD_EXECUTABLE(test  test.c)

# Specify the libraries that the executable test needs to link
TARGET_LINK_LIBRARIES(test   ${LIB_CLN_NAME})

4. Demo Source Code Analysis

A sample GCI program code is provided, which includes logging into the database, executing SQL statements, etc., with explanations of the key code segments.

1) Interface Calls and Process Flow

2) Demo Example

#include "gci.h" // GCI interface definition file

GCIEnv *envhp = NULL; 
GCISvcCtx *svchp = NULL;
GCIError *errhp = NULL;
GCIStmt *stmtp = NULL;

// Log into the database
int logdb()
{
    GCItext *dbname = (GCItext *)"testdb"; // Database name, modify as needed (ensure the database exists in the instance)
    GCItext *user = (GCItext *)"root"; // Username, modify as needed
    GCItext *pswd = (GCItext *)"111111"; // Password, modify as needed

    if (GCIEnvCreate(&envhp, GCI_THREADED | GCI_OBJECT, (dvoid *)0, 0, 0, 0, 0, (dvoid **)0) != GCI_SUCCESS)
    {
        printf("GCIEnvCreate: create env handle failed!\n");
    }

    if (GCIHandleAlloc((dvoid *)envhp, (dvoid **)&svchp, GCI_HTYPE_SVCCTX, 0, (dvoid **)0) != GCI_SUCCESS)
    {
        printf("GCIHandleAlloc: allocate svcctx handle failed!\n");
    }

    if (GCIHandleAlloc((dvoid *)envhp, (dvoid **)&errhp, GCI_HTYPE_ERROR, 0, (dvoid **)0) != GCI_SUCCESS)
    {
        printf("GCIHandleAlloc: allocate error handle failed!\n");
    }

    // Call the login interface to connect to the database
    if (GCILogon(envhp, errhp, &svchp, user, strlen((char *)user), pswd, strlen((char *)pswd), dbname, strlen((char *)dbname)) != GCI_SUCCESS)
    {
        printf("logon database failed!\n");
    }
}

// Execute SQL statements
{
    GCIText sql[256] = {0};

    // Allocate statement handle
    if (GCIHandleAlloc((dvoid *)envhp, (dvoid **)&stmtp, GCI_HTYPE_STMT, 0, (dvoid **)0) != GCI_SUCCESS)
    {
        printf("GCIHandleAlloc: allocate stmt handle failed!\n");
    }

    // Prepare SQL statement
    strcpy((char *)sql, "create table t_table(id int)");
    GCIStmtPrepare(stmtp, errhp, sql, strlen((char *)sql), 0, 0);

    // Execute the prepared SQL statement
    GCIStmtExecute(svchp, stmtp, errhp, 1, 0, NULL, NULL, GCI_COMMIT_ON_SUCCESS);
}

5. Compiling and Running the GCI Program

1) Set the environment variables:

   cd /home/gci/demo
   source /home/gci/etc/client.ksh

If needed, set the username and password:

   export DBUSER 
   export DBPWD

2) Run the script files clean.sh and build_linux_debug_shared.sh, then execute make:

   ./clean.sh
   ./build_linux_debug_shared.sh
   make

3) Source the profile or ksh file from the IDS installation directory (e.g., /home/gbase):

   source ol_gbasedbt.ksh

4) Run the executable, e.g., ./test:

Through this detailed guide, you should now have a comprehensive understanding of how to use GCI for database programming in the GBase 8s database. GCI provides an efficient and flexible way to access the database, helping developers enhance the development efficiency and performance of database applications. We hope this article will serve as a valuable resource in your GBase 8s database development.