TDR Table
TDR tables are data tables defined and accessed according to the TDR protocol.
In addition to TDR tables, TcaplusDB also provides PB (Protobuf) tables, which are data tables defined and accessed according to the TDR protocol.
There is no essential difference between PB tables and TDR tables. Users can decide whether to use PB tables or TDR tables according to their familiarity with PB tables or TDR tables. It should be noted that the functions supported by PB and TDR tables in the current TcaplusDB are somewhat different. When selecting which table to use, users also need to consider whether the function can meet app requirements.
1. About TDR
TDR (Tencent Data Representation) is the basic component for game development launched by Tencent. All components are developed based on TDR. DR (Data Representation) components are released in the form of libraries and TDR tools. TDR-API is essentially equivalent to a set of algorithms independent of data structures. Common API functions mainly include network codec, XML data input and output, data visualization, object relational mapping, data sorting. The TDR tool supports meta transformations between various formats and can generate C/C ++data structures to define head files based on an XML meta description. The TDR tool can also generate code that can realize specified functions. Currently, it supports the generation of C++\AS3\C# code, and the supported functions include network codec, XML data input and output, and data visualization.
TDR uses XML to describe and define protocol files, which can be converted into corresponding head files and cpp files using the TDR tool. The TDR tool can generate structures, cmdID definitions and corresponding unpacking functions. The generated structures and functions can be directly applied in programs. Tdr supports the generation of C\AS3\C# languages. There are dynamic updates in the operation of games. The compatibility of protocols is the most concerning in the actual application of game protocols, including the compatibility of the CS protocol and the SS protocol. Tdr handles protocol compatibility using the version number. Newly added fields should include the corresponding version number and the overall version number of TDR. Tdr is packaged with the corresponding maximum version number and field version number. Tdr packages the data according to the version number of the other party, and unpacks the data according to the version number. It supports compatibility from the high version to the low version.
<struct name="users" version="1" primarykey="user_id,username,role_id" splittablekey="user_id" desc="user table">
<entry name="user_id" type="uint64" desc="user id"/>
<entry name="username" type="string" size="64" desc="login username"/>
<entry name="role_id" type="int32" desc="a user can have multiple roles"/>
<entry name="level" type="int32" defaultvalue="1" desc="role's level"/>
<entry name="role_name" type="string" size="1024" desc="role's name" version="100"/>
<entry name="last_login_time" type="string" size="64" defaultvalue="" desc="user login timestamp" version="101"/>
<entry name="last_logout_time" type="string" size="64" defaultvalue="" desc="user logout timestamp" version="102"/>
<index name="index1" column="user_id"/>
</struct>
For example, in the above protocol, the last several fields are newly added fields and must be increased strictly in accordance with the version number. In addition to the version number in the specific structure, the overall version number must be modified.
<metalib name="tcaplus_tb" tagsetversion="1" version="1">
In this way, the TDR packaged data includes specific overall version number and field version number information. It supports compatibility from the high version to the low version, but not compatibility from the low version to the high version. In the actual operation of the release version, the newly added fields must be upgraded strictly in accordance with the version number. The newly added fields and the overall version number should be updated simultaneously. Furthermore, there are numerous modifications, including the CS and SS protocols, when adding new fields. The steps to check the version number are time-consuming and require manual assurance.
2. Examples of the TDR Table Definition File
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<metalib name="tcaplus_tb" tagsetversion="1" version="4">
<struct name="TestInfo" version="1" desc="" >
<entry name="d" type="uint64" />
<entry name="test" type="uint64" />
</struct>
<struct name="TableInfo" version="1" desc="" >
<entry name="c" type="TestInfo" />
<entry name="test" type="uint64" />
<entry name="string_array" type="string" size="100" />
<entry name="binary" type="tinyint" />
</struct>
<struct name="simple_struct" version="4">
<entry name="c_int8" type="int8" defaultvalue="-1"/>
<entry name="c_uint8" type="uint8" defaultvalue="2"/>
<entry name="c_int16" type="int16" defaultvalue="-3"/>
<entry name="c_uint16" type="uint16" defaultvalue="4"/>
<entry name="c_int32" type="int32" defaultvalue="-5"/>
<entry name="c_uint32" type="uint32" defaultvalue="6"/>
<entry name="c_int64" type="int64" defaultvalue="-7"/>
<entry name="c_uint64" type="uint64" defaultvalue="8"/>
</struct>
<union name="union_type" version="1">
<entry name="Id" type="int32" id="0" defaultvalue="0" desc="id" />
<entry name="Name" type="string" id="1" size="64" defaultvalue="hello" desc="name" />
</union>
<struct name="struct_type" version="1">
<entry name="x" type="int32" defaultvalue="0" desc="x" />
<entry name="y" type="int32" defaultvalue="0" desc="y" />
<entry name="score" type="double" defaultvalue="1.11" version="2" />
<entry name="rank" type="uint8" defaultvalue="1" version="3" />
<entry name="title" type="string" size="48" desc="title" />
<entry name="level2_struct" type="struct_nested" version="2" />
</struct>
<struct name="table_list" version="1" primarykey="uin,name,key1" splittablekey="uin" customattr2="TableType=LIST;ListNum=100;DataProtocolType=PLAIN">
<entry name="uin" type="uint64" desc="QQ"/>
<entry name="name" type="string" size="255" desc="Name"/>
<entry name="key1" type="uint8" desc="key4"/>
<entry name="level" type="int32" defaultvalue="1" />
<entry name="count" type="uint8" defaultvalue="0" />
<entry name="array_count" type="uint32" defaultvalue="1" />
<entry name="items" type="uint64" count="10" refer="array_count"/>
<entry name="c_int8" type="int8" defaultvalue="-1"/>
<entry name="c_uint8" type="uint8" defaultvalue="2"/>
<entry name="c_int16" type="int16" defaultvalue="-3"/>
<entry name="c_uint16" type="uint16" defaultvalue="4"/>
<entry name="c_int32" type="int32" defaultvalue="-5"/>
<entry name="c_uint32" type="uint32" defaultvalue="6"/>
<entry name="c_int64" type="int64" defaultvalue="-7"/>
<entry name="c_uint64" type="uint64"/>
<entry name="c_float" type="float" defaultvalue="1.23456789" version="2"/>
<entry name="c_double" type="double" defaultvalue="9.87654321" version="3" />
<entry name="c_string" type="string" size="200" version="3" />
<entry name="c_string_128K" type="string" size="VALUE_128KB_SIZE" defaultvalue="123456789"/>
<entry name="c_string_256K" type="string" size="VALUE_256KB_SIZE" defaultvalue="123456789"/>
<entry name="c_binary" type="tinyint" count="10" refer="array_count" />
<entry name="binary" type="tinyint" version="5"/>
<entry name="selector" type="short" />
<entry name="single_struct" type="struct_type"/>
<entry name="simple_struct" type="simple_struct" version="4"/>
<entry name="single_union_selector" type="int8" defaultvalue="0" />
<entry name="single_union" type="union_type" select="single_union_selector" />
<entry name="array" type="TableInfo" count="3" refer="array_count"/>
<entry name="c_union" type="union_type" select="selector"/>
<entry name="union_array" type="union_type" count="3" select="selector" refer="array_count"/>
<entry name="c_struct" type="struct_type"/>
<entry name="struct_array" type="struct_type" count="3" refer="array_count"/>
<index name="index1" column="uin"/>
<index name="index2" column="uin,name"/>
</struct>
</metalib>
Description:
The element metalib is the root element of the xml file.
Only the struct element containing the attribute primarykey can define a table; otherwise, it is just a regular structure.
Each time the table structure is modified, the value of the version attribute should be increased by 1, and the initial version is always 1.
The primarykey attribute specifies primary key fields. You can specify up to 8 primary key fields for the generic table and 7 for the list table.
The splittablekey attribute is equivalent to the shard key. The TcaplusDB table is split and stored on multiple storage nodes. The splittablekey must be one of the primary key fields, and a good splittablekey should be highly distributed with a wide range of values.
The desc attribute contains a description of the current element.
The entry element defines a field. Supported value types include int32, string, char, int64, double, short, etc.
The index element defines an index, which must contain the splittablekey. Since primary key fields can be used to query the table, the index should not be the same as the primary key attribute.
In addition, you can use union to create nested types.
The union element contains a collection of primitive types, such as integers and strings, and the Union can be referenced as a custom type.
The Macro tag defines constants.
<union name="union_type" version="1">
<entry name="Id" type="int32" id="0" defaultvalue="0" desc="id" />
<entry name="Name" type="string" id="1" size="64" defaultvalue="hello" desc="name" />
</union>
customattr2:
TableType: specifies table types, such as list or sortlist. If no type is specified, it defaults to generic table, and the generic table does not need to add the customattr2 attribute. For details on the description of table types, see Generic Table and List Table.
ListNum: specifies the maximum number of values that a single key can point to in a list or sortlist table. If this value is exceeded, it can specify to delete old elements from the head or tail.
SortFieldNum: used in the sortlist table to indicate the number of sort fields in the table. Each sort field should be identified with customattr2. For example, the first is "sort1" and the second is "sort2".
SortRule: used in the sortlist table to indicate the sorting rule of the table. For example, DESC indicates the descending order and INSC indicates the ascending order. If there are multiple sort fields, sort according to the sequence number. The field with a smaller sequence number has a higher priority. For example, if the sorting rule is descending: it is in descending order by sort1 when the sort1 is different; it is in descending order by sort2 when the sort1 is the same, and so on.
<struct name="following_action_list" version="1" primarykey="game,myuin", customattr2="TableType=SORTLIST;ListNum=1023;SortFieldNum=1;SortRule=DESC">
<entry name="TimeStamp" type="uint32" desc="in minute" />
<entry name="time" type="uint32" customattr2="sort1" desc="time"/>
</struct>
The relevant attributes mentioned in the examples are described in detail below.
3. Descriptions of the TDR Table Definition File
3.1. File Structure
3.1.1. XML head file
The standard XML head file is as follows:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
Use GBK as the character encoding to reduce the impact of character encoding problems in the early stage. Use UTF-8 as the character encoding for multilingual support and portability in the long run.
For now, use:
<?xml version="1.0" encoding="GBK" standalone="yes" ?>
3.1.2. metalib
An XML file can have only one root element. For meta description files, the root element is metalib. It indicates that the contents of the XML file are a collection of meta descriptions.
3.2. Attribute Description
3.2.1. TcaplusDB related attributes
3.2.1.1. primarykey
The primarykey attribute indicates the primary key of the database table corresponding to this element. Its value is a specific child meta member name string that takes the current element as the parent element. If the primary key contains multiple members, the member names are separated by commas (',').
Constraints:
Members as primary keys cannot be compound data types but can only be basic built-in data types.
Members' values as primary keys cannot be NULL.
<struct name="GameItem" primarykey="gameid,itemid">
<entry name="gameid" type="uint" />
<entry name="itemid" type="uint" />
<entry name="buytime" type="datetime" />
<entry name="validtime" type="datetime" />
</struct>
As described above, the GameItem data table uses two members, gameid and itemid, as primary keys.
3.2.1.2. splittablekey (splittable factor/splittable attribute)
The splittablekey attribute indicates the data source that calculates the mapping relationship between the current structure and the specific data table. Its value is a specific child meta member that takes the current element as the parent element. It supports the combination of multiple key fields into a splittablekey.
Constraints:
Members cannot be compound data types but can only be basic built-in data types (except for void types).
<struct name="GameItem" primarykey="gameid,itemid" splittablekey="gameid">
<entry name="gameid" type="uint" />
<entry name="itemid" type="uint" />
<entry name="buytime" type="datetime" />
<entry name="validtime" type="datetime" />
</struct>
3.2.1.3. index (Local index
An index based on the TcaplusDB primary key field is created with the table. Once a table is created, you cannot add, modify, or delete local indexes. When a table is deleted, the local indexes are also deleted.
The local index is a real-time index. When data is inserted or deleted, the index data will be updated at the same time.
The local index field must be included in the primary key field, and the field must also contain splittable factors. Therefore, the final query is performed on a data shard.
The local index supports only equivalent query.
A table can create multiple local indexes. The query must contain all the fields of a local index.
Currently, only Generic tables support local indexes.
<struct name="PLAYERONLINECNT" version="1" primarykey="TimeStamp,GameSvrID,GameAppID" splittablekey="TimeStamp">
<entry name="TimeStamp" type="uint32" desc="in minute" />
<entry name="GameSvrID" type="string" size="64" />
<entry name="GameAppID" type="string" size="64" desc="gameapp id" />
<index name="index_1" column="TimeStamp"/>
<index name="index_2" column="TimeStamp, GameSvrID"/>
<index name="index_3" column="TimeStamp, GameAppID"/>
</struct>
As shown above, the index name cannot be the same, and different indexes must have different columns.
3.2.2. Generic attributes
Generic attributes are those that all non-root elements can have except the root element. For those attributes that are not generic, describe them together when describing related elements. But for include elements, only the name attribute of the generic attribute is meaningful.
3.2.2.1. id
The id attribute indicates the unique identity of the element, which can be used in the API provided by the DR to find and locate specific elements.
The value of id can be either a literal number or a Macro name (for non-macro elements).
Constraints:
The id attribute values of all child elements under the same parent element cannot be the same.
The id attribute of the metalib element can only be a literal number, not a Macro name.
The value of the id attribute of the struc/union element can only be 0 or a positive integer.
3.2.2.2. name
The name attribute provides the character type identity of the element. The Name can be used in the API provided by the DR to find and locate specific elements.
Constraints:
The value of the Name attribute for all children of the same parent element cannot be the same except as described below.
The attribute value of the name attribute is case-sensitive, that is, name = "net" and name = "NET" are considered to be different attribute values.
All elements described by the meta must contain a name attribute.
3.2.2.3. cname
The cname attribute provides the Chinese identifier for elements. Meaningful Chinese names provide a better understanding of the meaning of the elements. (The known application field is reading data from Excel to generate the required memory structure).
3.2.2.4. version
The version attribute indicates the version number of the meta description library when the element is introduced. The version number provides a basis for tailoring when packaging and unpacking. The value of the version attribute can be either a literal number or a Macro name (for non-macro elements).
Constraints:
Metalib, struct, and union elements must contain the version attribute.
For struct and union elements, the version attribute indicates their base version number, that is, the version number indicates the library version number at the time of the element's addition to metalibat.
Constraints on the version attribute of the metalib, struct, union, and entry elements:
The metalib element must specify a version attribute. This version attribute indicates the current version of the meta description library, called library version. The change in the library version number reflects the change in the overall meta description library. When a library changes, the library version number must be kept in sync. The library version number can only be increased, not decreased.
Each struct and union meta must contain a version attribute. This version attribute indicates the library version number at the time of its creation. This attribute is called MetaBaseVersion.Once the table is created, it cannot be changed.
Each meta member has its unique current version number. The version number indicates the library version number of the metaMember at the time of its addition. In other words, the version number indicates the library version in which the meta member was introduced. When a MetaMember does not define its version number, it inherits the base version number of its meta by default.
The current version number of a meta is the maximum current version number of its members.
3.2.2.5. desc
The desc attribute is description information. The desc provides some brief description of the element, indicating its purpose, meaning, etc.
3.2.3. metalib element
The metalib element can only contain the following child elements: include, macro, macrosgroup, struct, and union.
In addition to the id, name, and version attributes described above, metalib can also contain the following attributes: tagsetversion.
3.2.3.1. name
Only XML description files with the same name attribute value can be put together to generate the meta description library, unless the name attribute is an empty string. The name attribute of metalib is similar to a namespace.
3.2.3.2. tagsetversion
This attribute indicates the version of the XML tag set used by the meta description, allowing the attribute handler to be compatible with XML description files defined with different versions of the meta tag set.
This attribute's value is an unsigned integer that must be increased and updated with a new version number whenever the meta description XML tag set definition is changed.
If this attribute is not included in the metaLib element in the XML file, the handler parses by default according to the latest version of the tag definition supported by the DR API.
Constraints:
The tagsetversion value of the meta description XML tag set in this file is defined as 1. That is, the tagsetversion attribute value of the metaLib element of the XML description file generated using the tag defined in this file is 1.
3.2.3.3. include element
The include element must be a child of the metalib element.
The include element indicates dependencies between XML files. The include element only needs to define the file attribute, but it is recommended to define the name (generic) attribute. Defining a globally unique name attribute helps to provide detailed location information for irregularities when TDR performs normative checks on include elements. Strictly speaking, the include attribute does not belong to the metabase. The include element does not affect the hash value of the metabase and is not subject to version constraints. TDR does not check the uniqueness of the name attribute of the include node.
When using the xml2h function of TDR, the include element is converted to the #include macro definition in the head file, and the xml suffix in the file pathname corresponding to the file attribute value is directly replaced with h.
For example, the include element in an XML file
<include name="head" file="./head.xml">
The following macro definition in the corresponding head file:
#include "./head.h"
When using the cplusplus function of TDR, the include element is converted to the #include macro definition in the head file, and the xml suffix in the file pathname corresponding to the file attribute value is directly replaced with h, and the directory information in the path is deleted. The reason why the directory information in the path is deleted is that for the cplusplus function, TDR generates all files in the same directory.
For example, the include element in an XML file
<include name="head" file="../comm.xml">
The following macro definition in the corresponding head file:
#include "comm.h"
For multiple include elements in the XML file, TDR handles these include elements in turn.
3.2.3.4. file
The file attribute indicates other XML files that the current XML file depends on. If the file attribute value of the include element in the XML file is the current XML file path itself or is "", this include element has no effect.
Constraints:
The file specified by the file attribute value (XML file path) must be in the list of XML files specified on the command line (when starting the TDR tool).
3.2.4. macro element
The macro element can be a child of a metalib element or a macrosgoup element. The macro element has a similar meaning to the macro in C and is mapped to the macro in C in actual handling. The macro element is relatively simple. All it needs is a name (generic) attribute and a value attribute.
3.2.4.1. value
The value attribute indicates the value represented by the macro (compared with the macro in C, the value of the name attribute is the name of the macro, and the value of the value attribute is the content of the macro). The value can be either a literal number or the name of a previously defined Macro.
Constraints:
The value attribute is currently stored as an int data type, so it can only handle data within the range of the int data type.
3.2.5. macrosgroup element
The macrosgroup element classifies macro elements, and each class of macro elements forms a macro definition group. The Macrosgroup only needs to include the name and desc attributes.
The child of the macrosgroup element is the macro element. The macro element can also not belong to any macro definition group.
Constraints:
The macrosgroup element must specify the name attribute.
The value attribute value of the macro element of the macrosgroup must be unique, that is, macro elements with the same value attribute value cannot be placed under the same macrosgroup element.
<macro name="MAX_BODY_LEN" value="32000" />
<macrosgroup name=”MsgID” desc=”id of net message” >
<macro name="CMD_LOGIN" value="0" />
<macro name="CMD_LOGOUT" value="1" />
</macrosgroup >
3.2.6. struct element
The struct element must be a child of the metalib element, with one struct for each table in tcaplus.
The struct element are the most complex elements in DR, and are similar to the struct in C language.
3.2.6.1. size
The size attribute indicates the memory footprint of the struct. If no size attribute is specified, the size of the struct is automatically determined by computing the sizes of the members. However, by specifying the size attribute, this struct can preoccupy more space. The size specified by the size attribute cannot be smaller than the size automatically calculated.The string type field in entry must define the size attribute size
3.2.6.2. align
The align attribute corresponds to the compiler's #pragma pack command. The align attribute specifies the alignment size of all members inside the struct. If no align attribute is specified, the default alignment size is 1. Specifying the align attribute affects the size of the structure and the offset of each member.
3.2.6.3. customattr2
The customattr2 attribute defines the attributes of the table, including:
TableType: specifies table types, such as list or sortlist. If no type is specified, it defaults to generic table, and the generic table does not need to add the customattr2 attribute. For details on the description of table types, see Generic Table and List Table.
ListNum: specifies the maximum number of values that a single key can point to in a list or sortlist table. If this value is exceeded, it can specify to delete old elements from the head or tail.
SortFieldNum: used in the sortlist table to indicate the number of sort fields in the table. Each sort field should be identified with customattr2. For example, the first is "sort1" and the second is "sort2".
SortRule: used in the sortlist table to indicate the sorting rule of the table. For example, DESC indicates the descending order and INSC indicates the ascending order. If there are multiple sort fields, sort according to the sequence number. The field with a smaller sequence number has a higher priority. For example, if the sorting rule is descending: it is in descending order by sort1 when the sort1 is different; it is in descending order by sort2 when the sort1 is the same, and so on.
<struct name="table_Sortlist_single" primarykey="key, name" customattr2="TableType=SORTLIST;ListNum=1023;SortFieldNum=1;SortRule=DESC" version="5" desc="used for the list table traversal test, requiring 4 shards, and the list number is 1023 at the maximum" >
...
</struct>
3.2.6.4. entry child element
The entry corresponds to the concept of a meta member. The following describes the attributes that the entry element contains.
3.2.6.4.1. type
The type attribute indicates the data type of the entry member. The value can be a basic built-in data type or a custom compound data type. In the DR API, the value of the type attribute is not case-sensitive.
Constraints:
Custom compound types do not support backward references.
<struct name="type1">
</struct>
<struct name="type2">
<entry name="item1" type="int" />
<entry name="item2" type="float" />
<entry name="item3" type="type1" />
</struct>
The supported basic data types in C/C++/C# are:
| Type Name | Category | Length (In Byte) | Range |
|---|---|---|---|
| byte | Byte | 1 | |
| char | Single-byte Character | 1 | |
| tinyint | Integer | 1 | -128~127 |
| tinyuint | Integer | 1 | 0~255 |
| smallint | Integer | 2 | -32768~32767 |
| smalluint | Integer | 2 | 0~65535 |
| int | Integer | 4 | -231~231-1 |
| uint | Integer | 4 | 0~232-1 |
| bigint | Integer | 8 | -263~263-1 |
| biguint | Integer | 8 | 0~264-1 |
| float | Float | 4 | |
| double | Float | 8 | |
| date | Date | 4 | -9999-00-00 ~9999-12-31 |
| time | Time | 4 | -999:00:00~999:59:59 |
| dateTime | Date/Time | 8 | 0000-00-00 00:00:00~9999-12-31 23:59:59 |
| string | String | Variable | |
| wchar | Wide Character | 2 | |
| wstring | Wide Character Set | ||
| ip | Ipv4 address | 4 | 0.0.0.0～255:255:255:255 |
| void | Void | ||
| int8 | Integer | 1 | -128~127 |
| uint8 | Integer | 1 | 0~255 |
| int16 | Integer | 2 | -32768~32767 |
| uint16 | Integer | 2 | 0~65535 |
| int32 | Integer | 4 | -231~231-1 |
| unit32 | Integer | 4 | 0~232-1 |
| int64 | Integer | 8 | -263~263-1 |
| uint64 | Integer | 8 | 0~264-1 |
- date
Indicates the date data type. The range supported by C/C++ is -9999-00-00 to 9999-12-31. The range supported by C# is 0001-01-01 to 9999-12-31. DR API uses a 4-byte integer to store date data, the actual storage format can be customized. The display, input and output format of date data type is "YYYY-MM-DD". DR provides an API interface for converting between storage format and display format.
- time
Indicates the time data type. The range supported by C/C++ is -999:00:00 to 999:59:59. The range supported by C# is 00:00:00 to 23:59:59. DR API uses a 4-byte integer to store time data, the actual storage format can be customized. The display, input and output format of time data type is "HHH:MM:SS". DR provides an API interface for converting between storage format and display format.
- datetime
Indicates the date and time data type. The range supported by C/C++ is -9999-00-00 00:00:00~9999-12-31 23:59:59. The range supported by C# is 0001-01-01 00:00:00 ~9999-12-31 23:59:59. DR API uses a 8-byte long integer to store datetime data, the actual storage format can be customized. The display, input and output format of date data type is "YYYY-MM-DD HH:MM:SS". DR provides an API interface for converting between storage format and display format.
- ip
The basic IP data type is an IPV4 address. The input and display string is in "Number." format. The format of the string is: a.b.c.d, where a,b,c,d are numbers between 0-255, which can be expressed in octal, decimal or hexadecimal.
| ipv4 address string | Description |
|---|---|
| "4.3.2.16" | Decimal |
| "004.003.002.020" | Octal |
| "0x4.0x3.0x2.0x10" | Hexadecimal |
| "4.003.002.0x10" | Mixed |
- void
The main purpose of introducing the Void data type in TDR is to support generic pointers. Therefore, the void type must be used with a pointer together.
3.2.6.4.2. size
The size attribute indicates the memory footprint of the element. If no size attribute is specified, the size of this element is automatically determined by computing the sizes of its members. However, by specifying the size attribute, this element can preoccupy more space. The size specified by the size attribute cannot be smaller than the size automatically calculated.
The value can be a positive integer or a valid macro definition.
Constraints:
For custom type (union/struct) elements, the size attribute set by the entry is ignored and the size attribute defined in the union/struct element is used.
For built-in data types, only string is currently available. The wstring type supports the size attribute. Other built-in data types do not support the size attribute.
<struct name="type1" >
<entry name="name" type="string" size="32" />
<entry name="pass" type="string" size="32" />
</struct>
3.2.6.4.3. count
The count attribute indicates the number of current meta members (array size). The count can be a literal number or a Macro.
If no count attribute is specified, the default value is 1. Otherwise, the value must be an integer with a range of > = 1. In this case, the refer attribute must be used to indicate the meta members that can be used to determine the size of the array.
<macro name="MAX_COUNT" value="100" />
<struct name="type1">
<entry name="item1" type="int" count="10" />
<entry name="item2" type="float" count="MAX_COUNT" />
<entry name="is_exist" type="int" />
<entry name="item3" type="int" refer="is_exist" />
<entry name="total" type="int" />
<entry name="item4" type="int" count="10" refer="total" />
</struct>
It should be noted that the count and refer attributes do not need to be defined for the string type of the first level field. If yes, they can be nested into the struct. For example:
<macro name="MAX_TEX_ID_LENGTH" value="35" />
<macro name="MAX_TEX_IDS_COUNT" value="150" />
<struct name="Cube1150" version="1" primarykey="FUin" splittablekey="FUin" >
<entry name="TxnIds" type="TxnIdWrapper" count="MAX_TEX_IDS_COUNT" version="2" refer="TxnIdsCount" />
</struct>
<struct name="TxnIdWrapper" version="2" >
<entry name="TxnId" type="string" size="MAX_TEX_ID_LENGTH" />
</struct>
3.2.6.4.4. refer
The refer attribute usually points to another meta member in the meta structure.
When the current meta member is an array, the value of the element pointed to by the refer attribute indicates the actual size of the data member.
When the current meta member is a single element, the value of the element pointed to by the refer attribute indicates whether the data member exists in the actual data (the data used to process Option).
The value can be: a specific child element contained by the immediate parent of the element (backward references are not supported, and the value element must precede the current element).
<struct name="type1">
<entry name="item1" type="int" />
<entry name="item2" type="float" count="10" refer="item1" />
</struct>
Extension case: When referring to child elements that are not at the same level as the current element, they can be specified in the form of Path.Target.
<struct name="type1">
<entry name="item1" type="int" />
<entry name="item2" type="int" />
</struct>
<struct name="type2">
<entry name="head" type="type1" />
<entry name="item4" type="float" count="10" refer="head.item1" />
</struct>
Constraints:
The refer attribute must refer to an element whose value is less than or equal to the value of the element's count attribute. Take the above example: The value of head.item1 must not be greater than 10; When the element is a single element, the default count attribute is 1, and then the refer attribute can only refer to an element with a value of 1 or 0, where a value of 1 means the specific element exists, and a value of 0 means the element does not exist.
The refer attribute of this element refers to an element that cannot be specified as a sizeinfo or versionindicator attribute by another element or by a parent element.
3.2.6.4.5. defaultvalue
The defaultvalue attribute specifies how to value the value of this meta member if it is not explicitly defined.
The value can be: a valid string, and the content of the string should match the type of the meta member.
If no defaultvalue attribute is specified, the default value is 0 (and the array is not populated).
Constraints:
Currently, default values are supported for built-in data types, but not for custom compound data types.
<struct name="type1">
<entry name="item1" type="int" count="100" defaultvalue="100" />
<entry name="item2" type="date" defaultvalue="2009-11-03" />
<entry name="item3" type="int"/>
</struct>
3.2.6.4.6. select
The select attribute is similar to the refer attribute, and usually points to another meta member in the meta structure.
The select attribute indicates how to select data members in the union. The value of the element pointed to by the select attribute is usually used to determine which data member is used in the union.
The value can be: a specific child element contained by the immediate parent of the element (backward references are not supported, and the value element must precede the current element).
<union name="type1">
<entry name="item1" type="int" id="1" />
<entry name="item2" type="int" id="2" />
</union>
<struct name="type2">
<entry name="selector" type="short" />
<entry name="item3" type="type1" select="selector" />
</struct>
3.2.6.4.7. customattr2
The customattr2 attribute indicates whether the field belongs to a sort field. For example, if the sorting rule is descending: it is in descending order by sort1 when the sort1 is different; it is in descending order by sort2 when the sort1 is the same, and so on.
<struct name="table_Sortlist_single" primarykey="key, name" customattr2="TableType=SORTLIST;ListNum=1023;SortFieldNum=1;SortRule=DESC" version="5" desc="used for the list table traversal test, requiring 4 shards, and the list number is 1023 at the maximum" >
<entry name="key" type="uint32" desc="when a single uint32 is a KEY, hashcode = key % 10000"/>
<entry name="name" type="int16" />
<entry name="type_int16" type="int16" desc="type_int16" customattr2="sort1"/>
<entry name="type_int64" type="int64" desc="type_int64" customattr2="sort2"/>
</struct>
3.2.7. Union element
The union element must be a child of the metalib element.
The union element is similar to the union in C language. The union element and struct element are essentially the same in definition. The difference between union and struct elements is the same as the difference between union and struct in C language.
3.2.7.1. entry child element
Like the struct element, entry also corresponds to the concept of a meta member. The entry child element in the union can have the same attributes as the entry child element in the struct, and can also have two additional attributes.
Constraints:
The union can no longer contain meta members of union type.
3.2.7.1.1 minid & maxid
The ID attribute is usually used to determine which meta member is selected in the union. However, in practical applications, it may be necessary to use a range to correspond to a meta member, which is represented by the minid and maxid attributes.
When using minid and maxid, it means an interval: [minid, maxid].
When using ID, it means an interval: [ID, ID].
The child element of the union type data structure may have no ID, which means that this child element is the default element. This child element matches the selection when no other child element matches.
In order to support multiple value ranges, the names of the child elements of the meta structure of the union type can be repeated, but the types of these child elements with the same name must be identical (in this case, a hint of the Info type should be given at compile time).
Constraints:
One and only one of the child elements of the union element can have no ID attribute.
The maxid and minid attributes must both exist.
If the maxid, minid, and id attributes exist at the same time, maxid and minid are used to select members in the union structure.
<union name="type1">
<entry name="example" type="int" minid="1" maxid="100" />
<entry name="example" type="int" id="108" />
<entry name="example" type="int" minid="200" maxid="300" />
<entry name="example" type="int" id="-99" />
<entry name="item2" type="int" id="2" />
</union>
The value range of the selector corresponding to the child element of this example can be: {[1,100], [108,108], [200,300], [-99,-99]}.
4. Descriptions of the TDR Table Modification
The constraints on modifying table meta information are as follows:
XML/TDR file
(1) Duplicate field names are not allowed in a table. The Key field name, Value field name, Value field name and Key field name must not be duplicates.
(2) The value of the primarykey in the tdr meta definition (that is, the key field name) must belong to the existing field name, and the value of the splittablekey must belong to the existing primarykey value (that is, the Key field name). Note: The primarykey defines the Key field.
(3) It is not allowed to delete the Key field, add the Key field, or modify the Key field type. The length of the Key field cannot be modified. It is not allowed to configure the default value for the Key field.
(4) It is allowed to add a Value field and modify the default value of the Value field. It is not allowed to delete the Value field and modify the Value field type. The maximum length of the Value field can be lengthened but not shortened. The default value of the Value field can be modified, but the actual length of the default Value cannot exceed the maximum length of the Value field.
(5) The Index field must belong to the name of the existing Key field, the Index field must contain the field specified by splittablekey, and all the Index fields must belong to the primarykey.
(6) It is not allowed to duplicate field names in the Index field. The length of the column attribute of the Index field cannot exceed 120 bytes.
(7) It is not allowed for the Index field to be configured for a List table.
(8) The maximum number of LIST elements in a List type table can be increased, but not decreased. At the same time, the maximum number of LIST elements in a List type table cannot exceed 10000.
(9) The number of indexes and the field names included in the index cannot be modified.
(10) The version of tcapsvrs where the table is located should be higher than 3.13.0.115217 to modify the "maximum number of LIST elements".
(11) Current TDR limitations: The key field name and the value field name cannot be modified.
(12) If the newly added field is a field with count defined but no refer defined, it will not affect modifications to the table, but it is not allowed to modify the count later.Once the count and size attributes are defined, the table can only be changed to larger and not smaller, and there is no need to modify the version number.
(13) The maximum number of entry fields in the tcaplus table is 256. When the number reaches 110, there will be a warning prompt. The maximum number of values in the list type table should be reduced by 1.
5. Examples of the TDR Table Modification
Original structure:
<?xml version="1.0" encoding="GBK" standalone="yes" ?>
<metalib name="tcaplus_tb" tagsetversion="1" version="1">
<struct name="PLAYERONLINECNT" version="1" primarykey="TimeKey,GameSvrID" splittablekey="TimeKey">
<entry name="TimeKey" type="uint32" desc="time min" />
<entry name="GameSvrID" type="string" size="32" />
<entry name="GameAppID" type="string" size="64" desc="game app id" />
<entry name="OnlineCntIOS" type="uint32" defaultvalue="0" desc="ios online" />
<entry name="OnlineCntAndroid" type="uint32" defaultvalue="0" desc="android online" />
<entry name="array_count" type="uint32" defaultvalue="1" />
<entry name="items" type="uint64" count="10" refer="array_count"/>
<entry name="strstr" type="string" size="4096" desc="string" />
<entry name="strstr1" type="string" size="4096" desc="string" />
<index name="index1" column="TimeKey"/>
<index name="index2" column="TimeKey,GameSvrID"/>
</struct>
</metalib>
5.1. Example 1: Adding a field in a struct
The version number of metalib is increased by one.
The version number of the new field strstr2 is the version number of the new metalib.
<?xml version="1.0" encoding="GBK" standalone="yes" ?>
<metalib name="tcaplus_tb" tagsetversion="1" version="2">
<struct name="PLAYERONLINECNT" primarykey="TimeKey,GameSvrID" splittablekey="TimeKey" version="1">
<entry name="TimeKey" type="uint32" desc="time min" />
<entry name="GameSvrID" type="string" size="32" />
<entry name="GameAppID" type="string" size="64" desc="game app id" />
<entry name="OnlineCntIOS" type="uint32" defaultvalue="0" desc="ios online" />
<entry name="OnlineCntAndroid" type="uint32" defaultvalue="0" desc="android online" />
<entry name="array_count" type="uint32" defaultvalue="1" />
<entry name="items" type="uint64" count="10" refer="array_count"/>
<entry name="strstr" type="string" size="4096" desc="string" />
<entry name="strstr1" type="string" size="4096" desc="string" />
<entry name="strstr2" type="string" size="4096" desc="string" version="2"/>
<index name="index1" column="TimeKey"/>
<index name="index2" column="TimeKey,GameSvrID"/>
</struct>
</metalib>
5.2. Example 2: Adding a new struct
The version number of metalib is increased by one.
The version number of the new structure TestInfo is the new metalib version number.
The version number of the new tableinfo field is the new metalib version number.
<?xml version="1.0" encoding="GBK" standalone="yes" ?>
<metalib name="tcaplus_tb" tagsetversion="1" version="3">
<struct name="TestInfo" version="3" desc="" >
<entry name="d" type="uint64" />
<entry name="test" type="uint64" />
</struct>
<struct name="PLAYERONLINECNT" primarykey="TimeKey,GameSvrID" splittablekey="TimeKey" version="1">
<entry name="TimeKey" type="uint32" desc="time min" />
<entry name="GameSvrID" type="string" size="32" />
<entry name="GameAppID" type="string" size="64" desc="game app id" />
<entry name="OnlineCntIOS" type="uint32" defaultvalue="0" desc="ios online" />
<entry name="OnlineCntAndroid" type="uint32" defaultvalue="0" desc="android online" />
<entry name="array_count" type="uint32" defaultvalue="1" />
<entry name="items" type="uint64" count="10" refer="array_count"/>
<entry name="strstr" type="string" size="4096" desc="string" />
<entry name="strstr1" type="string" size="4096" desc="string" />
<entry name="strstr2" type="string" size="4096" desc="string" version="2"/>
<entry name="tableinfo" type="TestInfo" desc="table info" version="3"/>
<index name="index1" column="TimeKey"/>
<index name="index2" column="TimeKey,GameSvrID"/>
</struct>
</metalib>
5.3. Example 3: Expanding the size of an array (without modifying the version number)
- The count of the modified field items becomes 15.
<?xml version="1.0" encoding="GBK" standalone="yes" ?>
<metalib name="tcaplus_tb" tagsetversion="1" version="3">
<struct name="TestInfo" version="3" desc="" >
<entry name="d" type="uint64" />
<entry name="test" type="uint64" />
</struct>
<struct name="PLAYERONLINECNT" primarykey="TimeKey,GameSvrID" splittablekey="TimeKey" version="1">
<entry name="TimeKey" type="uint32" desc="time min" />
<entry name="GameSvrID" type="string" size="32" />
<entry name="GameAppID" type="string" size="64" desc="game app id" />
<entry name="OnlineCntIOS" type="uint32" defaultvalue="0" desc="ios online" />
<entry name="OnlineCntAndroid" type="uint32" defaultvalue="0" desc="android online" />
<entry name="array_count" type="uint32" defaultvalue="1" />
<entry name="items" type="uint64" count="15" refer="array_count" />
<entry name="strstr" type="string" size="4096" desc="string" />
<entry name="strstr1" type="string" size="4096" desc="string" />
<entry name="strstr2" type="string" size="4096" desc="string" version="2"/>
<entry name="tableinfo" type="TestInfo" desc="table info" version="3"/>
<index name="index1" column="TimeKey"/>
<index name="index2" column="TimeKey,GameSvrID"/>
</struct>
</metalib>