SOS: Scalable Object Store  4.0.0
 All Classes Functions Variables Typedefs Enumerations Enumerator Groups Pages
Schema Functions

Functions

sos_schema_t sos_schema_new (const char *name)
 Create a schema. More...
 
void sos_schema_free (sos_schema_t schema)
 
sos_schema_t sos_schema_dup (sos_schema_t schema)
 Create a copy of a schema. More...
 
size_t sos_schema_count (sos_t sos)
 Return the number of schema in container. More...
 
int sos_schema_add (sos_t sos, sos_schema_t schema)
 Add a schema to a container. More...
 
sos_schema_t sos_schema_from_template (sos_schema_template_t t)
 Create a schema from a SOS template. More...
 
sos_schema_t sos_schema_by_name (sos_t sos, const char *name)
 Find the schema with the specified name. More...
 
sos_schema_t sos_schema_by_id (sos_t sos, uint32_t id)
 Find a schema by id. More...
 
void sos_schema_print (sos_schema_t schema, FILE *fp)
 Print the schema to a File pointer. More...
 
int sos_schema_delete (sos_t sos, const char *name)
 Remove a schema from a container. More...
 
sos_schema_t sos_schema_first (sos_t sos)
 Return a handle to the first schema in the container. More...
 
sos_schema_t sos_schema_next (sos_schema_t schema)
 Return a handle to the next schema in the container. More...
 
const char * sos_schema_name (sos_schema_t schema)
 Returns the schema's name. More...
 
int sos_schema_id (sos_schema_t schema)
 Return the schema's unique id. More...
 
int sos_schema_attr_count (sos_schema_t schema)
 Return the number of attributes in the schema. More...
 
int sos_schema_attr_add (sos_schema_t schema, const char *name, sos_type_t type,...)
 Add an attribute to a schema. More...
 
int sos_schema_index_add (sos_schema_t schema, const char *attr_name)
 Add an index to an attribute. More...
 
int sos_schema_index_modify (sos_schema_t schema, const char *name, const char *idx_type, const char *key_type, const char *idx_args)
 Modify the index for an attribute. More...
 
sos_attr_t sos_schema_attr_by_name (sos_schema_t schema, const char *name)
 Find an attribute by name. More...
 
sos_attr_t sos_schema_attr_by_id (sos_schema_t schema, int attr_id)
 Find an attribute by id. More...
 
sos_attr_t sos_schema_attr_first (sos_schema_t schema)
 
sos_attr_t sos_schema_attr_last (sos_schema_t schema)
 
sos_attr_t sos_schema_attr_next (sos_attr_t attr)
 
sos_attr_t sos_schema_attr_prev (sos_attr_t attr)
 
int sos_attr_id (sos_attr_t attr)
 Return the attribute's ordinal ID. More...
 
const char * sos_attr_name (sos_attr_t attr)
 Return the attribute's name. More...
 
sos_type_t sos_attr_type (sos_attr_t attr)
 Return the attribute's type. More...
 
sos_index_t sos_attr_index (sos_attr_t attr)
 Test if an attribute has an index. More...
 
size_t sos_attr_size (sos_attr_t attr)
 Return the size of an attribute's data. More...
 
sos_schema_t sos_attr_schema (sos_attr_t attr)
 Return the schema of an attribute. More...
 
sos_array_t sos_attr_join_list (sos_attr_t attr)
 Return an array with the list of attributes in the join list. More...
 
int sos_obj_attr_by_name_from_str (sos_obj_t sos_obj, const char *attr_name, const char *attr_value, char **endptr)
 Set an object attribute's value from a string. More...
 
size_t sos_obj_attr_strlen (sos_obj_t obj, sos_attr_t attr)
 Return the length of the string required for the object value. More...
 
int sos_attr_is_ref (sos_attr_t attr)
 Return !0 if the attribute is a reference.
 
int sos_attr_is_array (sos_attr_t attr)
 Return !0 if the attribute is an array.
 
void * sos_obj_ptr (sos_obj_t obj)
 Return a pointer to the object's data. More...
 
size_t sos_array_count (sos_value_t val)
 
sos_value_t sos_array_new (sos_value_t val, sos_attr_t attr, sos_obj_t obj, size_t count)
 
sos_obj_t sos_array_obj_new (sos_t sos, sos_type_t type, size_t count)
 
int sos_value_is_array (sos_value_t v)
 Return !0 if the value is an array.
 
sos_type_t sos_value_type (sos_value_t v)
 Return the value's type. More...
 
