TcaplusDB PB Table C++SDK Get Started

The preparations for using the C++SDK mainly include:

1. Prepare the environment;
2. Create an App;
3. Create a game zone;
4. Create a table;
5. Collect environmental information;
6. Download SDK;
7. Configure the development environment.

If the above preparations have been completed, they can be skipped.

1. Prepare the Environment

Refer to Create a Cluster to deploy the TcaplusDB cluster, or apply for the TcaplusDB service.

2. Create an App

Refer to Create an App to create an App.

3. Create A Game Zone

Refer to Create a Game Zone to create a game zone (Zone).

4. Create A Table

Refer to Add a Table to add a table.

PB tables are divided into Generic tables and List tables. All pb tables of TcaplusDB depend on this table tcaplusservice.optionv1.proto

// TcaplusService option Ver.1
// Author: Calvinshao
// 2016-8-1

syntax = "proto2";

package tcaplusservice;

import "google/protobuf/descriptor.proto";

extend google.protobuf.MessageOptions
{
    optional string tcaplus_primary_key = 60000; //Tcaplus Primary Key
    repeated string tcaplus_index = 60001; //Tcaplus Index
}

extend google.protobuf.FieldOptions
{
    optional uint32 tcaplus_size = 60000; // Tcaplus field size
    optional string tcaplus_desc = 60001; // Tcaplus description
}

4.1. Generic Table Definition Descriptions

Content example of the Generic table description file:

syntax = "proto3";         // Specify the protobuf language version, proto3.

// Import the TcaplusDB public definition service 
import "tcaplusservice.optionv1.proto";

message game_players {  // Define a TcaplusDB table, including the message type

// Create a primary key field based on the option tcaplusservice.tcaplus_primary_key
// A single table of TcaplusDB can specify up to 8 primary key fields (3.37.0 and later)
    option(tcaplusservice.tcaplus_primary_key) = "player_id, player_name, player_email";
    option(tcaplusservice.tcaplus_sharding_key) = "player_id";

    // Create a primary key index based on the option tcaplusservice.tcaplus_index
    option(tcaplusservice.tcaplus_index) = "index_1(player_id, player_name)";
    option(tcaplusservice.tcaplus_index) = "index_2(player_id, player_email)";

    // Numeric types supported by TcaplusDB:
    // int32, int64, uint32, uint64, sint32, sint64, bool, fixed64, sfixed64, double, fixed32, sfixed32, float, string, bytes
    // Nested type: message

    // Primary key field
    int64 player_id = 1; 
    string player_name = 2;
    string player_email = 3;

    // Common (non-primary) key field
    int32 game_server_id = 4;
    repeated string login_timestamp = 5;
    repeated string logout_timestamp = 6;
    bool is_online = 7;

    payment pay = 8;
}

message payment {

int64 pay_id = 1;
uint64 amount = 2;
int64 method = 3;

}

Refer to PB Table for the format description of the PB table description file.

4.2. List Table Definition Descriptions

Content example of the List table description file:

syntax = "proto3";

package myTcaplusTable;

import "tcaplusservice.optionv1.proto";

message tb_online_list {
    option(tcaplusservice.tcaplus_primary_key) = "openid,tconndid,timekey";
    option(tcaplusservice.tcaplus_customattr) = "TableType=LIST;ListNum=1900";

    int32 openid = 1;
    int32 tconndid = 2;
    string timekey = 3;
    string gamesvrid = 4;
    int32 logintime = 5 ;
    repeated int64 lockid = 6;
    pay_info pay = 7;

    message pay_info {
        uint64 total_money = 1;
        uint64 pay_times = 2;
    }
    map<string, pay_info> projects = 8;
}

Refer to PB Table for the format description of the PB table description file.

The TableType=LIST in tcaplus_customattr defined by the table is used to identify the List table, and the ListNum attribute is also used to specify how many elements can be stored in a single List at most.

Note: Since the List table has a built-in primarykey field to store the element serial numbers in the List, users can only define up to 7 primarykey fields for the List table.

5. Collect Environmental Information

