man page(1) manual page
Table of Contents

NAME

Hx - The Hx toolkit for building web interfaces to Qddb databases.

SYNOPSIS

Hx:Init <schema_desc>
Hx:DefinedEntryForm <schema_desc> <format> Hx:ColumnSpecs <schema_desc> <name> <exclude attrs> \ <not checked attrs> <num columns>
Hx:SortSpecs <schema_desc> <name> <exclude attrs> \ <not checked attrs> <num specs>
Hx:GetPostedData
Hx:Search <schema_desc> <search list>
Hx:FormatTable <table_desc> <rowtitles=1|0> <coltitles=1|0> Hx:PruneTable <table_desc> first last
Hx:DefinedListing <schema_desc> <table_desc> format Hx:ParseError
Hx:NoSearch
Hx:NoMatches
Hx:GenericSearchEngine schema_name webmaster hostname \ mypath dbdir \
?rowincr maxrows title opening message signature procs? Hx:GenericSubmissionForm schema_name webmaster hostname \ mypath dbdir ?title opening message signature procs?

DESCRIPTION

The Hx toolkit allows programmers to easily build custom CGI web applications. A typical CGI script is in the following form for searching:

#!/usr/local/qddb/bin/qtclsh
lappend auto_path $qddb_library/hx
set dir "/var/www/cgi-bin/qddb"
set mypath "/cgi-bin/qddb/search"
set dbname MyLittleDatabase
Hx:GenericSearchEngine $dbname joe@www.somewhere \ www.somewhere $mypath $dir

For data entry, the script is very similar to the script for searching:

#!/usr/local/qddb/bin/qtclsh
lappend auto_path $qddb_library/hx
set dir "/var/www/cgi-bin/qddb"
set mypath "/cgi-bin/qddb/submit"
set dbname MyLittleDatabase
Hx:GenericSubmissionForm $dbname joe@www.somewhere \ www.somewhere $mypath $dir

Hx:Init
initializes the Hx toolkit. It should be called before using any Hx commands.

Hx:DefinedEntryForm
returns an HTML form that must then be enclosed between <form></form>. <format> is a Tcl list: {
{attribute label-width entry-type entry-width ?entry-height? ?values?} {<html> <br><br><p>Some stuff for the middle} {attribute label-width entry-type entry-width ?entry-height? ?values?} }
where attribute is the attribute name (also used as the entry name), label-width is the width of the entry's label which comes from the verbosename schema option, entry-type is one of the supported HTML form entry types (also select-single or select-multiple), and entry-width/entry-height are the width and height options to the entry. Multiple sublists may be on a single line to denote that those entries should be on a single line in the form. The currently available entry types are text, radio, checkbox, and textarea. A special entry type label allows you to build a label for an attribute and place it anywhere you like. The values list element specifies a value for checkboxes, radiobuttons, select-single, and select-multiple entry-types. Another special entry type <html> is provided to denote that everything after <html> should be inserted verbatim in the form.

Hx:ColumnSpecs
returns a formatted HTML table of checkboxes allowing the user to specify the columns of a table. The <name> is the name you wish to use for the posted results (for example, hx-columns). <exclude attrs> is a Tcl list of attribute names you want to exclude from the table, usually a list of private fields. <not checked attrs> are those attributes you do not want selected by default. <num columns> is the number of columns you want in the table containing the checkboxes.

Hx:SortSpecs
returns an HTML formatted set of selection entries allowing the user to specify the sorting of the search results. The <name> is the name you wish to use for the posted results (for example, hx_sorted). <exclude attrs> is a Tcl list of attribute names you want to exclude from the each selection, usually a list of private fields. <not checked attrs> are those attributes you do not want selected by default. <num specs> is the number of selection entries that you want (typically around 3-4).

Hx:GetPostedData
returns a list of lists, suitable for passing to Hx:Search. This list can also contain nonattribute form data, which is ignored by Hx:Search. The format of the list returned by Hx:GetPostedData is:

{
{name value} {name value}
}

where name is either an attribute name or the name of a form entry that was manually introduced into the form.

Hx:Search
accepts a list returned by Hx:GetPostedData and returns a Qddb keylist descriptor if the search is properly formatted, or an error otherwise. The keylist descriptor may then be passed to qddb_table(n) to obtain the corresponding search results.

Hx:Search does not attempt to verify whether the search criteria contains fields that were not supposed to be displayed. It is the programmer's responsibility to check for this situation if they so desire.

Hx:FormatTable
accepts a table descriptor as returned by qddb_rows(n), and two arguments specifying whether to print the row and column titles. The default is to print both row and column titles. You may optionally process the table before calling this routine for special effects such as justification, etc.