size_t sos_value_size (sos_value_t value)
 Get the size of an attribute value. More...
 
void * sos_value_as_key (sos_value_t value)
 
char * sos_obj_attr_to_str (sos_obj_t obj, sos_attr_t attr, char *str, size_t len)
 Format an object attribute as a string. More...
 
int sos_obj_attr_from_str (sos_obj_t obj, sos_attr_t attr, const char *str, char **endptr)
 Set the object attribute from a string. More...
 

Detailed Description

Function Documentation

int sos_attr_id ( sos_attr_t  attr)

Return the attribute's ordinal ID.

Parameters
attrThe attribute handle.
Returns
The attribute id.
sos_index_t sos_attr_index ( sos_attr_t  attr)

Test if an attribute has an index.

Parameters
attrThe sos_attr_t handle
Returns
!0 if the attribute has an index
sos_array_t sos_attr_join_list ( sos_attr_t  attr)

Return an array with the list of attributes in the join list.

The function will return NULL if the attribute is not of the type SOS_TYPE_JOIN.

retval->count - The attribute count. retval->data.uint32_[0..count-1] - The id of each attribute

Parameters
attrThe attribute handle
Returns
A pointer to an array defining the join list.
const char * sos_attr_name ( sos_attr_t  attr)

Return the attribute's name.

Returns
The attribute name
sos_schema_t sos_attr_schema ( sos_attr_t  attr)

Return the schema of an attribute.

Parameters
attrThe attribute handle
Returns
The schema handle
size_t sos_attr_size ( sos_attr_t  attr)

Return the size of an attribute's data.

Parameters
attrThe sos_attr_t handle
Returns
The size of the attribute's data in bytes
sos_type_t sos_attr_type ( sos_attr_t  attr)

Return the attribute's type.

Returns
The attribute type
int sos_obj_attr_by_name_from_str ( sos_obj_t  sos_obj,
const char *  attr_name,
const char *  attr_value,
char **  endptr 
)

Set an object attribute's value from a string.

This convenience function set's an object's attribute value specified as a string. The attribute to set is specified by name.

For example:

int rc = sos_obj_attr_by_name_from_str(an_obj, "my_int_attr", "1234");
if (!rc)
   printf("Success!!\n");

See the sos_obj_attr_from_str() function to set the value with a string if the attribute handle is known.

Parameters
sos_objThe object handle
attr_nameThe attribute name
attr_valueThe attribute value as a string
endptrReceives the point in the str argumeent where parsing stopped. This parameter may be NULL.
Return values
0Success
EINVALThe string format was invalid for the attribute type
ENOSYSThere is no string formatter for this attribute type
int sos_obj_attr_from_str ( sos_obj_t  obj,
sos_attr_t  attr,
const char *  str,
char **  endptr 
)

Set the object attribute from a string.

Parameters
objThe object handle
attrThe attribute handle
strThe input string value to parse
endptrReceives the point in the str argumeent where parsing stopped. This parameter may be NULL.
Return values
0The string was successfully parsed and the value set
EINVALThe string was incorrectly formatted for this value type.
size_t sos_obj_attr_strlen ( sos_obj_t  obj,
sos_attr_t  attr 
)

Return the length of the string required for the object value.

This function returns the size of the buffer required to hold the object attribute value if formatted as a string. This function is useful when allocating buffers used with the sos_obj_attr_to_str() function.

Parameters
objThe object handle
attrThe attribute handle
Returns
The size of the string in bytes.
char* sos_obj_attr_to_str ( sos_obj_t  obj,
sos_attr_t  attr,
char *  str,
size_t  len 
)

Format an object attribute as a string.

Parameters
objThe object handle
attrThe attribute handle
strPointer to the string to receive the formatted value
lenThe size of the string in bytes.
Returns
A pointer to the str argument or NULL if there was a formatting error.
void* sos_obj_ptr ( sos_obj_t  obj)

Return a pointer to the object's data.

This function returns a pointer to the object's internal data. The application is responsible for understanding the internal format. The application must call sos_obj_put() when finished with the object to avoid a memory leak.

This function is intended to be used when the schema of the object is well known by the application. If the application is generic for all objects, see the sos_value() functions.

Parameters
obj
Return values
void* pointer to the objects's data
int sos_schema_add ( sos_t  sos,
sos_schema_t  schema 
)

Add a schema to a container.

A a new schema to the container. A schema with the same name must not already exist in the container.

