home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / database / cdb112.zip / CDB.DOC next >
Text File  |  1991-01-31  |  42KB  |  1,546 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.                       C DataBase Management System (CDB)
  23.  
  24.  
  25.                                  Version 1.12
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.                         Copyright (C) 1989, 1990, 1991
  54.                                       by
  55.                           Daytris Information Systems
  56.  
  57.  
  58.  
  59.  
  60.  
  61.                                  Introduction
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.     CDB is a complete database development kit designed for C programmers.
  76.  
  77.     CDB is based on the NETWORK database model and uses the ISAM method-
  78.     ology for key file management.  The NETWORK database model is the latest
  79.     concept in database management.  The kit also uses the advanced concept
  80.     of a Data Definition Language (DDL).  Using the DDL, a developer can
  81.     design and re-design their database with minimal effort and absolutely
  82.     no code changes.
  83.  
  84.     CDB is written completely in C for portability and the source code is
  85.     available from the authors upon registration.  See the registration
  86.     form in the latter part of this manual.
  87.  
  88.     CDB is compatible with both Microsoft C and Turbo C.  Large models only.
  89.     However, the code is extremely portable.  This version of CDB is also a
  90.     single user version.  A LAN version is not currently available.
  91.  
  92.     All support will be conviently handled for the present via electronic
  93.     mail using the CompuServe ID indicated below or call directly.
  94.  
  95.     Developer:  Todd C. Fearn
  96.                 Daytris Information Systems
  97.                 81 Bright Street, Suite 1E
  98.                 Jersey City, NJ 07302
  99.                 (201) 332-5228
  100.                 CompuServe ID 72500,1426
  101.  
  102.  
  103.  
  104.                           Database Development Files
  105.  
  106.  
  107.  
  108.         These files are contained in the ARC file CDB.ARC:
  109.  
  110.         CDB.DOC         This file
  111.         UPDATES.DOC     A history of CDB modifications
  112.         MSCCDB.LIB      Microsoft C database development library
  113.         TCCDB.LIB       Turbo C database development library
  114.         DDLP.EXE        Data Definition Language Parser
  115.         DBDLIST.EXE     Database Definition (DBD) file display utility
  116.         DBMGR.H         Database development header file
  117.         TEST.DDL        Example DDL (Data Definition Language) file
  118.         TEST.C          Example CDB development file
  119.       * MSCTEST.MAK     Microsoft C test.c make file
  120.       * TCTEST.MAK      Turbo C test.c make file
  121.  
  122.  
  123.         These files are contained in the ARC file CDBSRC.ARC:
  124.         (Received upon registration)
  125.  
  126.         DBMGR.C         CDB source files
  127.         DBFIND.C
  128.         DBGET.C
  129.         DBADD.C
  130.         DBUPD.C
  131.         DBDEL.C
  132.         DBCURR.C
  133.         DBPAGE.C
  134.         DBSLOT.C
  135.         DBFILE.C
  136.         DBFUNCS.C
  137.         STDINC.H        CDB header files
  138.         DBXTRN.H
  139.       * MSCLIB.MAK      Microsoft C CDB library make file
  140.       * TCLIB.MAK       Turbo C CDB library make file
  141.  
  142.         MAIN.C          DDLP source files
  143.         PARSE.C
  144.         DDLP.C
  145.         ERROR.C
  146.         DDLP.H          DDLP header file
  147.       * DDLP.MAK        DDLP make file
  148.  
  149.         DBDLIST.C       DBDLIST source file
  150.       * DBDLIST.MAK     DBDLIST make file
  151.  
  152.  
  153.     * All make files are Unix Make compatible.
  154.  
  155.  
  156.  
  157.                         Data Definition Language (DDL)
  158.  
  159.  
  160.     The Data Definition Language is used to define your database.  DDLP
  161.     (Data Definition Language Parser) is used to create a .DBD (Database
  162.     Definition) file from the DDL.  The .DBD file is read into memory
  163.     when the database is opened and is used as a map into this particular
  164.     database.  DDLP will also output a C header file defining your data-
  165.     base records in a standard C format.
  166.  
  167.     This concept allows you to change your database model at will during
  168.     the development cycle of your project without changing one line of
  169.     development code.
  170.  
  171.     A sample DDL (test.ddl) is included in this kit.  Notice that the DDL
  172.     is very similar to a C header file.  The only differences from a
  173.     standard C header file are the keywords: PREFIX, CONNECT, and KEY.
  174.  
  175.  
  176.     PREFIX
  177.  
  178.     Before we can discuss this prefix, you must first know how the database
  179.     files are created.  For each record defined in the DDL, a separate
  180.     data and a separate key file will be created when you add the first
  181.     record of this type.  The key file will only be created if you have
  182.     a key field in the record.  The data file for the first record in the
  183.     DBD is named XXXX0001.DAT where XXXX is the predefined prefix.  The
  184.     key file is named XXXX0001.KEY.
  185.  
  186.     The prefix can be up to 4 characters.  This prefix is not required.
  187.     For example, if you choose a prefix of "ABC" as shown in test.ddl, when
  188.     the first record of the first file is added, two files will be created.
  189.     They will be ABC0001.KEY and ABC0001.DAT.
  190.  
  191.     Note: Keep in mind that the first record in the DDL may not correspond
  192.           to the file name XXXX0001.XXX.  This is because DDLP rearranges
  193.           the records in alphabetic order when it creates the DBD.  So the
  194.           XXXX0001.XXX file will correspond to the alphabetically lowest
  195.           record value in the DDL.
  196.  
  197.  
  198.     CONNECT
  199.  
  200.     This keyword allows you to make connections between records without
  201.     physically storing keys in each record to connect them.
  202.  
  203.     For example, if you would like to connect an "Invoice" to a "Customer"
  204.     using the old relational concept, you must store a unique key in both
  205.     records and then retrieve the records using the unique key.  Using
  206.     CDB, once you add the "Customer" and the "Invoice", you can make a
  207.     set connection between the two records using the "DbSetAdd" macro.
  208.     DbSetAdd( "Customer", "Invoice");  "Customer" becomes the owner of the
  209.     "Invoice".  "Invoice" is a member of that particular "Customer".  The
  210.     connection is only possible if you have defined in the "Customer"
  211.     record a connection to the "Invoice" record.  This is a one-to-many
  212.     relationship.
  213.  
  214.  
  215.  
  216.     To create a many-to-many relationship using the same example, a
  217.     "connect customer;" placed in the "Invoice" record would enable you to
  218.     make the "Customer" a member record of the "Invoice".  Using the macro
  219.     DbSetAdd( "Invoice", "Customer"); would make the set connection.
  220.     Although you may rarely see the need for a many-to-many relationship,
  221.     the power to do so is available.
  222.  
  223.  
  224.     KEY
  225.  
  226.     This keyword simply defines a key field for a record.  You can have
  227.     up to 8 keys per record and the maximum size of a key field is 256
  228.     bytes.  If you have registered and have the source code, these
  229.     limitations can be overcome very easily by modifying #define values.
  230.     If a record is defined with no keys, that record cannot be accessed
  231.     unless there is a set connection to that particular record.
  232.  
  233.  
  234.  
  235.                                   Utilities
  236.  
  237.  
  238.  
  239.     DDLP.EXE
  240.  
  241.     DDLP is the DDL parser (compiler) that creates a DataBase Definition
  242.     file (.DBD) from the DDL.  This .DBD file is used as a map into the
  243.     database when this database is opened.  DDLP also creates a header
  244.     file from the DDL for use in your C program.
  245.  
  246.     Usage: DDLP filename(.ddl)
  247.  
  248.  
  249.  
  250.  
  251.     DBDLIST.EXE
  252.  
  253.     DBDLIST is a DBD display utility.  Using this utility you can display
  254.     the internal contents of a .DBD file.
  255.  
  256.     Usage: DBDLIST filename.dbd
  257.  
  258.  
  259.  
  260.                          Modifying the Database Design
  261.  
  262.  
  263.  
  264.     It is very simple to modify the general database design by changing
  265.     some of the defined values in DBMGR.H.
  266.  
  267.  
  268.     #define NBRHANDLES 12
  269.  
  270.     This value is the number of file handles allowed to be open by the
  271.     database at one time.  If you have a database with a large number of
  272.     records, it is a good idea to leave this value alone or increase it
  273.     slightly.  Remember that the maximum number of file handles available
  274.     for a process under DOS is 20 and the system uses 5.  If your database
  275.     has only a few records, it may be a good idea to lower this value.
  276.  
  277.     For example, suppose your database has only 3 records.  Each has at
  278.     least one key field.  Since the maximum number of files for this
  279.     database is 6, you should reduce the NBRHANDLES to 6.
  280.  
  281.     The file handles are opened and closed using an LRU (least recently
  282.     used) algorithm for maximum file handle management.
  283.  
  284.  
  285.     #define MAXKEY 8
  286.  
  287.     This value is the maximum number of keys that a single record can have.
  288.     You can adjust this value according to your usage.  It is recommended
  289.     that this value be a power of 2.
  290.  
  291.  
  292.     #define KEYPAGESIZE 512
  293.  
  294.     This value is the size of a page for the .key data files.  The keys
  295.     in the database are stored on pages in a sorted order.  The pages are
  296.     linked together through a link list.  If your database key fields are
  297.     very large, you may wish to increase this value to store more keys on
  298.     a page.  Note: The larger the key page size, the longer the access
  299.     time for read and writing.  It is recommended that this value be a
  300.     power of 2.
  301.  
  302.  
  303.     #define NBRPAGES 16
  304.  
  305.     This value is the number of key pages that are buffered in RAM.  These
  306.     buffers are accessed using an LRU (least recently used) algorithm for
  307.     maximum page management.
  308.  
  309.  
  310.     #define DATAPAGESIZE 2048
  311.  
  312.     This value is the size of a page for the .dat data files.  Each record
  313.     is stored in slots on pages in the data files.  Each slot has some
  314.     reserved information at beginning of each slot.  It is recommended that
  315.     this value be a power of 2.
  316.  
  317.  
  318.  
  319.     #define DATASLOTSIZE 1024
  320.  
  321.     This value is the maximum size of a data slot.  Each data file is made
  322.     up of pages which consist of a group of slots.  You will need to
  323.     increase this value if any of your record sizes, when plugged into the
  324.     formula below, exceed 1024.
  325.  
  326.     Formula: (C structure byte length) + 6 +
  327.              (number of owners of this record * 8) +
  328.              (number of members of this record * 12) > 1024
  329.  
  330.     If you have very large C structures you should check them.  It is
  331.     recommended that DATASLOTSIZE be a power of 2.
  332.  
  333.  
  334.  
  335.                              Database Macro Index
  336.  
  337.  
  338.  
  339.  
  340.  
  341.     General Database Macros
  342.  
  343.     void DbClose( void);
  344.     void DbFlush( void);
  345.     int  DbOpen( char *database);
  346.  
  347.  
  348.     Record Macros
  349.  
  350.     int  DbRecordAdd( char *record, char *source);
  351.     int  DbRecordDelete( char *record);
  352.     int  DbRecordFindByKey( char *record, char *field, char *key);
  353.     int  DbRecordFindFirst( char *record, char *field);
  354.     int  DbRecordFindLast( char *record, char *field);
  355.     int  DbRecordFindNext( char *record, char *field);
  356.     int  DbRecordFindPrev( char *record, char *field);
  357.     int  DbRecordGetCurrency( char *record, char *currency);
  358.     int  DbRecordGetByKey( char *record, char *field, char *target, char *key);
  359.     int  DbRecordGetCurrent( char *record, char *field, char *target);
  360.     int  DbRecordGetFirst( char *record, char *field, char *target);
  361.     int  DbRecordGetLast( char *record, char *field, char *target);
  362.     int  DbRecordGetNext( char *record, char *field, char *target);
  363.     int  DbRecordGetPrev( char *record, char *field, char *target);
  364.     int  DbRecordUpdate( char *record, char *source);
  365.     int  DbRecordUpdCurrency( char *record, char *currency);
  366.  
  367.  
  368.     Set Macros
  369.  
  370.     int  DbSetAdd( char *owner, char *member);
  371.     int  DbSetDelete( char *owner, char *member);
  372.     int  DbSetFindFirst( char *owner, char *member);
  373.     int  DbSetFindLast( char *owner, char *member);
  374.     int  DbSetFindNext( char *owner, char *member);
  375.     int  DbSetFindPrev( char *owner, char *member);
  376.     int  DbSetGetFirst( char *owner, char *member, char *target);
  377.     int  DbSetGetLast( char *owner, char *member, char *target);
  378.     int  DbSetGetNext( char *owner, char *member, char *target);
  379.     int  DbSetGetOwner( char *owner, char *member, char *target);
  380.     int  DbSetGetPrev( char *owner, char *member, char *target);
  381.  
  382.  
  383.     All database macros call the function "dbc" to provide one central
  384.     entry and exit point in the database.
  385.  
  386.  
  387.  
  388.  
  389.     DbClose
  390.     -------------------------------------------------------------------------
  391.  
  392.  
  393.  
  394.     void DbClose( void);
  395.  
  396.  
  397.     Description
  398.  
  399.         This call closes the database that is currently open.
  400.  
  401.  
  402.     Example
  403.  
  404.         #include <dbmacro.h>
  405.  
  406.         main()
  407.             {
  408.             strcpy( dbpath, "\\PROJECT\\DATA");
  409.  
  410.             if( DbOpen( "test.dbd"))
  411.                 {
  412.                 ...error handling
  413.                 }
  414.  
  415.                 .
  416.                 .
  417.                 .
  418.  
  419.             Dbclose();
  420.             }
  421.  
  422.  
  423.  
  424.  
  425.     DbFlush
  426.     -------------------------------------------------------------------------
  427.  
  428.  
  429.  
  430.     void DbFlush( void);
  431.  
  432.  
  433.     Description
  434.  
  435.         This function forces all data written to the database to disk.
  436.  
  437.  
  438.     Example
  439.  
  440.         #include <dbmacro.h>
  441.  
  442.         Function()
  443.             {
  444.             DbRecordUpdate( "customer", &customer);
  445.  
  446.             DbFlush();
  447.             }
  448.  
  449.  
  450.  
  451.  
  452.     DbOpen
  453.     -------------------------------------------------------------------------
  454.  
  455.  
  456.  
  457.     int DbOpen( database);
  458.         char *database;                         Database name
  459.  
  460.  
  461.     Description
  462.  
  463.         This call opens a database.  The database must be a DBD (DataBase
  464.         dictionary) created using DDLP.  Only one database can be opened at
  465.         a time.  The global "dbpath" buffer can be used to define the
  466.         database path.  If "dbpath" is not set, the default path is the
  467.         current directory.
  468.         
  469.  
  470.     Example
  471.  
  472.         #include <dbmacro.h>
  473.  
  474.         main()
  475.             {
  476.             strcpy( dbpath, "\\PROJECT\\DATA");
  477.  
  478.             if( DbOpen( "test.dbd"))
  479.                 {
  480.                 ...error handling
  481.                 }
  482.             }
  483.  
  484.  
  485.  
  486.  
  487.     DbRecordAdd
  488.     -------------------------------------------------------------------------
  489.  
  490.  
  491.  
  492.     int DbRecordAdd( record, source);
  493.         char *record;                           Record name
  494.         char *source;                           Source pointer
  495.         
  496.  
  497.     Description
  498.         Add a record to the database.
  499.  
  500.  
  501.     Example
  502.  
  503.         #include <dbmacro.h>
  504.  
  505.         Function()
  506.             {
  507.             struct CustomerTable customer;
  508.  
  509.                 .
  510.                 .
  511.                 .
  512.             fill record
  513.                 .
  514.                 .
  515.                 .
  516.  
  517.             if( DbRecordAdd( "customer", (char *)&customer))
  518.                 printf( "Error: adding customer record\n");
  519.             }
  520.  
  521.  
  522.  
  523.  
  524.     DbRecordDelete
  525.     -------------------------------------------------------------------------
  526.  
  527.  
  528.  
  529.     int DbRecordDelete( record);
  530.         char *record;                           Record name
  531.         
  532.  
  533.     Description
  534.         Delete a record in the database.  The record you wish to delete must
  535.         be current.
  536.  
  537.  
  538.     Example
  539.  
  540.         #include <dbmacro.h>
  541.  
  542.         Function()
  543.             {
  544.             long accountNbr = 1000L;
  545.             struct CustomerTable customer;
  546.  
  547.  
  548.             if( DbRecordFindByKey( "customer", "acctnbr",
  549.                 (char *)&accountNbr))
  550.                 {
  551.                 printf( "Error: finding customer record\n");
  552.                 }
  553.  
  554.             if( DbRecordDelete( "customer"))
  555.                 printf( "Error: deleting customer record);
  556.             }
  557.  
  558.  
  559.  
  560.  
  561.     DbRecordFindByKey
  562.     -------------------------------------------------------------------------
  563.  
  564.  
  565.  
  566.     int DbRecordFindByKey( record, field, key);
  567.         char *record;                           Record name
  568.         char *field;                            Key field name
  569.         char *key;                              Key value used in search
  570.         
  571.  
  572.     Description
  573.         Find a specific record using a key field and a key value.  If the
  574.         exact match cannot be found the function will return E_NEXTGUESS
  575.         specifying that the match returned is the next best guess.
  576.  
  577.  
  578.     Example
  579.  
  580.         #include <dbmacro.h>
  581.  
  582.         Function()
  583.             {
  584.             unsigned long accountNbr = 1000L;
  585.  
  586.             if( DbRecordFindByKey( "customer", "acctnbr",
  587.                 (char *)&accountNbr))
  588.                 {
  589.                 printf( "Error: customer not found\n");
  590.                 }
  591.  
  592.             if( DbRecordFindByKey( "customer", "company",
  593.                 "Charter Insurance Inc."))
  594.                 {
  595.                 printf( "Error: customer not found\n");
  596.                 }
  597.             }
  598.  
  599.  
  600.  
  601.  
  602.     DbRecordFindFirst
  603.     -------------------------------------------------------------------------
  604.  
  605.  
  606.  
  607.     int DbRecordFindFirst( record, field);
  608.         char *record;                           Record name
  609.         char *field;                            Key field name
  610.         
  611.  
  612.     Description
  613.         Find the first record of a certain record type.  The record must be
  614.         retreived using a key field.
  615.  
  616.  
  617.     Example
  618.  
  619.         #include <dbmacro.h>
  620.  
  621.         Function()
  622.             {
  623.             if( DbRecordFindFirst( "customer", "zipcode"))
  624.                 printf( "Error: customer not found\n");
  625.             }
  626.  
  627.  
  628.  
  629.  
  630.     DbRecordFindLast
  631.     -------------------------------------------------------------------------
  632.  
  633.  
  634.  
  635.     int DbRecordFindLast( record, field);
  636.         char *record;                           Record name
  637.         char *field;                            Key field name
  638.         
  639.  
  640.     Description
  641.         Find the last record of a certain record type.  The record must be
  642.         retreived using a key field.
  643.  
  644.  
  645.     Example
  646.  
  647.         #include <dbmacro.h>
  648.  
  649.         Function()
  650.             {
  651.             if( DbRecordFindLast( "customer", "zipcode"))
  652.                 printf( "Error: customer not found\n");
  653.             }
  654.  
  655.  
  656.  
  657.  
  658.     DbRecordFindNext
  659.     -------------------------------------------------------------------------
  660.  
  661.  
  662.  
  663.     int DbRecordFindNext( record, field);
  664.         char *record;                           Record name
  665.         char *field;                            Key field name
  666.         
  667.  
  668.     Description
  669.         Find the next record of a certain record type.  The record must be
  670.         retreived using a key field.
  671.  
  672.  
  673.     Example
  674.  
  675.         #include <dbmacro.h>
  676.  
  677.         Function()
  678.             {
  679.             if( DbRecordFindNext( "customer", "zipcode"))
  680.                 printf( "Error: customer not found\n");
  681.             }
  682.  
  683.  
  684.  
  685.  
  686.     DbRecordFindPrev
  687.     -------------------------------------------------------------------------
  688.  
  689.  
  690.  
  691.     int DbRecordFindPrev( record, field);
  692.         char *record;                           Record name
  693.         char *field;                            Key field name
  694.         
  695.  
  696.     Description
  697.         Find the previous record of a certain record type.  The record must
  698.         be retreived using a key field.
  699.  
  700.  
  701.     Example
  702.  
  703.         #include <dbmacro.h>
  704.  
  705.         Function()
  706.             {
  707.             if( DbRecordFindLast( "customer", "zipcode"))
  708.                 printf( "Error: customer not found\n");
  709.             }
  710.  
  711.  
  712.  
  713.  
  714.     DbRecordGetCurrency
  715.     -------------------------------------------------------------------------
  716.  
  717.  
  718.  
  719.     int DbRecordGetCurrency( record, currency);
  720.         char *record;                           Record name
  721.         char *currency;                         Ptr to currency record
  722.  
  723.  
  724.     Description
  725.  
  726.         This function allows you to save the current position (currency) of
  727.         a specific record type.
  728.  
  729.  
  730.     Example
  731.  
  732.         #include <dbmacro.h>
  733.  
  734.         Function()
  735.             {
  736.             struct currency_index currency;
  737.  
  738.             DbRecordGetCurrency( (char *)¤cy, "customer");
  739.  
  740.                 .
  741.                 .
  742.                 .
  743.             processing
  744.                 .
  745.                 .
  746.                 .
  747.  
  748.             DbRecordUpdCurrency( (char *)¤cy, "customer");
  749.             }
  750.  
  751.  
  752.  
  753.  
  754.     DbRecordGetByKey
  755.     -------------------------------------------------------------------------
  756.  
  757.  
  758.  
  759.     int DbRecordGetByKey( record, field, target, key);
  760.         char *record;                           Record name
  761.         char *field;                            Key field name
  762.         char *target;                           Destination pointer
  763.         char *key;                              Key value used in search
  764.         
  765.  
  766.     Description
  767.         Get a specific record using a key field and a key value.  If the
  768.         exact match cannot be found the function will return E_NEXTGUESS
  769.         specifying that the match returned is the next best guess.
  770.  
  771.  
  772.     Example
  773.  
  774.         #include <dbmacro.h>
  775.  
  776.         Function()
  777.             {
  778.             unsigned long accountNbr = 1000L;
  779.             struct CustomerTable customer;
  780.  
  781.             if( DbRecordGetByKey( "customer", "acctnbr", (char *)&customer,
  782.                 (char *)&accountNbr))
  783.                 {
  784.                 printf( "Error: customer not found\n");
  785.                 }
  786.  
  787.             if( DbRecordGetByKey( "customer", "company", (char *)&customer,
  788.                 "Charter Insurance Inc."))
  789.                 {
  790.                 printf( "Error: customer not found\n");
  791.                 }
  792.             }
  793.  
  794.  
  795.  
  796.  
  797.     DbRecordGetCurrent
  798.     -------------------------------------------------------------------------
  799.  
  800.  
  801.  
  802.     int DbRecordGetCurrent( record, field, target);
  803.         char *record;                           Record name
  804.         char *field;                            Key field name
  805.         char *target;                           Destination pointer
  806.         
  807.  
  808.     Description
  809.         This function will retreive the current record of a specific record
  810.         type using the currency table for that record.  The record must be
  811.         retreived using a key field.
  812.  
  813.  
  814.     Example
  815.  
  816.         #include <dbmacro.h>
  817.  
  818.         Function()
  819.             {
  820.             struct CustomerTable customer;
  821.  
  822.             DbRecordGetCurrent( "customer", "zipcode", (char *)&customer);
  823.             }
  824.  
  825.  
  826.  
  827.  
  828.     DbRecordGetFirst
  829.     -------------------------------------------------------------------------
  830.  
  831.  
  832.  
  833.     int DbRecordGetFirst( record, field, target);
  834.         char *record;                           Record name
  835.         char *field;                            Key field name
  836.         char *target;                           Destination pointer
  837.         
  838.  
  839.     Description
  840.         Get the first record of a certain record type.  The record must be
  841.         retreived using a key field.
  842.  
  843.  
  844.     Example
  845.  
  846.         #include <dbmacro.h>
  847.  
  848.         Function()
  849.             {
  850.             struct CustomerTable customer;
  851.  
  852.             if( DbRecordGetFirst( "customer", "zipcode", (char *)&customer))
  853.                 printf( "Error: customer not found\n");
  854.             }
  855.  
  856.  
  857.  
  858.  
  859.     DbRecordGetLast
  860.     -------------------------------------------------------------------------
  861.  
  862.  
  863.  
  864.     int DbRecordGetLast( record, field, target);
  865.         char *record;                           Record name
  866.         char *field;                            Key field name
  867.         char *target;                           Destination pointer
  868.         
  869.  
  870.     Description
  871.         Get the last record of a certain record type.  The record must be
  872.         retreived using a key field.
  873.  
  874.  
  875.     Example
  876.  
  877.         #include <dbmacro.h>
  878.  
  879.         Function()
  880.             {
  881.             struct CustomerTable customer;
  882.  
  883.             if( DbRecordGetLast( "customer", "zipcode", (char *)&customer))
  884.                 printf( "Error: customer not found\n");
  885.             }
  886.  
  887.  
  888.  
  889.  
  890.     DbRecordGetNext
  891.     -------------------------------------------------------------------------
  892.  
  893.  
  894.  
  895.     int DbRecordGetNext( record, field, target);
  896.         char *record;                           Record name
  897.         char *field;                            Key field name
  898.         char *target;                           Destination pointer
  899.         
  900.  
  901.     Description
  902.         Get the next record of a certain record type.  The record must be
  903.         retreived using a key field.
  904.  
  905.  
  906.     Example
  907.  
  908.         #include <dbmacro.h>
  909.  
  910.         Function()
  911.             {
  912.             struct CustomerTable customer;
  913.  
  914.             if( DbRecordGetNext( "customer", "zipcode", (char *)&customer))
  915.                 printf( "Error: customer not found\n");
  916.             }
  917.  
  918.  
  919.  
  920.  
  921.     DbRecordGetPrev
  922.     -------------------------------------------------------------------------
  923.  
  924.  
  925.  
  926.     int DbRecordGetPrev( record, field, target);
  927.         char *record;                           Record name
  928.         char *field;                            Key field name
  929.         char *target;                           Destination pointer
  930.         
  931.  
  932.     Description
  933.         Get the previous record of a certain record type.  The record must be
  934.         retreived using a key field.
  935.  
  936.  
  937.     Example
  938.  
  939.         #include <dbmacro.h>
  940.  
  941.         Function()
  942.             {
  943.             struct CustomerTable customer;
  944.  
  945.             if( DbRecordGetPrev( "customer", "zipcode", (char *)&customer))
  946.                 printf( "Error: customer not found\n");
  947.             }
  948.  
  949.  
  950.  
  951.  
  952.     DbRecordUpdate
  953.     -------------------------------------------------------------------------
  954.  
  955.  
  956.  
  957.     int DbRecordUpdate( record, source);
  958.         char *record;                           Record name
  959.         char *source;                           Source pointer
  960.         
  961.  
  962.     Description
  963.         Update a record in the database.  The record you wish to update must
  964.         be current.
  965.  
  966.  
  967.     Example
  968.  
  969.         #include <dbmacro.h>
  970.  
  971.         Function()
  972.             {
  973.             long accountNbr = 1000L;
  974.             struct CustomerTable customer;
  975.  
  976.  
  977.             if( DbRecordGetByKey( "customer", "acctnbr", (char *)&customer,
  978.                 (char *)&accountNbr))
  979.                 {
  980.                 printf( "Error: getting customer record\n");
  981.                 }
  982.  
  983.                 .
  984.                 .
  985.                 .
  986.             modify record
  987.                 .
  988.                 .
  989.                 .
  990.  
  991.             if( DbRecordUpdate( "customer", (char *)&customer))
  992.                 printf( "Error: updating customer record);
  993.             }
  994.  
  995.  
  996.  
  997.  
  998.     DbRecordUpdCurrency
  999.     -------------------------------------------------------------------------
  1000.  
  1001.  
  1002.  
  1003.     int DbRecordUpdCurrency( record, currency);
  1004.         char *record;                           Record name
  1005.         char *currency;                         Ptr to currency record
  1006.  
  1007.  
  1008.     Description
  1009.  
  1010.         This function allows you to update the current position (currency) of
  1011.         a specific record type.
  1012.  
  1013.  
  1014.     Example
  1015.  
  1016.         #include <dbmacro.h>
  1017.  
  1018.         Function()
  1019.             {
  1020.             struct currency_index currency;
  1021.  
  1022.             DbRecordGetCurrency( (char *)¤cy, "customer");
  1023.  
  1024.                 .
  1025.                 .
  1026.                 .
  1027.             processing
  1028.                 .
  1029.                 .
  1030.                 .
  1031.  
  1032.             DbRecordUpdCurrency( (char *)¤cy, "customer");
  1033.             }
  1034.  
  1035.  
  1036.  
  1037.  
  1038.     DbSetAdd
  1039.     -------------------------------------------------------------------------
  1040.  
  1041.  
  1042.  
  1043.     int DbSetAdd( owner, member);
  1044.         char *owner;                            Owner name
  1045.         char *member;                           Member name
  1046.         
  1047.  
  1048.     Description
  1049.         Create a set connection between two records.  Both records must have
  1050.         currency before creating the set connection.
  1051.  
  1052.  
  1053.     Example
  1054.  
  1055.         #include <dbmacro.h>
  1056.  
  1057.         Function()
  1058.             {
  1059.             long accountNbr = 1000L;
  1060.  
  1061.             DbRecordFindByKey( "customer", "acctnbr", (char *)&accountNbr);
  1062.             DbFindRecordbyKey( "address", "zipcode", "99999");
  1063.  
  1064.             if( DbSetAdd( "customer", "address"))
  1065.                 printf( "Error: set connection not created\n");
  1066.             }
  1067.  
  1068.  
  1069.  
  1070.  
  1071.     DbSetDelete
  1072.     -------------------------------------------------------------------------
  1073.  
  1074.  
  1075.  
  1076.     int DbSetDelete( owner, member);
  1077.         char *owner;                            Owner name
  1078.         char *member;                           Member name
  1079.         
  1080.  
  1081.     Description
  1082.         Remove a set connection between two records.  Both records must have
  1083.         currency before removing the set connection.
  1084.  
  1085.  
  1086.     Example
  1087.  
  1088.         #include <dbmacro.h>
  1089.  
  1090.         Function()
  1091.             {
  1092.             long accountNbr = 1000L;
  1093.  
  1094.             DbRecordFindByKey( "customer", "acctnbr", (char *)&accountNbr);
  1095.             DbFindRecordbyKey( "address", "zipcode", "99999");
  1096.  
  1097.             if( DbSetDelete( "customer", "address"))
  1098.                 printf( "Error: set connection not deleted\n");
  1099.             }
  1100.  
  1101.  
  1102.  
  1103.  
  1104.     DbSetFindFirst
  1105.     -------------------------------------------------------------------------
  1106.  
  1107.  
  1108.  
  1109.     int DbSetFindFirst( owner, member);
  1110.         char *owner;                            Owner name
  1111.         char *member;                           Member name
  1112.         
  1113.  
  1114.     Description
  1115.         Find the first set connection between an owner and member record.
  1116.  
  1117.  
  1118.     Example
  1119.  
  1120.         #include <dbmacro.h>
  1121.  
  1122.         Function()
  1123.             {
  1124.             long accountNbr = 1000L;
  1125.  
  1126.             DbFindRecordbyKey( "customer", "acctnbr", (char *)&accountNbr);
  1127.  
  1128.             if( DbSetFindFirst( "customer", "address"))
  1129.                 printf( "Error: set connection not found\n");
  1130.             }
  1131.  
  1132.  
  1133.  
  1134.  
  1135.     DbSetFindLast
  1136.     -------------------------------------------------------------------------
  1137.  
  1138.  
  1139.  
  1140.     int DbSetFindLast( owner, member);
  1141.         char *owner;                            Owner name
  1142.         char *member;                           Member name
  1143.         
  1144.  
  1145.     Description
  1146.         Find the last set connection between an owner and member record.
  1147.  
  1148.  
  1149.     Example
  1150.  
  1151.         #include <dbmacro.h>
  1152.  
  1153.         Function()
  1154.             {
  1155.             long accountNbr = 1000L;
  1156.  
  1157.             DbFindRecordbyKey( "customer", "acctnbr", (char *)&accountNbr);
  1158.  
  1159.             if( DbSetFindLast( "customer", "address"))
  1160.                 printf( "Error: set connection not found\n");
  1161.             }
  1162.  
  1163.  
  1164.  
  1165.  
  1166.     DbSetFindNext
  1167.     -------------------------------------------------------------------------
  1168.  
  1169.  
  1170.  
  1171.     int DbSetFindNext( owner, member);
  1172.         char *owner;                            Owner name
  1173.         char *member;                           Member name
  1174.         
  1175.  
  1176.     Description
  1177.         Find the next set connection between an owner and member record.
  1178.  
  1179.  
  1180.     Example
  1181.  
  1182.         #include <dbmacro.h>
  1183.  
  1184.         Function()
  1185.             {
  1186.             long accountNbr = 1000L;
  1187.  
  1188.             DbFindRecordbyKey( "customer", "acctnbr", (char *)&accountNbr);
  1189.  
  1190.             if( DbSetFindFirst( "customer", "address"))
  1191.                 printf( "Error: set connection not found\n");
  1192.             if( DbSetFindNext( "customer", "address"))
  1193.                 printf( "Error: set connection not found\n");
  1194.             }
  1195.  
  1196.  
  1197.  
  1198.  
  1199.     DbSetFindPrev
  1200.     -------------------------------------------------------------------------
  1201.  
  1202.  
  1203.  
  1204.     int DbSetFindPrev( owner, member);
  1205.         char *owner;                            Owner name
  1206.         char *member;                           Member name
  1207.         
  1208.  
  1209.     Description
  1210.         Find the previous set connection between an owner and member record.
  1211.  
  1212.  
  1213.     Example
  1214.  
  1215.         #include <dbmacro.h>
  1216.  
  1217.         Function()
  1218.             {
  1219.             long accountNbr = 1000L;
  1220.  
  1221.             DbFindRecordbyKey( "customer", "acctnbr", (char *)&accountNbr);
  1222.  
  1223.             if( DbSetFindLast( "customer", "address"))
  1224.                 printf( "Error: set connection not found\n");
  1225.             if( DbSetFindPrev( "customer", "address"))
  1226.                 printf( "Error: set connection not found\n");
  1227.             }
  1228.  
  1229.  
  1230.  
  1231.  
  1232.     DbSetGetFirst
  1233.     -------------------------------------------------------------------------
  1234.  
  1235.  
  1236.  
  1237.     int DbSetGetFirst( owner, member, target);
  1238.         char *owner;                            Owner name
  1239.         char *member;                           Member name
  1240.         char *target;                           Destination pointer
  1241.         
  1242.  
  1243.     Description
  1244.         Get the first set connection between an owner and member record.
  1245.         The member record will be retrieved.
  1246.  
  1247.  
  1248.     Example
  1249.  
  1250.         #include <dbmacro.h>
  1251.  
  1252.         Function()
  1253.             {
  1254.             long accountNbr = 1000L;
  1255.             struct AddressTable address;
  1256.  
  1257.             DbFindRecordbyKey( "customer", "acctnbr", (char *)&accountNbr);
  1258.  
  1259.             if( DbSetGetFirst( "customer", "address", (char *)&address))
  1260.                 printf( "Error: set not found\n");
  1261.             }
  1262.  
  1263.  
  1264.  
  1265.  
  1266.     DbSetGetLast
  1267.     -------------------------------------------------------------------------
  1268.  
  1269.  
  1270.  
  1271.     int DbSetGetLast( owner, member, target);
  1272.         char *owner;                            Owner name
  1273.         char *member;                           Member name
  1274.         char *target;                           Destination pointer
  1275.         
  1276.  
  1277.     Description
  1278.         Get the last set connection between an owner and member record.
  1279.         The member record will be retrieved.
  1280.  
  1281.  
  1282.     Example
  1283.  
  1284.         #include <dbmacro.h>
  1285.  
  1286.         Function()
  1287.             {
  1288.             long accountNbr = 1000L;
  1289.             struct AddressTable address;
  1290.  
  1291.             DbFindRecordbyKey( "customer", "acctnbr", (char *)&accountNbr);
  1292.  
  1293.             if( DbSetGetLast( "customer", "address", (char *)&address))
  1294.                 printf( "Error: set not found\n");
  1295.             }
  1296.  
  1297.  
  1298.  
  1299.  
  1300.     DbSetGetNext
  1301.     -------------------------------------------------------------------------
  1302.  
  1303.  
  1304.  
  1305.     int DbSetGetNext( owner, member, target);
  1306.         char *owner;                            Owner name
  1307.         char *member;                           Member name
  1308.         char *target;                           Destination pointer
  1309.         
  1310.  
  1311.     Description
  1312.         Get the next set connection between an owner and member record.
  1313.         The member record will be retrieved.
  1314.  
  1315.  
  1316.     Example
  1317.  
  1318.         #include <dbmacro.h>
  1319.  
  1320.         Function()
  1321.             {
  1322.             long accountNbr = 1000L;
  1323.             struct AddressTable address;
  1324.  
  1325.             DbFindRecordbyKey( "customer", "acctnbr", (char *)&accountNbr);
  1326.  
  1327.             if( DbSetGetFirst( "customer", "address", (char *)&address))
  1328.                 printf( "Error: set not found\n");
  1329.             if( DbSetGetNext( "customer", "address", (char *)&address))
  1330.                 printf( "Error: set not found\n");
  1331.             }
  1332.  
  1333.  
  1334.  
  1335.  
  1336.     DbSetGetOwner
  1337.     -------------------------------------------------------------------------
  1338.  
  1339.  
  1340.  
  1341.     int DbSetGetOwner( owner, member, target);
  1342.         char *owner;                            Owner name
  1343.         char *member;                           Member name
  1344.         char *target;                           Destination pointer
  1345.         
  1346.  
  1347.     Description
  1348.         Get the owner of a record.  A set connection must exist between owner
  1349.         and member.  The owner record will be retrieved.
  1350.  
  1351.  
  1352.     Example
  1353.  
  1354.         #include <dbmacro.h>
  1355.  
  1356.         Function()
  1357.             {
  1358.             struct CustomerTable customer;
  1359.             struct AddressTable address;
  1360.  
  1361.             DbFindRecordbyKey( "address", "zipcode", "99999");
  1362.  
  1363.             if( DbSetGetOwner( "customer", "address", (char *)&customer))
  1364.                 printf( "Error: set not found\n");
  1365.             }
  1366.  
  1367.  
  1368.  
  1369.  
  1370.     DbSetGetPrev
  1371.     -------------------------------------------------------------------------
  1372.  
  1373.  
  1374.  
  1375.     int DbSetGetPrev( owner, member, target);
  1376.         char *owner;                            Owner name
  1377.         char *member;                           Member name
  1378.         char *target;                           Destination pointer
  1379.         
  1380.  
  1381.     Description
  1382.         Get the previous set connection between an owner and member record.
  1383.         The member record will be retrieved.
  1384.  
  1385.  
  1386.     Example
  1387.  
  1388.         #include <dbmacro.h>
  1389.  
  1390.         Function()
  1391.             {
  1392.             long accountNbr = 1000L;
  1393.             struct AddressTable address;
  1394.  
  1395.             DbFindRecordbyKey( "customer", "acctnbr", (char *)&accountNbr);
  1396.  
  1397.             if( DbSetGetLast( "customer", "address", (char *)&address))
  1398.                 printf( "Error: set not found\n");
  1399.             if( DbSetGetPrev( "customer", "address", (char *)&address))
  1400.                 printf( "Error: set not found\n");
  1401.             }
  1402.  
  1403.  
  1404.                                     Errors
  1405.  
  1406.  
  1407.  
  1408.     Every database call has the potential for errors to occur.  A return
  1409.     value of 0 indicates no error has occured.
  1410.  
  1411.  
  1412.     Error returns
  1413.     -------------
  1414.     E_INVALIDCASE       -2
  1415.     E_DOS               -1
  1416.     E_NORECNAME         1
  1417.     E_NOFLDNAME         2
  1418.     E_INVALIDSET        3
  1419.     E_NOTAKEY           4
  1420.     E_NOTFOUND          5
  1421.     E_NEXTGUESS         6
  1422.     E_NOCURRENT         7
  1423.     E_NONEXT            8
  1424.     E_NOPREV            9
  1425.     E_NOMEMBER          10
  1426.     E_NOOWNER           11
  1427.  
  1428.  
  1429.  
  1430.     E_INVALIDCASE   An internal database error. Should this error occur,
  1431.                     contact technical support.
  1432.     E_DOS           A DOS error has occured.  The error number is in the
  1433.                     global "errno".
  1434.     E_NORECNAME     The record name passed is not valid.
  1435.     E_NOFLDNAME     The field name passed is not valid.
  1436.     E_INVALIDSET    The set name combination passed is not a valid set.
  1437.                     The DDL keyword CONNECT must be used to enable set
  1438.                     connections between records to occur.
  1439.     E_NOTAKEY       Field name passed is not a key field.
  1440.     E_NOTFOUND      Record or set not found.
  1441.     E_NEXTGUESS     The key value passed was not found but the next closest
  1442.                     match was returned.
  1443.     E_NOCURRENT     There is no current record for the record(s) specified.
  1444.                     i.e You are trying to do a DbRecordGetNext before doing
  1445.                         a DbRecordGetFirst.
  1446.     E_NONEXT        Next record or set not found.
  1447.     E_NOPREV        Previous record or set not found.
  1448.     E_NOMEMBER      Owner record has no member.
  1449.     E_NOOWNER       Member record has no owner.
  1450.  
  1451.  
  1452.  
  1453.  
  1454.                              Registration Notification
  1455.  
  1456.  
  1457.  
  1458.  
  1459.     CDB is copyrighted and is the property of Daytris Information Systems.
  1460.  
  1461.     CDB is distributed as User-Supported software.  Commercial use or
  1462.     development using this product requires you to register.  Registering
  1463.     your copy of the software helps the authors continue to provide
  1464.     professional quality software at very reasonable prices.
  1465.  
  1466.     You have a royalty-free right to reproduce and distribute executable
  1467.     files created using the CDB libraries.
  1468.  
  1469.     The Basic Registration is $35.00 and includes the full library source
  1470.     code, all utility source code, make files, royalty-free use of library
  1471.     functions, unlimited technical support, and low-cost upgrades.
  1472.  
  1473.     Non-U.S. orders need to include $5.00 extra to cover additional shipping
  1474.     and handling charges.  Checks and money orders must be drawn on a U.S.
  1475.     bank.  Please send all payments payable in U.S. Dollars.
  1476.  
  1477.  
  1478.  
  1479.     Disclaimer.
  1480.  
  1481.     The authors claim no responsibility for any damages caused by the use or
  1482.     misuse of this product.  This product is distributed "as is" with no
  1483.     warranty expressed or implied.  The authors will not be responsible for
  1484.     any losses incurred, either directly or indirectly, by the use of this
  1485.     product. The authors reserve the right to make modifications at any
  1486.     time.  Prices are subject to change without notice.
  1487.  
  1488.  
  1489.     ---------------------------------------------------------------------
  1490.  
  1491.                            Registration Form for CDB
  1492.  
  1493.  
  1494.      
  1495.     Name:              _________________________________________________
  1496.  
  1497.     Company:           _________________________________________________
  1498.  
  1499.     Address:           _________________________________________________
  1500.  
  1501.     City, State, Zip:  _________________________________________________
  1502.  
  1503.     Telephone:         _________________________________________________
  1504.  
  1505.     Country:           _________________________________________________
  1506.  
  1507.     E-Mail Address:    _________________________________________________
  1508.  
  1509.  
  1510.  
  1511.  
  1512.     With registration you will receive the complete source code for CDB.
  1513.  
  1514.     Source Code Media:
  1515.  
  1516.     5 1/4 " diskette   ___
  1517.  
  1518.     3 1/2 " diskette   ___
  1519.  
  1520.     Send via E-MAIL    ___
  1521.  
  1522.     BBS                _____________________________
  1523.  
  1524.     Number of Copies   ___  X  $35  = ______________
  1525.  
  1526.  
  1527.      
  1528.  
  1529.     COMMENTS: Please feel free to add your thoughts or suggestions!
  1530.  
  1531.     _____________________________________________________________________
  1532.  
  1533.     _____________________________________________________________________
  1534.  
  1535.     _____________________________________________________________________
  1536.  
  1537.     _____________________________________________________________________
  1538.  
  1539.      
  1540.     Make Checks payable to:     Todd C. Fearn
  1541.  
  1542.     Mail to:                    Todd C. Fearn
  1543.                                 Daytris Information Systems
  1544.                                 81 Bright Street, Suite 1E
  1545.                                 Jersey City, NJ  07302
  1546.