When using the SDK, it requires some environment related parameters. See the following table for specific parameters and collection methods.

6. Download C++ SDK

For details about the C++ SDK release and download link, see PB Table SDK Download.

7. Configure the Compilation Development Environment

The SDK relies on some system libraries, mainly as follows:

• autoconf
• automake
• libtool
• curl
• make
• g++
• unzip
• gcc-c++
• openssl
• openssl-devel
• zlib-devel

It can be installed by clicking yum:

yum install -y autoconf automake libtool curl make g++ unzip gcc-c++ openssl openssl-devel zlib-devel

Protobuf installation:

You need to download source code to compile and install, or install the compiled protobuf. The version must be consistent with SDK

./configure --prefix=/usr/local/protobuf
make
make check
make install

Note: If there are problems in the compilation process, they are generally system library problems, which can be solved by referring to the online information

After installation, you can test whether it is OK. Then enter the /usr/local/protocbuf/bin directory to execute:

./protoc --version
#Display version number
libprotoc 3.5.0

7.1 Introduction to SDK Directories

• The include directory is the header file of the SDK. When using the SDK, it needs to include the corresponding header file. All API interfaces have comments, which can be viewed in the header file
• The lib directory is the SDK static library directory, which needs to be linked statically when compiling
• The example directory contains the operation examples of all PB and TDR tables. Please refer to the C++SDK Interfaces Instructions for details
• The bin directory stores TcaplusDB Client tools. Click the link to learn how to use them
• The cfg directory stores log configuration files used with the TcaplusDB Client tools

7.2 Convert Proto File to C++ Code

• PROTOBUF_HOME environment variable: specify the path of the installed protobuf dependency library. Please specify the path correctly as follows

• TCAPLUS_HOME environment variable: the path of the downloaded PB SDK after decompression. Please specify the path correctly as follows

export PROTOBUF_HOME=/usr/local/protobuf;
export TCAPLUS_HOME=/root/TcaplusPbApi3.46.0.199033.x86_64_release_20201210/release/x86_64/;

Convert the proto file to C code (example code path: ++examples/tcaplus/C++_pb2_asyncmode_simpletable/SingleOperation/add/conv.sh)

${PROTOBUF_HOME}/bin/protoc -I${PROTOBUF_HOME}/include/ -I${TCAPLUS_HOME}/include/tcaplus_pb_api/ --cpp_out=./  --proto_path=./ table_test.proto

7.3 Compile

Each example has a makefile file, and PROTOBUF_HOME and TCAPLUS_HOME are set according to 7.2 (example MakeFile path: examples/tcaplus/C++_pb2_asyncmode_simpletable/SingleOperation/add/Makefile)

# ================================================================
#Makefile for tcaplus example
#
# Date:   2016-09-14
#
# Copyright (C) 2016 Architechure IRED TENCENT
#
# ================================================================

CPPFILE=$(wildcard *.cpp)
CCFILE=$(wildcard *.cc)

#GENERATE_FILE=$(shell ./conv.sh )

LIBS += -L$(PROTOBUF_HOME)/lib/ -L$(TCAPLUS_HOME)/lib -Wl,-Bstatic -ltcaplusprotobufapi -lprotobuf -ltcew -lexpat -Wl,-Bdynamic -lpthread -lz -ldl -lcrypto -lanl

INC =-I$(PROTOBUF_HOME)/include/ -I$(TCAPLUS_HOME)/include/tcaplus_pb_api/ -I../../../C++_common_for_pb


.PHONY: all clean 

all:
        g++ -o mytest $(CCFILE) $(CPPFILE) $(INC) ${LIBS}  

clean:
        rm -f mytest     mytest.log*

8. Use C++SDK

Please refer to the C++SDK Interfaces Descriptions for details

9. FAQ

In the process of using the SDK, if you have questions (such as viewing the SDK version, configuring SDK log printing, upgrading the SDK, etc.), or errors, please refer to "FAQ" and "Meaning and Handling of Error Codes".

1. FAQ document;

2. Meaning and Handling of Error Codes document;