Parameters
sosThe container handle
schemaPointer to the new schema
Return values
0The schema was successfully added
EEXISTA schema with the same name already exists in the container.
ENOMEMInsufficient resources
EINVALAn invalid parameter was specified.
int sos_schema_attr_add ( sos_schema_t  schema,
const char *  name,
sos_type_t  type,
  ... 
)

Add an attribute to a schema.

Add an attribute to a schema. The schema can only be modified if it is not already a member of the container.

rc = sos_schema_attr_add(s, "an_int32_attr", SOS_TYPE_INT32); rc = sos_schema_attr_add(s, "a_float_attr", SOS_TYPE_FLOAT); rc = sos_schema_attr_add(s, "a_struct_attr", SOS_TYPE_STRUCT, 24); // 24B untyped value rc = sos_schema_attr_add(s, "a_float_array", SOS_TYPE_FLOAT_ARRAY); // Arrays have strict element type, but variable length char *join[] = { "an_int32_attr", "a_float_attr" }; rc = sos_schema_attr_add(s, "a_join_key", SOS_TYPE_JOIN, 2, join); // An attribute that is composed of two other attributes

Parameters
schemaThe schema
nameThe attribute name
typeThe attribute type

If the type is SOS_TYPE_STRUCT:

Parameters
sizeThe size in bytes of the attribute.

If the type is SOS_TYPE_JOIN:

Parameters
countThe number of attributes in this key
cmp_fnName of the key comparison function. If NULL, memcmp is used.
a_1-NCount additional arguments that specify the attribute names comprising the key
Return values
0Success
ENOMEMInsufficient resources
EEXISTAn attribute with that name already exists
EINUSEThe schema is already a member of a container
EINVALA parameter was invalid
sos_attr_t sos_schema_attr_by_id ( sos_schema_t  schema,
int  attr_id 
)

Find an attribute by id.

This function is useful for iterating through all attributes in the schema as shown in the following code fragment:

for (i = 0; i < sos_schema_attr_count(schema); i++) {
   sos_attr_t attr = sos_schema_attr_by_id(i);
   ... code to manipulate attribute ...
}
Parameters
schemaThe schema handle
attr_idThe attribute's ordinal id
Returns
The attribute handle or NULL if the attribute was not found.
sos_attr_t sos_schema_attr_by_name ( sos_schema_t  schema,
const char *  name 
)

Find an attribute by name.

Parameters
schemaThe schema handle
nameThe attribute's name
Returns
The attribute handle or NULL if the attribute was not found.
int sos_schema_attr_count ( sos_schema_t  schema)

Return the number of attributes in the schema.

This function returns the number of attributes in the schema. See the sos_schema_attr_by_id() function for an example that iterates through all attributes defined in the schema.

Parameters
schemaThe schema handle.
Return values
Thenumber of attributes in the schema.
sos_schema_t sos_schema_by_id ( sos_t  sos,
uint32_t  id 
)

Find a schema by id.

Each schema is assigned a unique identifier when it is created. Find the schema with the specified identifier. The schema returned may be used to create objects of this type in the container.

Parameters
sosThe container handle
idThe schema id
Return values
Apointer to the schema
NULLpointer if a schema with that name does not exist in the container
sos_schema_t sos_schema_by_name ( sos_t  sos,
const char *  name 
)

Find the schema with the specified name.

Find the schema with the specified name. The schema returned may be used to create objects of this type in the container.

Parameters
sosThe container handle
nameThe name of the schema
Returns
A pointer to the schema or a NULL pointer if a schema with that name does not exist in the container.
size_t sos_schema_count ( sos_t  sos)

Return the number of schema in container.

Parameters
sosThe container handle
Return values
Thenumber of schema in the container
int sos_schema_delete ( sos_t  sos,
const char *  name 
)

Remove a schema from a container.

Remove the schema with the specified name from the container. If there are any objects in the container that use the specified schema, the schema cannot be deleted.

Parameters
sosThe container handle
nameThe name of the container
Return values
0The schema was successfully deleted
EINUSEAn objects exists in the container that uses the specified schema
ENOENTNo schema was found with the specified name
sos_schema_t sos_schema_dup ( sos_schema_t  schema)

Create a copy of a schema.

Create a replica of a schema that is not associated with a container. This function is useful for adding a schema from one container to another container.

Parameters
schema
Return values
Apointer to the new schema
NULLInsufficient resources
sos_schema_t sos_schema_first ( sos_t  sos)

