| THE META-HTML LANGUAGE REFERENCE MANUAL

Direct Dbm Access | [TOC] | Language Operators

## Section Intro: Odbc Database Operators

Synopsis:

Meta-HTML PRO is optionally delivered with a complete ODBC compliant database module, providing a useful set of database commands for operating on commercial databases, such as ORACLE or SyBase. These extensions allow true SQL database interaction at many levels, providing a clean and flexible abstraction.

Commands:

odbc::cursor-get-column odbc::database-column-info odbc::database-columns-info odbc::database-delete-record odbc::database-exec-query odbc::database-exec-sql odbc::database-load-record odbc::database-next-record | odbc::database-query odbc::database-query-info odbc::database-save-package odbc::database-save-record odbc::database-set-options odbc::database-tables odbc::database-tables-info | odbc::get-connect-option odbc::get-info odbc::number-of-rows odbc::query-get-column odbc::set-connect-option odbc::sql-transact odbc::with-open-database

### Function Documentation

`<odbc::cursor-get-column CURSOR COLUMN-NUMBER>` | Simple

This can be called with a cursor which is the result from a call to database-exec-query.

It gets the data from the current result set, in column numbered COLUMN-NUMBER (starting at column 0).

`<odbc::database-column-info DBVAR TABLE FIELDNAME>` | Simple

Returns an alist of properties of a column of a table. Example: ((NAME . "realname")(LENGTH . "30")(TYPE . "GSQL_CHAR")(IS_UNIQUE . "")(IS_NULLABLE . "true")(QUALIFIER . "")(OWNER . "")(TYPENAME . "")(PRECISION . "0")(SCALE . "0")(RADIX . "0")(TABLE . "accounts"))

This is actually implemented by fetching information on *all* columns and selecting the specified one. It is thus more efficient, if you are looking for info on several columns, to use database-columns-info, and get all the column information in a single array.

`<odbc::database-columns-info DBVAR TABLE [RESULT=VAR]>` | Simple

Returns an array of alists of properties of the columns of a table.

An example of one entry in the result array:

((NAME . "realname")(LENGTH . "30")(TYPE . "GSQL_CHAR")(IS_UNIQUE . "")(IS_NULLABLE . "true")(QUALIFIER . "")(OWNER . "")(TYPENAME . "")(PRECISION . "0")(SCALE . "0")(RADIX . "0")(TABLE . "accounts"))

`<odbc::database-delete-record DBVAR KEY TABLE KEYNAME [TABLE=TABLENAME] [KEYNAME=FIELDNAME]>` | Simple

Deletes the specified record in the database referenced by DBVAR. The record to delete is specified by KEY and KEYNAME. An SQL DELETE query is issued which will delete any record in the table named TABLE whose field named KEYNAME matches the value of KEY.

You must supply TABLE and KEYNAME, where KEYNAME is the name of the primary key field in table.

`<odbc::database-exec-query DBVAR QUERY-STRING [CURSOR=VARNAME]>` | Simple

Executes the SQL query in QUERY-STRING The QUERY-STRING can be any expression Meta-HTML expression which evaluates to a valid SQL query or command string.

Returns a cursor object, which can be passed to `odbc::database-next-record`, `odbc::number-of-rows`, and `odbc::set-row-position`.

If the CURSOR keyword arg is supplied, the returned cursor value is stored in the supplied variable name.

`<odbc::database-exec-sql DBVAR QUERY-STRING>` | Simple

Executes the SQL query in QUERY-STRING, on the open database connection specified by DBVAR.

Returns TRUE if no errors are encountered.

This function differs from ODBC::DATABASE-EXEC-QUERY in that it does not return any cursor, so there is no way to get results back from the execution of your SQL command. Thus, it is most useful for sending commands which expect no return values, such as a SQL DELETE statement:

`<odbc::database-load-record DBVAR KEY [PACKAGE=PACKAGENAME] [TABLE=TABLENAME] [KEYNAME=FIELDNAME]>` | Simple

Load variable values from the database referenced by DBVAR and KEY into the package specified by PACKAGENAME (defaulting to the current package if not supplied).

TABLENAME and FIELDNAME must be supplied -- they specify the table and primary key field to be operated on.

`<odbc::database-next-record CURSORVAR [COLNAMES=NAMELIST] [PREFIXTABLENAMES] [PACKAGE=PACKAGENAME]>` | Simple

Fill the variables in PACKAGENAME (defaulting to the current package if not supplied) with the values of the next record which last satisfied the search referenced by CURSORVAR.

Each subsequent call gets a subsequent record from the list of results, until all of the results are exhausted.

Returns "true" if there are any records left in the search results, or the empty string if not.

