Schema API

C8UInt C8SchemaGetColumns(const C8Schema *i_s); – Purpose: For a given schema, returns the number of columns in the schema.

Parameters:

i_s: A pointer to a schema object.

Returns: The number of columns in the schema.

C8_TYPES C8SchemaGetColumnType(const C8Schema *ptr, C8UInt col_ndx); – Purpose: For a given schema and a particular column index in that schema, returns the type of information contained in that column. The type of information can be used in a switch statement or other control code. Column indexes are 0-based, not 1-based - in other words, they range from 0 to C8SchemaGetColumnsCount()-1.

Parameters:

ptr: A pointer to a schema object.
col_ndx: Indicates which column to get the info for. Note that column indexes are 0-based, not 1-based.

Returns: The type of information contained in that column. This is one of the enumerated data types defined for C8_TYPES; see c8types.h for details. The function returns C8_INVALID if col_ndx is out of range or if another error occurs.

C8_TYPES C8SchemaGetColumnTypeByName(const C8Schema *ptr, const char *i_fieldname); – Purpose: For a given schema and a particular column name in that schema, return the type of information contained in that column. The definition of C8_TYPES is in c8types.h. The type information can be used in a switch statement or other control code. Column indexes are 0-based, not 1-based, and they range from 0 to C8SchemaGetColumnsCount()-1.

Parameters:

ptr: A pointer to a schema object.
i_fieldname: The name of the field for which you want the data type.

Returns: The type of information contained in that column. This is one of the enumerated data types defined for C8_TYPES; see c8types.h for details. The function returns C8_INVALID if col_ndx is out of range or if another error occurs.

const C8Char* C8SchemaGetColumnName(const C8Schema *ptr, C8UInt col_num); – Purpose: For a given schema and a particular column index in that schema, return the name of that column.

Parameters:

ptr: A pointer to a schema object.
col_num: The index of the column you want the information for.

Returns: The name of the column. The return value is a pointer. Do not change the memory that the pointer points to, or C8Free() this pointer. The returned pointer is valid as long as the schema pointer is valid.

C8Status C8SchemaGetColumnPosition(const C8Schema *ptr, const C8Char *col_name, C8UInt *o_ndx); – Purpose: Given a schema pointer and a column name, return the corresponding column number. Column names are 0-based, not 1-based.

Parameters:

ptr: A pointer to a schema object.
col_name: The name of the column for which you want the info.
o_ndx: A pointer to a C8UInt that can hold the column number.

Returns: C8_OK if successful, C8_FAIL otherwise.

C8Schema *C8SchemaCreate(void); – Purpose: This creates a schema that is empty (i.e. for which no columns are defined). You can add columns by using the C8SchemaAddColumn() function. The schema must be destroyed with C8SchemaDestroy().

Parameters: none.

Returns: A new schema pointer, or NULL if there was an error.

C8Status C8SchemaAddColumn(C8Schema *i_schema, C8_TYPES i_type, const C8Char *i_name) – Purpose: Adds a column to the schema. The new column will have the specified name and data type.

Parameters:

i_schema: The schema you want to add a column to.
i_type: The data type of the new column.
i_name: The name of the new column.

Returns: C8_OK if success, C8_FAIL otherwise.

C8Schema *C8SchemaReadFromFile(const C8Char *i_filename) – Purpose: Reads a schema from a file. The input parameter is the name of the file to read the schema from. This file must contain a compiled schema (a "tuple descriptor"). For information about how to compile a .ccs schema file and generate a .ccx file, see Compile a Project or a Schema File.

Parameters:

i_filename: The name of the file from which to read the schema.

Returns: Returns a pointer to the schema if successful, NULL otherwise. When you are done using the schema, the returned pointer must be freed with a call to C8SchemaDestroy().

C8Schema *C8SchemaReadFromString(const C8Char *i_str) – Purpose: Reads a schema from a string. The input parameter is the string to read the schema from. The stream must contain the XML text representation of a compiled schema (in other words, a "tuple descriptor").

Parameters:

i_str: The string from which to read the schema.

Returns: A pointer to the schema if successful, NULL otherwise. When you are done using the schema, the returned pointer must be freed with a call to C8SchemaDestroy().

void C8SchemaDestroy(C8Schema* i_schema) – Purpose: Destroys a schema by de-allocating its memory. Any constant pointers returned by calling functions with this schema are invalidated upon return from this method.

Parameters:

i_schema: A pointer to the schema to destroy.

Returns: Nothing.

C8Status C8SchemaToXML(const C8Schema *i_s, C8Char **o_buf) – Purpose: Converts a schema to a string containing the schema's XML representation. The representation is of a compiled schema (a tuple descriptor). This function allocates enough memory for the string, and the pointer returned through the o_buf parameter needs to be freed with a call to C8Free().

Parameters:

i_s: A pointer to a schema.
o_buf: A pointer that can be set to point to a string containing the XML representation of the schema.

Returns: C8_OK if success, C8_FAIL otherwise (in which case o_buf is unchanged).

C8Status C8SchemaWriteToFile(const C8Schema *i_s, const C8Char *i_fn) – Purpose: Writes a schema to a file in tuple descriptor representation.

Parameters:

i_s: A pointer to the schema.
i_fn: The name of the file to write the schema to.

Returns: C8_OK if success, C8_FAIL otherwise.

C8Bool C8SchemaCompare(const C8Schema *i_s1, const C8Schema *i_s2) – Purpose: Return a value indicating whether two schemas are identical.

Parameters:

i_s1: First schema.
i _ s2: Second schema.

Returns: C8_TRUE if the schemas are identical, C8_FALSE otherwise.