;;; sec8.mhtml: -*- Meta-HTML -*- 

;;;  Copyright (c) 1996 Universal Access Inc.
;;;  Author: Henry Minsky (hqm@ua.com) Sun Sep 15 11:06:47 1996.

<set-var title="Using The Database">
<include header.mhtml>

<plain-text>
  <pagelist-control-panel>
  <h2>Using The Database</h2>

  Built into Meta-HTML is a simple-to-use yet extremely powerful
  database. It can save free form variable (unlimited) length records
  based on an arbitrary key.

  Let's say we want to make a database of employee information, keyed
  on their email address.

  You can create as many database files as you like, and place them
  anywhere in your filesystem.

  The <funref with-open-database> tag is used to open a database
  file for reading or writing. All access within the scope of the
  <funref with-open-database> is exclusive, so you can use it
  to do atomic transactions.

  <H3> Saving Records In A Database File</h3>

  First we must decide where our database file will be kept. The
  pathname we will use for this example is <tt>/tmp/people.db</tt>.  The
  '.db' suffix should be used for database file names.

  To save some data under a key in a database, we use the
  <funref database-save-record> tag.

  Let's say we have some data stored in some page variables:

  <example-table>
  <set-var name="Mick Jagger"
         age=74
         salary=2.3e7 ;;;Exponential notation!
	 email=mick@stones.com
</example-table>

To save this record under the email address, we would do

<example-table>
<with-open-database mydb "/tmp/people.db" MODE=WRITE-CREATE>
  <database-save-record mydb <get-var email> name age salary>
</with-open-database>
</example-table>

The data in the variables <tt>name</tt>, <tt>age</tt>, and
<tt>salary</tt> are now stored under the key "mick@stones.com" in the
database.

Let's save another record:
</plain-text>

<example-table>
<set-var name="Keith Richards"
         age=87
         salary=1.3e7 
	 email=keith@stones.com

<with-open-database mydb "/tmp/people.db" MODE=WRITE-CREATE>
  <database-save-record mydb <get-var email> name age salary>
</with-open-database>
</example-table>

<plain-text>
Note that a database file can be created automagically the first time
it is referenced, if you use the WRITE-CREATE mode flag when accessing
it. Other modes are WRITE and READ. See the <funref
with-open-database> documentation for more details.

<h3> Reading Data From A Database </h3>
 
The <funref database-load-record> tag is used to reload data records
from the database. 
</plain-text>

<example-table>
<with-open-database mydb "/tmp/people.db" MODE=WRITE-CREATE>
  <database-load-record mydb "mick@stones.com">
</with-open-database>

<get-var name>
Mick Jagger
</example-table>

<plain-text>
<funref database-load-record> looks up the data stored under the given
key, and reloads the data into the original variable names under which
they were stored. Thus, after executing the <funref
database-load-record> above, the variables <tt>name</tt>,
<tt>age</tt>, and <tt>salary</tt> assigned values "Mick Jagger"
values.

<h3> Putting Record Data Into Packages</h3>

<funref database-load-record> normally reloads the record data into
variables in the DEFAULT package. You can specify an explicit
package to use, with the PACKAGE keyword argument. 
</plain-text>

<example-table>
<with-open-database mydb "/tmp/people.db" MODE=WRITE-CREATE>
  <database-load-record mydb "mick@stones.com" package=band-members>
</with-open-database>

<get-var band-members::name>
Mick Jagger
<get-var band-members::age>
74
</example-table>

<plain-text>
<h3>Saving An Entire Package as a Record</h3> <funref
database-save-package> can be used to save the entire contents of a
package. It is like <funref database-save-record> except that instead
of taking a list of variables, it takes a single package name, and
saves every symbol in the package into the designated record.
</plain-text>

<example-table>
<set-var staff::name="Keith Richards"
         staff::age=87
         staff::salary=1.3e7 
	 email=keith@stones.com

<with-open-database mydb "/tmp/people.db" MODE=WRITE-CREATE>
  <database-save-package mydb <get-var email> staff>
</with-open-database>
</example-table>

<pagelist-control-panel>
<include footer.mhtml>