If COLNAMES is supplied, then the column values of this result are bound sequentially to these commas-separated list of names instead of the field names in the result set.

    <odbc::database-next-record mydb cursor package=tmp
                    colnames="a.name, a.partnum, b.name">
    <get-var tmp::b.name>
    <get-var tmp::a.name>

If is non-null, or the database connection option SQL-PREFIX-TABLENAMES is non-null, then for each column in the result set, use the column's table name, if it exists, as a prefix to the column name as the variable name.

`<odbc::database-query DBVAR EXPR QUERY [COLNAMES=NAMELIST] [PREFIXTABLENAMES] [QUERY=QUERY-STRING] [FORMAT=FEXPR] [KEYS=VARNAME] [KEYNAME=FIELDNAME]>` | Simple

Select and optionally format records in the database DB according to the criterion in FEXPR.

QUERY is an SQL query, which returns a list of rows.

For each result row, EXPR is then evaluated, with the column values of each row bound to their corresponding column name. If the result of that evaluation is not an empty string, then that record is selected for further processing by either FORMAT, KEYS, or to return in plain text the list of keys. If FORMAT is present, it is an expression to evaluate in the context of the database fields, (as with EXPR).

The example below shows an SQL query which is formatted as rows of an HTML table. In this case, the EXPR is simply the constant true, and all of the selection of records is done via the SQL query itself. The EXPR could be used to impose additional conditions to decide whether to invoke the format expression on a row.

      <odbc::with-open-database rdb database=rolodex
    			    host=localhost>
      <table border=1>
        <tr><th>Name</th><th>Age</th></tr>
      <odbc::database-query rdb true
    			query="SELECT * FROM people WHERE name like 'Washington' ORDER BY lastname"
    			format=<prog <tr>
    				 <td>
    				 <get-var lastname>, <get-var firstname>
    				 </td>
    				 <td>
    				 <get-var age>
    				 </td>
    				 </tr>>>
        </table>
      </odbc::with-open-database>

If KEYS is specified, it is the simple name of a variable to receive the array of keys which satisfied FEXPR. If you specify an argument for KEYS, you must also specify which column to collect the values from, using the KEYNAME keyword argument.

If the optional argument COLNAMES is supplied, then for each row, column values are bound sequentially to these comma-separated names instead of the column names in the result set.

    <odbc::database-query mydb true query=<get-var query>
                          colnames="foo.name, bar.name"
                          format=<prog FOO.NAME IS
    				<get-var foo.name>
    				BAR.NAME IS
    				<get-var bar.name>>>

If PREFIXTABLENAMES is non-null, or the database connection option SQL-PREFIX-TABLENAMES is non-null, then for each column in the result set, use the column's table name, if it exists, as a prefix to the column name as the variable name.

`<odbc::database-query-info CURSOR [RESULT=VARNAME]>` | Simple

Returns an array of alists of information about the columns of the given cursor's query result set.

This is similar to the format returned by database-columns-info. Example:

    ((NAME . "realname")(LENGTH . "30")(TYPE . "GSQL_CHAR")(IS_UNIQUE . "")(IS_NULLABLE . "true")
    (QUALIFIER . "")(OWNER . "")(TYPENAME . "")(PRECISION . "0")(SCALE . "0")(RADIX . "0")(TABLE . "accounts"))

`<odbc::database-save-package DBVAR KEY PACKAGE [KEYNAME=FIELDNAME] [TABLE=TABLENAME]>` | Simple

Save the variables in PACKAGE associated with the value KEY in column KEYNAME in the table TABLENAME of the database referenced by DBVAR.

This only saves variables which have names matching existing table fields. Package prefixes are stripped from the variables, and the symbol name is used as the column name to store the data. Symbol names and column names are treated in a case-insensitive manner.

`` is implemented to first attempt to do a SQL INSERT into the table, and if that fails to try a UPDATE query, with KEYNAME = KEY.

Example: Say we want to save some information about employee Kate Mulgrew, in a table of employees, which has a primary key field named "id", and we want to save this record with id=103:

     <set-var baz::name="Kate Mulgrew" baz::age=45 baz::salary=34000
        baz::dept=travel>
      <set-var result=<odbc::database-save-package mydb 103 baz
    					       table=employees keyname=id>>

If a variable in the package you are saving corresponds to a column with a numeric field type, and the value of the variable is the empty string, the system will attempt to store a NULL value into this field of the record. If the table does not support NULL values on that column, the operation will fail.

`<odbc::database-save-record DB KEY TABLE KEYNAME [VAR...] [TABLE=TABLENAME] [KEYNAME=FIELDNAME]>` | Simple

Does an INSERT and UPDATE to try to store the data into TABLE using the single key KEYNAME, with value KEY.

NOTE: If the key field for table you are using is not configured as the primary key, then it is possible to create duplicate entries in the database.

If you have a variable which does not match a field name in the table, that variable is silently ignored.

