Help file for DBHTML




DBHTML is a utility to display the schema for an IMAGE database
in either DBSCHEMA syntax or as an HTML file.

When generating HTML, it has the ability to include documentation
for the database, sets, and items ... and create hypertext links
from the "schema" to the documentation.

Commands:

   DO      [prefix]

      If a prefix is specified, finds the more recent redo line
      that matches the prefix and re-submits it.  If no prefix is
      specified, the most recent input is re-submitted.

   ECHO text

      Echoes the rest of the line to $stdlist.  This could be
      useful in a USE file.

   Exit

      Terminates DBHTML.

   FLAGS basename [output_filename] ...

      Shortcut for:  SCHEMA basename [output_filename] FLAGS ...

   Help    [command_name_prefix]

      HELP  displays the entire help text.
      HELP H    displays help for all commands starting
                with H.

   HTML  basename [output_filename]  [options]

      options ::=  C      |
                   DELete |
                   DOCumentation doc_filename] [C]

      Generates an HTML page describing the specified database.
      If output_flename is omitted, output is sent to $STDLIST.
      By default, if an existing file with the same output name
      exists, the command is aborted.  The DELETE option tells
      DBHTML that it should purge any existing file with the same
      name.  The DOC option tells HTML to read documentation from
      the specified ASCII file, and to include it on in the HTML
      generated.

      If a DOCUMENTATION file name is not specified, DBHTML will
      look for DO.  For example, if you specified
      a basename of SALES.DATA, then DBHTML will look for a
      documentation file called SALESDO.DATA.

      The C option adds a section to the HTML documenting the
      C language "structs" that one might use to access the
      data in each dataset.

      Note: the "output_filename" may not be "C", "DELete", or
      "DOCumentation".

   LISTREDO

      Lists the REDO stack, which persists across runs (while in
      the same session or job).

   QUICKREF basename [options]
         options ::=  [...]

      Lists basic information about a database.

   REDO    [prefix]

      If a prefix is specified, finds the more recent redo line
      that matches the prefix and presents it for editing and
      re-submitting.

      If no prefix is specified, the most recent input is
      presented for editing and re-submitting.

      The editor used by REDO is QZMODIFY.  Pressing ^W and then
      H will result in help information.

   RESET     [...]

      See SET

   SCHEMA basename [output_filename]  [options]
         options ::=  <[no]DELete    |
                       [no]EXTRAS    |
                       [no]FEAtures  |
                       FLAGS         |
                       [no]PATHS     >

      Generates a DBSCHEMA-style output describing the specified
      database.  If output_filename is omitted, output is sent to
      $STDLIST.  By default, if an existing file with the same
      output name exists, the command is aborted.

      The DELETE option tells DBHTML that it should purge any
      existing file with the same name.

      The EXTRAS option (on by default) tells DBHTML that
      extra information should be displayed (as comments).

      The FEATURES option (on by default) tells DBHTML that
      to report the features used by the database (e.g., does it
      use DDX? MDX? Jumbo?)

      The FLAGS option (off by default) tells DBHTML to only
      display "flag" information (i.e., various bits/flags,
      but *not* the passwords, items, or sets).

      The PATHS option says "I want extra path comments emitted".

   SET / RESET [options...]
         options ::=
               [no]ALLOWMPE
               BATCH
               [no]COLTRUNcate
               [no]DEBUGCAP
               [no]DEBUG1
               DEMO
               [no]LP
               [no]PAGING
               [no]PASSwords
               [no]SHORTUClist

      Turns on the specified option(s) or flag(s).  The state of
      all options/flags is reported at the end of the SET (or
      RESET) command.  To see the options and flags without
      changing any of them, enter: SET

      SET ALLOWMPE tells DBHTML that the user may enter MPE
      commands (e.g., :showtime).  This option may be SET
      only from the startup.dbhtml.allegro file, or by
      a user with SM capability.
      NOTE: allowing MPE commands might open a security hole.
      The default is RESET ALLOWMPE.

      SET LP routes all subsequent output to the printer instead
      of to the terminal.  RESET LP cancels this.

      The PASSWORDS option tells DBTHML to emit actual passwords
      in the output.  RESET PASSWORDS prevents the passwords
      from being emitted.
      The default is SET PASSWORDS

      SET SHORTUCLIST (the default)

   STRUCT  basename [output_filename]  [options]

      options ::=  DELete

      Generates C structs and typedefs for the items and datasets.

      If output_flename is omitted, output is sent to $STDLIST.
      By default, if an existing file with the same output name
      exists, the command is aborted.  The DELETE option tells
      DBHTML that it should purge any existing file with the same
      name.

      Note: the "output_filename" may not be "C", "DELete", or
      "DOCumentation".

   SUFFIX 

      Converts a dataset number (e.g, 200) into a dataset
      filename suffix (e.g., 'A0'), or vice versa
      (e.g., "SALESA0" into "200").

   USEq filename

      Tells DBHTML to read commands from the specified file.
      Normally, USE will echo the lines as it reads them.
      USEQ tells DBHTML to not do such an echo.

   VERSION

      Reports version of DBHTML.

   XML basename [filename]  [DELete]

      Produces a rudimentary XML description of the database
      schema.  (See HTML or SCHEMA for the semantics of
      "filename" and "DELETE".)  \

Syntax note: where multiple parameters are optional, commas are
needed to indicate omission of a parameter if you want to specify
subsequent parameters.
-----------------------------------------------------------------

At startup, DBHTML does an implicit:

   USEQ startup.dbhtml.allegro

(disallowing file equates).  This allows you to have common
startup commands (e.g., SET/RESET).
-----------------------------------------------------------------

The DOCUMENTATION file, if one exists, is a flat ASCII file
with a mixture of DBHTML documentation directives and text
documenting the data sets, data items, and miscellaneous
documentation.

In the documentation file, comment lines (which will not be
copied into the generated HTML) are any lines beginning with
the text "\!".

Note: the text is treated as HTML text, which means that
text lines may be reformatted by the user's browser if you
don't prevent it.

The three directives are: \SET, \ITEM, and \MISCellaneous.

   \SET setname
      ...tells DBHTML that this is the start of documentation
         for the specified data set.
   \ITEM itemname
      ...tells DBHTML that this is the start of documentation
         for the specified data item.
   \MISCellaneous
      ...tells DBHTML that this is the start of miscellaneous
         documentation.

The SET, ITEM, and MISCellaneous keywords may be in any case.

A documentation file may have zero or more \SET sections,
zero or more \ITEM sections, and zero or one \MISCellaneous
sections.  An example file, which also shows that HTML
elmements may be in the documentation (see the section for
set2):

   \! badbits  2001-10-03
   \set set1
   this is set set1, a set of no particular value.

   \SET set2
   this is set set2, a BOLD set.
   
this is more text
this is the last line of text for set2 \item item1 this is item1, an I1 item. this is the last line of text for item I1 \item item2 this is item2, of which we know nothing \misc this is where you might put database general comments.

this is a link to Allegro. ----------------------------------------------------------------- NOTE: if you find problems, please email sieler@allegro.com