MYSQLDOC

Name

mysqldoc

Purpose (one Line Only)

Build a documentation file from internal mySQL documentation.

Description

Calling Sequence

mysqldoc,lun,table,outfile

Inputs

lun - The logical unit of the pipe (previously opened by openmysql).
-or-
String with the name of the database to access.
If string is supplied then the database is opened
at the start and closed at the end.
table - String containing name of mySQL table to document.
Default is to process all tables in the database.
If default is used, then outfile is ignored.
If processing the entire database, then an extra file
named "documentation.html" is created with a master index
for the entire database.
outfile - String with file name for output (default=table+'.html')

Optional Input Parameters

Keyword Input Parameters

DBNAME - String with name of the database being examined.
Default='' if the database is already open. If the
database name is provided in lun then the default is
to use the value of lun.
OUTDIR - String with the name of the directory to put the output files.
Default=current directory

Outputs

All output is to the output file.

Keyword Output Parameters

Common Blocks

Side Effects

Restrictions

Requires access to a MySQL server (established by
use of openmysql) as well as valid permissions for reading
the database.
I don't yet know how to test and make sure the table sought actually
exists in the database. For the moment, if you give a non-existent
table, the program will crash most unpleasantly.

Procedure

Special information:
The documentation for a database resides in the "doc" table.
This table must be defined similar to this:
+-----------+-------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+-----------+-------------+------+-----+---------+-------+
| tablename | varchar(20) | YES | | NULL | |
| field | varchar(20) | YES | | NULL | |
| units | varchar(20) | YES | | NULL | |
| source | varchar(80) | YES | | NULL | |
| info | text | YES | | NULL | |
+-----------+-------------+------+-----+---------+-------+
The exact lengths of the first four fields is not critical.
For a normal field in a database you will provide the tablename
and field along with its information in units,source,info. An
indirect reference can be imbedded in the info field and looks
like < where key is replaced by a short string. This string
will be searched for under the "field" field where tablename is
set to NULL. The text found will replace < in the output
html file. The general description of a table is stored in a
record with tablename="table" and field is NULL. For these records
"source" will contain a short description that will populate the
master summary table and "info" will contain a detailed but general
description of the purpose and usage for the table. There is also
one special record per doc database where tablename and field are
both NULL. In this record, the info field will contain a general
description of the entire database which will appear on the master
index page.
In general, units, source, and info will all be filled in for every
database field. Sometimes units make no sense for a field. In this
case put [[none]] in the field to leave the units blank. NULL is
reserved to indicate that no information has yet been provided.
If you want to suppress a documentation page for a table (ie., one
that is for internal testing purposes only), then set source to
xxHIDExx in the record where tablename="table" and field is NULL.

Modification History

2005/01/19, Written by Marc W. Buie, Lowell Observatory
2005/02/01, MWB, special handling for enum types.
2005/10/10, MWB, added call to mysqldocscan validator