Shared Address Space B-tree. More...

#include "sasstringbtreenode.h"

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);
       }
  }

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);

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

Typedef Documentation

typedef void* SASStringBTree_t

Handle to an instance of String B-tree.

The type is SAS_RUNTIME_STRINGBTREE

Function Documentation

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation