home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / dos / diverses / text_cla / memlib.man < prev    next >
Encoding:
Text File  |  1992-05-12  |  24.6 KB  |  1,239 lines
  1. NAME
  2.     MemHepDeque - retrieves an element from the heap
  3.  
  4. SYNOPSIS
  5.  
  6.     #include <memlib.h>
  7.  
  8.     SHORT APIENTRY
  9.     MemHepDeque(psHeap,psPriority,ppvData)
  10.     HEAP_P psHeap;
  11.     PSHORT psPriority;
  12.     PVOID * ppvData;
  13.  
  14. DESCRIPTION
  15.  
  16.     The priority and pvData from psHeap -> psHeapData[0] are
  17.     returned.  The heap is adjusted as necessary after the
  18.     call.
  19.  
  20.     HEAP_P  psHeap;       /* main heap structure */
  21.     PVOID   pvData;    /* for MemHepDeq() */
  22.     SHORT   sPriority; /* for MemHepDeq() */
  23.  
  24.     C_STATUS = MemHepInit(&psHeap,10);  /* init for 10 members */
  25.     
  26.     C_STATUS = MemHepEnq(psHeap, 7, ptrToData);  /* prio = 7 */
  27.  
  28.     C_STATUS = MemHepDeq(psHeap, &sPriority, &pvData);
  29.  
  30.  
  31. RESOURCE NAME
  32.  
  33.     MEMLIB.LIB
  34.  
  35. DIAGNOSTICS
  36.  
  37.     C_OK       = element returned
  38.     C_NOTOK = heap empty
  39.  
  40.  
  41. NAME
  42.     MemHepDown - adjusts a heap after a deque
  43.  
  44. SYNOPSIS
  45.  
  46.     #include <memlib.h>
  47.  
  48.     SHORT APIENTRY
  49.     MemHepDown(psHeap, sRoot)
  50.     HEAP_P psHeap;
  51.     SHORT sRoot;
  52.  
  53. DESCRIPTION
  54.  
  55.     Adjusts heap psHeap starting from sRoot.  This routine is
  56.     called by MemHepDeque() and there is not reason to call it
  57.     in your application.
  58.       
  59. RESOURCE NAME
  60.  
  61.     MEMLIB.LIB
  62.  
  63. DIAGNOSTICS
  64.  
  65.     C_OK       - always returned
  66.  
  67.  
  68. NAME
  69.     MemHepEnque - adds an element and its priority to a heap
  70.  
  71. SYNOPSIS
  72.  
  73.     #include <memlib.h>
  74.  
  75.     SHORT APIENTRY
  76.     MemHepEnque(psHeap,sPriority,pvData)
  77.     HEAP_P psHeap;
  78.     SHORT  sPriority;
  79.     PVOID  pvData;
  80.  
  81. DESCRIPTION
  82.  
  83.     Adds pvData (pointer) with sPriority to heap in psHeap.
  84.       
  85. RESOURCE NAME
  86.  
  87.     MEMLIB.LIB
  88.  
  89. DIAGNOSTICS
  90.  
  91.     C_OK       = element added
  92.     C_NOTOK = element not added, heap full
  93.  
  94. NAME
  95.     MemHepInit - initialize a heap before use
  96.  
  97. SYNOPSIS
  98.  
  99.     #include <memlib.h>
  100.  
  101.     SHORT APIENTRY
  102.     MemHepInit(ppsHeap, sNumElms)
  103.     HEAP_PP  ppsHeap;
  104.     SHORT    sNumElms;
  105.  
  106. DESCRIPTION
  107.  
  108.     Initializes a heap through (*ppsHeap) to have sNumElms elements.
  109.     
  110.     The heap is implemented in MemHep*** functions by using a header
  111.     structure (HEAP_T) which contains a pointer to an array of
  112.     data structures (HEAP_DATA_T).   MemHepInit() must be called
  113.     prior to any of the other MemHep*** functions.
  114.  
  115.     HEAP_P  psHeap;       /* main heap structure */
  116.     PVOID   pvData;    /* for MemHepDeq() */
  117.     SHORT   sPriority; /* for MemHepDeq() */
  118.  
  119.     C_STATUS = MemHepInit(&psHeap,10);  /* init for 10 members */
  120.     
  121.     C_STATUS = MemHepEnq(psHeap, 7, ptrToData);  /* prio = 7 */
  122.  
  123.     C_STATUS = MemHepDeq(psHeap, &sPriority, &pvData);
  124.  
  125.  
  126. RESOURCE NAME
  127.  
  128.     MEMLIB.LIB
  129.  
  130. DIAGNOSTICS
  131.  
  132.     C_OK       - always returned
  133.  
  134.  
  135. NAME
  136.     MemHepSwap - swaps two HEAP_DATA_T elements
  137.  
  138. SYNOPSIS
  139.  
  140.     #include <memlib.h>
  141.  
  142.     SHORT APIENTRY
  143.     MemHepSwap(psHeap1,psHeap2)
  144.     HEAP_DATA_P  psHeap1;
  145.     HEAP_DATA_P  psHeap2;
  146.  
  147. DESCRIPTION
  148.  
  149.     Uses memcpy() to swap two HEAP_DATA_T elements.
  150.       
  151. RESOURCE NAME
  152.  
  153.     MEMLIB.LIB
  154.  
  155. DIAGNOSTICS
  156.  
  157.     C_OK       - always returned
  158.  
  159.  
  160. NAME
  161.     MemHepUp - adjusts a heap after a Enque
  162.  
  163. SYNOPSIS
  164.  
  165.     #include <memlib.h>
  166.  
  167.     SHORT APIENTRY
  168.     MemHepUp(psHeap)
  169.     HEAP_P  psHeap;
  170.  
  171. DESCRIPTION
  172.  
  173.     Adjuts a heap through psHeap after a MemHepEnque() call.
  174.  
  175.     This is an MemHep*** internal function and there should
  176.     not be any reason to call this from your program.
  177.       
  178. RESOURCE NAME
  179.  
  180.     MEMLIB.LIB
  181.  
  182. DIAGNOSTICS
  183.  
  184.     C_OK       - always returned
  185.  
  186.  
  187. NAME
  188.     MemHepVacateHeap - removes all entries from a heap.
  189.  
  190. SYNOPSIS
  191.  
  192.     #include <memlib.h>
  193.  
  194.     SHORT APIENTRY
  195.     MemHepVacateHeap(ppsHeap,fFreeData)
  196.     HEAP_PP  ppsHeap;
  197.     BOOL     fFreeData;
  198.  
  199. DESCRIPTION
  200.  
  201.     Typically used when all done with a heap.   All alloc'ed
  202.     memory via (*ppsHeap) is free()'ed.  If fFreeData is 
  203.     C_TRUE, each HEAP_DATA_T will be checked and if
  204.     the -> pvData pointer is not NULL, it will free() on
  205.     the -> pvData.
  206.       
  207.     HEAP_P  psHeap;       /* main heap structure */
  208.     PVOID   pvData;    /* for MemHepDeq() */
  209.     SHORT   sPriority; /* for MemHepDeq() */
  210.  
  211.     /*
  212.     **  Create heap, init for 10 elements
  213.     */
  214.  
  215.     C_STATUS = MemHepInit(&psHeap,10); 
  216.     
  217.     C_STATUS = MemHepEnq(psHeap, 7, ptrToData);  /* prio = 7 */
  218.  
  219.     C_STATUS = MemHepDeq(psHeap, &sPriority, &pvData);
  220.  
  221.     C_STATUS = MemHepVacateHeap(&psHeap, C_TRUE); /* remove heap */
  222.  
  223.  
  224. RESOURCE NAME
  225.  
  226.     MEMLIB.LIB
  227.  
  228. DIAGNOSTICS
  229.  
  230.     C_OK       - always returned
  231.  
  232.  
  233. NAME
  234.     MemLstAddAfterMember - adds a member after another member in a list.
  235.  
  236. SYNOPSIS
  237.  
  238.     #include <memlib.h>
  239.  
  240.     SHORT APIENTRY
  241.     MemLstAddAfterMember(psPrev, psNewMember)
  242.     LLIST_P  psPrev;
  243.     LLIST_P  psNewMember;
  244.  
  245. DESCRIPTION
  246.  
  247.     Inserts psNewMember into the linked-list just after psPrev member.
  248.  
  249.     Element psNewMember must have already been allocated via 
  250.     MemLstAllocMember().
  251.  
  252.     The link list head pointer is not reset here because we assume 
  253.     add afters will never come BEFORE the head pointer.
  254.       
  255. RESOURCE NAME
  256.  
  257.     MEMLIB.LIB
  258.  
  259. DIAGNOSTICS
  260.  
  261.     C_OK       - always returned
  262.  
  263. NAME
  264.     MemLstAddBeforeMember - adds a member before another member in a list.
  265.  
  266. SYNOPSIS
  267.  
  268.     #include <memlib.h>
  269.  
  270.     SHORT APIENTRY
  271.     MemLstAddBeforeMember(psListRoot,psPrev,psNewMember,ppsRetMember)
  272.     LLIST_P psListRoot;
  273.     LLIST_P psPrev;
  274.     LLIST_P psNewMember;
  275.     LLIST_PP ppsRetMember;
  276.  
  277. DESCRIPTION
  278.  
  279.     Inserts psNewMember into the linked-list just before psPrev member.
  280.  
  281.     Element psNewMember must have already been allocated via 
  282.     MemLstAllocMember().
  283.  
  284.     The link list head pointer may be modified so it is passed in via
  285.         psListRoot and returned via ppsRetMember;
  286.  
  287.     C_STATUS = MemLstAddBeforeMember(psListRoot,
  288.                        psPrev,
  289.                        psNewMember,
  290.                        &psListRoot);
  291.  
  292. RESOURCE NAME
  293.  
  294.     MEMLIB.LIB
  295.  
  296. DIAGNOSTICS
  297.  
  298.     C_OK       - always returned
  299.  
  300.  
  301. NAME
  302.     MemLstAllocMember - allocates a new list member.
  303.  
  304. SYNOPSIS
  305.  
  306.     #include <memlib.h>
  307.  
  308.     SHORT APIENTRY
  309.     MemLstAllocMember(ppsRetMember)
  310.     LLIST_PP  ppsRetMember;
  311.  
  312. DESCRIPTION
  313.  
  314.     Allocates a new list member.
  315.  
  316.     All MemLst*** functions use the doubly-linked list structure:
  317.  
  318.     struct LLIST_S
  319.     {
  320.        struct LLIST_S  *psPrev;   /* pointer to previous member */
  321.        struct LLIST_S  *psNext;   /* pointer to next member */
  322.        VOID   *pvData;            /* pointer to data */
  323.     };
  324.  
  325.     typedef struct LLIST_S LLIST_T;  /* _T = stucture */
  326.     typedef LLIST_T *LLIST_P;        /* _P = pointer to structure */
  327.     typedef LLIST_T **LLIST_PP;      /* _PP = address/pointer to pointer */
  328.  
  329.  
  330.  
  331.     LLIST_P  psNewMember;
  332.  
  333.     C_STATUS = MemLstAllocMember(&psNewMember);
  334.  
  335.  
  336. RESOURCE NAME
  337.  
  338.     MEMLIB.LIB
  339.  
  340. DIAGNOSTICS
  341.  
  342.     C_OK       - member allocated
  343.                 (pointer not NULL on return)
  344.         C_NOTOK - member could not be allocated
  345.                 (pointer NULL on return)
  346.  
  347.  
  348. NAME
  349.     MemLstDeleteMember - deletes a member from a list
  350.  
  351. SYNOPSIS
  352.  
  353.     #include <memlib.h>
  354.  
  355.     SHORT APIENTRY
  356.     MemLstDeleteMember(psListRoot,psMember,ppsRetMember)
  357.     LLIST_P psListRoot;    
  358.     LLIST_P psMember;      
  359.     LLIST_PP ppsRetMember; 
  360.  
  361. DESCRIPTION
  362.  
  363.     Deletes psMember from list psListRoot.  Element psListRoot is
  364.     returned via ppsRetMember.
  365.  
  366.     C_STATUS = MemLstDeleteMember(psListRoot,
  367.                         psMember,
  368.                     &psListRoot);
  369.  
  370. RESOURCE NAME
  371.  
  372.     MEMLIB.LIB
  373.  
  374. WARNINGS
  375.  
  376.     MemLstDeleteMember does NOT free the pvData that the member
  377.     is pointing too.  That is the applications responsibility.
  378.     You may not want the pvData to be freed but just the list 
  379.         members themselves.  (A case for this is when moving data 
  380.         from one list to another.)
  381.  
  382.     Also check MemLstUnlinkMember().
  383.  
  384. DIAGNOSTICS
  385.  
  386.     C_OK       - always returned
  387.  
  388.  
  389.  
  390.  
  391. NAME
  392.     MemLstFindMember - search a list to find a member
  393.  
  394. SYNOPSIS
  395.  
  396.     #include <memlib.h>
  397.  
  398.     SHORT APIENTRY
  399.     MemLstFindMember(psListRoot,pvData,compare_func,psRetMember)
  400.     LLIST_P psListRoot;     
  401.     PVOID   pvData;            
  402.     SHORT   (*compare_func)(); 
  403.     LLIST_PP  ppsRetMember;  
  404.  
  405. DESCRIPTION
  406.  
  407.     Searches list psListRoot for pvData using compare_func.  If a
  408.     match is found between the passed pvData and member -> pvData 
  409.     then the address of the member is returned via ppsRetMember.
  410.  
  411.     LLIST_P  psSearchMember = NULL;
  412.  
  413.     ....
  414.  
  415.     C_STATUS = MemLstFindMember(psListRoot,
  416.                       (PCHAR) "1234",
  417.                       compare_func,
  418.                       &psSearchMember);
  419.  
  420. RESOURCE NAME
  421.  
  422.     MEMLIB.LIB
  423.  
  424. DIAGNOSTICS
  425.  
  426.     C_OK       - always returned
  427.  
  428.            (ppsRetMember = NULL on return if not found)
  429.  
  430.            (ppsRetMember != NULL on return not found)
  431.           
  432.  
  433.  
  434. NAME
  435.     MemLstFindTailMember - find the tail (last) member in a list
  436.  
  437. SYNOPSIS
  438.  
  439.     #include <memlib.h>
  440.  
  441.     SHORT APIENTRY
  442.     MemLstFindTailMember(psListRoot,ppsRetMember)
  443.     LLIST_P psListRoot;     
  444.     LLIST_PP  ppsRetMember;  
  445.  
  446. DESCRIPTION
  447.  
  448.     Walks through the list starting at psListRoot and goes to the end.
  449.         The tail (last) member of the list is returned in ppsRetMember.
  450.  
  451. RESOURCE NAME
  452.  
  453.     MEMLIB.LIB
  454.  
  455. DIAGNOSTICS
  456.  
  457.     C_OK       - always returned
  458.  
  459.  
  460.  
  461. NAME
  462.     MemLstInsertMember - inserts a new member into a list
  463.  
  464. SYNOPSIS
  465.  
  466.     #include <memlib.h>
  467.  
  468.     SHORT APIENTRY
  469.     MemLstInsertMember(psListRoot,psMember,compare_func,ppsRetMember)
  470.     LLIST_P  psListRoot;
  471.     LLIST_P  psMember;
  472.     SHORT    (*compare_func)();
  473.     LLIST_PP ppsRetMember;
  474.  
  475. DESCRIPTION
  476.  
  477.     Inserts psMember into list starting at psListRoot by using 
  478.     compare_func.   Places entries in list in ascending order.  
  479.     The compare function must emulate the return values of memcmp().
  480.     The head of the list is returned via ppsRetMember.  Element 
  481.     psMember must have been allocated via MemLstAllocMember.
  482.  
  483.  
  484.     C_STATUS = MemLstInsertMember(psListRoot,
  485.                      psMember,
  486.                      compare_func,
  487.                      &psListRoot);
  488.  
  489.     Note:    The MemLst*** functions provide more flexibility on
  490.         how data is added (Insert, AddBefore, AddAfter) than
  491.         the MemQue*** or MemStk functions.  For this reason,
  492.         the parameter to the MemLst*** (and MemTre***) functions
  493.         is the member (or node) to be added and not just the
  494.         data itself.
  495.  
  496. RESOURCE NAME
  497.  
  498.     MEMLIB.LIB
  499.  
  500. WARNINGS
  501.  
  502.     Duplicate 'keys' are allowed.
  503.  
  504. DIAGNOSTICS
  505.  
  506.     C_OK       - always returned
  507.  
  508.  
  509.  
  510. NAME
  511.     MemLstUnlinkMember - Unlinks a member from a list
  512.  
  513. SYNOPSIS
  514.  
  515.     #include <memlib.h>
  516.  
  517.     SHORT APIENTRY
  518.     MemLstUnlinkMember(psListRoot,psMember,ppsRetMember)
  519.     LLIST_P psListRoot;    
  520.     LLIST_P psMember;      
  521.     LLIST_PP ppsRetMember; 
  522.  
  523. DESCRIPTION
  524.  
  525.     Unlinks psMember from list psListRoot.  Element psListRoot is
  526.     returned via ppsRetMember.
  527.  
  528.     C_STATUS = MemLstUnlinkMember(psListRoot,
  529.                         psMember,
  530.                     &psListRoot);
  531.  
  532.     The difference between MemLstUnlinkMember and MemLstDeleteMember
  533.     is that the delete does a full delete (remove and free) whereas
  534.     the unlink does un-hooks the member from the list but does not
  535.     free it.  Unlink is usefull when you need to rearrange members
  536.     within a list.
  537.  
  538. RESOURCE NAME
  539.  
  540.     MEMLIB.LIB
  541.  
  542. DIAGNOSTICS
  543.  
  544.     C_OK       - always returned
  545.  
  546.  
  547. NAME
  548.     MemLstVacateList - removes all members from a list
  549.  
  550. SYNOPSIS
  551.  
  552.     #include <memlib.h>
  553.  
  554.     SHORT APIENTRY
  555.     MemLstVacateList(ppsListRoot,fFreeData)
  556.     LLIST_PP  ppsListRoot;
  557.     BOOL      fFreeData;
  558.  
  559.  
  560. DESCRIPTION
  561.  
  562.     Traverses the list starting at (*ppsListRoot).  At each member,
  563.     checks if fFreeData is C_TRUE; if it is, then does a free on
  564.     each members -> pvData.  Always does a free on the member itself.
  565.     If (*ppsListRoot) was the head/root of the list, then is reset
  566.     to NULL on return.
  567.  
  568.     C_STATUS = MemLstVacateList(&psListRoot,C_FALSE);
  569.  
  570. RESOURCE NAME
  571.  
  572.     MEMLIB.LIB
  573.  
  574. DIAGNOSTICS
  575.  
  576.     C_OK       - always returned
  577.  
  578. NAME
  579.     MemQueDeqMember - dequeues a member from a list/queue
  580.  
  581. SYNOPSIS
  582.  
  583.     #include <memlib.h>
  584.  
  585.     SHORT APIENTRY
  586.     MemQueDeqMember(ppsListHead,ppsListTail, ppvData)
  587.     LLIST_PP psListHead;
  588.     LLIST_PP psListTail;
  589.     PVOID * ppvData;
  590.  
  591. DESCRIPTION
  592.  
  593.     Removes a member from the (FIFO) queue and sets (*ppvData) to the
  594.     address that the queue member -> pvData had.
  595.  
  596.     The queue is implemented using the LLIST_T types which the
  597.     MemLst*** functions use.  The main difference between the 
  598.     MemQue*** and MemLst*** functions is that the creation and
  599.     deletion of the LLIST_P entries is handled AUTOMATICALLY 
  600.     for your application by the MemQue*** functions.  
  601.  
  602.     LLIST_P  psQueHead = NULL;
  603.     LLIST_P  psQueTail = NULL;
  604.     PVOID    pvData;
  605.  
  606.     pvData = (PVOID) &something;
  607.  
  608.     C_STATUS = MemQueEnqMember(&psQueHead,&psQueTail,pvData);
  609.  
  610.     C_STATUS = MemQueDeqMember(&psQueHead,&psQueTail,&pvData);
  611.  
  612.  
  613.     If you want a LIFO queue rather then FIFO queue, then check
  614.     the MemStk*** stack functions.
  615.  
  616.     There is no MemQueVacateQueue() function.  Since the
  617.     queue is maintained using the MemLst*** functions, to vacate
  618.     a queue, set the tail pointer to null, then send the head 
  619.     pointer into MemLstVacateList().
  620.  
  621. RESOURCE NAME
  622.  
  623.     MEMLIB.LIB
  624.  
  625. DIAGNOSTICS
  626.  
  627.        C_OK     - always returned
  628.  
  629.  
  630. NAME
  631.     MemQueEnqMember - Adds/queues a member into a list/queue
  632.  
  633. SYNOPSIS
  634.  
  635.     #include <memlib.h>
  636.  
  637.     SHORT APIENTRY
  638.     MemQueEnqMember(ppsListHead,ppsListTail, pvData)
  639.     LLIST_PP psListHead;
  640.     LLIST_PP psListTail;
  641.     PVOID pvData;
  642.  
  643. DESCRIPTION
  644.  
  645.     Adds a member to the (FIFO) queue.  The member will hold the
  646.     value of pvData in its -> pvData.
  647.  
  648.     The queue is implemented using the LLIST_T types which the
  649.     MemLst*** functions use.  The main difference between the 
  650.     MemQue*** and MemLst*** functions is that the creation and
  651.     deletion of the LLIST_P entries is handled AUTOMATICALLY 
  652.     for your application by the MemQue*** functions.  
  653.  
  654.     LLIST_P  psQueHead = NULL;
  655.     LLIST_P  psQueTail = NULL;
  656.     PVOID    pvData;
  657.  
  658.     pvData = (PVOID) &something;
  659.  
  660.     C_STATUS = MemQueEnqMember(&psQueHead,&psQueTail,pvData);
  661.  
  662.     C_STATUS = MemQueDeqMember(&psQueHead,&psQueTail,&pvData);
  663.  
  664.     If you want a LIFO queue rather then FIFO queue, then check
  665.     the MemStk*** stack functions.
  666.  
  667. RESOURCE NAME
  668.  
  669.     MEMLIB.LIB
  670.  
  671. DIAGNOSTICS
  672.  
  673.        C_OK     - always returned
  674.  
  675. NAME
  676.     MemStkClearStack - initializes a stack pointer to NULL
  677.  
  678. SYNOPSIS
  679.  
  680.     #include <memlib.h>
  681.  
  682.     SHORT APIENTRY
  683.     MemStkClearStack(ppsLlistStack)
  684.     LLIST_PP  ppsLlistStack;
  685.  
  686. DESCRIPTION
  687.  
  688.     Initializes a stack pointer to NULL.
  689.  
  690.     Call this before any other MemStk*** functions.
  691.  
  692.  
  693.         Stacks are implemented here in link list using the 
  694.         MemLst routines.
  695.  
  696.         Stacks are also known as LIFO (Last In First Out) Queues
  697.  
  698.         Push a stack and that member is placed on top
  699.         Pop a stack and top member is returned and removed 
  700.  
  701.  
  702.         Top of Stack      StackMember  ->   Pointer to data to hold/remember
  703.                              |
  704.                              v
  705.                           StackMember  ->   Pointer to data to hold/remember
  706.                              |
  707.                              v
  708.         Bot of Stack      StackMember  ->   Pointer to data to hold/remember
  709.       
  710.  
  711. RESOURCE NAME
  712.  
  713.     MEMLIB.LIB
  714.  
  715. DIAGNOSTICS
  716.  
  717.        C_OK     - always returned
  718.  
  719. NAME
  720.     MemStkEmptyStack - initializes a stack pointer to NULL
  721.  
  722. SYNOPSIS
  723.  
  724.     #include <memlib.h>
  725.  
  726.     SHORT APIENTRY
  727.     MemStkEmptyStack(psLlistStack,bEmpty)
  728.     LLIST_P  psLlistStack;
  729.     BOOL   * bEmpty;
  730.  
  731. DESCRIPTION
  732.  
  733.     Determines if stack (psLlistStack) is empty.
  734.     Result is returned in (*bEmpty).
  735.  
  736.     LLIST_P  psStack;
  737.     BOOL     fEmpty;
  738.  
  739.     /* clear stack at program start only */
  740.  
  741.     C_STATUS = MemStkClearStack(&psStack);
  742.  
  743.     C_STATUS = MemStkEmptyStack(psStack,&fEmpty)
  744.  
  745.     if(fEmpty)
  746.        /* stack is empty */
  747.     else
  748.        /* stack is not empty */
  749.  
  750. RESOURCE NAME
  751.  
  752.     MEMLIB.LIB
  753.  
  754. DIAGNOSTICS
  755.  
  756.        C_OK     - always returned
  757.  
  758. NAME
  759.     MemStkPop - removes/pops an element off the stack
  760.  
  761. SYNOPSIS
  762.  
  763.     #include <memlib.h>
  764.  
  765.     SHORT APIENTRY
  766.     MemStkPop(ppsLlistStackHead,ppvElementPointer)
  767.     LLIST_PP  ppsLlistStackHead;
  768.     PVOID  *  ppvElementPointer;
  769.  
  770. DESCRIPTION
  771.  
  772.     Removes an element from the top of the stack and sets 
  773.     (*ppvElementPointer) to the pvData which was saved from 
  774.     the original MemStkPush().
  775.  
  776.     LLIST_P  psStack;
  777.     PVOID    pvData;
  778.  
  779.     pvData = somedata;
  780.  
  781.     /* clear stack at program start only */
  782.  
  783.     C_STATUS = MemStkClearStack(&psStack);
  784.  
  785.     C_STATUS = MemStkPush(&psStack,pvData);
  786.  
  787.     C_STATUS = MemStkPop(&psStack,&pvData);
  788.  
  789.  
  790. RESOURCE NAME
  791.  
  792.     MEMLIB.LIB
  793.  
  794. DIAGNOSTICS
  795.  
  796.        C_OK     - always returned
  797.  
  798.            ((*ppvElementPointer) = NULL on return if stack is empty)
  799.  
  800.             
  801.  
  802. NAME
  803.     MemStkPush - places/pushes an element onto the stack
  804.  
  805. SYNOPSIS
  806.  
  807.     #include <memlib.h>
  808.  
  809.     SHORT APIENTRY
  810.     MemStkPush(ppsLlistStackHead,pvElementPointer)
  811.     LLIST_PP  ppsLlistStackHead;
  812.     PVOID     pvElementPointer;
  813.  
  814. DESCRIPTION
  815.  
  816.     Places data (pvElementPointer) onto stack (*ppsLlistStackHead).
  817.  
  818.  
  819.     LLIST_P  psStack;
  820.     PVOID    pvData;
  821.  
  822.     pvData = somedata;
  823.  
  824.     /* clear stack at program start only */
  825.  
  826.     C_STATUS = MemStkClearStack(&psStack);
  827.  
  828.     C_STAUS = MemStkPush(&psStack,pvData);
  829.  
  830. RESOURCE NAME
  831.  
  832.     MEMLIB.LIB
  833.  
  834. DIAGNOSTICS
  835.  
  836.        C_OK     - always returned
  837.  
  838. NAME
  839.     MemStkVacateStack - clears all entries from a stack
  840.  
  841. SYNOPSIS
  842.  
  843.     #include <memlib.h>
  844.  
  845.     SHORT APIENTRY
  846.     MemStkVacateStack(ppsLlistStack,fFreeData)
  847.     LLIST_PP  ppsLlistStack;
  848.     BOOL   fFreeData;
  849.  
  850.  
  851. DESCRIPTION
  852.  
  853.     Removes all elements from stack (*ppsLListStack).  
  854.     If fFreeData = C_TRUE, will also free the data that
  855.     is being pointed to by the stack.
  856.  
  857.     LLIST_P  psStack;
  858.     PVOID    pvData;
  859.  
  860.     pvData = somedata;
  861.  
  862.     /* clear stack at program start only */
  863.  
  864.     C_STATUS = MemStkClearStack(&psStack);
  865.  
  866.     C_STAUS = MemStkPush(&psStack,pvData);
  867.  
  868.     C_STATUS = MemStkVacateStack(&psStack,C_FALSE);
  869.  
  870.  
  871. RESOURCE NAME
  872.  
  873.     MEMLIB.LIB
  874.  
  875. DIAGNOSTICS
  876.  
  877.        C_OK     - always returned
  878.  
  879.            ((*ppsLlistStack) = NULL on return)
  880.  
  881.             
  882.  
  883. NAME
  884.     MemTreAllocNode - allocate a new tree node
  885.  
  886. SYNOPSIS
  887.  
  888.     #include <memlib.h>
  889.  
  890.     SHORT APIENTRY 
  891.         MemTreAllocNode (ppsRetNode) 
  892.     TNODE_PP  ppsRetNode;        
  893.  
  894. DESCRIPTION
  895.  
  896.     Allocates memory for a new tree node.  Initializes new node pointers.  
  897.     Uses calloc() to obtain the memory.
  898.  
  899.     All MemTre*** functions use the following structure:
  900.  
  901.     struct TNODE_S 
  902.     {            
  903.        PVOID          pvData;    /* pointer to application data */
  904.        struct TNODE_S *psLeft;   /* left child (internal use) */
  905.        struct TNODE_S *psRight;  /* right child (internal use */
  906.     }; 
  907.  
  908.     typedef struct TNODE_S TNODE_T;    /* structure type */
  909.     typedef TNODE_T *TNODE_P;          /* pointer to structure */
  910.     typedef TNODE_T **TNODE_PP;        /* address/pointer to pointer */
  911.  
  912.  
  913. RESOURCE NAME
  914.  
  915.     MEMLIB.LIB
  916.  
  917. DIAGNOSTICS
  918.  
  919.        C_OK     = allocated node
  920.              (pointer not NULL on return)
  921.        C_NOTOK  = could not allocate node
  922.              (pointer NULL on return)
  923.  
  924.  
  925.  
  926.  
  927.  
  928. NAME
  929.     MemTreDeleteNode - searches for and deletes a node from a tree.
  930.  
  931. SYNOPSIS
  932.  
  933.     #include <memlib.h>
  934.  
  935.     SHORT APIENTRY
  936.     MemTreDeleteNode(psTree,pvData,compare_func,ppsRetNode)
  937.     TNODE_P  psTree;
  938.     PVOID    pvData;
  939.     SHORT   (*compare_func)();
  940.     TNODE_PP ppsRetNode;
  941.  
  942. DESCRIPTION
  943.  
  944.     Searches for pvData starting at psTree.  At each node it compares
  945.         the pvData data passed in with each nodes -> pvData by calling
  946.     the compare_func.   The compare function must know what type of
  947.         data is being compared.  The return values from the compare 
  948.     function must emulate those of memcmp()/strcmp().
  949.     
  950.     The new value for psTree is returned in ppsRetNode.
  951.  
  952.     C_STATUS = MemTreDeleteNode(psTree,
  953.                       (PVOID) "Testing", 
  954.                                       compare_func,
  955.                                       &psTree);
  956.       
  957. RESOURCE NAME
  958.  
  959.     MEMLIB.LIB
  960.  
  961. DIAGNOSTICS
  962.  
  963.     C_OK       - node found and deleted
  964.     C_NOTOK - node not found                                      
  965.  
  966.  
  967. NAME
  968.     MemTreFindNode - searches for a node in a tree.
  969.  
  970. SYNOPSIS
  971.  
  972.     #include <memlib.h>
  973.  
  974.     SHORT APIENTRY
  975.     MemTreFindNode(psTree,pvData,compare_func,ppsRetNode)
  976.     TNODE_P  psTree;
  977.     PVOID    pvData;
  978.     SHORT   (*compare_func)();
  979.     TNODE_PP ppsRetNode;
  980.  
  981. DESCRIPTION
  982.  
  983.     Searches for pvData starting at psTree.  At each node it compares
  984.         the pvData data passed in with each node -> pvData by calling
  985.     the compare_func().   The compare function must know what type of
  986.         data is being compared.  The return values from the compare 
  987.     function must emulate those of memcmp()/strcmp().
  988.     
  989.     If the data was found, the address of the node member is returned
  990.     via ppsRetNode.   If the data was not found, ppsRetNode will be 
  991.     set to NULL
  992.  
  993.  
  994.     TNODE_P  psTree;
  995.     TNODE_P  psSearchNode = NULL;
  996.  
  997.     ....
  998.  
  999.     C_STATUS = MemTreFindNode(psTree,
  1000.                       (PVOID) "Testing", 
  1001.                                       compare_func,
  1002.                                       &psSearchNode);
  1003.  
  1004.     if(psSearchNode != NULL)
  1005.        /* data found */
  1006.     else
  1007.        /* data not found */
  1008.  
  1009.       
  1010. RESOURCE NAME
  1011.  
  1012.     MEMLIB.LIB
  1013.  
  1014. DIAGNOSTICS
  1015.  
  1016.     C_OK       - always returned
  1017.  
  1018.  
  1019. NAME
  1020.     MemTreInsertNode - inserts a new node into a tree.
  1021.  
  1022. SYNOPSIS
  1023.  
  1024.     #include <memlib.h>
  1025.  
  1026.     SHORT APIENTRY
  1027.     MemTreInsertNode(psTree,psNode,compare_func,ppsRetNode)
  1028.     TNODE_P  psTree;
  1029.     TNODE_P  psNode;
  1030.     SHORT   (*compare_func)();
  1031.     TNODE_PP ppsRetNode;
  1032.  
  1033. DESCRIPTION
  1034.  
  1035.     Inserts psNode into tree psTree using compare_func.  New head of
  1036.         tree (psNode) is returned via ppsRetNode.   The compare function 
  1037.         must know what type of data is being compared.  The return values 
  1038.         from the compare function must emulate those of memcmp()/strcmp().
  1039.     
  1040.     TNODE_P  psTree;
  1041.      TNODE_P  psNewNode;
  1042.  
  1043.     ....
  1044.  
  1045.     C_STATUS = MemTreAllocNode(&psNewNode);
  1046.  
  1047.     C_STATUS = MemTreInsertNode(psTree,
  1048.                       psNewNode,
  1049.                                       compare_func,
  1050.                                       &psTree);
  1051.  
  1052.       
  1053. RESOURCE NAME
  1054.  
  1055.     MEMLIB.LIB
  1056.  
  1057. WARNINGS
  1058.     
  1059.     Duplicate 'keys' are permitted.  Duplicates (via pvData) are 
  1060.     inserted in first-appearance order.
  1061.  
  1062. DIAGNOSTICS
  1063.  
  1064.     C_OK       - always returned
  1065.  
  1066.  
  1067. NAME
  1068.     MemTreLeaf - determines if a tree node is a leaf 
  1069.  
  1070. SYNOPSIS
  1071.  
  1072.     #include <memlib.h>
  1073.  
  1074.     SHORT APIENTRY
  1075.     MemTreLeaf(psTnode)
  1076.     TNODE_P  psTnode;
  1077.  
  1078. DESCRIPTION
  1079.  
  1080.     Determines if a tree node is a leaf (no left or right children).
  1081.     Is used internally by other MemTre*** functions.
  1082.  
  1083. RESOURCE NAME
  1084.  
  1085.     MEMLIB.LIB
  1086.  
  1087. DIAGNOSTICS
  1088.  
  1089.        C_OK     = Node is a leaf
  1090.        C_NOTOK  = Node is not a leaf
  1091.  
  1092.  
  1093. NAME
  1094.     MemTreRotateNodeLeft - rotates a tree node to the Left
  1095.  
  1096. SYNOPSIS
  1097.  
  1098.     #include <memlib.h>
  1099.  
  1100.     SHORT APIENTRY
  1101.     MemTreRotateNodeLeft(psTnode,ppsRetNode)
  1102.     TNODE_P  psTnode;
  1103.     TNODE_PP ppsRetNode;
  1104.  
  1105. DESCRIPTION
  1106.  
  1107.     Rotates a tree node to the Left.   
  1108.     Is used internally by other MemTre*** functions.
  1109.  
  1110. RESOURCE NAME
  1111.  
  1112.     MEMLIB.LIB
  1113.  
  1114. DIAGNOSTICS
  1115.  
  1116.        C_OK     = Always returned
  1117.  
  1118. NAME
  1119.     MemTreRotateNodeRight - rotates a tree node to the right
  1120.  
  1121. SYNOPSIS
  1122.  
  1123.     #include <memlib.h>
  1124.  
  1125.     SHORT APIENTRY
  1126.     MemTreRotateNodeRight(psTnode,ppsRetNode)
  1127.     TNODE_P  psTnode;
  1128.     TNODE_PP ppsRetNode;
  1129.  
  1130. DESCRIPTION
  1131.  
  1132.     Rotates a tree node to the right.   
  1133.     Is used internally by other MemTre*** functions.
  1134.  
  1135. RESOURCE NAME
  1136.  
  1137.     MEMLIB.LIB
  1138.  
  1139. DIAGNOSTICS
  1140.  
  1141.        C_OK     = Always returned
  1142.  
  1143. NAME
  1144.     MemTreVacateTree - deletes all nodes in a tree
  1145.  
  1146. SYNOPSIS
  1147.  
  1148.     #include <memlib.h>
  1149.  
  1150.     SHORT APIENTRY
  1151.     MemTreVacateTree(ppsTree, fFreeData)
  1152.     TNODE_PP  ppsTree;
  1153.     BOOL      fFreeData;
  1154.  
  1155. DESCRIPTION
  1156.  
  1157.     Traverses the tree starting at (*ppsTree).  At each node,
  1158.     checks if fFreeData is C_TRUE; if it is, then does a free on
  1159.     each nodes -> pvData.  Always does a free on the node itself.
  1160.     If (*ppsTree) was the head/root of the tree, then is reset
  1161.     to NULL on return.
  1162.  
  1163.     C_STATUS = MemTreVacatetree(&psTreeRoot,C_FALSE);
  1164.  
  1165.  
  1166. RESOURCE NAME
  1167.  
  1168.     MEMLIB.LIB
  1169.  
  1170. DIAGNOSTICS
  1171.  
  1172.        C_OK     - always returned
  1173.  
  1174.  
  1175. NAME
  1176.     MemHepSearch - searches a heap for an entry
  1177.  
  1178. SYNOPSIS
  1179.  
  1180.     #include <memlib.h>
  1181.  
  1182.     SHORT APIENTRY
  1183.         MemHepSearch(psHeap,pvData,compare_func,ppsHeapData)
  1184.         HEAP_P  psHeap;
  1185.         PVOID   pvData;
  1186.         SHORT    (*compare_func)(PVOID,PVOID);
  1187.         HEAP_DATA_PP  ppsHeapData;
  1188.  
  1189. DESCRIPTION
  1190.  
  1191.         Searches the heap defined through psHeap.  The search is linear
  1192.         through each element.  The compare_func() is called at each element
  1193.         to determine if a match is made between a heap entry and pvData.
  1194.  
  1195. RESOURCE NAME
  1196.  
  1197.     MEMLIB.LIB
  1198.  
  1199. DIAGNOSTICS
  1200.  
  1201.     C_OK       - always returned
  1202.                     (ppsHeapData = NULL if no match)
  1203.                     (ppsHeapData != NULL if match, is set to heap entry)
  1204.  
  1205.  
  1206. NAME
  1207.     MemTreWalkTree - walks (traverses) a tree
  1208.  
  1209. SYNOPSIS
  1210.  
  1211.     #include <memlib.h>
  1212.  
  1213.         SHORT APIENTRY
  1214.         MemTreWalkTree(psTnode, sOrder, AppFunc)
  1215.         TNODE_P psTnode;
  1216.         SHORT  sOrder;
  1217.         SHORT (APIENTRY *AppFunc)(PVOID);
  1218.  
  1219. DESCRIPTION
  1220.  
  1221.     Traverses the tree starting at psTnode.   Variable sOrder
  1222.         indicates if traversal is C_PRE_ORDER, C_IN_ORDER, or
  1223.         C_POST_ORDER.  At each leaf (terminal node), the 
  1224.         application supplied AppFunc is invoked and it is passed
  1225.         the current TNODE_P.   This is a recursive routine.
  1226.  
  1227.         The function can be used to process all nodes in a tree
  1228.         such as for printing, processing, or deleting.
  1229.         
  1230.  
  1231. RESOURCE NAME
  1232.  
  1233.     MEMLIB.LIB
  1234.  
  1235. DIAGNOSTICS
  1236.  
  1237.        C_OK     - always returned
  1238.  
  1239.