Specific APIs:spc
Specific APIs spc The Xbase++ C-API Container API

Container API Foundation

The container API allows access to the internal data structures of Xbase++. Each variable in Xbase++ is based internally on a data structure called aContainer object. Each container object manages the type and the value of a variable. Access to a container is only possible through the ContainerHandle of the object.

The container API uses functions to create new container objects (_conNew...()), to read their values (_conGet...()) and to change their values (_conPut...()). Because the ContainerHandle of a parameter can be accessed and the return value of a function set using the container API, all of the operations of the parameter API can also be accomplished with the container API. Note: Even though the _par...() and _con...() functions can be used jointly, it is recommended that the container API will be used.

For each of the functions of the container API, success or failure of the function is determined by examining the return value. Functions which returnContainerHandles return the value NULLCONTAINER when an error occurs. All other functions indicate an error by a return value not equal to NULL.

Instead of testing the type of container and then reading the value, the value should be read and the return value tested. This is because Xbase++ allows several threads in an application, all of which can access Xbase++ variables. So that programs can work correctly, all operations on variables are atomic. This keeps two threads from attempting to change the value of a variable at the same time. In this situation, the changes are executed sequentially such that the second change sets the value.

Examination of the variable type with _conType() and reading the value with _conGet...() are two different operations. Therefore, it is possible that the variable could be changed by another thread after testing the type but before reading the value.

The following chapter gives an alphabetical reference of all container API functions.

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.