If you try to save character data into a numeric field, the insert or update will fail, and you can check the error message in odbc::odbc-error-message[]

`<odbc::database-set-options DBVAR [SQL-ESCAPE-CHARACTER-CODE=INT] [SQL-TRUNCATE-COLUMNS=BOOLEAN]>` | Simple

Sets various database-specific options.

SQL-ESCAPE-CHARACTER-CODE sets the character which is used to escape single quotes in strings.

If SQL-TRUNCATE-COLUMNS is non-null, then queries composed by database-save-record and database-save-package will have character string field data automatically truncated to the max column width of the field being stored into, before the query is ever sent to the SQL server.

`<odbc::database-tables DBVAR [RESULT=VARNAME]>` | Simple

Return the names of the tables in the database referenced by DBVAR as a newline separated list. If VARNAME is supplied, it is the name of the variable to receive the table names. This must be done with a database already open, i.e., within the scope of a `odbc::with-open-database`.

`<odbc::database-tables-info DBVAR [RESULT=VAR] [TABLETYPE=EXPRESSION] [TABLEQUALIFIER=EXPRESSION] [TABLENAME] [TABLEOWNER=EXPRESSION]>` | Simple

Returns an array of alists, one per table in the database.

Each alist contains database-specific information about the table, including at least the NAME of the table. ((name . "table_name"))

The optional tablemumble args are ANSI SQL regexp patterns.

The optional RESULT argument specifies a variable to put the result array into.

`<odbc::get-connect-option DBVAR FINFOTYPE>` | Simple

Performs ODBC SQLGetConnectOption call. Returns the requested data value specified by FINFOTYPE

Valid values for FINFOTYPE are:

    SQL_ACCESS_MODE
    SQL_AUTOCOMMIT
    SQL_LOGIN_TIMEOUT
    SQL_OPT_TRACE
    SQL_OPT_TRACEFILE
    SQL_TRANSLATE_DLL
    SQL_TRANSLATE_OPTION
    SQL_TXN_ISOLATION
    SQL_CURRENT_QUALIFIER
    SQL_ODBC_CURSORS
    SQL_QUIET_MODE
    SQL_PACKET_SIZE

`<odbc::get-info DBVAR FINFOTYPE>` | Simple

Performs ODBC GetInfo call. Returns the requested data value specified by FINFOTYPE

Valid values for FINFOTYPE are:

    SQL_DRIVER_NAME
    SQL_ODBC_VER
    SQL_CURSOR_COMMIT_BEHAVIOR
    SQL_CURSOR_ROLLBACK_BEHAVIOR
    SQL_DEFAULT_TXN_ISOLATION
    SQL_TXN_ISOLATION_OPTION
    SQL_NON_NULLABLE_COLUMNS
    SQL_DRIVER_HLIB
    SQL_DRIVER_ODBC_VER
    SQL_QUALIFIER_LOCATION

`<odbc::number-of-rows CURSORVAR>` | Simple

Returns the number of rows which were found as a result of the last query issued for CURSORVAR.

Cursors are created as the result of direct SQL queries by `odbc::database-exec-query`.

`<odbc::query-get-column COLUMN-NUMBER>` | Simple

This can be only be called within the scope of the odbc::database-query function.

It gets the data from the current result set, in column numbered COLUMN-NUMBER (starting at column 0).

`<odbc::set-connect-option DBVAR FINFOTYPE VALUE>` | Simple

Performs ODBC SQLSetConnectOption call. Returns the requested data value specified by FINFOTYPE

Valid values for FINFOTYPE are:

    SQL_ACCESS_MODE
    SQL_AUTOCOMMIT
    SQL_LOGIN_TIMEOUT
    SQL_OPT_TRACE
    SQL_OPT_TRACEFILE
    SQL_TRANSLATE_DLL
    SQL_TRANSLATE_OPTION
    SQL_TXN_ISOLATION
    SQL_CURRENT_QUALIFIER
    SQL_ODBC_CURSORS
    SQL_QUIET_MODE
    SQL_PACKET_SIZE

`<odbc::sql-transact DBVAR [ACTION=COMMIT|ROLLBACK]>` | Simple

Perform transaction, to either commit or rollback all operations on the current database connection.

ACTION can be one of COMMIT or ROLLBACK. If unspecified, ACTION defaults to COMMIT.

NOTE: ODBC connections default to AUTOCOMMIT mode. See `` and ``.

`<odbc::with-open-database DBVAR [DSN=DSN-STRING]> body </odbc::with-open-database>` | Complex

Create an environment in which other ODBC database commands can be given. First, the database referenced by DBNAME is locked and opened, 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.

Example:

     <odbc::with-open-database rdb DSN="DSN=oracle;host=localhost;database=test">
    ...
    </odbc::with-open-database>

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