Programming at Client Side

Section operations

To create a new section, use function TBASE_CreateSection. It must be created directly in parent section (See database structure to choose a suitable location). The name of new section must be shorter than 128 characters. Tha attribute can be TBATTR_NOVALUES, that means that section can have only subsections. Otherwise it can ontain values. The advantage of sections without values is that it can avoid sharing problem. The user cen also pass the security attributes parameter. It can be NULL, in this case is inherited from parent.

When the given section already exists - it is open in dynamic mode. The handle of of just open section is returned. It can be used to manipulate values or subsections of it. Handles of open sections are local to threads. To release the open section use function TBASE_CloseSection.

In order the function TBASE_OpenSection open the existing section. In contrary to creation, the name parameter can be a path (not a single name) related to base section given also as parameter. If base is root, give reserved value TBSECTION_ROOT instead of handle. It can be open in 3 modes; snapshot, dynamic or default. The returned handle must be released in the same manner as after creating.

In the snapshot mode the temporary copy of section content (excluding subsections) is created while opening. This mode is read-only. The advantage of it is that the user does not 'own' the opened section letting others to modify it in the meantime.

The dynamic mode is related to the real image of section. The opening mode is allowed only when the user has a TBACCESS_OPENDYNAMIC access right. Unlike in snapshot when the section is open in this mode - it cannot be modified any elsewhere.

In the default mode, the engine decides what mode should be applied. When the user has TBACCESS_OPENDYNAMIC access right, the dynamic mode is used. Otherwise the section is open in snapshot mode.

The other section functions can be used to delete, rename or create a new link to section in an other parent in the same database file. The functions TBASE_ExportSection, TBASE_ImportSection are deprecated and it would be better to reimplement them.

Value operations

A new value should be first allocated by TBASE_AllocValue. A source memory block and type should be given as parameter. Later it can be stored in section by TBASE_SetValue. When the edit mode has not been explicitely initialized by TBASE_Edit function, it is done implicitely. The edit mode is available only when the section is open nowhere else (SWMR semantics) in dynamic mode, otherwise the trial will fail. The values are not set directly, but buffered. Later they should be commited by TBASE_Update. The function also leaves edit mode. When multiple values are set - it is recommended to make a single commit after all. To get an existing value the function TBASE_GetValue should be called. It returns the pointer of obtained value. Both allocated and loaded values should be freed by function TBASE_FreeValue.

Other operations

• If you want to manipulate black and white lists use functions TBASE_Acl....
• To set or get security attributes of section use functions TBASE_GetSectionSecurity, TBASE_SetSectionSecurity

Function definitions

All these functions are declared in file treebase.h