home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / dos / database / db12 / db.doc < prev    next >
Encoding:
Text File  |  1987-11-24  |  31.7 KB  |  1,005 lines
  1.  
  2.  
  3.                          
  4.  
  5.  
  6.  
  7.  
  8.         ######    ######        ######    #######  #####
  9.         #     # #     #     #     # #     # #     #
  10.         #     # #     #     #     # #     # #
  11.         #     # ######        #     # #     # #
  12.         #     # #     #   ###    #     # #     # #
  13.         #     # #     #   ###    #     # #     # #     #
  14.         ######    ######      ###    ######    #######  #####
  15.             
  16.  
  17.             #     #    #         #####
  18.             #     #   ##        #     #
  19.             #     #  # #              #
  20.             #     #    #         #####
  21.              #   #       #      ###    #
  22.               # #       #      ###    #
  23.                #     #####      ###    #######
  24.  
  25.  
  26.  
  27.               (c) 1987 Ken Harris
  28.                    901 E. Hampton
  29.                    Milwaukee, WI  53217
  30.                    (414) 962-1961
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48. /****************************************************************************/
  49. /*                                                                          */
  50. /*      This software is made available on an AS-IS basis. Unrestricted     */
  51. /*      use is granted provided that the copywrite notice remains intack.   */
  52. /*    The author makes no warranties expressed or implied; however, any   */
  53. /*    feedback is welcome.                            */
  54. /*                                                                          */
  55. /****************************************************************************/
  56.          
  57.  
  58.     V1.2 Release Notes:
  59.     ---- ------- -----
  60.  
  61.     (1)  The DB_READ_LAST and DB_READ_PREV routines have been added
  62.          to allow backwards traversal. The routines work for all three
  63.          file types. DB_DELETE should not be used with these routines.
  64.          The delete routine sets the current record pointer so that a
  65.          subsequent DB_READ_NEXT will work correctly. A DB_READ_PREV
  66.          loop with DB_DELETES will result in skipped records.
  67.                                   
  68.  
  69.     (2)  A number of bugs in the file create routine have been fixed.
  70.  
  71.  
  72.     (3)  A file corruption bug in the index delete routine has been
  73.          fixed.
  74.  
  75.  
  76.     (4)  The distribution has been divided into three separately
  77.          compiled files. 
  78.  
  79.  
  80.     (5)  Large memory model now works correctly.
  81.  
  82.  
  83.     (6)  A lot of "warning" type problems have been cleaned up.
  84.  
  85.     (7)  Just before releasing V1.2 Microsoft C V5.0 rolled in
  86.          the door so I was able to fix a couple of problems. 
  87.          There are still some warning messages while compiling
  88.          db_main.c. This is the result of ",..." type declarations
  89.          used to prevent type checking of the user_data argument.
  90.          User programs don't have to type cast user_data to char*
  91.          to avoid warnings.
  92.  
  93.     (8)  I have avoided the temptation of using too many of the
  94.          ANSI C extensions for those folks with old compilers.
  95.          Also I'd rather not fill the code with a zillion IFDEF's.
  96.          
  97.  
  98.         +----------+            -------------------               +----------+
  99.         | db_Intro |            - DB Introduction -               | db_Intro |
  100.         +----------+            -------------------               +----------+
  101.  
  102.  
  103.  
  104.         o Description
  105.  
  106.                     This document describes the DB package for maintaining
  107.             data files. The package consists of a library of file handling
  108.             routines which may be linked with user programs.
  109.  
  110.             The following three file organizations are supported:
  111.  
  112.                (1) Sequential - The file is a sequential stream of records.
  113.  
  114.                (2) Index      - Data records are stored in an index sequential
  115.                                 organization.
  116.  
  117.                (3) Random     - Data records are stored using a hashed method.
  118.                       
  119.  
  120.             The following operations are supported:
  121.  
  122.                    db_add         -  Add a New Record to a Data Set
  123.                    db_create      -  Create a New Data Set
  124.                    db_close       -  Close an Open Data Set
  125.                    db_delete      -  Delete the Current Record
  126.                    db_error_msg   -  Get Error Message Text
  127.                    db_find        -  Find a Record by Key
  128.                    db_get_rec_no  -  Get Relative Record #
  129.                    db_open        -  Open an Existing Data Set
  130.                    db_read_atr    -  Read Attribute Data
  131.                    db_read_direct -  Read by Record #
  132.                    db_read_first  -  Read First Record
  133.                    db_read_next   -  Read Next Record
  134.                    db_update      -  Update the Current Record
  135.                    db_update_atr  -  Update Attribute Data
  136.  
  137.  
  138.         +------+           -------------------------------           +------+
  139.         | db.h |           - Data Set Structures Defines -           | db.h |
  140.         +------+           -------------------------------           +------+
  141.  
  142.  
  143.  
  144.         o Summary
  145.  
  146.                 #include <db.h>
  147.  
  148.  
  149.  
  150.         o Description
  151.  
  152.                 This header file contains the definitions for the global
  153.                 structures that are used by all of the DB routines. It 
  154.                 should be included in any program that calls DB routines.
  155.                 The user program needs only to declare DATA_SET descriptor
  156.                 pointers for the data sets that are to be used. The
  157.                 DATA_SET descriptor pointer is used to refer to the data
  158.                 sets.
  159.  
  160.  
  161.                 A global variable db_error is used to return a status
  162.                 value after any call to a DB routine. The header file
  163.                 includes constant declarations for db_error values. 
  164.                 The user program can check for specific conditions
  165.                 such as DB_END_OF_FILE. A function call db_error_msg()
  166.                 can be used to get the error message text corresponding
  167.                 to the value of db_error.
  168.  
  169.         +--------+     ------------------------------------         +--------+
  170.         | db_add |     -  Add a New Record to a Data Set  -         | db_add |
  171.         +--------+     ------------------------------------         +--------+
  172.  
  173.  
  174.  
  175.         o Summary
  176.  
  177.                 #include <db.h>
  178.  
  179.                 ulong db_add(ds, user_data)
  180.                   DATA_SET  ds;
  181.                   char     *user_data;
  182.  
  183.  
  184.  
  185.         o Description
  186.  
  187.                 This function is used to add a new record to a data set.
  188.                 The data set is specified by the input ds and user_data
  189.                 points to the data record to be added.
  190.  
  191.                 For Indexed and Random data sets, the first field of the
  192.                 data record (user_data) must contain the record key value.
  193.  
  194.                 The value of Current Record (used by db_read_next) is reset
  195.                 to NONE by this operation.
  196.  
  197.  
  198.  
  199.         o Returns
  200.  
  201.                 The relative record number of the new record is returned.
  202.                 If an error occurs a zero value is returned and the global
  203.                 db_error contains the error number.
  204.  
  205.  
  206.  
  207.         +----------+         ----------------------------         +----------+
  208.         | db_close |         -  Close an Open Data Set  -         | db_close |
  209.         +----------+         ----------------------------         +----------+
  210.  
  211.  
  212.  
  213.         o Summary
  214.  
  215.                 #include <db.h>
  216.  
  217.                 DATA_SET db_close(ds)
  218.                   DATA_SET  ds;
  219.  
  220.  
  221.  
  222.         o Description
  223.  
  224.                 This function terminates all processing for an open data set.
  225.                 The associated file is closed and all dynamic storage is
  226.                 released.
  227.  
  228.  
  229.  
  230.         o Returns
  231.  
  232.                 The completion status of the function is returned in the
  233.         global db_error. The function itself returns a NULL pointer
  234.         value.
  235.  
  236.         +-----------+         -------------------------         +-----------+
  237.         | db_create |         - Create a New Data Set -         | db_create |
  238.         +-----------+         -------------------------         +-----------+
  239.  
  240.  
  241.  
  242.         o Summary
  243.  
  244.                 #include <db.h>
  245.  
  246.                 DATA_SET db_create(path, fname, fhdr)
  247.                   char *path, *fname;
  248.                   FILE_HDR fhdr;
  249.  
  250.  
  251.  
  252.         o Description
  253.  
  254.                 This function is used to create a new data set. The inputs
  255.                 are as follows:
  256.  
  257.                      path   -  Path name of data directory
  258.                      fname  -  File name of new data set
  259.                      fhdr   -  Pointer to the file header structure
  260.  
  261.  
  262.                 The structure information about the data set is passed in
  263.                 a file header record. For a create ONLY, the user program
  264.                 must allocate a file header record for the data set and fill
  265.                 in the necessary values. This is a kludge that will be 
  266.                 replaced by a utility program of some sort to do file
  267.                 creates. The following file header fields are required:
  268.  
  269.                      Sequential Organization
  270.                         fh_file_type  = DB_SEQ
  271.                         fh_data_size  = nn
  272.  
  273.                      Indexed Organization
  274.                         fh_file_type  = DB_INDEX
  275.                         fh_data_size  = nn         (includes key size)
  276.                         fh_key_size   = nn
  277.  
  278.                      Random Organization
  279.                         fh_file_type  = DB_RANDOM
  280.                         fh_data_size  = nn         (includes key size)
  281.                         fh_key_size   = nn
  282.                         fh_base_size  = nn
  283.  
  284.  
  285.                 
  286.                 The following fields may optionally be specified:
  287.  
  288.                         fh_block_size = nn
  289.                         fh_atr_size   = nn
  290.                         fh_file_stat  = DB_DUP_ALLOWED  (Index only)
  291.  
  292.  
  293.  
  294.  
  295.         o Returns
  296.  
  297.                 This function returns a pointer to the data set descriptor
  298.                 block for the newly created data set. This value should be 
  299.                 used for future references to the data set. The status of 
  300.                 the data set is open.
  301.  
  302.                 The return status is available in the global db_error. If 
  303.                 an error occurs the new data set is not created and a null
  304.                 descriptor pointer is returned.
  305.  
  306.         +-----------+      -------------------------------      +-----------+
  307.         | db_delete |      -  Delete the Current Record  -      | db_delete |
  308.         +-----------+      -------------------------------      +-----------+
  309.  
  310.  
  311.  
  312.         o Summary
  313.  
  314.                 #include <db.h>
  315.  
  316.                 void db_delete(ds)
  317.                   DATA_SET  ds;
  318.  
  319.  
  320.  
  321.         o Description
  322.  
  323.                 This function is used to delete the Current Record from the
  324.                 data set specified by ds.
  325.  
  326.                 This function must be preceeded by some function that 
  327.                 establishes the Current Record for the data set.
  328.  
  329.  
  330.  
  331.         o Returns
  332.  
  333.                 The completion status is returned in the global db_error. 
  334.                 A non-zero value indicates an error. The Current Record
  335.                 for the data set is reset to NONE.
  336.  
  337.         +----------+          -------------------------          +----------+
  338.         | db_error |          -  Global Error Status  -          | db_error |
  339.         +----------+          -------------------------          +----------+
  340.  
  341.  
  342.  
  343.         o Summary
  344.  
  345.                 extern int db_error;
  346.  
  347.  
  348.  
  349.         o Description
  350.  
  351.                 This global variable contains the completion status of
  352.                 the most recent db_xxxx call. The following values and
  353.                 associated constants are defined for V1.1:
  354.  
  355.  
  356.                         DB_FILE_NOT_FOUND      1
  357.                         DB_READ_ERROR          2
  358.                         DB_END_OF_FILE         3
  359.                         DB_WRITE_ERROR         4
  360.                         DB_FILE_NOT_CREATED    5
  361.                         DB_FILE_NOT_OPEN       6
  362.                         DB_INVALID_BLOCK       7
  363.                         DB_BUFFER_ERROR        8
  364.                         DB_NO_CURRENT_REC      9
  365.                         DB_DELETED_REC        10
  366.                         DB_INVALID_FREE       11
  367.                         DB_INVALID_BLK_SIZE   12
  368.                         DB_INVALID_INDEX      13
  369.                         DB_REC_NOT_FOUND      14
  370.                         DB_DUP_NOT_ALLOWED    15
  371.                         DB_INVALID_REQUEST    16
  372.                         DB_INVALID_RANDOM     17
  373.                         DB_INVALID_FHDR       18
  374.                         DB_VERSION_ERROR      19
  375.  
  376.  
  377.         +--------------+     ----------------------------    +--------------+
  378.         | db_error_msg |     -  Get Error Message Text  -    | db_error_msg |
  379.         +--------------+     ----------------------------    +--------------+
  380.  
  381.  
  382.  
  383.         o Summary
  384.  
  385.                 #include <db.h>
  386.  
  387.                 char *db_error_msg(error)
  388.                   int   error;
  389.  
  390.  
  391.  
  392.         o Description
  393.  
  394.                 This function is used to get an error message corresponding
  395.                 to the error number returned in db_error.
  396.  
  397.  
  398.  
  399.         o Returns
  400.  
  401.                 A pointer to the error message is returned.
  402.  
  403.  
  404.         +---------+          --------------------------           +---------+
  405.         | db_find |          -  Find a Record by Key  -           | db_find |
  406.         +---------+          --------------------------           +---------+
  407.  
  408.  
  409.  
  410.         o Summary
  411.  
  412.                 #include <db.h>
  413.  
  414.                 void db_find(ds, user_data, key, key_size)
  415.                   DATA_SET  ds;
  416.                   char     *user_data;                   
  417.                   char     *key;
  418.                   int       key_size;
  419.  
  420.  
  421.  
  422.         o Description
  423.  
  424.                 This function is used to find a record by key value. The
  425.                 following are inputs:
  426.  
  427.                      ds         -  specifies the data set
  428.                      user_data  -  pointer to the destination buffer
  429.                      key        -  pointer to key value
  430.                      key_size   -  length of the key field
  431.  
  432.                 The key_length field allows for matching less than the
  433.                 entire record key in an Index data set. A key_size of zero
  434.                 defaults to entire key length. For a Random data set, the
  435.                 key_length field is ignored.
  436.  
  437.                 This function is not valid for Sequential data sets.
  438.                 
  439.  
  440.  
  441.         o Returns
  442.  
  443.                 The data record is read into the buffer pointed to by
  444.                 user_data. The read record becomes the Current Record
  445.                 for this data set. The completion status is returned 
  446.                 in the global db_error. A non-zero value indicates an 
  447.                 error.
  448.  
  449.  
  450.  
  451.         +---------------+    ---------------------------    +---------------+
  452.         | db_get_rec_no |    -  Get Relative Record #  -    | db_get_rec_no |
  453.         +---------------+    ---------------------------    +---------------+
  454.  
  455.  
  456.  
  457.         o Summary
  458.  
  459.                 #include <db.h>
  460.  
  461.                 ulong db_get_rec_no(ds)
  462.                   DATA_SET  ds;
  463.  
  464.  
  465.  
  466.         o Description
  467.  
  468.                 This function returns the Relative Record Number for the
  469.                 Current Record in the data set specified by ds. The
  470.                 Relative  Record Number for records in sequential data
  471.                 sets is fixed; however, for records in Index and Random
  472.                 data sets the value may be changed due to reorganizations
  473.                 that occur when adds and deletes take place.
  474.                 occur.
  475.  
  476.  
  477.  
  478.         o Returns
  479.  
  480.                 The value of the relative record number is returned.
  481.                 If there is an error, a NULL value is returned and the
  482.                 global db_error contains the error code.
  483.  
  484.  
  485.         +---------+        -------------------------------        +---------+
  486.         | db_open |        -  Open an Existing Data Set  -        | db_open |
  487.         +---------+        -------------------------------        +---------+
  488.  
  489.  
  490.  
  491.         o Summary
  492.  
  493.                 #include <db.h>
  494.  
  495.                 DATA_SET db_create(path, fname)
  496.                   char *path, *fname;
  497.  
  498.  
  499.  
  500.         o Description
  501.  
  502.                 This function is used to open an existing data set. The inputs
  503.                 are as follows:
  504.  
  505.                      path   -  Path name of data directory
  506.                      fname  -  File name of the data set
  507.  
  508.  
  509.  
  510.         o Returns
  511.  
  512.                 This function returns a pointer to the data set descriptor
  513.                 block for the data set. This value should be used for future 
  514.                 references to the data set.
  515.  
  516.                 If an error occurs a NULL value is returned and the global
  517.                 db_error contains the error number.
  518.  
  519.  
  520.  
  521.  
  522.         +-------------+       -------------------------       +-------------+
  523.         | db_read_atr |       -  Read Attribute Data  -       | db_read_atr |
  524.         +-------------+       -------------------------       +-------------+
  525.  
  526.  
  527.  
  528.         o Summary
  529.  
  530.                 #include <db.h>
  531.  
  532.                 void db_read_atr(ds, user_data)
  533.                   DATA_SET  ds;                 
  534.                   char     *user_data;
  535.  
  536.  
  537.  
  538.         o Description
  539.  
  540.                 This function is used to read the attribute record for a
  541.                 data set. The data set is specified by ds and user_data
  542.                 points to the destination buffer.
  543.  
  544.                 The attribute data is a single user-define record that
  545.                 may be used to store some global data for the data set.
  546.  
  547.  
  548.  
  549.  
  550.         o Returns
  551.  
  552.                 The attribute record is read into the buffer pointed to by
  553.                 user_data. The completion status is returned in the global 
  554.                 db_error. A non-zero value indicates an error.
  555.  
  556.         +----------------+     -----------------------     +----------------+
  557.         | db_read_direct |     -  Read by Record #   -     | db_read_direct |
  558.         +----------------+     -----------------------     +----------------+
  559.  
  560.  
  561.  
  562.         o Summary
  563.  
  564.                 #include <db.h>
  565.  
  566.                 void db_read_direct(ds, rec_no, user_data)
  567.                   DATA_SET  ds;                 
  568.                   ulong     rec_no;
  569.                   char     *user_data;
  570.  
  571.  
  572.  
  573.         o Description
  574.  
  575.                 This function is used to read a record directly by using its
  576.                 Relative Record Number. The data set is specified by ds,
  577.                 the Relative Record Number is rec_no and user_data points
  578.                 to the destination buffer.
  579.  
  580.  
  581.  
  582.         o Returns
  583.  
  584.                 The data record is read into the buffer pointed to by
  585.                 user_data. The read record becomes the Current Record
  586.                 for this data set. The completion status is returned 
  587.                 in the global db_error. A non-zero value indicates an 
  588.                 error.
  589.  
  590.  
  591.         +---------------+      -----------------------      +---------------+
  592.         | db_read_first |      -  Read First Record  -      | db_read_first |
  593.         +---------------+      -----------------------      +---------------+
  594.  
  595.  
  596.  
  597.         o Summary
  598.  
  599.                 #include <db.h>
  600.  
  601.                 void db_read_first(ds, user_data)
  602.                   DATA_SET  ds;
  603.                   char     *user_data;
  604.  
  605.  
  606.  
  607.         o Description
  608.  
  609.                 This function is used to read the first record from a data set.
  610.                 The data set is specified by ds and user_data points to the
  611.                 destination buffer for the record.
  612.  
  613.  
  614.  
  615.         o Returns
  616.  
  617.                 The data record is read into the buffer pointed to by
  618.                 user_data. The read record becomes the Current Record
  619.                 for this data set. The completion status is returned 
  620.                 in the global db_error. A non-zero value indicates an 
  621.                 error.
  622.  
  623.  
  624.     +--------------+       ----------------------         +--------------+
  625.     | db_read_last |       -  Read Last Record  -         | db_read_last |
  626.     +--------------+       ----------------------         +--------------+
  627.  
  628.  
  629.  
  630.         o Summary
  631.  
  632.                 #include <db.h>
  633.  
  634.         void db_read_last(ds, user_data)
  635.                   DATA_SET  ds;
  636.                   char     *user_data;
  637.  
  638.  
  639.  
  640.         o Description
  641.  
  642.         This function is used to read the last record from a data set.
  643.                 The data set is specified by ds and user_data points to the
  644.                 destination buffer for the record.
  645.  
  646.  
  647.  
  648.         o Returns
  649.  
  650.                 The data record is read into the buffer pointed to by
  651.                 user_data. The read record becomes the Current Record
  652.                 for this data set. The completion status is returned 
  653.                 in the global db_error. A non-zero value indicates an 
  654.                 error.
  655.  
  656.  
  657.         +--------------+       ----------------------        +--------------+
  658.         | db_read_next |       -  Read Next Record  -        | db_read_next |
  659.         +--------------+       ----------------------        +--------------+
  660.  
  661.  
  662.  
  663.         o Summary
  664.  
  665.                 #include <db.h>
  666.  
  667.                 void db_read_next(ds, user_data)
  668.                   DATA_SET  ds;
  669.                   char     *user_data;
  670.  
  671.  
  672.  
  673.         o Description
  674.  
  675.                 This function is used to read the next record from a data set.
  676.                 The data set is specified by ds and user_data points to the
  677.                 destination buffer for the record.
  678.  
  679.                 This function must be preceeded by some function that 
  680.                 establishes the Current Record for the data set. For example
  681.                 db_read_first followed by db_read_next until end of file
  682.                 occurs. The value of Current Record is reset to NONE by
  683.                 a db_add.
  684.  
  685.  
  686.  
  687.         o Returns
  688.  
  689.                 The data record is read into the buffer pointed to by
  690.                 user_data. The read record becomes the Current Record
  691.                 for this data set. The completion status is returned 
  692.                 in the global db_error. A non-zero value indicates an 
  693.                 error.
  694.  
  695.  
  696.         +--------------+       ----------------------        +--------------+
  697.     | db_read_prev |       -  Read Prev Record  -         | db_read_prev |
  698.         +--------------+       ----------------------        +--------------+
  699.  
  700.  
  701.  
  702.         o Summary
  703.  
  704.                 #include <db.h>
  705.  
  706.         void db_read_prev(ds, user_data)
  707.                   DATA_SET  ds;
  708.                   char     *user_data;
  709.  
  710.  
  711.  
  712.         o Description
  713.  
  714.         This function is used to read the previous record from a data
  715.         set. The data set is specified by ds and user_data points to
  716.         the destination buffer for the record.
  717.  
  718.                 This function must be preceeded by some function that 
  719.                 establishes the Current Record for the data set. For example
  720.         db_read_last followed by db_read_prev until end of file
  721.                 occurs. The value of Current Record is reset to NONE by
  722.         a db_add. 
  723.  
  724.         db_read_prev should not be used with db_delete. db_delete
  725.         positions the current pointer so that a db_read_next will
  726.         be correct. A db_read_prev loop with deletes will skip
  727.         records.
  728.  
  729.  
  730.  
  731.         o Returns
  732.  
  733.                 The data record is read into the buffer pointed to by
  734.                 user_data. The read record becomes the Current Record
  735.                 for this data set. The completion status is returned 
  736.                 in the global db_error. A non-zero value indicates an 
  737.                 error.
  738.  
  739.  
  740.  
  741.         +-----------+      -------------------------------      +-----------+
  742.         | db_update |      -  Update the Current Record  -      | db_update |
  743.         +-----------+      -------------------------------      +-----------+
  744.  
  745.  
  746.  
  747.         o Summary
  748.  
  749.                 #include <db.h>
  750.  
  751.                 void db_update(ds, user_data)
  752.                   DATA_SET  ds;
  753.                   char     *user_data;
  754.  
  755.  
  756.  
  757.         o Description
  758.  
  759.                 This function is used to update the Current Record for the
  760.                 data set specified by ds. The contents of the data record
  761.                 pointed to by user_data are written back to the data set.
  762.  
  763.                 This function must be preceeded by some function that 
  764.                 establishes the Current Record for the data set.
  765.  
  766.  
  767.  
  768.         o Returns
  769.  
  770.                 The completion status is returned in the global db_error. 
  771.                 A non-zero value indicates an error. The Current Record
  772.                 for the data set is reset to NONE.
  773.  
  774.  
  775.         +---------------+    ---------------------------    +---------------+
  776.         | db_update_atr |    -  Update Attribute Data  -    | db_update_atr |
  777.         +---------------+    ---------------------------    +---------------+
  778.  
  779.  
  780.  
  781.         o Summary
  782.  
  783.                 #include <db.h>
  784.  
  785.                 void db_update_atr(ds, user_data)
  786.                   DATA_SET  ds;                 
  787.                   char     *user_data;
  788.  
  789.  
  790.  
  791.         o Description
  792.  
  793.                 This function is used to update the attribute record for a
  794.                 data set. The data set is specified by ds and user_data
  795.                 points to the source buffer to be written to the attribute
  796.                 area for the data set.
  797.  
  798.                 The attribute data is a single user-define record that
  799.                 may be used to store some global data for the data set.
  800.  
  801.  
  802.  
  803.  
  804.         o Returns
  805.  
  806.                 The completion status is returned in the global db_error.
  807.                 A non-zero value indicates an error.
  808.  
  809.  
  810.         +-------------+     ------------------------------     +-------------+
  811.         | fname_dflts |     -  Merge File Name Defaults  -     | fname_dflts |
  812.         +-------------+     ------------------------------     +-------------+
  813.  
  814.  
  815.  
  816.         o Summary
  817.  
  818.                 char *fname_dflts(fname, dflt)
  819.                   char *fname, *dflt;
  820.  
  821.  
  822.  
  823.         o Description
  824.  
  825.                 This function merges a file name string with a
  826.                 default file name. For example the following would
  827.                 force a default extension of ".c" if no extension
  828.                 was present.
  829.  
  830.                         x = fname_dflts(fname,".c");
  831.  
  832.  
  833.  
  834.         o Returns
  835.  
  836.                 A pointer to the resulting static string is returned.
  837.  
  838.  
  839.         +--------+           -----------------------              +--------+
  840.         | fparse |           -  Parse a File Spec  -              | fparse |
  841.         +--------+           -----------------------              +--------+
  842.  
  843.  
  844.  
  845.         o Summary
  846.  
  847.                 fparse(fstr, o_node, o_dev, o_dir, o_file, o_ext, o_ver)
  848.                   char *fstr, *o_node, *o_dev, *o_dir, *o_file, *o_ext, *o_ver;
  849.  
  850.  
  851.  
  852.         o Description
  853.  
  854.                 This function parses a file specification fstr into component
  855.                 parts. Not all of these components apply to generic MS-DOS.
  856.  
  857.                         o_node  - Node name
  858.                         o_dev   - Device name
  859.                         o_dir   - Directory Path
  860.                         o_file  - File name
  861.                         o_ext   - File extension
  862.                         o_ver   - Version number
  863.  
  864.  
  865.  
  866.         o Returns
  867.  
  868.                 The component strings are copied into the buffers pointed
  869.                 to by the o_* args.
  870.  
  871.  
  872.         +--------+             -------------------                  +--------+
  873.         | memedt |             -  Edit a Buffer  -                  | memedt |
  874.         +--------+             -------------------                  +--------+
  875.  
  876.  
  877.  
  878.         o Summary
  879.  
  880.                 void memedt(mem, cnt, flag)
  881.                  char *mem;
  882.                  int   cnt, flag;
  883.  
  884.  
  885.  
  886.         o Description
  887.  
  888.                 This function performs an edit on the string mem of
  889.                 length count. The flag specifies edit options:
  890.  
  891.                           1    -   trim parity bit
  892.                           2    -   discard all spaces and tabs
  893.                           4    -   discard excess characters
  894.                           8    -   discard leading spaces & tabs
  895.                          16    -   reduce spaces and tabs to 1
  896.                          32    -   convert to upper case
  897.                          64    -   *** not used ***
  898.                         128    -   discard trailing spaces & tabs
  899.                         256    -   don't alter char in quotes
  900.  
  901.  
  902.  
  903.         o Returns
  904.  
  905.                 The string is edited in place.
  906.  
  907.  
  908.         +------+              --------------------------             +------+
  909.         | sort |              -  Callable Record Sort  -             | sort |
  910.         +------+              --------------------------             +------+
  911.  
  912.  
  913.  
  914.         o Summary
  915.  
  916.                 void  sort_init(rec_size, spec_str)
  917.                   int   rec_size;
  918.                   char *spec_str;
  919.  
  920.                 void  sort_release(data_rec)
  921.                   char *data_rec;
  922.  
  923.                 void  sort_merge()
  924.  
  925.                 char *sort_return(data_rec)
  926.                   char *data_rec;
  927.  
  928.  
  929.  
  930.         o Description
  931.  
  932.                 This set of functions provides a callable record sort
  933.                 facility:
  934.  
  935.                 sort_init - Initialize the sort. This must be done first.
  936.                             rec_size = the size of the data record
  937.                             spec_str = string of sort specs separated
  938.                                        by commas. "spec,spec,spec..."
  939.                             spec     = XXn.n
  940.                                        ||| |
  941.                                        ||| +--- size of field     (bytes)
  942.                                        ||+----- starting position (1 relative)
  943.                                        ||
  944.                                        |+------ Format   A = Alpha
  945.                                        |                 U = Unsigned integer
  946.                                        |                 I = Integer
  947.                                        |                 R = Real
  948.                                        |
  949.                                        +------- Sequence A = Ascending
  950.                                                          D = Descending
  951.  
  952.                 sort_release - Release a record to the sort. data_rec
  953.                                points to the data.
  954.  
  955.                 sort_merge   - Do the sort merge operation.
  956.  
  957.                 sort_return  - Return a record from the sort and put
  958.                                it in data_rec. A pointer to the data
  959.                                record is returned. A NULL value indicates
  960.                                end of file.
  961.  
  962.  
  963.  
  964.         o Returns
  965.  
  966.                 If a sort error occurs an error message is printed and
  967.                 the program aborts.
  968.  
  969.         +--------+             -------------------                  +--------+
  970.         | stredt |             -  Edit a String  -                  | stredt |
  971.         +--------+             -------------------                  +--------+
  972.  
  973.  
  974.  
  975.         o Summary
  976.  
  977.                 void stredt(str, flag)
  978.                  char *str;
  979.                  int   flag;
  980.  
  981.  
  982.  
  983.         o Description
  984.  
  985.                 This function performs an edit on the null terminated
  986.                 string str. The flag specifies edit options:
  987.  
  988.                           1    -   trim parity bit
  989.                           2    -   discard all spaces and tabs
  990.                           4    -   discard excess characters
  991.                           8    -   discard leading spaces & tabs
  992.                          16    -   reduce spaces and tabs to 1
  993.                          32    -   convert to upper case
  994.                          64    -   *** not used ***
  995.                         128    -   discard trailing spaces & tabs
  996.                         256    -   don't alter char in quotes
  997.  
  998.  
  999.  
  1000.         o Returns
  1001.  
  1002.                 The string is edited in place.
  1003.  
  1004.  
  1005.