sasstringbtree.h File Reference

Shared Address Space B-tree. More...

`#include "sasstringbtreenode.h"`

Go to the source code of this file.

## Typedefs

typedef void * | SASStringBTree_t
| Handle to an instance of String B-tree. More...

## Functions

__C__ SASStringBTree_t | SASStringBTreeFixedCreate (block_size_t block_size)
| Create a fixed SAS B-Tree of block_size size capacity. More...
__C__ SASStringBTree_t | SASStringBTreeExpandCreate (SASStringBTree_t btree)
| Internal function that creates new block of B-Tree nodes for an expanding SAS B-Tree btree. More...
__C__ SASStringBTree_t | SASStringBTreeCreate (block_size_t block_size)
| Create a new expanding SAS B-Tree with initial heap_size size and default page_size for nodes. More...
__C__ SASStringBTree_t | SASStringBTreeCreatePageSize (block_size_t block_size, block_size_t page_size)
| Create a new expanding SAS B-Tree with heap_size size and page_size node size. More...
__C__ void | SASStringBTreeDestroy (SASStringBTree_t btree)
| Destroy the SAS B-Tree btree. More...
__C__ block_size_t | SASStringBTreeAllocSize (SASStringBTree_t btree)
| Return the page size used for node allocation for btree. More...
__C__ block_size_t | SASStringBTreeFreeSpace (SASStringBTree_t btree)
| Return the total available node free space for btree. More...
__C__ SASStringBTreeNode_t | SASStringBTreeAlloc (SASStringBTree_t btree)
| Internal function to allocate a new SASStringBTreeNode_t for SAS B-Tree btree. More...
__C__ SASStringBTreeNode_t | SASStringBTreeNearAlloc (void *nearObj)
| Internal function to allocate a new SASStringBTreeNode_t from the containing SAS B-Tree near an existing nearObj. More...
__C__ void | SASStringBTreeFree (SASStringBTree_t btree, SASStringBTreeNode_t free_block)
| Internal function to return a SASStringBTreeNode_t free_block to the free space of B-tree btree for later reuse as a node. More...
__C__ void | SASStringBTreeNearDealloc (void *memAddr)
| Internal function to free the SASStringBTreeNode_t at memAddr from its associated SASStringBTree_t B-Tree block. More...
__C__ SASStringBTreeNode_t | SASStringBTreeGetRootNode (SASStringBTree_t btree)
| Internal function that returns the root SASStringBTreeNode_t node for btree B-Tree. More...
__C__ SASStringBTreeNode_t | SASStringBTreeGetRootNodeNoLock (SASStringBTree_t btree)
| Internal function that returns the root SASStringBTreeNode_t node for btree B-Tree. More...
__C__ long | SASStringBTreeGetModCount (SASStringBTree_t btree)
| Return the number or insert/replace/remove operations performed on btree. More...
__C__ long | SASStringBTreeGetModCount_nolock (SASStringBTree_t btree)
| Return the number or insert/replace/remove operations performed on btree. More...
__C__ char * | SASStringBTreeGetMaxKey (SASStringBTree_t btree)
| Return the maximum key string from btree. More...
__C__ char * | SASStringBTreeGetMaxKey_nolock (SASStringBTree_t btree)
| Return the maximum key string from btree. More...
__C__ char * | SASStringBTreeGetMinKey (SASStringBTree_t btree)
| Return the minimum key string from btree. More...
__C__ char * | SASStringBTreeGetMinKey_nolock (SASStringBTree_t btree)
| Return the minimum key string from btree. More...
__C__ int | SASStringBTreeContainsKey (SASStringBTree_t btree, char *key)
| Return true if the SAS B-Tree btree contains the key key. More...
__C__ int | SASStringBTreeContainsKey_nolock (SASStringBTree_t btree, char *key)
| Return true if the SAS B-Tree btree contains the key key. More...
__C__ void * | SASStringBTreeGet (SASStringBTree_t btree, char *key)
| Return the memory address value associated with key in SAS B-Tree btree. More...
__C__ void * | SASStringBTreeGet_nolock (SASStringBTree_t btree, char *key)
| Return the memory address value associated with key in SAS B-Tree btree. More...
__C__ int | SASStringBTreeIsEmpty (SASStringBTree_t btree)
| Return true if the SAS B-Tree btree is empty. More...
__C__ int | SASStringBTreeIsEmpty_nolock (SASStringBTree_t btree)
| Return true if the SAS B-Tree btree is empty. More...
__C__ long | SASStringBTreeGetCurCount (SASStringBTree_t btree)
| Return the number of elements in the SAS B-Tree btree. More...
__C__ int | SASStringBTreePut (SASStringBTree_t btree, char *key, void *value)
| Add a new element value with key key in the SAS B-Tree btree. More...
__C__ int | SASStringBTreePut_nolock (SASStringBTree_t btree, char *key, void *value)
| Add a new element value with key key in the SAS B-Tree btree. More...
__C__ void * | SASStringBTreeReplace (SASStringBTree_t btree, char *key, void *value)
| Replace the associated value of the element with key key in SAS B-Tree btree with the value value. More...
__C__ void * | SASStringBTreeReplace_nolock (SASStringBTree_t btree, char *key, void *value)
| Replace the associated value of the element with key key in SAS B-Tree btree with the value value. More...
__C__ void * | SASStringBTreeRemove (SASStringBTree_t btree, char *key)
| Remove the key key and its associated value from SAS B-Tree btree. More...
__C__ void * | SASStringBTreeRemove_nolock (SASStringBTree_t btree, char *key)
| Remove the key key and its associated value from SAS B-Tree btree. More...
__C__ SASStringBTree_t | SASStringBTreeInit (void *block, block_size_t block_size, block_size_t page_size, int expanding)
| Internal function to initialize storage as a B-tree. More...
__C__ void | SASStringBTreeDestroyNoLock (SASStringBTree_t btree)
| Destroy the SAS B-Tree btree. More...
__C__ block_size_t | SASStringBTreeFreeSpaceNoLock (SASStringBTree_t btree)
| Internal function. Return the total available free space on SAS B-Tree btree. More...
__C__ SASStringBTreeNode_t | SASStringBTreeAllocNoLock (SASStringBTree_t btree)
| Internal function. Allocate a new SASStringBTreeNode_t from SAS B-Tree btree. More...
__C__ SASStringBTreeNode_t | SASStringBTreeNearAllocNoLock (void *nearObj)
| Internal function. Allocate a new SASStringBTreeNode_t from SAS B-Tree near nearObj. More...
__C__ void | SASStringBTreeNearDeallocNoLock (void *memAddr)
| Internal function. Free the SASStringBTreeNode_t on memAddr from its associated SASStringBTree_t B-Tree. More...
__C__ void | SASStringBTreeFreeNoLock (SASStringBTree_t btree, SASStringBTreeNode_t free_block)
| Internal function. Free the SASStringBTreeNode_t free_block from B-tree btree. More...

