documentation/Fannie/developer/db-creation.html from CORE-POS/IS4C

documentation/Fannie/developer/db-creation.html
Summary

Maintainability

Test Coverage

Issues
<html>
<head>
    <title>Database Creation System</title>
</head>
<body>
    <div style="text-align:center;margin-bottom:10px;font-size:80%;">
    updated as of: March 30, 2015<br />
    last author: Andy Theuninck
    </div>
    <div style="border: solid 1px black; font-size: 115%; padding: 1em;">
    The latest documentation can be found on the <a href="https://github.com/CORE-POS/IS4C/wiki/Fannie-Schema-Management">Project Wiki</a>.
    The information below may be out of date. 
    </div>
I revised database creation a bit. It still takes place in the
install script (install/index.php), the work is no longer
all in one multi-thousand line file.
<p />
The create_if_needed function (install/db.php) does most of the
heavy lifting. It takes five arguments:
<ul>
<li>$con - a SQLManager object connected to the appropriate database</li>
<li>$dbms - the database system. Probably MYSQL or MSSQL</li>
<li>$db_name - the <i>user defined</i> database name</li>
<li>$table_name - the table to create</li>
<li>$stddb - a <i>standardized</i> database name</li>
</ul>
The only real gotcha is the double database names. There are two
so that the user doesn't have to call their databases is4c_op
and is4c_log, but the create_if_needed function can still discern
which database we're talking about. By convention, $stddb should 
be <i>op</i>, <i>trans</i>, or <i>arch</i>. Yay brevity.
<p />
Next are create statement scripts. Each table or view should have
it's own create statement script. These PHP files live in the
install/sql directory, with a subdirectory for each database.
The name of the file should match the name of the table. Example:
the create statement script for the products table is
install/sql/op/products.php.
<p />
A create statement script should generate a query string that will
create the appropriate table or view and assign it to the variable
$CREATE[$stdb.$table_name]. Example: products would assign its
query to $CREATE["op.products"]. Create statement scripts are
included directly; no need to return anything. The array-entry naming 
convention is just a sanity check.
<p />
Comment your create statement scripts. Any comments included are
used to auto-generate HTML documentation for the database.
</body>
</html>