Return a handle to the first schema in the container.

Parameters
sosThe SOS handle
Return values
Theschema pointer
NULLIf there are no schema defined in the container
sos_schema_t sos_schema_from_template ( sos_schema_template_t  t)

Create a schema from a SOS template.

This convenience function creates a SOS schema from a structure that specifies the schema name and an array of attribute definitions. For example:

struct sos_schema_template employee = {
    .name = "employee",
    .attrs = {
         {
             .name = "First",
             .TYPE = SOS_TYPE_BYTE_ARRAY
         },
         {
              .name = "Last",
              .type = SOS_TYPE_BYTE_ARRAY,
              .indexed = 1
         },
         {
              .name = "Salary",
              .type = SOS_TYPE_FLOAT
         },
         { NULL } // terminates attribute list
    }
};
sos_schema_t schema = sos_schema_from_template(&employee);
Parameters
tPointer to a template structure
Return values
sos_schema_tcreated from the structure definition.
int sos_schema_id ( sos_schema_t  schema)

Return the schema's unique id.

Every schema has a unique Id that is stored along with the object in the database. This a llows the object's type to be identified.

Parameters
schemaThe schema handle.
Return values
Theschema Id
int sos_schema_index_add ( sos_schema_t  schema,
const char *  attr_name 
)

Add an index to an attribute.

Marks an attribute as having a key-value index. The index is not actually created until the schema containing the attribute is added to the container.

Parameters
schemaThe schema handle
attr_nameThe attribute name
Return values
0The index was succesfully added.
ENOENTThe specified attribute does not exist.
EINVALOne or more parameters was invalid.
int sos_schema_index_modify ( sos_schema_t  schema,
const char *  name,
const char *  idx_type,
const char *  key_type,
const char *  idx_args 
)

Modify the index for an attribute.

By default an attribute index is a modified form of a B+Tree that efficiently handles duplicate keys. There are, however, other index types as well as user-defined indices. The type of index is specified as a string that identifies a shared library that implements the necessary index strategy routines, e.g. insert, delete, etc...

For keys, the default key type is associated with the attribute's data type, however, it is possible to implement user-defined key types. These are useful for indexing complex data types that are not understood as primitive types; for example a set of fields that are represented as a UINT64.

Parameters
schemaThe schema handle.
nameThe attribute name.
idx_typeThe index type name. This parameter cannot be null.
key_typeThe key type name. It may be null, in which case, the default key type for the attribute will be used.
...Some index types have additional parameters, for example, the BXTREE has an order parameter that specifies the number of entries in each BXTREE node.
Return values
0The index was succesfully added.
ENOENTThe specified attribute does not exist.
EINVALOne or more parameters was invalid.
const char * sos_schema_name ( sos_schema_t  schema)

Returns the schema's name.

Parameters
schemaThe schema handle.
Returns
The schema's name.
sos_schema_t sos_schema_new ( const char *  name)

Create a schema.

A schema defines a SOS object. Every object in a SOS database is associated with a schema via an internal schema_id.

After a schema is created it must be associated with one or more containers. See the sos_schema_add() function to add a schema to a container so that objects of that type can subsequently be created in the container. Once a schema has been added, it can be looked up with the sos_schema_by_name() and sos_schema_by_id() functions.

Objects are created with the sos_obj_new() function. This function takes a schema-handle as it's argument. The schema-id is saved internally with the object data. An object is therefore self-describing.

Parameters
nameThe name of the schema. This name must be unique within the container.
Returns
A pointer to the new schema or a NULL pointer if there is an error. The errno variable is set to provide detail on the error.
sos_schema_t sos_schema_next ( sos_schema_t  schema)

Return a handle to the next schema in the container.

Parameters
schemaThe schema handle returned by sos_schema_first() or sos_schema_next()
Return values
Theschema pointer
NULLIf there are no more schema defined in the container
void sos_schema_print ( sos_schema_t  schema,
FILE *  fp 
)

Print the schema to a File pointer.

This convenience function formats the schema definition in YAML and writes it to the specified FILE pointer. For example:

sos_schema_t schema = sos_container_find(sos, "Sample");
sos_schema_print(schema, stdout);
Parameters
schemaThe schema handle
fpThe output FILE pointer
size_t sos_value_size ( sos_value_t  value)

Get the size of an attribute value.

Parameters
valueThe value handle
Returns
The size of the attribute value in bytes
sos_type_t sos_value_type ( sos_value_t  v)

Return the value's type.

Returns
The type