Hx:DefinedListing
accepts a schema descriptor, a table descriptor as returned by qddb_rows(n), and a format specification list. The specification list is a Tcl list of the following form:
{
{attribute entry-type ?entry-width?} {<html> <br><br><p>Some stuff for the middle} {myattr label 0} {myattr textarea 0}
}

HxPruneTable
accepts two arguments, the first and last rows you want to keep in the table, and prunes the other rows from the table. The row titles are modified to reflect each row's real position in the original table.

Hx:ParseError
is usually called to inform the user of a parsing error returned by Hx:Search.

Hx:NoSearch
is usually called to inform the user that they did not specify any search criteria.

Hx:NoMatches
is usually called to inform the user that their search did not produce any results.

Hx:GenericSearchEngine

schema_name - name of the relation (not a schema descriptor)

webmaster
- e-mail address of the webmaster
hostname
- web server's host name
mypath
- full path of the executing script
dbdir
- full path of the directory containing the Qddb relation "schema_name"

Optional arguments are as follows. Note that these arguments are optional from left to right, that is, if you specify title, you must also specify rowincr and maxrows. All these options default to the empty string.

rowincr
- rows displayed on a page (default 10)
maxrows
- total rows to allow
title
- <title> parameter
opening
- Large opening statement
message
- Message under opening statement
signature
- A signature if necessary
procs
- A Tcl list of procedure names: {entryproc listingproc tableproc columnproc sortproc}

entryproc must be the name of a valid procedure of the following form (defaults to

Hx:GenericEntryForm):

proc MyEntryProc {schema_desc} { # Some entry form goes here. Typically, # you want to call Hx:DefinedEntryForm # with special parameters. }

listingproc must be the name of a valid procedure of the following form (defaults to Hx:GenericList-ing):

proc MyListingProc {schema_desc table_desc} { # Some entry form goes here. Typically, # you want to call Hx:DefinedListing # with special parameters and/or manipulate # the table before passing it to Hx:DefinedListing }

tableproc must be the name of a valid procedure of the following form (defaults to Hx:FormatTable):

proc MyTableProc {table_desc} { # Some entry form goes here. Typically, # you want to call Hx:FormatTable # with special parameters and/or manipulate # the table before passing it to Hx:FormatTable. }

columnproc must be the name of a valid procedure of the following form (defaults to Hx:ColumnSpecs and requires the same arguments):

proc MyColumnSpecs {schema_desc varname exclude_attrs notchecked_attrs numcolumns} { # Some column specs go here. Typically, # you want to call Hx:ColumnSpecs # with special parameters or define your # own column specs as follows: append retval "<input type=hidden name=$name value=EntryNumber>" append retval "<input type=hidden name=$name value=Title>" append retval "<input type=hidden name=$name value=Size>" return $retval
}

sortproc must be the name of a valid procedure of the following form (defaults to Hx:SortSpecs and requires the same arguments):

proc MySortSpecs {schema_desc varname exclude_attrs notchecked_attrs numcolumns} { # Some sorting specs go here. Typically, # you want to call Hx:SortSpecs # with special parameters or define your # own custom sorting specs as follows:

append retval "<input type=hidden name=$name-1
value= append retval "<input type=hidden name=$name-2 value=Title>" append retval "<input type=hidden name=$name-3 value=EntryDate>" return $retval }

Hx:GenericSubmissionForm
outputs to stdout a generic submission form. The required parameters are:
schema_name - name of the relation (not a schema descriptor)
webmaster
- e-mail address of the webmaster
hostname
- web server's host name
mypath
- full path of the executing script
dbdir
- full path of the directory containing the Qddb relation "schema_name"

Optional arguments are as follows. Note that these arguments are optional from left to right, that is, if you specify opening, you must also specify title. All these options default to the empty string.

title
- <title> parameter
opening
- Large opening statement
message
- Message under opening statement
signature
- A signature if necessary
procs
- A Tcl list of procedure names: {entryproc checkproc}

entryproc is the same format as Hx:Generic-SearchEngine and defaults to Hx:GenericEntryForm.

checkproc must be the name of a valid procedure of the following form:

proc MyTupleCheckProc {tuple_desc} { # Some checks for valid fields and such go # here. If something is amiss, output # an error to stdout, and exit }

REFERENCES

A Guide to QDDB
Eric H. Herrin II and Raphael A. Finkel

Qddb User's Guide

An ASCII Database for Fast Queries of Relatively Stable Data

Eric H. Herrin II and Raphael A. Finkel Computing Systems, Volume 4 Number 2
University of California Press, Berkeley CA

Schema and Tuple Trees: An Intuitive Structure for Representing Relational Data
Eric H. Herrin, II and Raphael A. Finkel Computing Systems, Volume 9, Number 2
MIT Press, Cambridge MA

TCL and the TK Toolkit
John K. Ousterhout
Addison-Wesley, 1994
ISBN 0-201-63337-X

DIAGNOSTICS

BUGS

None known.


Table of Contents