home *** CD-ROM | disk | FTP | other *** search
/ PC Press 1997 July / Sezamfile97_1.iso / msdos / c / cbase11.a03 / CBASE11.ZIP / MAN / CBDDLP.MAN < prev    next >
Text File  |  1993-01-01  |  7KB  |  151 lines
  1. NAME
  2.      cbddlp - cbase data definition language processor
  3.  
  4. SYNOPSIS
  5.      cbddlp ddlfile
  6.  
  7. DESCRIPTION
  8.      The cbddlp command processes cbase data definition language (DDL)
  9.      files.  A cbase database can be specified in a DDL file, which is
  10.      then processed using cbddlp to generate the C files required by
  11.      cbase to manipulate that database.  cbddlp requires that DDL
  12.      files have the suffix ".ddl".  The C files generated are given
  13.      the same name as the DDL file except for the suffix; a .h and a
  14.      .i file are generated.  The .h file must be included by every
  15.      module accessing the database, while the .i file must be included
  16.      by exactly one module of every program that accesses the database.
  17.  
  18.      There are three types of DDL statements:  data file, index file,
  19.      and record.  The syntax for the record statement is
  20.  
  21.           record recname {
  22.                [[unique ]key] dbtype fldname[\[elemc\]];
  23.                ...
  24.           };
  25.  
  26.      recname is the name of the record.  dbtype is the database data
  27.      type of the field.  fldname is the name of the field, and must be
  28.      unique for a given database.  elemc specifies the number of
  29.      elements for array data types; this may be any C expression valid
  30.      for defining the size of a static array.  The key keyword
  31.      specifies that an index is to be maintained on this field.  The
  32.      unique keyword specifies that the keys in this index must be
  33.      unique.  Multiple records can be defined in the same DDL file.
  34.  
  35.      User-defined data types may also be specified in a DDL file, but
  36.      require an additional piece of information.  For the predefined
  37.      data types, cbddlp knows what the corresponding C data type is
  38.      (t_string : char, t_int : int, etc.).  But for user-defined data
  39.      types, this must be explicitly specified.  The syntax for this is
  40.      as follows.
  41.  
  42.           [[unique ]key] dbtype:ctype fldname[[elemc]];
  43.  
  44.      where dbtype is a user-defined database data type and ctype is
  45.      the corresponding C data type.  ctype must consist of only one
  46.      identifier; if the C data type consists of multiple identifiers
  47.      (e.g., long double), either #define or typedef must be used to
  48.      reduce it to one identifier (e.g., typedef long double ldouble).
  49.  
  50.      The syntax for the data file statement is
  51.  
  52.           data file "filename" contains recname;
  53.  
  54.      filename is the name of the file in which recname records are to
  55.      be stored.  The data file statement must precede its associated
  56.      record statement.
  57.  
  58.      The syntax for the index file statement is
  59.  
  60.           index file "filename" contains keyname;
  61.  
  62.      filename is the name of the file in which keyname keys are to be
  63.      indexed.  The index file statement must precede the record
  64.      statement containing the associated key.
  65.  
  66.      C comments may appear in DDL files wherever white space is
  67.      allowed, with the exception of within the keyword pairs "data
  68.      file" and "index file".  C preprocessor statements may also be
  69.      placed in DDL files, but cannot currently span multiple lines,
  70.      nor can comments on the same line as a preprocessor statement;
  71.      any line beginning with the # character (excluding any leading
  72.      white space) will be passed directly through to the generated .h
  73.      file.
  74.  
  75.      In the headers generated by cbddlp, a macro for the record name
  76.      is constructed by converting all lower case letters in the record
  77.      name to capitals.  A macro is also defined for each field in the
  78.      same fashion.  The initial characters (up to four) of the first
  79.      field name of a record preceding the first underscore are used as
  80.      a prefix for the field count macro and field definition list.
  81.      This prefix must be unique for all records in a database.  The
  82.      field count macro identifier is constructed by converting this
  83.      prefix to capitals and appending FLDC.  The field definition list
  84.      identifier is constructed by appending fldv to the prefix.
  85.  
  86. EXAMPLE
  87.      Below is given an example DDL file for a rolodeck database
  88.      consisting of a single record.
  89.  
  90.      /* constants */
  91.      #define NAME_MAX     (40)   /* max name length */
  92.      #define ADDR_MAX     (40)   /* max address length */
  93.      #define NOTELIN_MAX   (4)   /* note lines */
  94.      #define NOTECOL_MAX  (40)   /* note columns */
  95.  
  96.      /* file assignments */
  97.      data file  "rolodeck.dat" contains rolodeck;
  98.      index file "rdcont.ndx"   contains rd_contact;
  99.      index file "rdcomp.ndx"   contains rd_company;
  100.  
  101.      record rolodeck {                        /* rolodeck record */
  102.          unique key t_string
  103.                       rd_contact[NAME_MAX];   /* contact name */
  104.          t_string     rd_title[41];           /* contact title */
  105.          key t_string rd_company[NAME_MAX];   /* company name */
  106.          t_string     rd_addr[81];            /* address */
  107.          t_string     rd_city[26];            /* city */
  108.          t_string     rd_state[3];            /* state */
  109.          t_string     rd_zip[11];             /* zip code */
  110.          t_string     rd_phone[13];           /* phone number */
  111.          t_string     rd_ext[5];              /* phone extension */
  112.          t_string     rd_fax[13];             /* fax number */
  113.          t_string     rd_notes[NOTELIN_MAX * NOTECOL_MAX];
  114.                                               /* notes */
  115.      };
  116.  
  117.      If the name of this DDL file was rolodeck.ddl, the generated C
  118.      files would be rolodeck.h and rolodeck.i.  The cbase name macro
  119.      would be ROLODECK (the record identifier capitalized).  The field
  120.      count macro would be RDFLDC, and the field definition list would
  121.      be rdfldv.  The rolodeck would be therefore be opened (for
  122.      writing) with the C statement
  123.  
  124.           cbopen(ROLODECK, "r+", RDFLDC, rdfldv);
  125.  
  126.      The phone number from the current record would be read from the
  127.      database with
  128.  
  129.          cbgetrf(cbp, RD_PHONE, buf);
  130.  
  131.  
  132. NOTES
  133.      For a make utility to automatically process DDL files without an
  134.      explicit rule for each one, suffix rules defining the creation of
  135.      the data definition header files from a DDL file can be added to
  136.      the makefile.  For the standard UNIX make, the following
  137.      instructions would be inserted near the beginning of the
  138.      makefile.
  139.  
  140.      # suffix rules
  141.      .SUFFIXES:  .ddl .h .i
  142.  
  143.      .ddl.h:
  144.           cbddlp $<
  145.  
  146.      .ddl.i:
  147.           cbddlp $<
  148.  
  149.      The exact procedure for other make utilities varies.
  150.  
  151.