DEV Community

Cong Li
Cong Li

Posted on

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
Enter fullscreen mode Exit fullscreen mode

Make the following changes:

GCICLIENTDIR=/home/gci  # Path to GCI

GBASEDBTCSDK=/home/gbase # Path to CSDK

GBASEDBTSERVER=ol_gbasedbt # Instance name
Enter fullscreen mode Exit fullscreen mode

2. Environment Variables and Their Meanings for Compiling GCI Programs

1) Set the database connection username and password:

   export DBUSER=gbasedbt 
   export DBPWD=Big4ifmx
Enter fullscreen mode Exit fullscreen mode

(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
Enter fullscreen mode Exit fullscreen mode

Additional Environment Variables (Optional)

1) Set the date format:

   export DBDATE=Y4MD-
Enter fullscreen mode Exit fullscreen mode

2) Set character encoding:

   export DB_LOCALE=ZH_CN.UTF8 
   export CLIENT_LOCALE=ZH_CN.UTF8
Enter fullscreen mode Exit fullscreen mode

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

   export LD_LIBRARY_PATH=${GBASEDBTDIR}/lib:${GBASEDBTDIR}/lib/esql:${GBASEDBTDIR}/lib/cli
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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})
Enter fullscreen mode Exit fullscreen mode

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

Image description

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);
}
Enter fullscreen mode Exit fullscreen mode

5. Compiling and Running the GCI Program

1) Set the environment variables:

   cd /home/gci/demo
   source /home/gci/etc/client.ksh
Enter fullscreen mode Exit fullscreen mode

If needed, set the username and password:

   export DBUSER 
   export DBPWD
Enter fullscreen mode Exit fullscreen mode

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

   ./clean.sh
   ./build_linux_debug_shared.sh
   make
Enter fullscreen mode Exit fullscreen mode

Image description

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

   source ol_gbasedbt.ksh
Enter fullscreen mode Exit fullscreen mode

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

Image description

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.

Top comments (0)