## Detailed Description

Shared Address Space B-tree.

Allocate SAS block storage and manage it as a B-tree data structure using null terminate "C" strings as keys and addresses as associated value. This provides "map" (or association) between a string and an arbitrary address. One expected usage is to provide human readable labels for arbitrary data structures within SAS storage. These labels can be passed as program arguments to allow programs to find data persistent elements from previous sessions.

The String B-tree keeps the string data sorted and allows search/insert/delete in logarithmic time. The B-Tree is organized into page-size nodes to improve storage locality for search and minimize paging when very large B-Trees are needed.

A new SBT can be constructed using the functions SASStringBTreeCreate, SASStringBTreeExpandCreate, or SASStringBTreeCreatePageSize. The functions differs for the options provides. A SAS block can be initialized as a SBT by using the function SASStringBTreeInit.

SASStringBTree_t stringBTree;
stringBTree = SASStringBTreeCreate (blockSize);
if (stringBTree)
{
rc = SASStringBTreePut (stringBTree, "\mykeys\", mydata);
if (rc)
{
printf("inserted \mykeys\ into BTree@%p for %p", stringBTree, mtdate);
}
}
SASStringBTree_t
void * SASStringBTree_t
Handle to an instance of String B-tree.
Definition: sasstringbtree.h:102
SASStringBTreeCreate
__C__ SASStringBTree_t SASStringBTreeCreate(block_size_t block_size)
Create a new expanding SAS B-Tree with initial heap_size size and default page_size for nodes.
SASStringBTreePut
__C__ int SASStringBTreePut(SASStringBTree_t btree, char *key, void *value)
Add a new element value with key key in the SAS B-Tree btree.

The helper functions SASStringBTreePut, SASStringBTreeReplace, and SASStringBTreeRemove can be used to insert, replace and remove a string/pointer tuple from SBT. Others useful functions are SASStringBTreeContainsKey, which returns if a key exists; and SASStringBTreeGet, which returns the value of a key.

The enumeration API from sasstringbtreeenum.h can be use to iterate over the (in whole or part) of contents of BTree in key order.

The functions above apply SASLock and SASUnlock around each string operation to insure consistency of the string.

If at process needs exclusive access or needs to scan or populate a string quickly, the application can SASLock the SASStringBTree_t, then use the *_nolock forms of the function above for faster access.

SASStringBTree_t stringBTree;
SASStringBTreeEnum_t senum;
char *keyref;
SASLock (stringBTree, SasUserLock__READ);
senum = SASStringBTreeEnumCreate (stringBTree);
if (!senum)
{
printf ("SASStringBTreeEnumCreate (%p) failed", stringBTree);
return 1;
}
while (SASStringBTreeEnumHasMore (senum))
{
keyref = ((char *) SASStringBTreeEnumNext_nolock (senum);
if (keyref)
{
// process reference value associated with next enum
}
}
SASUnlock (stringBTree);
SASUnlock
__C__ void SASUnlock(vm_address_t addr)
UnLock a SAS Address.
SASLock
__C__ void SASLock(vm_address_t addr, sas_userlock_request_t lockT)
Lock a SAS Address.
SASStringBTreeEnumCreate
__C__ SASStringBTreeEnum_t SASStringBTreeEnumCreate(SASStringBTree_t btree)
Create a SASStringBTreeEnum_t enumeration that can be used to iterate over the name space of a String...
SASStringBTreeEnumHasMore
__C__ int SASStringBTreeEnumHasMore(SASStringBTreeEnum_t sbtenum)
Return status of a SASStringBTreeEnum_t enumeration.
SASStringBTreeEnum_t
void * SASStringBTreeEnum_t
Handle to an instance of String BTree Enumeration.
Definition: sasstringbtreeenum.h:113
SASStringBTreeEnumNext_nolock
__C__ void * SASStringBTreeEnumNext_nolock(SASStringBTreeEnum_t sbtenum)
Move the enumeration to the next String BTree key entry and return the associated address value.

Finally, a created SAS B-Tree can be destroy with SASStringBTreeDestroy

## Typedef Documentation

## SASStringBTree_t

typedef void* SASStringBTree_t

Handle to an instance of String B-tree.

The type is SAS_RUNTIME_STRINGBTREE

## Function Documentation

## SASStringBTreeAlloc()

__C__ SASStringBTreeNode_t SASStringBTreeAlloc | ( | SASStringBTree_t | btree | ) |

Internal function to allocate a new SASStringBTreeNode_t for SAS B-Tree btree.

The sas_type_t must be SAS_RUNTIME_STRINGBTREE. The function holds a write lock over B-Tree btree. The created SASStringBTreeNode_t can be modified using the functions at sasstringbtreenode.h.

Parameters

  btree | Handle to the SASStringBTree_t.

Returns
  A new SASStringBTreeNode_t handle or 0 if creation fails.

## SASStringBTreeAllocNoLock()

__C__ SASStringBTreeNode_t SASStringBTreeAllocNoLock | ( | SASStringBTree_t | btree | ) |

Internal function. Allocate a new SASStringBTreeNode_t from SAS B-Tree btree.

Similar to SASStringBTreeAlloc but this function hilds no lock.

Parameters

  btree | Handle the to SASStringBTree_t.

Returns
  A new SASStringBTreeNode_t handle or 0 if creation fails.

## SASStringBTreeAllocSize()

__C__ block_size_t SASStringBTreeAllocSize | ( | SASStringBTree_t | btree | ) |

Return the page size used for node allocation for btree.

The sas_type_t must be SAS_RUNTIME_STRINGBTREE.

Parameters

  btree | Handle the to SASStringBTree_t.

Returns
  The page size value in bytes.

## SASStringBTreeContainsKey()

__C__ int SASStringBTreeContainsKey | ( | SASStringBTree_t | btree,
|  | char * | key
| ) |  |

Return true if the SAS B-Tree btree contains the key key.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. The function holds a read lock over B-Tree btree. This function searches the B-Tree for a matching key and returns true if found.

Parameters

  btree | Handle to the SASStringBTree_t.
  key | Null terminated key string to search.

Returns
  1 if the key is within btree or 0 otherwise.

## SASStringBTreeContainsKey_nolock()

__C__ int SASStringBTreeContainsKey_nolock | ( | SASStringBTree_t | btree,
|  | char * | key
| ) |  |

Return true if the SAS B-Tree btree contains the key key.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. This function searches the B-Tree for a matching key and returns true if found.

This nolock form should only be used when the referenced SASStringBTree_t is known to be locked by the application or contained within a larger structure with a controlling lock.

Parameters

  btree | Handle to the SASStringBTree_t.
  key | Null terminated key string to search.

Returns
  1 if the key is within btree or 0 otherwise.

## SASStringBTreeCreate()

__C__ SASStringBTree_t SASStringBTreeCreate | ( | block_size_t | block_size | ) |

Create a new expanding SAS B-Tree with initial heap_size size and default page_size for nodes.

Create and initialize a B-Tree. The storage block must be power of two in size and SAS type returned is SAS_RUNTIME_STRINGBTREE. The internal page size used is the default one defined in sasalloc.h (4096).

Parameters

  block_size | Size of the B-Tree to create.

Returns
  A handle to created SASStringBTree_t or 0 if creation fails.

## SASStringBTreeCreatePageSize()

__C__ SASStringBTree_t SASStringBTreeCreatePageSize | ( | block_size_t | block_size,
|  | block_size_t | page_size
| ) |  |

Create a new expanding SAS B-Tree with heap_size size and page_size node size.

Similar to SASStringBTreeCreate but with additional option to set the internal node page size.

Parameters

  block_size | Size of the B-Tree to create.
  page_size | Size of the internal node pages.

Returns
  A handle to created SASCompoundHeap_t or 0 if creation fails.

## SASStringBTreeDestroy()

__C__ void SASStringBTreeDestroy | ( | SASStringBTree_t | btree | ) |

Destroy the SAS B-Tree btree.

The type must be SAS_RUNTIME_STRINGBTREE. Destroy holds an exclusive write lock while clearing the control blocks and freeing the SAS block (or blocks for a expanding B-Tree).

Parameters

  btree | Handle of the SASStringBTree_t to be destroyed.

## SASStringBTreeDestroyNoLock()

__C__ void SASStringBTreeDestroyNoLock | ( | SASStringBTree_t | btree | ) |

Destroy the SAS B-Tree btree.

Similar to SASStringBTreeDestroy but this function holds no lock.

Parameters

  btree | Handle of the SASStringBTree_t to be destroyed.

## SASStringBTreeExpandCreate()

__C__ SASStringBTree_t SASStringBTreeExpandCreate | ( | SASStringBTree_t | btree | ) |

Internal function that creates new block of B-Tree nodes for an expanding SAS B-Tree btree.

Create a block and initialize it to provide additional B-Tree node space to an existing expanding SAS B-Tree btree. This block is added the internal block list of the B-Tree.

Parameters

  btree | The SAS B-Tree to be expanded by one block.

Returns
  A new SASStringBtree_t handle or 0 if the block allocate or initialization fails.

## SASStringBTreeFixedCreate()

__C__ SASStringBTree_t SASStringBTreeFixedCreate | ( | block_size_t | block_size | ) |

Create a fixed SAS B-Tree of block_size size capacity.

Create and initialize a B-Tree. The storage block must be power of two in size and the SAS type returned is SAS_RUNTIME_STRINGBTREE. The internal page size used is the default one defined in sasalloc.h (4096).

Parameters

  block_size | Size of the B-Tree to create.

Returns
  A handle to created SASStringBtree_t or 0 if creation fails.

## SASStringBTreeFree()

__C__ void SASStringBTreeFree | ( | SASStringBTree_t | btree,
|  | SASStringBTreeNode_t | free_block
| ) |  |

Internal function to return a SASStringBTreeNode_t free_block to the free space of B-tree btree for later reuse as a node.

The sas_type_t must be SAS_RUNTIME_STRINGBTREE. The functions holds a write lock over B-Tree btree.

Parameters

  btree | Handle to the SASStringBTree_t.
  free_block | Handle to the SASStringBTreeNode_t to be freed.

## SASStringBTreeFreeNoLock()

__C__ void SASStringBTreeFreeNoLock | ( | SASStringBTree_t | btree,
|  | SASStringBTreeNode_t | free_block
| ) |  |

Internal function. Free the SASStringBTreeNode_t free_block from B-tree btree.

Similar to SASStringBTreeFree but this function holds no lock.

Parameters

  btree | Handle to the SASStringBTree_t.
  free_block | Handle to the SASStringBTreeNode_t to be freed.

## SASStringBTreeFreeSpace()

__C__ block_size_t SASStringBTreeFreeSpace | ( | SASStringBTree_t | btree | ) |

Return the total available node free space for btree.

The sas_type_t must be SAS_RUNTIME_STRINGBTREE. The function holds a write lock while calculating the total node free space from B-Tree.

Parameters

  btree | Handle to the SASStringBTree_t.

Returns
  The total available free node space in bytes.

## SASStringBTreeFreeSpaceNoLock()

__C__ block_size_t SASStringBTreeFreeSpaceNoLock | ( | SASStringBTree_t | btree | ) |

Internal function. Return the total available free space on SAS B-Tree btree.

Similar to SASStringBTreeFreeSpace but this function holds no lock.

Parameters

  btree | Handle the to SASStringBTree_t.

Returns
  The total available free space in bytes.

## SASStringBTreeGet()

__C__ void * SASStringBTreeGet | ( | SASStringBTree_t | btree,
|  | char * | key
| ) |  |

Return the memory address value associated with key in SAS B-Tree btree.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. The function holds a read lock over B-Tree btree. This function searches the B-Tree for a matching key and if found, returns the associated memory address value.

Parameters

  btree | Handle to the SASStringBTree_t.
  key | Null terminated key string to search.

Returns
  The associated memory address with key or 0 if the B-Tree btree does not contain the key or if an error occurs.

## SASStringBTreeGet_nolock()

__C__ void * SASStringBTreeGet_nolock | ( | SASStringBTree_t | btree,
|  | char * | key
| ) |  |

Return the memory address value associated with key in SAS B-Tree btree.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. This function searches the B-Tree for a matching key and if found, returns the associated memory address value.

This nolock form should only be used when the referenced SASStringBTree_t is known to be locked by the application or contained within a larger structure with a controlling lock.

Parameters

  btree | Handle to the SASStringBTree_t.
  key | Null terminated key string to search.

Returns
  The associated memory address with key or 0 if the B-Tree btree does not contain the key or if an error occurs.

## SASStringBTreeGetCurCount()

__C__ long SASStringBTreeGetCurCount | ( | SASStringBTree_t | btree | ) |

Return the number of elements in the SAS B-Tree btree.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. The function holds a read lock over B-Tree btree.

Parameters

  btree | Handle to the SASStringBTree_t.

Returns
  Number of elements within the B-Tree btree.

## SASStringBTreeGetMaxKey()

__C__ char * SASStringBTreeGetMaxKey | ( | SASStringBTree_t | btree | ) |

Return the maximum key string from btree.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. The function holds a read lock over B-Tree btree. The maximum key is the right most entry of the right most node.

Note
  this value it stored in the header of the SASStringBTree_t initial block and should never be modified by the application.

Parameters

  btree | Handle to the SASStringBTree_t.

Returns
  Null terminated maximum key string from B-Tree btree or 0 if the B-Tree does not have any key or if an error occurs.

## SASStringBTreeGetMaxKey_nolock()

__C__ char * SASStringBTreeGetMaxKey_nolock | ( | SASStringBTree_t | btree | ) |

Return the maximum key string from btree.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. The maximum key is the right most entry of the right most node.

Note
  this value it stored in the header of the SASStringBTree_t initial block and should never be modified by the application.

This nolock form should only be used when the referenced SASStringBTree_t is known to be locked by the application or contained within a larger structure with a controlling lock.

Parameters

  btree | Handle to the SASStringBTree_t.

Returns
  Null terminated maximum key string from B-Tree btree or 0 if the B-Tree does not have any key or if an error occurs.

## SASStringBTreeGetMinKey()

__C__ char * SASStringBTreeGetMinKey | ( | SASStringBTree_t | btree | ) |

Return the minimum key string from btree.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. The function holds a read lock over B-Tree btree. The minimum key is the left most entry of the left most node.

Note
  this value it stored in the header of the SASStringBTree_t initial block and should never be modified by the application.

Parameters

  btree | Handle to the SASStringBTree_t.

Returns
  Null terminated minimum key string from B-Tree btree or 0 if the B-Tree does not have any key or if an error occurs.

## SASStringBTreeGetMinKey_nolock()

__C__ char * SASStringBTreeGetMinKey_nolock | ( | SASStringBTree_t | btree | ) |

Return the minimum key string from btree.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. The minimum key is the left most entry of the left most node.

Note
  this value it stored in the header of the SASStringBTree_t initial block and should never be modified by the application.

This nolock form should only be used when the referenced SASStringBTree_t is known to be locked by the application or contained within a larger structure with a controlling lock.

Parameters

  btree | Handle to the SASStringBTree_t.

Returns
  Null terminated minimum key string from B-Tree btree or 0 if the B-Tree does not have any key or if an error occurs.

## SASStringBTreeGetModCount()

__C__ long SASStringBTreeGetModCount | ( | SASStringBTree_t | btree | ) |

Return the number or insert/replace/remove operations performed on btree.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. The function holds a read lock over B-Tree btree. An initialized SAS B-Tree starts with mod count 1 and it is incremented each time a insert/replace/remove operation is performed.

Parameters

  btree | Handle to the SASStringBTree_t.

Returns
  The number of insert/replace/remove operations performed on btree.

## SASStringBTreeGetModCount_nolock()

__C__ long SASStringBTreeGetModCount_nolock | ( | SASStringBTree_t | btree | ) |

Return the number or insert/replace/remove operations performed on btree.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. An initialized SAS B-Tree starts with mod count 1 and it is incremented each time a insert/replace/remove operation is performed.

This nolock form should only be used when the referenced SASStringBTree_t is known to be locked by the application or contained within a larger structure with a controlling lock.

Parameters

  btree | Handle to the SASStringBTree_t.

Returns
  The number of insert/replace/remove operations performed on btree.

## SASStringBTreeGetRootNode()

__C__ SASStringBTreeNode_t SASStringBTreeGetRootNode | ( | SASStringBTree_t | btree | ) |

Internal function that returns the root SASStringBTreeNode_t node for btree B-Tree.

The sas_type_t must be SAS_RUNTIME_STRINGBTREE. The functions holds a read lock over B-Tree btree.

Parameters

  btree | Handle to the SASStringBTree_t.

Returns
  The root node or 0 if no root is available or if an error occurs.

## SASStringBTreeGetRootNodeNoLock()

__C__ SASStringBTreeNode_t SASStringBTreeGetRootNodeNoLock | ( | SASStringBTree_t | btree | ) |

Internal function that returns the root SASStringBTreeNode_t node for btree B-Tree.

Similar to function SASStringBTreeGetRootNode but the function holds no lock.

Parameters

  btree | Handle to the SASStringBTree_t.

Returns
  The root node or 0 if no root is available or if an error occurs.

## SASStringBTreeInit()

__C__ SASStringBTree_t SASStringBTreeInit | ( | void * | block,
|  | block_size_t | block_size,
|  | block_size_t | page_size,
|  | int | expanding
| ) |  |

Internal function to initialize storage as a B-tree.

An internal function used to initialize the control blocks within the specific storage block block as a SAS String B-tree. Both block_size and page_size must be power of two in size and have the same power of two (or better) alignment. The SAS type created is SAS_RUNTIME_STRINGBTREE.

Parameters

  block | Block of allocated SAS storage.
  block_size | Size of the B-tree within the block.
  page_size | Size of page size to use.
  expanding | boolean indicates if the B-tree is expand or fixed.

Returns
  A handle to the initialized SASStringBtree_t or 0 if an error occurs.

## SASStringBTreeIsEmpty()

__C__ int SASStringBTreeIsEmpty | ( | SASStringBTree_t | btree | ) |

Return true if the SAS B-Tree btree is empty.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. The function holds a read lock over B-Tree btree.

Parameters

  btree | Handle to the SASStringBTree_t.

Returns
  1 if the B-Tree is not empty or 0 otherwise.

## SASStringBTreeIsEmpty_nolock()

__C__ int SASStringBTreeIsEmpty_nolock | ( | SASStringBTree_t | btree | ) |

Return true if the SAS B-Tree btree is empty.

The sas_type_t must be SAS_RUNTIME_STRINGTREE.

This nolock form should only be used when the referenced SASStringBTree_t is known to be locked by the application or contained within a larger structure with a controlling lock.

Parameters

  btree | Handle to the SASStringBTree_t.

Returns
  1 if the B-Tree is not empty or 0 otherwise.

## SASStringBTreeNearAlloc()

__C__ SASStringBTreeNode_t SASStringBTreeNearAlloc | ( | void * | nearObj | ) |

Internal function to allocate a new SASStringBTreeNode_t from the containing SAS B-Tree near an existing nearObj.

The function is similar to SASStringBTreeAlloc but accepts a memory address of another SASStringBTreeNode_t from within the containing SASStringBTree_t.

Todo:
  I wonder if nearObj should be SASStringBTreeNode_t to made the usage/intent clear.

Parameters

  nearObj | Memory address of the SASStringBTree_t handler.

Returns
  A new SASStringBTreeNode_t handle or 0 if creation fails.

## SASStringBTreeNearAllocNoLock()

__C__ SASStringBTreeNode_t SASStringBTreeNearAllocNoLock | ( | void * | nearObj | ) |

Internal function. Allocate a new SASStringBTreeNode_t from SAS B-Tree near nearObj.

Similar to SASStringBTreeNearAlloc but this function holds no lock.

Parameters

  nearObj | Memory address of the handle to the SASStringBTree_t.

Returns
  A new SASStringBTreeNode_t handle or 0 if creation fails.

## SASStringBTreeNearDealloc()

__C__ void SASStringBTreeNearDealloc | ( | void * | memAddr | ) |

Internal function to free the SASStringBTreeNode_t at memAddr from its associated SASStringBTree_t B-Tree block.

The Function is similar to SASStringBTreeFree but the memAddr is used as the SASStringBTreeNode_t and the associated containing SASStringBTree_t address is calculated from the node.

Parameters

  memAddr | Memory address associated with the SASStringBTreeNode_t to be freed.

## SASStringBTreeNearDeallocNoLock()

__C__ void SASStringBTreeNearDeallocNoLock | ( | void * | memAddr | ) |

Internal function. Free the SASStringBTreeNode_t on memAddr from its associated SASStringBTree_t B-Tree.

Similar to SASStringBTreeNearDealloc but this function holds no lock.

Parameters

  memAddr | Memory address associated with the SASStringBTreeNode_t to be freed.

## SASStringBTreePut()

__C__ int SASStringBTreePut | ( | SASStringBTree_t | btree,
|  | char * | key,
|  | void * | value
| ) |  |

Add a new element value with key key in the SAS B-Tree btree.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. The function holds a write lock over B-Tree btree. This function inserts the key and associated memory address value into the B-Tree. This B-Tree implementation does not allow duplicated key values.

Parameters

  btree | Handle to the SASStringBTree_t.
  key | Key to use as index for the value.
  value | Memory address to insert in the B-Tree.

Returns
  1 if the operation succeeds or 0 otherwise. For example if the key already exist in this B-Tree.

## SASStringBTreePut_nolock()

__C__ int SASStringBTreePut_nolock | ( | SASStringBTree_t | btree,
|  | char * | key,
|  | void * | value
| ) |  |

Add a new element value with key key in the SAS B-Tree btree.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. This function inserts the key and associated memory address value into the B-Tree. This B-Tree implementation does not allow duplicated key values.

This nolock form should only be used when the referenced SASStringBTree_t is known to be locked by the application or contained within a larger structure with a controlling lock.

Parameters

  btree | Handle to the SASStringBTree_t.
  key | Key to use as index for the value.
  value | Memory address to insert in the B-Tree.

Returns
  1 if the operation succeeds or 0 otherwise. For example if the key already exist in this B-Tree.

## SASStringBTreeRemove()

__C__ void * SASStringBTreeRemove | ( | SASStringBTree_t | btree,
|  | char * | key
| ) |  |

Remove the key key and its associated value from SAS B-Tree btree.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. The function holds a write lock over B-Tree btree. This function searches the B-Tree for a matching key and if found, removes the key and associates value from this B-Tree.

Note
  removing the key and associated value from the B-Tree does not remove or alter the data at that memory address. It only removes the associated between the and key and the address from this B-Tree.

Parameters

  btree | Handle to the SASStringBTree_t.
  key | Key value to be removed from this B-Tree.

Returns
  The address of the previous item or 0 if an error occurs.

## SASStringBTreeRemove_nolock()

__C__ void * SASStringBTreeRemove_nolock | ( | SASStringBTree_t | btree,
|  | char * | key
| ) |  |

Remove the key key and its associated value from SAS B-Tree btree.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. This function searches the B-Tree for a matching key and if found, removes the key and associates value from this B-Tree.

Note
  removing the key and associated value from the B-Tree does not remove or alter the data at that memory address. It only removes the associated between the and key and the address from this B-Tree.

This nolock form should only be used when the referenced SASStringBTree_t is known to be locked by the application or contained within a larger structure with a controlling lock.

Parameters

  btree | Handle to the SASStringBTree_t.
  key | Key value to be removed from this B-Tree.

Returns
  The address of the previous item or 0 if an error occurs.

## SASStringBTreeReplace()

__C__ void * SASStringBTreeReplace | ( | SASStringBTree_t | btree,
|  | char * | key,
|  | void * | value
| ) |  |

Replace the associated value of the element with key key in SAS B-Tree btree with the value value.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. The function holds a write lock over B-Tree btree. This function searches the B-Tree for a matching key and if found, replaces the associated memory address value with value, and returns the previous associated value.

Parameters

  btree | Handle to the SASStringBTree_t.
  key | Key to use as index for the value.
  value | Memory address to replace in the B-Tree.

Returns
  The address of the previous associated value for the matching key, or 0 if an error occurs.

## SASStringBTreeReplace_nolock()

__C__ void * SASStringBTreeReplace_nolock | ( | SASStringBTree_t | btree,
|  | char * | key,
|  | void * | value
| ) |  |

Replace the associated value of the element with key key in SAS B-Tree btree with the value value.

The sas_type_t must be SAS_RUNTIME_STRINGTREE. This function searches the B-Tree for a matching key and if found, replaces the associated memory address value with value, and returns the previous associated value.

This nolock form should only be used when the referenced SASStringBTree_t is known to be locked by the application or contained within a larger structure with a controlling lock.

Parameters

  btree | Handle to the SASStringBTree_t.
  key | Key to use as index for the value.
  value | Memory address to replace in the B-Tree.

Returns
  The address of the previous associated value for the matching key, or 0 if an error occurs.