home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_300 / 311_01 / db.doc < prev    next >
Text File  |  1990-04-22  |  48KB  |  1,459 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, 1990
  28.  
  29.                               Ken Harris
  30.                   901 E. Hampton
  31.                   Milwaukee, WI  53217
  32.                   (414) 962-1961
  33.                   harris@cvax.cs.uwm.edu
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50. /****************************************************************************/
  51. /*                                                                          */
  52. /*      This software is made available on an AS-IS basis. Unrestricted     */
  53. /*      use is granted provided that the copyright notice remains intact.   */
  54. /*    The author makes no warranties expressed or implied; however, any   */
  55. /*    feedback is welcome.                            */
  56. /*                                                                          */
  57. /****************************************************************************/
  58.          
  59.  
  60.     V1.2 Release Notes:
  61.     ---- ------- -----
  62.  
  63.     (1)  The DB_READ_LAST and DB_READ_PREV routines have been added
  64.          to allow backwards traversal. The routines work for all three
  65.          file types. DB_DELETE should not be used with these routines.
  66.          The delete routine sets the current record pointer so that a
  67.          subsequent DB_READ_NEXT will work correctly. A DB_READ_PREV
  68.          loop with DB_DELETES will result in skipped records.
  69.                                   
  70.  
  71.     (2)  A number of bugs in the file create routine have been fixed.
  72.  
  73.  
  74.     (3)  A file corruption bug in the Index delete routine has been
  75.          fixed.
  76.  
  77.  
  78.     (4)  The distribution has been divided into three separately
  79.          compiled files. 
  80.  
  81.  
  82.     (5)  Large memory model now works correctly.
  83.  
  84.  
  85.     (6)  A lot of "warning" type problems have been cleaned up.
  86.  
  87.     (7)  Just before releasing V1.2 Microsoft C V5.0 rolled in
  88.          the door so I was able to fix a couple of problems. 
  89.          There are still some warning messages while compiling
  90.          db_main.c. This is the result of ",..." type declarations
  91.          used to prevent type checking of the user_data argument.
  92.          User programs don't have to type cast user_data to char*
  93.          to avoid warnings.
  94.  
  95.     (8)  I have avoided the temptation of using too many of the
  96.          ANSI C extensions for those folks with old compilers.
  97.          Also I'd rather not fill the code with a zillion IFDEF's.
  98.          
  99.  
  100.  
  101.     V1.3 Release Notes:
  102.     ---- ------- -----
  103.  
  104.     (1)  A variable type file has been added. It is a sequential file
  105.          with variable length records.
  106.  
  107.     (2)  A simple object dictionary manager has been added. It works
  108.          well for a small data base of non-homogeneous objects, for
  109.          example setup data records.
  110.  
  111.     (3)  The file descriptor pointer is now called DATA_FILE instead of
  112.          DATA_SET. DATA_SET is still defined so that V1.2 programs
  113.          will compile.
  114.  
  115.     (4)  The db_create routine arguments have changed. An option
  116.          string is now passed instead of a df_file_hdr pointer. This
  117.          is much cleaner. It will require changing any V1.2 programs
  118.          before they will work.
  119.  
  120.     (5)  A number of routines now take an optional final record size
  121.          argument. This is only required for VAR type files. It may
  122.          be ignored for other file types.
  123.  
  124.     (6)  Existing V1.2 data files should work with V1.3 routines.
  125.          The first time the file is openned and updated the file
  126.          version will be changed from 1.2 to 1.3.
  127.  
  128.     (7)  Compiler conditionals have been added to DB_MAIN.C to
  129.          bracket references to file-type specific routines. This
  130.          makes it possible to build a library with support for
  131.          only file types you need. The lexical variables are
  132.          SEQ, RAN, IDX, VAR and ALL. So if SEQ is defined, then
  133.          sequential file support is included, etc. Note that
  134.          DB_DICT uses VAR files. If an attempt is made to access
  135.          an unsupported file-type an error will occur. 
  136.  
  137.          Only the references to routines are IFDEFed. If you build
  138.          a subset library you will probably get warning messages
  139.          about some unreferenced variables. It's ok.
  140.  
  141.     (8)  Compiler conditionals are used to bracket compiler specific
  142.          code. The current conditionals are:
  143.         MSC   - Microsoft C
  144.         TURBO - Turbo C
  145.         SYSV  - Unix Sys V 
  146.  
  147.          In addition ANSI can be defined to use ANSI style function
  148.          prototypes. You will probably want to edit #defines for
  149.          your compiler and ANSI at the beginning of db.h.
  150.  
  151.     (9)  A header file, dblib.h, has been added for building the
  152.          library. It is not needed for application programs. It
  153.          contains compiler specific includes and defines.
  154.  
  155.     V1.3 Release Notes (cont):
  156.     ---- ------- -----
  157.  
  158.     (10) The header file contains references to DB_LINK routines.
  159.          These are routines for linking records between files.
  160.          They have not been included in the distribution.
  161.  
  162.     (11) The routines memedt and stredt are no longer used by the
  163.          db routines and have been removed from the distribution.
  164.  
  165.     (12) The *test.c files are intended to provide a minimal test
  166.          of the routines. If the the tests run to compeletion
  167.          without crashing or generating a DB-ERROR then there is
  168.          a good chance that you're in business. The tests are
  169.          not necessarily good examples of using the routines.
  170.  
  171.     (13) The routines have been built and tested on several
  172.          different machines. Most of the development for v1.3
  173.          was done under Ultrix on a VAXstation-2000 with gcc.
  174.          It has also been sucessfully built using MSC 5.1 and
  175.          Turbo C 2.0 under MSDOS and cc under Unix on a 3B1. 
  176.  
  177.          If your compiler is not one of these you should still 
  178.          be able to build the routines without too much trouble.
  179.          Search through the code for MSC 's and add an
  180.          appropriate case for your compiler. 
  181.  
  182.     (14) Note that although this code works fine on Unix systems,
  183.          it is still single user. There is no support for record
  184.          locking or file sharing. 
  185.  
  186.         +----------+            -------------------               +----------+
  187.         | db_Intro |            - DB Introduction -               | db_Intro |
  188.         +----------+            -------------------               +----------+
  189.  
  190.  
  191.  
  192.         o Description
  193.  
  194.                     This document describes the DB package for maintaining
  195.             data files. The package consists of a library of file handling
  196.             routines which may be linked with user programs.
  197.  
  198.             The following four file organizations are supported:
  199.  
  200.                (1) Sequential - This file is a sequential stream of fixed
  201.                 length records.
  202.  
  203.                (2) Index      - Data records are stored in an ISAM type
  204.                                 organization.
  205.  
  206.                (3) Random     - Data records are stored using a hashed method.
  207.  
  208.            (4) Variable   - A sequential stream of variable length
  209.                 records.
  210.                      
  211.  
  212.             The following operations are supported:
  213.  
  214.             db_read_last         -  Read Last Record 
  215.             db_read_prev         -  Read Prev Record
  216.                 db_add               -  Add a New Record a File 
  217.                 db_close             -  Close an Open Data Set
  218.                 db_create            -  Create a New Data Set
  219.                 db_delete            -  Delete the Current Record
  220.                 db_dict_add          -  Dict Add Object
  221.                 db_dict_close        -  Dict Close 
  222.                 db_dict_delete       -  Dict Object Delete 
  223.                 db_dict_delete_all   -  Dict Delete All 
  224.                 db_dict_dump         -  Dict Dump to a File
  225.                 db_dict_find         -  Dict Find Object
  226.                 db_dict_find_all     -  Dict Find All 
  227.                 db_dict_init         -  Dict Initialize
  228.                 db_dict_load         -  Dict Load From File
  229.                 db_error_msg         -  Get Error Message Text
  230.                 db_find              -  Find a Record by Key   
  231.                 db_get_rec_no        -  Get Relative Record # 
  232.                 db_open              -  Open an Existing Data Set
  233.                 db_read_atr          -  Read Attribute Data  
  234.                 db_read_direct       -  Read by Record #   
  235.                 db_read_first        -  Read First Record 
  236.                 db_read_next         -  Read Next Record 
  237.                 db_reorg             -  Reorganize Free Space
  238.                 db_update            -  Update the Current Record
  239.                 db_update_atr        -  Update Attribute Data 
  240.  
  241.         +------+           -------------------------------           +------+
  242.         | db.h |           - Data Set Structures Defines -           | db.h |
  243.         +------+           -------------------------------           +------+
  244.  
  245.  
  246.  
  247.         o Summary
  248.  
  249.                 #include <db.h>
  250.  
  251.  
  252.  
  253.         o Description
  254.  
  255.                 This header file contains the definitions for the global
  256.                 structures that are used by all of the DB routines. It 
  257.                 should be included in any program that calls DB routines.
  258.                 The user program needs only to declare DATA_FILE descriptor
  259.                 pointers for the data files that are to be used. The
  260.                 DATA_FILE descriptor pointer is used to refer to the data
  261.                 files.
  262.  
  263.  
  264.                 A global variable db_error is used to return a status
  265.                 value after any call to a DB routine. The header file
  266.                 includes constant declarations for db_error values. 
  267.                 The user program can check for specific conditions
  268.                 such as DB_END_OF_FILE. A function call db_error_msg()
  269.                 can be used to get the error message text corresponding
  270.                 to the value of db_error.
  271.  
  272.         +--------+     ------------------------------------         +--------+
  273.         | db_add |     -  Add a New Record to a Data Set  -         | db_add |
  274.         +--------+     ------------------------------------         +--------+
  275.  
  276.  
  277.  
  278.         o Summary
  279.  
  280.                 #include <db.h>
  281.  
  282.                 ulong db_add(df, user_data, data_size)
  283.                   DATA_FILE  df;
  284.                   void     *user_data;
  285.           int       data_size;
  286.  
  287.  
  288.  
  289.         o Description
  290.  
  291.                 This function is used to add a new record to a data file.
  292.                 The data file is specified by the input df and user_data
  293.                 points to the data record to be added.
  294.  
  295.                 For Indexed and Random data files, the first field of the
  296.                 data record (user_data) must contain the record key value.
  297.  
  298.         For Variable data files, the data_size field contains the
  299.         size of the variable length user_data record. The field
  300.         is not used for the other file types.
  301.  
  302.                 The value of Current Record (used by db_read_next) is reset
  303.                 to NONE by this operation.
  304.  
  305.  
  306.  
  307.         o Returns
  308.  
  309.                 The relative record number of the new record is returned.
  310.                 If an error occurs a zero value is returned and the global
  311.                 db_error contains the error number.
  312.  
  313.  
  314.  
  315.         +----------+         ----------------------------         +----------+
  316.         | db_close |         -  Close an Open Data Set  -         | db_close |
  317.         +----------+         ----------------------------         +----------+
  318.  
  319.  
  320.  
  321.         o Summary
  322.  
  323.                 #include <db.h>
  324.  
  325.                 DATA_FILE db_close(df)
  326.                   DATA_FILE  df;
  327.  
  328.  
  329.  
  330.         o Description
  331.  
  332.                 This function terminates all processing for an open data file.
  333.                 The associated file is closed and all dynamic storage is
  334.                 released.
  335.  
  336.  
  337.  
  338.         o Returns
  339.  
  340.                 The completion status of the function is returned in the
  341.         global db_error. The function itself returns a NULL pointer
  342.         value.
  343.  
  344.         +-----------+         -------------------------         +-----------+
  345.         | db_create |         - Create a New Data Set -         | db_create |
  346.         +-----------+         -------------------------         +-----------+
  347.  
  348.  
  349.  
  350.         o Summary
  351.  
  352.                 #include <db.h>
  353.  
  354.                 DATA_FILE db_create(path, fname, options)
  355.                   char *path, *fname, *options;
  356.  
  357.  
  358.  
  359.         o Description
  360.  
  361.                 This function is used to create a new data file. The inputs
  362.                 are as follows:
  363.  
  364.                      path    -  Path name of data directory
  365.                      fname   -  File name of new data file
  366.                      options -  Create options string 
  367.  
  368.  
  369.         The option string contains a list of create options
  370.         seperated by commas. The following options are supported:
  371.  
  372.             SEQ         - Sequential file organization 
  373.             RAN          - Random file organization
  374.             IDX          - Index file organization
  375.             VAR          - Variable file organization  
  376.             BLK    = nnn - Size of block 
  377.             REC    = nnn - Size of record
  378.             BASE   = nnn - Size of Random file base area
  379.                        (Should be a prime number)
  380.             KEY    = nnn - Size of the record key
  381.             ATR    = nnn - Size of Attribute block   
  382.             DUPS         - Duplicate record keys allowed
  383.             NODUPS       - Duplicate record keys NOT allowd
  384.  
  385.  
  386.                 O P T I O N   T A B L E
  387.                 ===========   =========
  388.  
  389.  
  390.                 +===============================+
  391.                 |   -- File Organizations --    |
  392.         +===============+=======+=======+=======+=======+
  393.         |  - Options -  | SEQ   | RAN   | IDX   | VAR   |
  394.         +===============+=======+=======+=======+=======+
  395.         | SEQ        | REQ    | -    | -    + -    |
  396.         +---------------+-------+-------+-------+-------+
  397.         | RAN        | -    | REQ    | -    + -    |
  398.         +---------------+-------+-------+-------+-------+
  399.         | IDX        | -    | -    | REQ    + -    |
  400.         +---------------+-------+-------+-------+-------+
  401.         | VAR        | -    | -    | -    + REQ    |
  402.         +---------------+-------+-------+-------+-------+
  403.         | BLK        | OPT    | OPT    | OPT    + OPT    |
  404.         +---------------+-------+-------+-------+-------+
  405.         | REC        | REQ    | REQ    | REQ    + REQ    |
  406.         +---------------+-------+-------+-------+-------+
  407.         | BASE        | -    | REQ    | -    + -    |
  408.         +---------------+-------+-------+-------+-------+
  409.         | KEY        | -    | REQ    | REQ    + -    |
  410.         +---------------+-------+-------+-------+-------+
  411.         | ATR        | OPT    | OPT    | OPT    + OPT    |
  412.         +---------------+-------+-------+-------+-------+ 
  413.         | DUPS         | -    | -    | OPT    + -    |
  414.         +---------------+-------+-------+-------+-------+
  415.         | NODUPS    | -    | -    | OPT    + -    |
  416.         +===============+=======+=======+=======+=======+
  417.           REQ = Required   OPT = Optional  - = Doesn't Apply
  418.  
  419.  
  420.     o Examples:
  421.  
  422.         df = db_create("c:\\data", "test.dat", "SEQ, REC=32");
  423.  
  424.         df = db_create("", "test.dat", "RAN,REC=32,KEY=2,BASE=29");
  425.  
  426.         df = db_create("", "test.dat", "IDX, REC=50, KEY=5");
  427.  
  428.  
  429.         o Returns
  430.  
  431.                 This function returns a pointer to the data file descriptor
  432.                 block for the newly created data file. This value should be 
  433.                 used for future references to the data file. The status of 
  434.                 the data file is open.
  435.  
  436.                 The return status is available in the global db_error. If 
  437.                 an error occurs the new data file is not created and a null
  438.                 descriptor pointer is returned.
  439.  
  440.         +-----------+      -------------------------------      +-----------+
  441.         | db_delete |      -  Delete the Current Record  -      | db_delete |
  442.         +-----------+      -------------------------------      +-----------+
  443.  
  444.  
  445.  
  446.         o Summary
  447.  
  448.                 #include <db.h>
  449.  
  450.                 void db_delete(df)
  451.                   DATA_FILE  df;
  452.  
  453.  
  454.  
  455.         o Description
  456.  
  457.                 This function is used to delete the Current Record from the
  458.                 data file specified by df.
  459.  
  460.                 This function must be preceeded by some function that 
  461.                 establishes the Current Record for the data file.
  462.  
  463.  
  464.  
  465.         o Returns
  466.  
  467.                 The completion status is returned in the global db_error. 
  468.                 A non-zero value indicates an error. The Current Record
  469.                 for the data file is reset to NONE.
  470.  
  471.         +---------+           -------------------------           +---------+
  472.         | db_dict |           -  Dictionary Routines  -           | db_dict |
  473.         +---------+           -------------------------           +---------+
  474.  
  475.  
  476.  
  477.         o Description
  478.  
  479.         The dictionary routines can be used to maintain a simple
  480.         object dictionary. Objects are of arbitrary size and are
  481.         referenced by name and type. A dictionary may be dumped
  482.         to or loaded from a VAR file. If the DB_DICT routines are
  483.         to be used, VAR file support must be included in the
  484.         library.
  485.  
  486.         A dictionary is memory resident. It makes a good place
  487.         to store a non-homogenous collection of objects (records).
  488.         
  489.  
  490.         The following functions are supported:
  491.  
  492.                 db_dict_add          -  Dict Add Object
  493.                 db_dict_close        -  Dict Close 
  494.                 db_dict_delete       -  Dict Object Delete 
  495.                 db_dict_delete_all   -  Dict Delete All 
  496.                 db_dict_dump         -  Dict Dump to a File
  497.                 db_dict_find         -  Dict Find Object
  498.                 db_dict_find_all     -  Dict Find All 
  499.                 db_dict_init         -  Dict Initialize
  500.                 db_dict_load         -  Dict Load From File
  501.  
  502.         +--------------+        ---------------------        +--------------+
  503.         | db_dict_init |        -  Dict Initialize  -        | db_dict_init |
  504.         +--------------+        ---------------------        +--------------+
  505.  
  506.  
  507.  
  508.         o Summary
  509.  
  510.                 #include <db.h>
  511.  
  512.                 DICT db_dict_init() 
  513.  
  514.  
  515.  
  516.         o Description
  517.  
  518.         This function is used to create a new dictionary. It must
  519.         be called before any other dictionary routines.
  520.  
  521.  
  522.  
  523.         o Returns
  524.  
  525.         A pointer to the new dictionary is returned. If an error
  526.         occurs a NULL pointer is returned and db_error contains
  527.         the error code.
  528.  
  529.         +---------------+          ----------------         +---------------+
  530.         | db_dict_close |          -  Dict Close  -         | db_dict_close |
  531.         +---------------+          ----------------         +---------------+
  532.  
  533.  
  534.  
  535.         o Summary
  536.  
  537.                 #include <db.h>
  538.  
  539.                 void db_dict_close(dict)
  540.           DICT dict;
  541.  
  542.  
  543.  
  544.         o Description
  545.  
  546.                 This function is used to close up the dictionary dict.
  547.         All allocated storage will be freed. The dict variable
  548.         should be set to NULL after a close.
  549.  
  550.  
  551.  
  552.         o Returns
  553.  
  554.                 The completion status is returned in the global db_error. 
  555.                 A non-zero value indicates an error.
  556.  
  557.         +-------------+         ---------------------         +-------------+
  558.         | db_dict_add |         -  Dict Add Object  -         | db_dict_add |
  559.         +-------------+         ---------------------         +-------------+
  560.  
  561.  
  562.  
  563.         o Summary
  564.  
  565.                 #include <db.h>
  566.  
  567.                 void *db_dict_add(dict, name, o_type, o_size, obj)
  568.           DICT  dict;        /* Dictionary pointer        */
  569.           char *name;          /* Name of the object        */
  570.           int   o_type;        /* Object type            */
  571.           int   o_size;        /* Object size            */
  572.           void *obj;        /* Pointer to the object    */
  573.  
  574.  
  575.  
  576.         o Description
  577.  
  578.         This function is used to add a new object to a dictionary.
  579.         The dictionary is specified by dict. Name is the lookup
  580.         name for the object. The o_type is a user specified type 
  581.         which can be used to group like objects together. The o_size
  582.         is the size of the object in bytes. Obj is a pointer to
  583.         the object. If sucessful, a new object is created in the
  584.         specified dictionary and the contents of obj are copied
  585.         to it. 
  586.  
  587.  
  588.  
  589.         o Returns
  590.  
  591.         A pointer to the new object is returned. If an error occurs,
  592.         a NULL pointer is returned and db_error contains the error
  593.         code.
  594.  
  595.         +----------------+    ------------------------     +----------------+
  596.         | db_dict_delete |    -  Dict Object Delete  -     | db_dict_delete |
  597.         +----------------+    ------------------------     +----------------+
  598.  
  599.  
  600.  
  601.         o Summary
  602.  
  603.                 #include <db.h>
  604.  
  605.                 void db_dict_delete(dict, name, o_type)
  606.           DICT  dict;
  607.           char *name;
  608.           int   o_type;
  609.  
  610.  
  611.  
  612.         o Description
  613.  
  614.         This function is used to delete an object from the
  615.         dictionary dict. Name is the name of the object to
  616.         delete. O_type is the type of the object to delete.
  617.         There may be mutiple objects with the same name but
  618.         different types. If o_type is 0, then all types will
  619.         be deleted. If sucessful, the matching object(s) is
  620.         removed.
  621.  
  622.  
  623.  
  624.         o Returns
  625.  
  626.                 The completion status is returned in the global db_error. 
  627.                 A non-zero value indicates an error. 
  628.  
  629.         +--------------------+     ---------------     +--------------------+
  630.         | db_dict_delete_all |     Dict Delete All     | db_dict_delete_all |
  631.         +--------------------+     ---------------     +--------------------+
  632.  
  633.  
  634.  
  635.         o Summary
  636.  
  637.                 #include <db.h>
  638.  
  639.                 void db_dict_delete_all(dict, o_type)
  640.                   DICT  dict;
  641.           int   o_type;
  642.  
  643.  
  644.  
  645.         o Description
  646.  
  647.                 This function is used to delete all objects of type o_type
  648.         from the dictionary dict. If o_type is 0 then all objects
  649.         will be removed.
  650.  
  651.  
  652.  
  653.  
  654.         o Returns
  655.  
  656.                 The completion status is returned in the global db_error. 
  657.                 A non-zero value indicates an error.
  658.  
  659.         +--------------+      -------------------------      +--------------+
  660.         | db_dict_dump |      -  Dict Dump to a File  -      | db_dict_dump |
  661.         +--------------+      -------------------------      +--------------+
  662.  
  663.  
  664.  
  665.         o Summary
  666.  
  667.                 #include <db.h>
  668.  
  669.                 void db_dict_dump(dict, path, fname)
  670.           DICT   dict;
  671.           char  *path;
  672.           char  *fname;
  673.  
  674.  
  675.  
  676.         o Description
  677.  
  678.                 This function is used to dump the objects in a dictionary
  679.         dict to a file. The file is specified by path and fname.
  680.         A new VAR file will be created.
  681.  
  682.  
  683.  
  684.         o Returns
  685.  
  686.                 The completion status is returned in the global db_error. 
  687.                 A non-zero value indicates an error.
  688.  
  689.         +--------------+        ----------------------       +--------------+
  690.         | db_dict_find |        -  Dict Find Object  -       | db_dict_find |
  691.         +--------------+        ----------------------       +--------------+
  692.  
  693.  
  694.  
  695.         o Summary
  696.  
  697.                 #include <db.h>
  698.  
  699.                 void *db_dict_find(dict, name, o_type)
  700.           DICT  dict;
  701.           char *name;
  702.           int   o_type;
  703.  
  704.  
  705.  
  706.         o Description
  707.  
  708.                 This function is used to lookup an object in dictionary
  709.         dict. Name is the name of the object to look for and o_type
  710.         is the type. If o_type is 0 then the first matching object
  711.         of any type will be found.
  712.  
  713.  
  714.  
  715.         o Returns
  716.  
  717.         A pointer to the found object is returned. If no matching
  718.         object is found, a NULL pointer is returned and an error
  719.         code is placed in db_error.
  720.  
  721.         +------------------+     -------------------     +------------------+
  722.         | db_dict_find_all |     -  Dict Find All  -     | db_dict_find_all |
  723.         +------------------+     -------------------     +------------------+
  724.  
  725.  
  726.  
  727.         o Summary
  728.  
  729.                 #include <db.h>
  730.  
  731.                 int db_dict_find_all(dict, o_type, nlist, olist)
  732.                   DICT    dict;        /* Dictionary        */
  733.           int     o_type;    /* Object type        */
  734.           char ***nlist;    /* List of object names    */
  735.           void ***olist;    /* List of object ptrs    */
  736.  
  737.  
  738.  
  739.         o Description
  740.  
  741.         This function is used to retrieve all the objects of type
  742.         o_type from dictionary dict. If o_type is 0, then all
  743.         types will be retrieved. The function allocates space and
  744.         creates a list of pointers to the object names and a list
  745.         of pointers to the objects themselves. Nlist and olist
  746.         will be updated to point to the above two lists resp.
  747.         The two lists should be freed when done with them.  
  748.  
  749.  
  750.  
  751.     o Example
  752.  
  753.         DICT  dict;
  754.         char *names[], *objs[];
  755.         int   i, cnt;
  756.  
  757.  
  758.         cnt = db_find_all(dict, 1, &names, &objs);
  759.         for (i=0; i<cnt; i++)
  760.             printf("name[%d]=%s\n", names[i]);
  761.  
  762.         free(name);
  763.         free(objs);
  764.  
  765.  
  766.         o Returns
  767.  
  768.         A count of the number of objects found is returned. The
  769.         two pointers nlist and olist are updated to point to the
  770.         list of names and objects resp. If an error occurs, 0
  771.         is returned, nlist and olist are set to NULL and an error
  772.         code is place in db_error.
  773.  
  774.         +--------------+       ------------------------      +--------------+
  775.         | db_dict_load |       -  Dict Load From File -      | db_dict_load |
  776.         +--------------+       ------------------------      +--------------+
  777.  
  778.  
  779.  
  780.         o Summary
  781.  
  782.                 #include <db.h>
  783.  
  784.                 void db_dict_load(dict, path, fname)
  785.                   DICT  dict;
  786.           char *path;
  787.           char *fname;
  788.  
  789.  
  790.  
  791.         o Description
  792.  
  793.                 This function is used to load a dictionary dict with
  794.         objects from a file. The file is specified by path and
  795.         fname. The dictionary must already be initialized. This
  796.         allows multiple loads to a single dictionary. The file
  797.         fname must be an existing VAR type file.
  798.  
  799.  
  800.  
  801.         o Returns
  802.  
  803.                 The completion status is returned in the global db_error. 
  804.                 A non-zero value indicates an error.
  805.  
  806.         +----------+          -------------------------          +----------+
  807.         | db_error |          -  Global Error Status  -          | db_error |
  808.         +----------+          -------------------------          +----------+
  809.  
  810.  
  811.  
  812.         o Summary
  813.  
  814.                 extern int db_error;
  815.  
  816.  
  817.  
  818.         o Description
  819.  
  820.                 This global variable contains the completion status of
  821.                 the most recent db_xxxx call. The following values and
  822.                 associated constants are defined for V1.3:
  823.  
  824.  
  825.             DB_FILE_NOT_FOUND      1
  826.             DB_READ_ERROR          2
  827.             DB_END_OF_FILE         3
  828.             DB_WRITE_ERROR         4
  829.             DB_FILE_NOT_CREATED    5
  830.             DB_FILE_NOT_OPEN       6
  831.             DB_INVALID_BLOCK       7
  832.             DB_BUFFER_ERROR        8
  833.             DB_NO_CURRENT_REC      9
  834.             DB_DELETED_REC        10
  835.             DB_INVALID_FREE       11
  836.             DB_INVALID_BLK_SIZE   12
  837.             DB_INVALID_INDEX      13
  838.             DB_REC_NOT_FOUND      14
  839.             DB_DUP_NOT_ALLOWED    15
  840.             DB_INVALID_REQUEST    16
  841.             DB_INVALID_RANDOM     17
  842.             DB_INVALID_FHDR       18
  843.             DB_VERSION_ERROR      19
  844.             DB_INVALID_LINK       20
  845.             DB_LINK_ERROR         21
  846.             DB_FTYPE_ERROR        22
  847.             DB_INVALID_OPTION     23
  848.             DB_ALLOC_ERROR        24
  849.             DB_VAR_SIZE_ERROR     25
  850.             DB_VAR_CSUM_ERROR     26
  851.             DB_UNSUPP_FEATURE     27
  852.             DB_INVALID_DICT       28
  853.             DB_INVALID_NAME       29
  854.             DB_INVALID_ERROR      30
  855.  
  856.         +--------------+     ----------------------------    +--------------+
  857.         | db_error_msg |     -  Get Error Message Text  -    | db_error_msg |
  858.         +--------------+     ----------------------------    +--------------+
  859.  
  860.  
  861.  
  862.         o Summary
  863.  
  864.                 #include <db.h>
  865.  
  866.                 char *db_error_msg(error)
  867.                   int   error;
  868.  
  869.  
  870.  
  871.         o Description
  872.  
  873.                 This function is used to get an error message corresponding
  874.                 to the error number returned in db_error.
  875.  
  876.  
  877.  
  878.         o Returns
  879.  
  880.                 A pointer to the error message is returned.
  881.  
  882.  
  883.         +---------+          --------------------------           +---------+
  884.         | db_find |          -  Find a Record by Key  -           | db_find |
  885.         +---------+          --------------------------           +---------+
  886.  
  887.  
  888.  
  889.         o Summary
  890.  
  891.                 #include <db.h>
  892.  
  893.                 void db_find(df, user_data, key, key_size)
  894.                   DATA_FILE  df;
  895.                   void     *user_data;                   
  896.                   char     *key;
  897.                   int       key_size;
  898.  
  899.  
  900.  
  901.         o Description
  902.  
  903.                 This function is used to find a record by key value. The
  904.                 following are inputs:
  905.  
  906.                      df         -  specifies the data file
  907.                      user_data  -  pointer to the destination buffer
  908.                      key        -  pointer to key value
  909.                      key_size   -  length of the key field
  910.  
  911.                 The key_length field allows for matching less than the
  912.                 entire record key in an Index data file. A key_size of zero
  913.                 defaults to entire key length. For a Random data file, the
  914.                 key_length field is ignored.
  915.  
  916.                 This function is not valid for Sequential ior variable data 
  917.         files.
  918.                 
  919.  
  920.  
  921.         o Returns
  922.  
  923.                 The data record is read into the buffer pointed to by
  924.                 user_data. The read record becomes the Current Record
  925.                 for this data file. The completion status is returned 
  926.                 in the global db_error. A non-zero value indicates an 
  927.                 error.
  928.  
  929.  
  930.  
  931.         +---------------+    ---------------------------    +---------------+
  932.         | db_get_rec_no |    -  Get Relative Record #  -    | db_get_rec_no |
  933.         +---------------+    ---------------------------    +---------------+
  934.  
  935.  
  936.  
  937.         o Summary
  938.  
  939.                 #include <db.h>
  940.  
  941.                 ulong db_get_rec_no(df)
  942.                   DATA_FILE  df;
  943.  
  944.  
  945.  
  946.         o Description
  947.  
  948.                 This function returns the Relative Record Number for the
  949.                 Current Record in the data file specified by df. The
  950.                 Relative  Record Number for records in sequential data
  951.                 files is fixed; however, for records in Index, Random
  952.         and Variable data files the value may be changed due to 
  953.         reorganizations that occur when adds and deletes take 
  954.         place.
  955.  
  956.  
  957.  
  958.         o Returns
  959.  
  960.                 The value of the relative record number is returned.
  961.         For Variable files the rrn is the lseek offsest of the
  962.         record. For the other file organizations, the rrn is
  963.         the actual record number from the beginning of the file.
  964.  
  965.                 If there is an error, a NULL value is returned and the
  966.                 global db_error contains the error code.
  967.  
  968.  
  969.         +---------+        -------------------------------        +---------+
  970.         | db_open |        -  Open an Existing Data Set  -        | db_open |
  971.         +---------+        -------------------------------        +---------+
  972.  
  973.  
  974.  
  975.         o Summary
  976.  
  977.                 #include <db.h>
  978.  
  979.                 DATA_FILE db_open(path, fname)
  980.                   char *path, *fname;
  981.  
  982.  
  983.  
  984.         o Description
  985.  
  986.                 This function is used to open an existing data file. The inputs
  987.                 are as follows:
  988.  
  989.                      path   -  Path name of data directory
  990.                      fname  -  File name of the data fileo
  991.         
  992.         The path argument can also be treated as a string of 
  993.         defaults.
  994.  
  995.  
  996.  
  997.         o Returns
  998.  
  999.                 This function returns a pointer to the data file descriptor
  1000.                 block for the data file. This value should be used for future 
  1001.                 references to the data file.
  1002.  
  1003.                 If an error occurs a NULL value is returned and the global
  1004.                 db_error contains the error number.
  1005.  
  1006.  
  1007.  
  1008.  
  1009.         +-------------+       -------------------------       +-------------+
  1010.         | db_read_atr |       -  Read Attribute Data  -       | db_read_atr |
  1011.         +-------------+       -------------------------       +-------------+
  1012.  
  1013.  
  1014.  
  1015.         o Summary
  1016.  
  1017.                 #include <db.h>
  1018.  
  1019.                 void db_read_atr(df, user_data)
  1020.                   DATA_FILE  df;                 
  1021.                   void      *user_data;
  1022.  
  1023.  
  1024.  
  1025.         o Description
  1026.  
  1027.                 This function is used to read the attribute record for a
  1028.                 data file. The data file is specified by df and user_data
  1029.                 points to the destination buffer.
  1030.  
  1031.                 The attribute data is a single user record that may be 
  1032.         used to store some global data for the data file.
  1033.  
  1034.  
  1035.  
  1036.  
  1037.         o Returns
  1038.  
  1039.                 The attribute record is read into the buffer pointed to by
  1040.                 user_data. The completion status is returned in the global 
  1041.                 db_error. A non-zero value indicates an error.
  1042.  
  1043.         +----------------+     -----------------------     +----------------+
  1044.         | db_read_direct |     -  Read by Record #   -     | db_read_direct |
  1045.         +----------------+     -----------------------     +----------------+
  1046.  
  1047.  
  1048.  
  1049.         o Summary
  1050.  
  1051.                 #include <db.h>
  1052.  
  1053.                 void db_read_direct(df, rec_no, user_data, data_size)
  1054.                   DATA_FILE  df;                 
  1055.                   ulong     rec_no;
  1056.                   void     *user_data;
  1057.           int      *data_size;
  1058.  
  1059.  
  1060.  
  1061.         o Description
  1062.  
  1063.                 This function is used to read a record directly by using its
  1064.                 Relative Record Number. The data file is specified by df,
  1065.                 the Relative Record Number is rec_no and user_data points
  1066.                 to the destination buffer.
  1067.  
  1068.  
  1069.  
  1070.         o Returns
  1071.  
  1072.                 The data record is read into the buffer pointed to by
  1073.                 user_data. If the file type is Variable, the length of
  1074.         the record read is placed in data_size. The read record 
  1075.         becomes the Current Record for this data file. The 
  1076.         completion status is returned in the global db_error. 
  1077.         A non-zero value indicates an error.
  1078.  
  1079.  
  1080.         +---------------+      -----------------------      +---------------+
  1081.         | db_read_first |      -  Read First Record  -      | db_read_first |
  1082.         +---------------+      -----------------------      +---------------+
  1083.  
  1084.  
  1085.  
  1086.         o Summary
  1087.  
  1088.                 #include <db.h>
  1089.  
  1090.                 void db_read_first(df, user_data, data_size)
  1091.                   DATA_FILE  df;
  1092.                   void     *user_data;
  1093.           int      *data_size;
  1094.  
  1095.  
  1096.  
  1097.         o Description
  1098.  
  1099.                 This function is used to read the first record from a 
  1100.         data file.  The data file is specified by df and user_data 
  1101.         points to the destination buffer for the record.
  1102.  
  1103.  
  1104.  
  1105.         o Returns
  1106.  
  1107.                 The data record is read into the buffer pointed to by
  1108.                 user_data. If the file type is Variable, the length of
  1109.         the record read is placed in data_size. The read record 
  1110.         becomes the Current Record for this data file. The 
  1111.         completion status is returned in the global db_error. 
  1112.         A non-zero value indicates an error.
  1113.  
  1114.  
  1115.     +--------------+       ----------------------         +--------------+
  1116.     | db_read_last |       -  Read Last Record  -         | db_read_last |
  1117.     +--------------+       ----------------------         +--------------+
  1118.  
  1119.  
  1120.  
  1121.         o Summary
  1122.  
  1123.                 #include <db.h>
  1124.  
  1125.         void db_read_last(df, user_data, data_size)
  1126.                   DATA_FILE  df;
  1127.                   void     *user_data;
  1128.           int      *data_size;
  1129.  
  1130.  
  1131.  
  1132.         o Description
  1133.  
  1134.         This function is used to read the last record from a 
  1135.         data file.  The data file is specified by df and user_data 
  1136.         points to the destination buffer for the record.
  1137.  
  1138.  
  1139.  
  1140.         o Returns
  1141.  
  1142.                 The data record is read into the buffer pointed to by
  1143.                 user_data. If the file type is Variable, the length of
  1144.         the record read is placed in data_size. The read record 
  1145.         becomes the Current Record for this data file. The 
  1146.         completion status is returned in the global db_error. 
  1147.         A non-zero value indicates an error.
  1148.  
  1149.  
  1150.         +--------------+       ----------------------        +--------------+
  1151.         | db_read_next |       -  Read Next Record  -        | db_read_next |
  1152.         +--------------+       ----------------------        +--------------+
  1153.  
  1154.  
  1155.  
  1156.         o Summary
  1157.  
  1158.                 #include <db.h>
  1159.  
  1160.                 void db_read_next(df, user_data, data_size)
  1161.                   DATA_FILE  df;
  1162.                   void     *user_data;
  1163.           int      *data_size;
  1164.  
  1165.  
  1166.  
  1167.         o Description
  1168.  
  1169.                 This function is used to read the next record from a 
  1170.         data file.  The data file is specified by df and user_data 
  1171.         points to the destination buffer for the record.
  1172.  
  1173.                 This function must be preceeded by some function that 
  1174.                 establishes the Current Record for the data file. For 
  1175.         example db_read_first followed by db_read_next until end 
  1176.         of file occurs. The value of Current Record is reset to 
  1177.         NONE by a db_add.
  1178.  
  1179.  
  1180.  
  1181.         o Returns
  1182.  
  1183.                 The data record is read into the buffer pointed to by
  1184.                 user_data. If the file type is Variable, the length of
  1185.         the record read is placed in data_size. The read record 
  1186.         becomes the Current Record for this data file. The 
  1187.         completion status is returned in the global db_error. 
  1188.         A non-zero value indicates an error.
  1189.  
  1190.  
  1191.         +--------------+       ----------------------        +--------------+
  1192.     | db_read_prev |       -  Read Prev Record  -         | db_read_prev |
  1193.         +--------------+       ----------------------        +--------------+
  1194.  
  1195.  
  1196.  
  1197.         o Summary
  1198.  
  1199.                 #include <db.h>
  1200.  
  1201.         void db_read_prev(df, user_data, data_size)
  1202.                   DATA_FILE  df;
  1203.                   void     *user_data;
  1204.           int      *data_size;
  1205.  
  1206.  
  1207.  
  1208.         o Description
  1209.  
  1210.         This function is used to read the previous record from a 
  1211.         data file. The data file is specified by df and user_data 
  1212.         points to the destination buffer for the record.
  1213.  
  1214.                 This function must be preceeded by some function that 
  1215.                 establishes the Current Record for the data file. For 
  1216.         example db_read_last followed by db_read_prev until end 
  1217.         of file occurs. The value of Current Record is reset to 
  1218.         NONE by a db_add. 
  1219.  
  1220.         db_read_prev should not be used with db_delete. db_delete
  1221.         positions the current pointer so that a db_read_next will
  1222.         be correct. A db_read_prev loop with deletes will skip
  1223.         records.
  1224.  
  1225.  
  1226.  
  1227.         o Returns
  1228.  
  1229.                 The data record is read into the buffer pointed to by
  1230.                 user_data. If the file type is Variable, the length of
  1231.         the record read is placed in data_size. The read record 
  1232.         becomes the Current Record for this data file. The 
  1233.         completion status is returned in the global db_error. 
  1234.         A non-zero value indicates an error.
  1235.  
  1236.  
  1237.  
  1238.         +----------+         ---------------------------         +----------+
  1239.         | db_reorg |         -  Reorganize Free Space  -         | db_reorg |
  1240.         +----------+         ---------------------------         +----------+
  1241.  
  1242.  
  1243.  
  1244.         o Summary
  1245.  
  1246.                 #include <db.h>
  1247.  
  1248.                 void db_reorg(df)
  1249.                   DATA_FILE  df;
  1250.  
  1251.  
  1252.  
  1253.         o Description
  1254.  
  1255.         When a VAR file record is deleted, the record is marked
  1256.         as deleted but still remains in the file. This function
  1257.         is used to reclaim the space held by deleted records.
  1258.         It is only valid for VAR files.
  1259.  
  1260.  
  1261.  
  1262.         o Returns
  1263.  
  1264.                 The completion status is returned in the global db_error. 
  1265.                 A non-zero value indicates an error.
  1266.  
  1267.         +-----------+      -------------------------------      +-----------+
  1268.         | db_update |      -  Update the Current Record  -      | db_update |
  1269.         +-----------+      -------------------------------      +-----------+
  1270.  
  1271.  
  1272.  
  1273.         o Summary
  1274.  
  1275.                 #include <db.h>
  1276.  
  1277.                 void db_update(df, user_data)
  1278.                   DATA_FILE  df;
  1279.                   void     *user_data;
  1280.  
  1281.  
  1282.  
  1283.         o Description
  1284.  
  1285.                 This function is used to update the Current Record for the
  1286.                 data file specified by df. The contents of the data record
  1287.                 pointed to by user_data are written back to the data file.
  1288.  
  1289.                 This function must be preceeded by some function that 
  1290.                 establishes the Current Record for the data file.
  1291.  
  1292.  
  1293.  
  1294.         o Returns
  1295.  
  1296.                 The completion status is returned in the global db_error. 
  1297.                 A non-zero value indicates an error. The Current Record
  1298.                 for the data file is reset to NONE.
  1299.  
  1300.  
  1301.         +---------------+    ---------------------------    +---------------+
  1302.         | db_update_atr |    -  Update Attribute Data  -    | db_update_atr |
  1303.         +---------------+    ---------------------------    +---------------+
  1304.  
  1305.  
  1306.  
  1307.         o Summary
  1308.  
  1309.                 #include <db.h>
  1310.  
  1311.                 void db_update_atr(df, user_data)
  1312.                   DATA_FILE  df;                 
  1313.                   void     *user_data;
  1314.  
  1315.  
  1316.  
  1317.         o Description
  1318.  
  1319.                 This function is used to update the attribute record for a
  1320.                 data file. The data file is specified by df and user_data
  1321.                 points to the source buffer to be written to the attribute
  1322.                 area for the data file.
  1323.  
  1324.                 The attribute data is a single user record that may be 
  1325.         used to store some global data for the data file.
  1326.  
  1327.  
  1328.  
  1329.  
  1330.         o Returns
  1331.  
  1332.                 The completion status is returned in the global db_error.
  1333.                 A non-zero value indicates an error.
  1334.  
  1335.  
  1336.         +-------------+     ------------------------------     +-------------+
  1337.         | fname_dflts |     -  Merge File Name Defaults  -     | fname_dflts |
  1338.         +-------------+     ------------------------------     +-------------+
  1339.  
  1340.  
  1341.  
  1342.         o Summary
  1343.  
  1344.                 char *fname_dflts(fname, dflt)
  1345.                   char *fname, *dflt;
  1346.  
  1347.  
  1348.  
  1349.         o Description
  1350.  
  1351.                 This function merges a file name string with a
  1352.                 default file name. For example the following would
  1353.                 force a default extension of ".c" if no extension
  1354.                 was present.
  1355.  
  1356.                         x = fname_dflts(fname,".c");
  1357.  
  1358.  
  1359.  
  1360.         o Returns
  1361.  
  1362.                 A pointer to the resulting static string is returned.
  1363.  
  1364.  
  1365.         +--------+           -----------------------              +--------+
  1366.         | fparse |           -  Parse a File Spec  -              | fparse |
  1367.         +--------+           -----------------------              +--------+
  1368.  
  1369.  
  1370.  
  1371.         o Summary
  1372.  
  1373.                 fparse(fstr, o_node, o_dev, o_dir, o_file, o_ext, o_ver)
  1374.                   char *fstr, *o_node, *o_dev, *o_dir, *o_file, *o_ext, *o_ver;
  1375.  
  1376.  
  1377.  
  1378.         o Description
  1379.  
  1380.                 This function parses a file specification fstr into component
  1381.                 parts. Not all of these components apply to generic MS-DOS.
  1382.  
  1383.                         o_node  - Node name
  1384.                         o_dev   - Device name
  1385.                         o_dir   - Directory Path
  1386.                         o_file  - File name
  1387.                         o_ext   - File extension
  1388.                         o_ver   - Version number
  1389.  
  1390.  
  1391.  
  1392.         o Returns
  1393.  
  1394.                 The component strings are copied into the buffers pointed
  1395.                 to by the o_* args.
  1396.  
  1397.  
  1398.         +------+              --------------------------             +------+
  1399.         | sort |              -  Callable Record Sort  -             | sort |
  1400.         +------+              --------------------------             +------+
  1401.  
  1402.  
  1403.  
  1404.         o Summary
  1405.  
  1406.                 void  sort_init(rec_size, spec_str)
  1407.                   int   rec_size;
  1408.                   char *spec_str;
  1409.  
  1410.                 void  sort_release(data_rec)
  1411.                   char *data_rec;
  1412.  
  1413.                 void  sort_merge()
  1414.  
  1415.                 char *sort_return(data_rec)
  1416.                   char *data_rec;
  1417.  
  1418.  
  1419.  
  1420.         o Description
  1421.  
  1422.                 This set of functions provides a callable record sort
  1423.                 facility:
  1424.  
  1425.                 sort_init - Initialize the sort. This must be done first.
  1426.                             rec_size = the size of the data record
  1427.                             spec_str = string of sort specs separated
  1428.                                        by commas. "spec,spec,spec..."
  1429.                             spec     = XXn.n
  1430.                                        ||| |
  1431.                                        ||| +--- size of field     (bytes)
  1432.                                        ||+----- starting position (1 relative)
  1433.                                        ||
  1434.                                        |+------ Format   A = Alpha
  1435.                                        |                 U = Unsigned integer
  1436.                                        |                 I = Integer
  1437.                                        |                 R = Real
  1438.                                        |
  1439.                                        +------- Sequence A = Ascending
  1440.                                                          D = Descending
  1441.  
  1442.                 sort_release - Release a record to the sort. data_rec
  1443.                                points to the data.
  1444.  
  1445.                 sort_merge   - Do the sort merge operation.
  1446.  
  1447.                 sort_return  - Return a record from the sort and put
  1448.                                it in data_rec. A pointer to the data
  1449.                                record is returned. A NULL value indicates
  1450.                                end of file.
  1451.  
  1452.  
  1453.  
  1454.         o Returns
  1455.  
  1456.                 If a sort error occurs an error message is printed and
  1457.                 the program aborts.
  1458.  
  1459.