Home Building DHTML Scripting Using Diaperglu Documention Key Script Commands Reference C Library API Reference Handy References About License Contact Forth Draft Standard
C Functions dg_gethlistheaderarrayheader dg_querycreatehlistheaderarray dg_gethlistheader dg_freehlistmemory dg_allocatehlistmemory dg_newhlist dg_freehlist dg_linklasthlistchildelement dg_unlinkhlistchildelement dg_newhlistelement dg_freehlistelement dg_gethlistlastchildofparent dg_gethlistfirstchild dg_prunehlistelement dg_gethlistnextsibling dg_gethlistprevioussibling dg_gethlistelementparent dg_getshlistelementnom dg_getshlistelementvalue dg_sethlistelementvalue dg_getshlistelement dg_sortcomparehlistnom dg_dobinaryinsertsortstep dg_findsortedhlistchildsub dg_findsortedhlistchild dg_getshlistelementnamene dg_changehlistelementparent dg_getnumberofsortedchildren dg_getidofsortedhlistchildn dg_addnsamechartostring dg_hlisttodglumlstring dg_newunsortedhlistelement dg_callhlistchildren dg_callhlistchildrenbyn dg_packhlist dg_unpackhlist dg_namestringtovaluestring dg_namestringtovaluestringflag   C Structures Bufferhandle
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_gethlistheaderarrayheader
//
// C prototype:
//  void dg_gethlistheaderarrayheader(
//    Bufferhandle* pBHarrayhead,
//    Freeablelstringarrayheader* phlistheaderarrayheader,
//    UINT64 hlistheaderarrayheaderlength)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderarrayheaderlength  This needs to be set to the size of the
//                                        hlist header array's header structure, which
//                                        is also sizeof(Freeablelstringarrayheader).
//
// Outputs:
//  Freeablelstringarrayheader*          pointer to memory supplied by caller to hold
//    phlistheaderarrayheader             the hierarchical list header array's header
//
// Action:
//  Copies the hlist header array's header to the memory supplied by the caller.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_querycreatehlistheaderarray
//
// C prototype:
//  UINT64 dg_querycreatehlistheaderarray(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
// Outputs:
//  UINT64 return                        buffer id of the hierarchical list header array.
//
// Action:
//  If the hierarchical list header array does not exist, this routine creates it and
//   returns the buffer id of the hierarchical list header array.
//  If the hierarchical list header array already exists, this routine just returns the
//   buffer id of the hierarchical list header array.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_gethlistheader
//
// C prototype:
//  void dg_gethlistheader(
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    Hlistheader* phlistheader,
//    UINT64 hlistheaderlength)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 id of the hierarchical list
//
//  UINT64 hlistheaderlength             this needs to be set to the size of an hlist 
//                                        header, which is sizeof(Hlistheader)
//  
//
// Outputs:
//
//  Hlistheader* phlistheader            pointer to memory supplied by the caller to 
//                                        hold a copy of the hlist's header
//  
//
// Action:
//  If the hierarchical list hlistheaderid exists, this routine copies it's header to 
//   the memory at phlistheader.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_freehlistmemory
//
// C prototype:
//  void dg_freehlistmemory (
//    Bufferhandle* pBHarrayhead, 
//    struct Hlistheader* phlist)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  struct Hlistheader* phlist           pointer to a hierarchical list's header 
//                                        structure
//
//
// Outputs:
//  none
//
// Action:
//  Frees the memory buffers associated with the hierarchical list.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_allocatehlistmemory
//
// C prototype:
//  void dg_allocatehlistmemory (
//    Bufferhandle* pBHarrayhead, 
//    struct Hlistheader* phlist, 
//    UINT64 hlistlength)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistlength                   this needs to be set to the size of an hlist 
//                                        header which is sizeof(Hlistheader)
//
// Outputs:
//  struct Hlistheader* phlist           pointer to memory supplied by the caller to 
//                                        hold a hierarchical list's header structure
//
// Action:
//  Allocates the memory buffers needed for a hierarchical list and stores their 
//   buffer ids into the hierarchical list header structure supplied by the caller.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_newhlist
//
// C prototype:
//  UINT64 dg_newhlist (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
// Outputs:
//  UINT64 return                        hlist id of the new hierarchical list.
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
// Action:
//  Allocates the memory buffers needed for a hierarchical list and stores their 
//   buffer ids into the hierarchical list header structure supplied by the caller.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_freehlist
//
// C prototype:
//  void dg_freehlist (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array 
//                                        where the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list to free.
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
// Outputs:
//  none
//
// Action:
//  Free's the hierarchical list, 
//   which includes freeing the memory buffers used by the hierarchical list, 
//   and freeing the hierarchical list's header's lstring in the hierarchical list 
//   header array.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_linklasthlistchildelement
//
// C prototype:
//  void dg_linklasthlistchildelement (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 elementheaderid,
//    UINT64 parentelementheaderid)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which  
//                                        is used as the bufferhandle for the array 
//                                        where the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 elementheaderid               element id of the element to link to the 
//                                        parent
//                                         This is also the 0 based index of the 
//                                         element header in the hierarchical list's 
//                                         element header array.
//
//  UINT64 parentelementheaderid         element id of the parent element
//                                         This is also the 0 based index of the 
//                                         parent element header in the hierarchical 
//                                         list's element header array.
//
// Outputs:
//  none
//
// Action:
//  A parent element has two lists for keeping track of it's children. The first is 
//   a linked list of it's children in the order of when the children were linked to 
//   the parent. The newest child is the one the parent points to, then each child
//   points to it's next older sibling, it's next newer sibling, and back to it's 
//   parent. The oldest child's next older sibling is DG_ENDOFWORDLIST (-1)
//  The other list is a list of the children's element id's sorted in order of their 
//   name strings.
//
//  This routine adds the child to the first list which is the linked list of what
//   order the children were linked to this parent. This element becomes the newest 
//   child of the parent. This routine does NOT add this child to the parent's list 
//   of sorted children.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_unlinkhlistchildelement
//
// C prototype:
//  void dg_unlinkhlistchildelement (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 elementheaderid)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 elementheaderid               element id of the child to unlink from the 
//                                        parent
//                                         This is also the 0 based index of the 
//                                          element header in the hierarchical list's 
//                                          element header array.
//
// Outputs:
//  none
//
// Action:
//  A parent element has two lists for keeping track of it's children. The first is 
//   a linked list of it's children in the order of when the children were linked to 
//   the parent. The newest child is the one the parent points to, then each child 
//   points to it's next older sibling, it's next newer sibling, and back to it's 
//   parent.
//  The other list is a list of the children's element id's sorted in order of their 
//   name strings.
//
//  This routine removes the child from the first list, which is the linked list of 
//   what order the children were linked to this parent. 
//   This child's next older sibling becomes the newest child of the parent.
//   This routine does NOT remove this child from the parent's list of sorted children.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_newhlistelement
//
// C prototype:
//  UINT64 dg_newhlistelement (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistid,
//    UINT64 parentelementid, 
//    unsigned char* pname,
//    UINT64 namelength,
//    unsigned char* pvalue,
//    UINT64 valuelength)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistid                       hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 parentelementid               parent element id of the new element
//                                        The new element will be a child of this 
//                                         element
//                                        if parentelementid == DG_ENDOFLIST it 
//                                         means you are adding a root element
//                                        an hlist can have more than one root in 
//                                         it, it is the callers resposibility to
//                                         keep track of them
//                                        This is also the 0 based index of the 
//                                         element header in the hierarchical 
//                                         list's element header array.
//
//  unsigned char* pname                 pointer to the initial name string for the 
//                                        new element
//
//  UINT64 namelength                    length of the initial name string for the 
//                                        new element in bytes
//
//  unsigned char* pvalue                pointer to the initial value string for the 
//                                        new element
//
//  UINT64 valuelength                   length of the initial value string for the 
//                                        new element in bytes
//
// Outputs:
//  UINT64 return                        element id of the newly created element
//                                        This is also the 0 based index of the 
//                                        element header in the hierarchical list's 
//                                        element header array.
//
// Action:
//  A parent element has two lists for keeping track of it's children. The first is a 
//   linked list of it's children in the order of when the children were linked to 
//   the parent. The newest child is the one the parent points to, then each child 
//   points to it's next older sibling, it's next newer sibling, and back to it's
//   parent.
//  The other list is a list of the children's element id's sorted in order of their 
//   name strings.
//
//  This routine creates the new element as a child of the indicated parent element 
//   in the indicated hlist and sets the new element's initial name string and value 
//   string to a copy of the strings passed in. The element is also added to the 
//   parent's two lists of children, becoming the newest child of the parent in the 
//   process.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_freehlistelement
//
// C prototype:
//  void dg_freehlistelement (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 elementheaderid)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the  
//                                        hierarchical list's header in the hierarchical 
//                                        list header array
//
//  UINT64 elementheaderid               element id of the element to free
//                                        This is also the 0 based index of the element 
//                                        header in the hierarchical list's element 
//                                        header array.
//
// Outputs:
//  none
//
// Action:
//  If this element has a parent, this routine removes the element from it's parent
//    element's lists of children. This routine also frees the element, which means it 
//    frees the element's header. This routine should not be called if this element has 
//    any children since it will abandon any children this element has. Technically you 
//    have to call dg_prunehlistelement on this element first... I should change this 
//    routine to either give an error if there are children, or make this routine call 
//    dg_prunehlistelement first.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_gethlistlastchildofparent
//
// C prototype:
//  UINT64 dg_gethlistlastchildofparent (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 parentelementid)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the  
//                                        hierarchical list's header in the hierarchical 
//                                        list header array
//
//  UINT64 parentelementheaderid         element id of the parent element
//                                         This is also the 0 based index of the parent 
//                                         element header in the hierarchical list's 
//                                         element header array.
//
// Outputs:
//  UINT64 return                        the element id of the child most recently  
//                                        added to this parent. If this parent has 
//                                        no children, DG_ENDOFWORDLIST (-1) is 
//                                        returned
//
// Action:
//  Returns the element id of the child most recently added to this parent. If this 
//   parent has no child, DG_ENDOFWORDLIST (-1) is returned.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_gethlistfirstchild
//
// C prototype:
//  UINT64 dg_gethlistfirstchild (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 parentelementid)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the hierarchical 
//                                        list header array
//
//  UINT64 parentelementheaderid         element id of the parent element
//                                         This is also the 0 based index of the parent 
//                                         element header in the hierarchical list's 
//                                         element header array.
//
// Outputs:
//  UINT64 return                        the element id of the oldest child added to
//                                        parent. If this parent has no children,
//                                        this DG_ENDOFWORDLIST (-1) is returned
//
// Action:
//  Returns the element id of the first child added to this parent that is still a 
//   child of this parent and has not been freed. If this parent has no child, 
//   DG_ENDOFWORDLIST (-1) is returned.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_prunehlistelement
//
// C prototype:
//  void dg_prunehlistelement (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 elementheaderid)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the hierarchical 
//                                        list header array
//
//  UINT64 elementheaderid               element id of the element to prune
//                                        This is also the 0 based index of the element 
//                                        header in the hierarchical list's element 
//                                        header array.
//
// Outputs:
//  none
//
// Action:
//  Recursively frees all the descendents of this element. This routine does not 
//   free the element itself.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_gethlistnextsibling
//
// C prototype:
//  UINT64 dg_gethlistnextsibling (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 childelementid)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the hierarchical 
//                                        list header array
//
//  UINT64 childelementid                element id of the child element
//                                        This is also the 0 based index of the element 
//                                        header in the hierarchical list's element 
//                                        header array.
//
// Outputs:
//  UINT64 return                        the next older sibling of this child's parent
//
// Action:
//  Returns the next older sibling of this element's parent. This usually the one 
//   added to this element's parent just before this element was added. If there is no 
//   more older siblings, DG_ENDOFWORDLIST is returned.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_gethlistprevioussibling
//
// C prototype:
//  UINT64 dg_gethlistprevioussibling (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 childelementid)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical  list's header in the  
//                                        hierarchical list header array
//
//  UINT64 childelementid                element id of the child element
//                                        This is also the 0 based index of the element 
//                                        header in the hierarchical list's element 
//                                        header array.
//
// Outputs:
//  UINT64 return                        the next older sibling of this child's parent
//
// Action:
//  Returns the next newer sibling of this element's parent. This usually the one 
//   added to this element's parent just after this element was added. If there is no 
//   more newer siblings, DG_ENDOFWORDLIST is returned.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_gethlistelementparent
//
// C prototype:
//  UINT64 dg_gethlistelementparent (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 elementid)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 elementid                     element id of the child element
//                                        This is also the 0 based index of the element 
//                                        header in the hierarchical list's element 
//                                        header array.
//
// Outputs:
//  UINT64 return                        the parent element id of this element
//
// Action:
//  Returns the parent element id of this element. If there is no parent element,
//   which means this is a root element, DG_ENDOFWORDLIST is returned.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_getshlistelementnom
//
// C prototype:
//  unsigned char* dg_getshlistelementnom (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 elementid,
//    UINT64* pnamelength)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 elementid                     element id of the element
//                                        This is also the 0 based index of the 
//                                        element header in the hierarchical list's 
//                                        element header array.
//
// Outputs:
//  unsigned char* return                pointer to the element's name string
//
//  UINT64* pnamelength                  pointer to a UINT64 supplied by the caller to 
//                                        hold the length of the element's name string
//
// Action:
//  Returns the pointer to and length of the element's name string.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_getshlistelementvalue
//
// C prototype:
//  unsigned char* dg_getshlistelementvalue (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 elementid,
//    UINT64* pvaluelength)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 elementid                     element id of the element
//                                        This is also the 0 based index of the element 
//                                        header in the hierarchical list's element 
//                                        header array.
//
// Outputs:
//  unsigned char* return                pointer to the element's value string
//
//  UINT64* pvaluelength                 pointer to a UINT64 supplied by the caller to 
//                                        hold the length of the element's value string
//
// Action:
//  Returns the pointer to and length of the element's value string.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_sethlistelementvalue
//
// C prototype:
//  void dg_sethlistelementvalue (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 elementid,
//    unsigned char* pvalue,
//    UINT64 valuelength)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical  list's header in the 
//                                        hierarchical list header array
//
//  UINT64 elementid                     element id of the element
//                                        This is also the 0 based index of the element 
//                                        header in the hierarchical list's element 
//                                        header array.
//
//  unsigned char* pvalue                pointer to the new value string
//
//  UINT64 valuelength                   length of the new value string
//
// Outputs:
//  none
//
// Action:
//  Replaces the element's value string with a copy of the value string passed in.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_getshlistelement
//
// C prototype:
//  void dg_getshlistelement (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 elementid,
//    unsigned char** ppname,
//    UINT64* pnamelength,
//    unsigned char** ppvalue,
//    UINT64* pvaluelength)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 elementid                     element id of the element
//                                        This is also the 0 based index of the element
//                                        header in the hierarchical list's element 
//                                        header array.
//
// Outputs:
//  unsigned char** ppname               pointer to memory supplied by the caller to  
//                                        hold apointer to the element's name string
//
//  UINT64* pnamelength                  pointer to memory supplied by the caller to 
//                                        hold the length of the element's name string
//
//  unsigned char** ppvalue              pointer to memory supplied by the caller to 
//                                        hold a pointer to the element's value string
//
//  UINT64* pvaluelength                 pointer to memory supplied by the caller to 
//                                        hold the length of the element's value string
//
// Action:
//  Returns pointers to and lengths of the elements name and value strings.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_sortcomparehlistnom
//
// C prototype:
//  INT64 dg_sortcomparehlistnom(
//    Bufferhandle* pBHarrayhead,
//    void* pcomparedata,
//    UINT64 comparedatalength,
//    UINT64 keyofmidrangevalue)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  void* pcomparedata                   pointer to a custom structure holding the data
//                                        needed for this compare routine.
//
//  UINT64 comparedatalength             length of the custom structure holding the data
//                                        needed for this compare routine.
//
//  UINT64 keyofmidrangevalue            index in hlist parent element's list of sorted
//                                        child ids of the child element to compare
//  
// Outputs:
//  INT64 return                         result of the compare
//                                        0 means the name strings matched
//                                        1 means the name string you are checking is 
//                                         greater than the one represented by 
//                                         keyofmidrangevalue 
//                                        -1 means the name string you are checking is 
//                                         less than the one represented by 
//                                         keyofmidrangevalue
//
// Action:
//  Uses the compare data structure passed in and the key of mid range value to 
//   compare a passed in name string against a name string from the sorted list of 
//   child elements.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_dobinaryinsertsortstep
//
// C prototype:
//  UINT64 dg_dobinaryinsertsortstep (
//    Bufferhandle* pBHarrayhead,
//    unsigned char* psortedkeyslstring,
//    UINT64 sortedkeyslength,
//    INT64 (*pcompareroutine)(Bufferhandle*, void*, UINT64, UINT64),
//    void* pcomparedata,
//    UINT64 comparedatalength,
//    UINT64* pstartindex,
//    UINT64* pendindex,
//    UINT64* ptofindbeforerangeflag,
//    UINT64* ploopdoneflag)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  unsigned char* psortedkeyslstring    pointer to an hlist parent element's list of 
//                                        child element indexes sorted by name string
//
//  UINT64 sortedkeyslength              wow this isn't used, I'll remove it. I could 
//                                        use it to make sure the indexes aren't out 
//                                        of array
//
// INT64 (*pcompareroutine)(Bufferhandle*, void*, UINT64, UINT64)
//                                       function pointer to the custom compare routine 
//                                        for this sort
//
//  void* pcomparedata                   pointer to a custom structure holding the data
//                                        needed for this compare routine.
//
//  UINT64 comparedatalength             length of the custom structure holding the data
//                                        needed for this compare routine.
//  
// Outputs:
//  UINT64* pstartindex                  pointer to the start index of the range to  
//                                        check in the parent's list of child element  
//                                        ids sorted by name string. This value may be 
//                                        changed by this function. 
//
//  UINT64* pendindex                    pointer to the end index of the range to check 
//                                        in the parent's list of child element ids 
//                                        sorted by name string. This value may be 
//                                        changed by this function. 
//
//  UINT64* ptofindbeforerangeflag       pointer to a flag which indicates when FORTH_TRUE
//                                        that all the elements in the range to check are  
//                                        greater than all elements before the range. This
//                                        value may be changed by this function.
//
//  UINT64* ploopdoneflag                pointer to a flag which indicates when FORTH_TRUE
//                                        that there are no more elements to check in the
//                                        range.           
//
// Action:
//  This routine does a step in a binary insert sort using the compare data and compare 
//   routine passed in. In freshman year of college, my professor called this 
//   algorithm a 'shell sort' so you may still see some mislabelings in the code.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_findsortedhlistchildsub
//
// C prototype:
//  UINT64 dg_findsortedhlistchildsub (
//   Bufferhandle* pBHarrayhead,
//   unsigned char* pname,
//   UINT64 namelength,  
//   UINT64 sortedkeyslstringlength,
//   unsigned char* psortedkeyslstring,
//   UINT64* pnamelstringoffsetbuffer,
//   unsigned char* pnamelstringstringbuffer,
//   UINT64* pindexofkeyaftermatch, 
//   UINT64* pkey)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  unsigned char* pname                 pointer to the name string to find
//
//  UINT64 namelength                    length of name string to find in bytes
//
//  UINT64 sortedkeyslstringlength       length of sorted keys lstring in bytes
//
//  unsigned char* psortedkeyslstring    pointer to sorted keys lstring
//
//  UINT64* pnamelstringoffsetbuffer     pointer to name lstring offset buffer
//
//  unsigned char* pnamelstringstringbuffer pointer to name lstring string buffer
//
// Outputs:
//  UINT64* pindexofkeyaftermatch        pointer to memory supplied by the caller that 
//                                        will hold the 0 based index of the child 
//                                        element in the parent's list of child elements 
//                                        sorted by name string of the first child 
//                                        having a greater name string.
//                                       
//
//  UINT64* pkey                         pointer to memory supplied by the caller that 
//                                        will hold the element id of the child element 
//                                        at the index ONE BEFORE the one at 
//                                        *pindexofkeyaftermatch.
//                                        In the event the compare flag returned is 0,
//                                        this holds the element id of the most 
//                                        recently added child with a matching name 
//                                        string.
//                                        In the event *pindexofkeyaftermatch is 0, 
//                                        pkey holds DG_ENDOFWORDLIST
//
// Action:
//  This routine does a binary search of the list of children sorted by name string 
//   for the first child with a name string greater than the one passed in. I did it 
//   this way so that the in the event multiple elements with the same name string 
//   are added, the most recently added will be the one found. This is to meet the  
//   FORTH requirement that new words with the same name are found before older words.
//  I added this routine to speed up the call hlist children function, so that it 
//   wouldn't have to get the pointers to the arrays for every child element.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_findsortedhlistchild
//
// C prototype:
//  UINT64 dg_findsortedhlistchild (
//   Bufferhandle* pBHarrayhead,
//   unsigned char* pname,
//   UINT64 namelength,  
//   UINT64 hlistheaderid, 
//   UINT64 parentelementid,      
//   UINT64* pindexofkeyaftermatch, 
//   UINT64* pkey)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  unsigned char* pname                 pointer to the name string to find
//
//  UINT64 namelength                    length of name string to find
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the  
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 parentelementid               element id of the parent element
//                                        This is also the 0 based index of the 
//                                        element header in the hierarchical list's 
//                                        element header array.
//  
// Outputs:
//  UINT64 return                        standard forth compare flag
//                                         0 if name is found
//                                         should be 1 if not found or empty list
//                                         -1 should not be possible
//                                         should be -2 if error
//                                         
//                                       
//  UINT64* pindexofkeyaftermatch        pointer to memory supplied by the caller 
//                                        that will hold the 0 based index of the child 
//                                        element in the parent's list of child 
//                                        elements sorted by name string of the first 
//                                        child having a greater name string.
//                                       
//
//  UINT64* pkey                         pointer to memory supplied by the caller that 
//                                        will hold the element id of the child 
//                                        element at the index ONE BEFORE the one at
//                                        *pindexofkeyaftermatch.
//                                        In the event the compare flag returned is 0,
//                                        this holds the element id of the most 
//                                        recently added child with a matching name 
//                                        string.
//                                        In the event *pindexofkeyaftermatch is 0, 
//                                        pkey holds DG_ENDOFWORDLIST
//
// Action:
//  This routine does a binary search of the list of children sorted by name string 
//   for the first child with a name string greater than the one passed in. I did it 
//   this way so that the in the event multiple elements with the same name string 
//   are added, the most recently added will be the one found. This is to meet the  
//   FORTH requirement that new words with the same name are found before older words.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_getshlistelementnamene
//
// C prototype:
//  const char* dg_getshlistelementnamene (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 elementid,
//    unsigned char** ppname,
//    UINT64* pnamelength)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the  
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 elementid                     element id of the element
//                                        This is also the 0 based index of the element 
//                                        header in the hierarchical list's element 
//                                        header array.
//
// Outputs:
//  const char* return                   dg_success if there is no error doing this 
//                                        routing otherwise an error code is returned 
//                                        which is usually dg_errorinsubroutine unless 
//                                        the error was from writing to the memory at 
//                                        ppname.
//                                       
//  unsigned char** ppname               pointer to a pointer supplied by the caller 
//                                        to hold a pointer to the element's name string
//
//  UINT64* pnamelength                  pointer to a UINT64 supplied by the caller to 
//                                        hold the length of the element's name string
//
// Action:
//  Returns the pointer to and length of the element's name string. If any errors occur, 
//   they are not pushed to the error stack and an error flag is returned instead. This 
//   is so this routine can be used by the words that display the contents of the error 
//   stack without adding to the  error stack.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_changehlistelementparent
//
// C prototype:
//  void dg_changehlistelementparent (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistid,
//    UINT64 elementid,
//    UINT64 newparentelementid)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistid                       hlist id of the hierarchical list
//                                        This is also the 0 based index of the  
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 elementid                     element id of the element to be moved to a 
//                                        new parent. This is also the 0 based index of 
//                                        the element header in the hierarchical list's 
//                                        element header array.
//
//  UINT64 newparentelementid            element id of the new parent
//                                        This is also the 0 based index of the element
//                                        header in the hierarchical list's element 
//                                        header array.
//  
// Outputs:
//  none
//
// Action:
//  Removes the element from it's current parent's child lists and adds the element 
//   to the child lists of the new parent. This element becomes the newest child of 
//   the new parent and is sorted into the newest parent's sorted list of children by 
//   it's name string.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_getnumberofsortedchildren
//
// C prototype:
//  UINT64 dg_getnumberofsortedchildren(
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 parentelementid)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistid                       hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 parentelementid               element id of the parent
//                                        This is also the 0 based index of the element 
//                                        header in the hierarchical list's element 
//                                        header array.
//  
// Outputs:
//  UINT64 return                        number of children in the parent's list of 
//                                        sorted children
//
// Action:
//  Returns the number of child element ids in the parent element's list of sorted 
//   children. If everything is working properly and you didn't manually alter the 
//   list or tried to free an element without pruning it's children first, this 
//   should also be the number of children in the parent's linked list of what order 
//   the children were added to the parent.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_getidofsortedhlistchildn
//
// C prototype:
//  UINT64 dg_getidofsortedhlistchildn(
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistheaderid,
//    UINT64 parentelementid,
//    UINT64 sortkeyindex)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistheaderid                 hlist id of the hierarchical list
//                                        This is also the 0 based index of the  
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 parentelementid               element id of the parent
//                                        This is also the 0 based index of the 
//                                        element header in the hierarchical list's 
//                                        element header array.
//
//  UINT64 sortkeyindex                  0 based index of a child element's id in 
//                                        the parent's list of children sorted by 
//                                        name string. This sorted list is stored 
//                                        in an array.
//  
// Outputs:
//  UINT64 return                        element id of the child at the sortkeyindex 
//                                        in parent's list of children sorted by 
//                                        name string.
//
// Action:
//  The parent element maintains a list it's children sorted by name string. This 
//   routine returns element id of the nth child in this list, where n is 
//   sortkeyindex.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_addnsamechartostring
//
// C prototype:
//  void dg_addnsamechartostring (
//    Bufferhandle* pBHarrayhead,
//    UINT64 n,
//    unsigned char c)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 n                             the number of characters to push onto the end 
//                                        of top string on the string stack
//
//  unsigned char c                      the character to use to push onto the end 
//                                        of the the string stack
// 
// Outputs:
//  none
//
// Action:
//  This routine pushes n copies of character c onto the end of the string stack.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_hlisttodglumlstring
//
// C prototype:
//  void dg_hlisttoxmlstring (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistid,
//    UINT64 rootelementid,
//    UINT64 indentationstepsize,
//    UINT64 currentindentationlevel)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistid                       hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical  list's header in the 
//                                        hierarchical list header array
//
//  UINT64 parentelementid               element id of the top parent element for the 
//                                        conversion. This is also the 0 based index of 
//                                        the element header in the hierarchical list's 
//                                        element header array.
//
//  UINT64 indentationstepsize           the number of spaces to indent each nesting 
//                                        level
//
//  UINT64 currentindentationlevel       the beginning indentation level of the top 
//                                        parent this is so the routine can be used 
//                                        for recursion
// 
// Outputs:
//  none
//
// Action:
//  This routine converts an hierarchical list starting at the designated root element 
//   and pushes it onto the end of the top string on the string stack. The name and 
//   value strings of each element are url encoded during this conversion. 
//   The format looks like this:
//   <topname$>topvalue$
//     <firstchildname$>firstchildvalue$
//       <firstsubchildname$>firstsubchildvalue$</firstsubchildname$>
//     </firstchildname$>
//     <secondchildname$>secondchildvalue$</secondchildname$>
//   </topname$>
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_newunsortedhlistelement
//
// C prototype:
//  UINT64 dg_newunsortedhlistelement (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistid,
//    Hlistheader myhlistheader,
//    UINT64 parentelementid, 
//    unsigned char* pname,
//    UINT64 namelength,
//    unsigned char* pvalue,
//    UINT64 valuelength,
//    UINT64 previouselementid,
//    UINT64 nextelementid)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistid                       hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the hierarchical 
//                                        list header array
//
//  Hlistheader myhlistheader            a copy of the hierarchical list header
//
//  UINT64 parentelementid               element id of this new element's parent
//                                        DG_ENDOFWORDLIST (-1) means this element is a 
//                                        root element. This is also the 0 based index 
//                                        of the element header in the hierarchical 
//                                        list's element header array.         
//
//  unsigned char* pname                 pointer to the string to use for the new 
//                                        element's name string
//
//  UINT64 namelength                    length of the name string
//
//  unsigned char* pvalue                pointer to the string to use for the new 
//                                        element's value string
//
//  UINT64 valuelength                   length of the value string
// 
//  UINT64 previouselementid             element id of what will be this child's next  
//                                        more recently added sibling
//                                        DG_ENDOFWORDLIST means this child will be 
//                                        the most recently added sibling
//                                        This is also the 0 based index of the element 
//                                        header in the hierarchical list's element 
//                                        header array.
//  
//  UINT64 nextelementid                 element id of what will be the child added just 
//                                        previous to this one
//                                        DG_ENDOFWORDLIST means this child will have 
//                                        been the first child added
//                                        This is also the 0 based index of the element 
//                                        header in the hierarchical list's element 
//                                        header array.
//
// Outputs:
//  UINT64 return                        element id of newly added child
//                                        This is also the 0 based index of the element 
//                                        header in the hierarchical list's element 
//                                        header array.
//
// Action:
//  This routine adds a child element to a parent element in a hierarchical list, but 
//   only adds the child to the parent's linked list of when children were added. 
//   This routine does not add the child to the list of sorted children.
//   The caller is responsible for making sure the linked list will be accurate after 
//    this child is added.
//   This routine is mainly for use during the diaperglu script initialization and 
//    allows diaperglu to quickly initialize a wordlist using a presorted list of words.
//   Also, free element ids are ignored during this and the new element is added to 
//    the end of the array.
//   This way successive calls to this function can guarantee element ids that go 
//    up by 1 each time, which is useful for calculating what previous element id 
//    and next element id should be.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_callhlistchildren
//
// C prototype:
//  void dg_callhlistchildren(
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistid,
//    UINT64 parentelementid,
//    UINT64 fsortedkeyslstringlength,
//    unsigned char* pfsortedkeyslstring,
//    UINT64* pfnamelstringoffsetbuffer,
//    unsigned char* pfnamelstringstringbuffer,
//    void (**pfunctions)(
//     Bufferhandle*, 
//     UINT64, 
//     UINT64, 
//     unsigned char*, 
//     UINT64, Hlistheader*))
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistid                       hlist id of the hierarchical list containing 
//                                        function names to do. This is also the 0 based 
//                                        index of the hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 parentelementid               parent element id in hlist containing function 
//                                        names to do
//
//  UINT64 fsortedkeyslstringlength      length in bytes of lstring array containing the 
//                                        sorted keys
//
//  unsigned char* pfsortedkeyslstring   pointer to lstring array containing the sorted 
//                                        keys. the 'keys' are UINT64 indexes into the 
//                                        function name array and the function pointer 
//                                        array
//
//  UINT64* pfnamelstringoffsetbuffer    pointer to the function names lstring array 
//                                        offset buffer
//
//  unsigned char* pfnamelstringstringbuffer  pointer to the function names lstring 
//                                        array string buffer
//
//  void (**pfunctions)(                 function pointer array containing functions 
//                                        to call the functions will be passed these 
//                                        parementers but do not have to use them
//    Bufferhandle*,                       pBHarrayhead
//    UINT64,                              hlistid
//    UINT64,                              parentelementid
//    unsigned char*,                      pparentvalue
//    UINT64,                              parentvaluelength
//    Hlistheader*))                       pointer to hlistid's hlist header
//
//
// Outputs:
//  none
//
// Action:
//  This routine goes through each child element in the order they were linked to the
//   parent in the hlist and finds the child's name string in the sorted function name
//   array. Then the 'key' of the found function name is used as an index into the
//   function pointer array to call the indexed function. So, the oldest child's 
//   indexed function is called first, then the next oldest, and so on with the 
//   newest child's function being called last.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_callhlistchildrenbyn
//
// C prototype:
//  void dg_callhlistchildrenbyn(
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistid,
//    UINT64 parentelementid,
//    UINT64 maxnumberoffunctions,
//    void (**pfunctions)(
//     Bufferhandle*, 
//     UINT64, 
//     UINT64, 
//     unsigned char*, 
//     UINT64, Hlistheader*))
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistid                       hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 parentelementid               parent element id in hlist
//
//  UINT64 maxnumberoffunctions          number of functions in the function array
//
//  void (**pfunctions)(                 function pointer array containing functions 
//                                        to call the functions will be passed these 
//                                        parementers but do not have to use them
//    Bufferhandle*,                       pBHarrayhead
//    UINT64,                              hlistid
//    UINT64,                              parentelementid
//    unsigned char*,                      pparentvalue
//    UINT64,                              parentvaluelength
//    Hlistheader*))                       pointer to hlistid's hlist header
//
//
// Outputs:
//  none
//
// Action:
//  This routine goes through each child element in the order they were linked to the
//   parent in the hlist and uses the child's name string as a UINT64 index into the
//   function pointer array to call the indexed function. So, the oldest child's 
//   indexed function is called first, then the next oldest, and so on with the 
//   newest child's function being called last.
//
// Note:
//  dg_callhlistchildrenbyn should be faster than dg_callhlistchildrenname because
//  dg_callhlistchildrenbyn does not have to find the index of the function name.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_packhlist
//
// C prototype:
//  UINT64 dg_packhlist (
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistid)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistid                       hlist id of the hierarchical list
//                                        This is also the 0 based index of the 
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//
// Outputs:
//  UINT64 return                        buffer id of a buffer containing the packed 
//                                        hlist
//
// Action:
//  This routine packs an hlist into one new buffer.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_unpackhlist
//
// C prototype:
//  UINT64 dg_unpackhlist (
//    Bufferhandle* pBHarrayhead,
//    UINT64 packedbufferid)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 packedhlistbufferid           buffer id of buffer holding the packed hlist
//
//
// Outputs:
//  UINT64 return                        hlist id of the unpacked hlist
//
// Action:
//  This routine unpacks an hlist from a buffer that holds a packed hlist.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_namestringtovaluestring
//
// C prototype:
//  unsigned char* dg_namestringtovaluestring(
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistid,
//    UINT64 elementid,
//    unsigned char* pname,
//    UINT64 namelength,
//    UINT64* pvaluelength)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistid                       hlist id of the hierarchical list
//                                        This is also the 0 based index of the  
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 elementid                     parent element id of the element in the 
//                                        hierarchical list. This is also the 0 based 
//                                        index of the element's name and value 
//                                        strings in the hlist's lstring arrays'
//
//  unsigned char*                       pointer to the name string of the child 
//                                        element to find under the parent element 
//                                        id in the hierarchical list
//
//  UINT64 namelength                    length of the name string of the child element 
//                                        to find under the parent element id in the 
//                                        hierarchical list
//
// Outputs:
//  UINT64* pvaluelength                 length of the value string if name string was 
//                                        found; 0 if name string was not found or
//                                        an error happened
//
//  unsigned char* return                pointer to the value string if name string 
//                                        was found
//                                        badbufferhandle (-1) if name string not 
//                                         found
//                                        badbufferhandle (-1) if an error happened
//
// Action:
//  This routine unpacks an hlist from a buffer that holds a packed hlist.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_namestringtovaluestringflag
//
// C prototype:
//  unsigned char* dg_namestringtovaluestringflag(
//    Bufferhandle* pBHarrayhead,
//    UINT64 hlistid,
//    UINT64 elementid,
//    unsigned char* pname,
//    UINT64 namelength,
//    UINT64* pvaluelength,
//    UINT64* pwherefoundflag)
//
// Inputs:
//  Bufferhandle* pBHarrayhead           pointer to a Bufferhandle structure which is 
//                                        used as the bufferhandle for the array where
//                                        the other bufferhandles are stored.
//
//  UINT64 hlistid                       hlist id of the hierarchical list
//                                        This is also the 0 based index of the  
//                                        hierarchical list's header in the 
//                                        hierarchical list header array
//
//  UINT64 elementid                     parent element id of the element in the 
//                                        hierarchical list. This is also the 0 based 
//                                        index of the element's name and value 
//                                        strings in the hlist's lstring arrays'
//
//  unsigned char*                       pointer to the name string of the child 
//                                        element to find under the parent element 
//                                        id in the hierarchical list
//
//  UINT64 namelength                    length of the name string of the child element 
//                                        to find under the parent element id in the 
//                                        hierarchical list
//
// Outputs:
//  UINT64* pvaluelength                 length of the value string if name string was 
//                                        found; 0 if name string was not found or
//                                        an error happened
//
// Outputs:
//  UINT64* pwherefoundflag              0 if name string was found moo
//
//  unsigned char* return                pointer to the value string if name string 
//                                        was found
//                                        badbufferhandle (-1) if name string not 
//                                         found
//                                        badbufferhandle (-1) if an error happened
//
// Action:
//  This routine unpacks an hlist from a buffer that holds a packed hlist.
//
// Failure cases:
// 
// //////////////////////////////////////////////////////////////////////////////////////