Macros to Create Data Shapes and Single Columns
Data shapes are the ThingWorx equivalent of Schemas for describing tabular information. They define the data types of the columns of InfoTables. InfoTables are a key data type for many C API functions. To simplify creation of Data Shapes, here are the commands to create the parts of a data shape:
• TW_MAKE_DATASHAPE(…)—Accepts a shape name and n number of arguments, each being a description of the data type of a column. Each argument must be presented in column order to describe the columns of a table. This macro calls the new C API function:
twExt_DataShape * twDataShape_CreateFromEntries(char* shapeName,
twDataShapeEntry* firstEntry, ...)
One difference between the function and the macro is that the function is more verbose. In addition, the function must have NULL as its last argument to terminate the parameter list while the macro TW_MAKE_DATASHAPE() does not have this requirement.
• TW_DS_ENTRY(fieldName,description,type)— Describes a single column present in a Data Shape. fieldname is a string that names a column. description is a sentence that describes the column. If no description is provided, the command TW_NO_DESCRIPTION can be used in place of a description string. The type argument can be any one of the twBaseType values, an abbreviated list of which is shown below:
◦ TW_NOTHING
◦ TW_STRING
◦ TW_NUMBER
◦ TW_BOOLEAN
◦ TW_DATETIME
◦ TW_INFOTABLE
◦ TW_LOCATION
◦ TW_TAGS
◦ TW_BLOB
◦ TW_INTEGER
Using these commands, you can construct a usable twDataShape:
twExt_DataShape* myShape = TW_MAKE_DATASHAPE(NO_SHAPE_NAME,
TW_DS_ENTRY("a",
TW_NO_DESCRIPTION, TW_NUMBER),
TW_DS_ENTRY("b",
TW_NO_DESCRIPTION, TW_BOOLEAN),
TW_DS_ENTRY("c", TW_NO_DESCRIPTION, TW_STRING) );
When a C compiler scans this code, the equivalent ThingWorx C API code is substituted and a Data Shape is allocated. The TS_DS_ENTRY() macro is a simple wrapper around the C SDK function:
twExt_DataShapeEntry * twDataShapeEntry_Create(const char * name,
const char * description,
enum BaseType type);
Also, macros handle the need to NULL terminate lists of arguments for functions that accept n number of arguments, such as TW_MAKE_DATASHAPE.
Tips
For definitions of all of the macros, refer to the file, twMacros.h, in the api subdirectory of the C SDK installation.
You can use the constant, TW_NO_DESCRIPTION, in any property, event or service description parameter such as the arguments of TW_PROPERTY(), TW_DS_ENTRY(), or TW_SERVICE(). You can also use this constant when you do not want to provide a description. This constant is also defined in twMacros.h.