| THE META-HTML LANGUAGE REFERENCE MANUAL

Session Operators | [TOC] | Msql Database Extensions

## Section Intro: Database Commands

Synopsis:

Meta-HTML contains commands for performing operations on a database. A database created by Meta-HTML contains records stored by key, where each record consists of a set of name/value pairs.

There is a single command for specifying which database you will be operating on: `with-open-database`. All of the remaining database commands only have an effect when executed within the scope of this function.

`database-query` is the command used to perform queries on a database, or to simply select a range of records to operate on.

Functions which load, store, or delete a record as a single atomic operation, return the string `"true"` when they succeed, and store an error message in `SYSTEM-ERROR-OUTPUT` when they do not.

Commands:

database-delete-record database-first-key database-load-record | database-next-key database-query database-save-package | database-save-record database-unique-key with-open-database

### Function Documentation

`<database-delete-record DBVAR KEY>` | Simple

Remove the record associated with KEY from the database referenced by DBVAR. This functions returns the string `"true"` upon success.

    <with-open-database db /tmp/file.db mode=write>
      <set-var deleted? = <database-delete-record db <get-var key>>>
    </with-open-database>

`<database-first-key DBVAR>` | Simple

Return a string representing the "first" key found in the database referenced by DBVAR. The key is suitable for input to any of the database functions which takes a key as input. The order in which keys are returned appears random, but the return value is always a suitable argument to `database-next-key`.

`<database-load-record DBVAR KEY [PREFIX=PACKAGE-NAME]>` | Simple

Load the variables from the record specified by KEY in the database referenced by DBVAR. If PREFIX=PACKAGE-NAME is given, the record variables are stored into the specified package, instead of the current package.

Upon success, this function returns the string `"true"`.

    <with-open-database db /tmp/file.db mode=read>
      <set-var loaded? = <database-load-record db <get-var name>>>
    </with-open-database>
    <when <get-var loaded?>>
      The record was loaded successfully.
    </when>

`<database-next-key DBVAR AFTER-KEY>` | Simple

Return the "next" key in the database. The key is found by looking at AFTER-KEY, which makes this function suitable for calling in a loop. For example, the following code iterates over an entire database.

    <with-open-database db /file.db mode=read>
      <set-var key=<database-first-key db>>
      <while <get-var key>>
        <package-delete record>
        <set-var loaded? =
          <database-load-record db <get-var key> package=record>>
        Key: <get-var key>, Name: <get-var record::name>
        <set-var key = <database-next-key db <get-var key>>>
      </while>
    </with-open-database>

`<database-query DBVAR EXPR [FORMAT=FEXPR] [KEYS=VARNAME] [SORT=FIELD1[] [FIELD2...]] [SORTORDER=REVERSE]>` | Simple

Select records from the database referenced by DBVAR, based on EXPR, perhaps sorting them based on the data in FIELDs, and optionally formatting them with the Meta-HTML expression in FEXPR.

Both EXPR and FEXPR are evaluated with the fields of the database as the current package, so references to variables which are not part of the record structure must be fully qualified (i.e., by prefixing them with a package name. See Packages for more information.) If the result of evaluating EXPR is not the empty string, then the record is selected for further processing by either FORMAT, KEYS, or to be returned in a plain text list of keys.

The order of evaluation is as follows:

First, the database is queried, and an internal list of selected records is created. Then, if SORT=FIELD1,FIELD2... is present, the records are sorted using the values of the specified fields. The order of the sort can be reversed by passed SORTORDER=REVERSE.

Next, if FORMAT=FEXPR is present, FEXPR is executed for each record, in an environment where the current package consists of bindings for each field's name to each field's value, and the special binding of `key` to the key of that record. Finally, if KEYS=VARNAME is present, VARNAME is the name of a variable into which the matched keys are stored as an array.

The SORT parameters indicates which fields to sort the resultant keys on; the field names FIELD1,FIELD2... are separated by commas.

Examples:

This simple query stores the key of every record in the database whose name field contains "Fox" into the variable named dbkeys:

    <with-open-database db "/www/data/employee.db" mode=read>
      <database-query db <match <get-var name> "Fox"> keys=dbkeys>
    </with-open-database>

This more complex query formats an alphabetical list of all the members of the database who are employed as carpenters, and are between the ages of 20 and 45, by creating links to a page which will (presumably) get a more detailed listing of the individual record:

    <with-open-database db "employee.db" mode=read>
      <database-query db sort=LastName
        <and <match <get-var job> "carpent">
             <gt age 20>
             <lt age 45>>
        format = <prog
                   <a href="detail-display.mhtml?<cgi-encode key>">
                   <get-var LastName>, <get-var FirstName>
                   </a>: <get-var Job>, <get-var Age>>>
    </with-open-database>

`<database-save-package DBVAR KEY PACKAGE [STRIP=TRUE]>` | Simple

Save the variables from the package PACKAGE in the database referenced by DBVAR in the record specified by KEY.

If STRIP=TRUE is supplied, then the names of the variables written to the database have their package prefix removed as they are written.

Upon success, this function returns the string `"true"`.

    <set-var foo::x=x foo::array[0]=val0 foo::array[1]=val1>
    <with-open-database db /tmp/file.db mode=write-create>
      <database-save-package db mykey foo strip=true>
    </with-open-database>

produces

    true

`<database-save-record DBVAR KEY [VAR1...VARN] [PACKAGE=PACKAGE-NAME]>` | Simple

Save the variables VAR1...VARN in the database referenced by DBVAR in the record specified by the key KEY. If PACKAGE-NAME is supplied, then the names of the variables written to the database are written as if they belonged to that package.

Upon success, this function returns the string `"true"`.

Also see `database-save-package`, and `database-load-record`.

    <with-open-database db /tmp/file.db mode=write-create>
      <set-var saved? =
         <database-save-record db <get-var name> name age size>>
    </with-open-database>
    <when <get-var saved?>>
      The record was stored successfully.
    </when>

`<database-unique-key DBVAR [SUGGESTION]>` | Simple

Return a key which is guaranteed to not already exist in the the database referenced by DB. If SUGGESTION is supplied, that key is tried first, and then subsequent attempts are various modifications to the suggestion.

`<with-open-database DBVAR DBNAME [MODE=OPEN-MODE]> body </with-open-database>` | Complex

Create an environment in which other database commands can be given. First, the database referenced by DBNAME is locked and opened in the mode specified by OPEN-MODE, and the resultant database handle is bound to the variable named by DBVAR. Then, the BODY code is executed. Finally, the database is closed, and further references to DBVAR are meaningless.

Please note that the file name specified by DBNAME should be a full pathname; it is not relative to Web space in any way.

OPEN-MODE should evaluate to one of the following:

- READER
  The caller wishes only to have read access to the specified database.

- WRITER
  The caller wishes to have both read and write access to the specified database.

- WRITE-CREATE
  The caller wishes both read and write access to the specified database. If the database does not exist, it is created.

Edit Section
Function Index
Variable Index

The META-HTML Reference Manual V1.4 Copyright © 1995, 1996, Brian J. Fox, 1996, 1997 Universal Access Inc.
Found a bug? Send mail to bug-manual@metahtml.com