This is Info file metahtml.info, produced by Makeinfo-1.65 from the
input file metahtml.texi.


File: metahtml.info,  Node: Top,  Up: (dir)

The Top Node
************

* Menu:

* Welcome To Meta-HTML
* The Purpose of Meta-HTML::
* Implementation Design::
* Language Syntax::
* Essential Language Features::
* Strings and Numbers::
* Input and Output::
* Defining New Tags::
* Managing the Page::
* Working with Sessions::
* Working with Databases::
* Working with the Server::
* Installation Guide::
* Installing the Server::
* Configuring the Apache Server::
* Configuring the Netscape Server::
* Configuring the NCSA Server::
* Configuring the CERN Server::
* Configuring the PLEXUS Server::
* Defined Meta-HTML Variables::
* Function Index::
* Variable Index::


File: metahtml.info,  Node: Welcome To Meta-HTML

Welcome To Meta-HTML
********************

   This document describes the Meta-HTML language, Version 5.0.  It
should not be considered a definitive reference manual by any means, as
the target remains somewhat mobile.  While the functions described in
this manual will continue to operate as documented, there may be new
functions or enhancements which supersede the functionality that the
documented ones provide.

   If you are really impatient, or you fancy yourself a wizard, I
suggest that you first look at the code examples at
http://www.metahtml.com/demos.

   Comments and/or suggestions for improvement on this manual, the
language definition, or writing style(!!) should be sent to
bug-manual@metahtml.com.

   Although World Wide Web use of the Internet has been growing at a
phenomenal rate over the past 3 years, there remains a dearth of
interesting and useful client/server applications.  Traditional
programming languages do not provide an optimal environment for
programming such applications because of the syntactical and
paradigmatic distance between traditional languages and the target
output, namely HTML.

   The stateless and dynamic nature of the WWW requires a level of
support from traditional programming languages for which they are hard
pressed to provide.  Must each application programmer write his or her
own tool set to accomplish goals which are fundamentally similar across
applications?

   Meta-HTML presents an alternative language choice for the design and
implementation of Web applications, and supplies three methods of
delivering the language.


File: metahtml.info,  Node: The Purpose of Meta-HTML

The Purpose of Meta-HTML
========================

   HTML is a description layout language.  It describes in general the
placement and visual style of elements in a page.  These elements are
generally sequences of text, with an occasional image thrown in for
good measure.

   Meta-HTML is a interpreted computer language with dynamic variables
and flow-control statements.  Although is is not a complete general
purpose computer language in the traditional sense (i.e., you cannot
write a version of a Meta-HTML interpreter in Meta-HTML) it does
perform processing and decision making of and on data elements.

   A quick example for the impatient is in order.  The text:

   You are connected to "localhost.ua.com" and reading text written by
Brian J. Fox.

   is produced in Meta-HTML by:

       <b>You are connected to ``<get-var ENV::SERVER_NAME>'' and
          reading text written by <get-var the-author>.</b>

   As the WWW grows, more and more document providers are realizing that
stateless connections are only useful for retrieving documents full of
static information, and that, at times, it can be very useful to
remember state pertaining to the browser that is connecting.

   The problem of keeping state for a particular browser user has been
resolved by various individuals; all of the solutions require
information to be passed back and forth between the browser and the
server.  For example, to play a WWW Blackjack game could involve the
passing back and forth of information including the current wins/losses
of the user, which cards have been dealt from the deck so far, and so
forth.  This information is most often passed to and fro in the form of
a "magic" URL.  The problems with passing information in this way are
two-fold:

  1. The information can be modified by the user before sending it
      back, which might allow a user to put more money in his or her
         bank account, for example, and, less importantly,

  2. The URL looks "ugly", since there is a large amount of
     information present which doesn't describe the essence of the
      location that the user is connecting to.

   Another mechanism can be taken advantage of when both the server and
browser being used support HTTP Cookies.  While this solves the problem
of "ugly" URLs, (this mechanism does not place information in the URL)
it generates a new problem: the user must be in possession of a
compliant browser, and be communicating with a compliant server.  In
addition, the information can be changed by the user before sending it
back.

   Meta-HTML solves the problem of keeping state for a particular
session, and it does it in a server and browser independent manner.
Our method requires no additional CGI programs to be written.  You can
read about the technical details in the *Note Session Operators::
section of this manual.


File: metahtml.info,  Node: Implementation Design

Implementation Design
=====================

   Initially, the vast majority of World Wide Web (WWW) documents
consisted of static pages of text and images, which were described
using HTML, and displayed using a browser which understood only the
HTML language.  The nature of a WWW connection is stateless by
definition; each request for information is not associated in any way
with any previous request for information, even when from the same
source.

   Connections are made from a browser to a WWW server, in which the
browser requests a particular item of data by specifying a Universal
Resource Locater (URL).  The server looks up the URL, and then returns
the data contained within.  While most URLs are static HTML documents,
there exists a mechanism in which a program can be run.  The output of
such a program is an HTML document, and  such programs are referred to
as Common Gateway Interface, or CGI programs.

   Meta-HTML is currently implemented as a CGI program which can be
executed every time the server is ready to retrieve a document.  As
before, the document to be retrieved can be a file of HTML, an image,
or a CGI program to be executed.  However, the document can also be a
file of Meta-HTML code, in which case the benefits of dynamic variables
and flow-control statements are fully realized.

   Although this implementation method is not server-specific, you still
must make a couple of configuration changes to your HTTP server in
order to hide the Meta-HTML program from the user.  Details are in the
Server Configuration section of this manual.


File: metahtml.info,  Node: Language Syntax

Language Syntax
===============

   A Meta-HTML document consists of plain text, HTML directives, and
Meta-HTML statements.

   The syntax of the Meta-HTML language was designed to be as similar
to HTML as possible, so as to not sacrifice readability of the total
document.  All of the Meta-HTML statements are delivered as a form   of
HTML tags.  There are two types of Meta-HTML tags:   simple and complex.

   A simple tag begins with an open angle bracket   (<) and ends with a
corresponding close angle bracket   (>).  The text enclosed within the
brackets is called the   body; it can contain assigned variables and
positional arguments.

   A complex tag begins with what looks exactly like a   simple tag,
continues throughout the body of the text, and ends with   the a
matching closing tag.  This is analogous to the use   of tags within
HTML.  The body of a complex tag is all of the text   which appears
between the opening tag and the closing tag, exclusive   of those tags
themselves.

   Here is an example of using the simple tag `set-var':

         <set-var foo=bar>

   Here is an example of using the complex tag `when':

         <when <get-var foo>>
           The value of `foo' is <get-var foo>.
         </when>

   Note that both the `set-var' and `when' forms   have opening tags
which contain additional material.  This   material is used to supply
information to the form.

   Additionally note that "simple" and "complex" do not refer to the
complexity of the function performed; they simply refer to the syntax
used to write the form in a document.  For example, the simple tag
*Note var-case:: performs a complex operation based upon   the
arguments it is given.

   Variables assigned in the opening (or simple) tag have the form:

         name=value

   This gives the variable referred to as `name' a local value   of
`value'.  Variable assignments such as these give the   Meta-HTML
writer a way to pass dynamic arguments to a function.  For   example,
the *Note with-open-database:: form can open the   requested database
in one of 3 modes; you control which one by locally   assigning the
variable `mode' within the form:

         <with-open-database db "/phones.db" mode=<get-var db-mode>>
          ...
         </with-open-database>

Quoting Syntax
..............

   At times, you will need to quote the expressions that you pass to
various Meta-HTML functions.  You do this with double quotes   (`"')
and blackslashes (`\').  Here is a   somewhat hairy example of quoting:

         <if <get-var "Space Name">
             <get-var "Space Name[space index]">
           <set-var space-name-present=false>>

   For most cases, quoting is unnecessary, because open braces are
expected to match close braces, and doubles quotes are expected to
come in pairs.  This is the usual case.  For example:

         <ifeq <get-var foo[index]> <get-var bar>
             <set-var array[index]=<get-var bar>-found>
           <set-var array[index]=<get-var bar>-missing>>

   In the above example, no quoting was required because the only
whitespace which appeared in the expression was within a set of
matched braces.


File: metahtml.info,  Node: Essential Language Features,  Next: Strings and Numbers,  Prev: Language Syntax,  Up: Top

Essential Language Features
***************************


File: metahtml.info,  Node: Variables

Variables
=========

   Meta-HTML provides a simple mechanism for the storage and retrieval
of variables during a single (possibly recursive) processing pass.  In
addition to this, functions are provided which test the value of a
variable, and conditionally execute other code based upon the result.

   There is also a mechanism to group a set of variables using *Note
Packages::.

Variable Types and Information
..............................

   There are internal functions in Meta-HTML which create binary
variables.  Such variables cannot be used in the ordinary way, since
the data contained within them may not retain integrity once printed
out and read back in.  You can check to see what the type of a
particular variable is with the *Note symbol-info:: function.

   Many variables are predefined by Meta-HTML, and made available to
the page writer.  The *Note Page Variables::  section of this manual
documents those variables fully, while the *Note Server Variables::
section contains more information on variables which control, or were
specifically created by, the web server.

 - Simple Tag: cgi-decode STRING [PACKAGE]
     Decode STRING into PACKAGE.

     If PACKAGE is not specified the current package is used.

     Also see *Note cgi-encode::.


 - Simple Tag: cgi-encode VAR1 [VAR2...]
     A CGI readable string is created from the names of VAR1 ... VARN
     and the associated values of those variables.  For example, if the
     variable `FOO-VAR' has the value `"Foo & Value"', then the
     invocation

              <cgi-encode FOO-VAR>

     returns:

     `FOO-VAR=Foo+%26+Value'


 - Simple Tag: coerce-var VARNAME [TYPE=(STRING|BINARY)]
     Coerces VARNAME's data to have the type specified by the argument
     to TYPE.  You can convert a binary object to a string object, and
     vice-versa.

             <with-open-stream s /tmp/file mode=read>
               <stream-get-contents s foo>
             </with-open-stream>
          
             <coerce-var foo type=string>


 - Simple Tag: copy-var FROM-VAR [TO-VAR...]
     Copies the variable FROM-VAR to each of the named TO-VARs.

     Each TO-VAR becomes the repository of a copy of the information
     already stored under FROM-VAR.  This is a true copy; not an alias
     to the original variable.

             <set-var foo=bar>
             <get-var foo>      ==> bar
             <get-var new>      ==>
             <copy-var foo new> ==>
             <get-var new>      ==> bar
          
             <copy-var *metahtml*::get-var foo>
             <foo new>          ==> bar


 - Simple Tag: decrypt VARNAME PASSWORD
     Decrypts the contents of the previously encrypted variable named
     by VARNAME using PASSWORD.

     The contents of VARNAME are modified - this function has no return
     value.

     This function only does something if Meta-HTML has been configured
     with the ` --with-des' option, currently only available to those
     sites which are physically located within the United States.

     Also see *Note encrypt::.


 - Simple Tag: encrypt VARNAME PASSWORD
     Encrypts the contents of the variable named by VARNAME using
     PASSWORD.

     The contents of VARNAME are modified - this function has no return
     value.

     This function only does something if Meta-HTML has been configured
     with the ` --with-des' option, currently only available to those
     sites which are physically located within the United States.

     Also see *Note decrypt::.


 - Simple Tag: get-var [NAME...]
     Returns (as a text string) the current value of the variables
     named by the NAMEs given.


 - Simple Tag: get-var-once [NAME...]
     Returns the current value of the variables named by the NAMEs
     given.  The interpreter pointer is then moved to after the
     returned data, thus preventing further interpretation of the data.


 - Simple Tag: set-var [NAME=VALUE...]
     Gives the variable NAME the value of VALUE for the current
     processing run.  Any number of name/value pairs may be given, and
     whitespace is not significant.  Where =VALUE is omitted, the value
     is the empty string.


 - Simple Tag: sort ARRAY-VAR
     Sort the contents of the array ARRAY-VAR.

     This does a quicksort ascending sort.


 - Simple Tag: subst-in-var VARNAME [THIS] [WITH-THAT] [...]
     Replaces all occurrences of THIS with WITH-THAT in the contents of
     the variable named VARNAME.  Both THIS and WITH-THAT are evaluated
     before the replacement is done. THIS can be any regular expression
     allowed by the POSIX extended regular expression matching.  This
     command can be useful when parsing the output of *Note cgi-exec::.


 - Simple Tag: unset-var [NAME...]
     Make NAMEs be non-existent in the page environment.


 - Simple Tag: var-exists VARNAME
     `var-exists' checks for the existence of the variable named by
     VARNAME, and returns `true' if that variable exists.

     The existence of a variable has nothing to do with its value - a
     variable exists if it has been created with *Note set-var::, and
     doesn't exist after it has been unset with *Note unset-var::.

            <set-var foo=1 bar>
            <var-exists foo>       ==> true
            <var-exists bar>       ==> true
            <get-var bar>          ==>
            <unset-var foo>
            <var-exists foo>       ==>



File: metahtml.info,  Node: Arrays

Arrays
======

   Meta-HTML allows the use of array variables as well as single
element variables.  In fact, all string variables in Meta-HTML can be
treated as array variables - there is no special command for creating
such variables.  Array variable values are referenced by placing the
array index directly after the variable name, enclosed in square
brackets ([ and ]).  Thus, a reference to the 3rd element of the array
FOO looks like:

        foo[3]

   When an array reference is made without any containing index, the
reference refers to the entire array.  So, to get the value of the
entire array stored in FOO, you would write:

        <get-var foo[]>

   In order to ease the writing of array references which rely on a
variable index, a variable name seen as an array reference index is
automatically looked up as if you had written   `<get-var VAR>'.
Finally, multiple values may be given in a *Note set-var:: command by
separating those values with newline characters.  The following
sequence of commands illustrates the typical use of array variables.

     <set-var array[] =
            "value-zero
             value-one
             value-two
             value-three">
         <set-var i=0>
         <while <get-var array[i]>>
           The value of array[<get-var i>] is `<get-var array[i]>'.<br>
           <increment i>
         </while>

   produces


               The value of array[0] is `value-zero'.
     
               The value of array[1] is `value-one'.
     
               The value of array[2] is `value-two'.
     
               The value of array[3] is `value-three'.


File: metahtml.info,  Node: Packages

Packages
========

   Packages are repositories which contain symbols and their values.

   Each time a symbol is referenced, a package must first be found, and
then the symbol may be found within that package. You indicate which
package to look the symbol up in by supplying a package prefix.  When
the prefix is not supplied, the symbol is looked up in the current
package.

   For example, a full reference to the symbol BAR stored in the FOO
package looks like:

        FOO::BAR

   There are very few commands specifically for dealing with packages,
because most of the operations are performed implicitly, rather than
explicitly.  To create a package, simply give the package name as part
of the symbol, in the place where the symbol is normally used.

        <set-var foo::bar = "Hello">

   This has the effect of creating the package FOO if it didn't already
exist.

 - Simple Tag: %%read-package-file FILENAME
     Reads packages from FILENAME.  FILENAME should contain the binary
     representation of packages that were written out with *Note
     %%write-package-file::, and nothing else.

     Returns a number indicating the number of packages read from the
     file.

     This is used internally by *Note require::.


 - Simple Tag: %%write-package-file FILENAME [PACKAGE-NAME...]
     Writes the binary representation of the packages specified by
     PACKAGE-NAMEs to the file specified by FILENAME.

     Returns the number of packages written.

     The packages may be read back in with *Note %%read-package-file::.
     This command is used in the `mklib' program in the Meta-HTML
     distribution.


 - Simple Tag: alist-to-package ALIST PACKAGE-NAME
     Takes the textual list representation of a package, and creates
     (or modifies) the package named by PACKAGE-NAME.


 - Complex Tag: in-package PACKAGE-NAME
     Evaluate BODY in an environment where variables which are not
     specifically prefixed with a package name are looked up and stored
     within PACKAGE-NAME.

     The special package name `"local"' creates an anonymous package
     within which to work.  The contents of local packages are only
     accessible within the expressions surrounded by the `in-package'
     operator.


 - Simple Tag: package-delete PACKAGE-NAME ...
     Remove the definition of the packages named by PACKAGE-NAME, and
     all of the variables defined within them.


 - Simple Tag: package-names
     Returns a newline separated list of the all of the named packages
     which are currently defined.  Because the list is newline
     separated, the result can easily be assigned to an array variable:

            <set-var all-packages[]=<package-names>>


 - Simple Tag: package-to-alist PACKAGE-NAME [STRIP=TRUE]
     Returns a Lisp readable string containing the names and values of
     the variables in PACKAGE.  If STRIP=TRUE is supplied, the package
     name is removed from the variables before placing them in the
     list.  See the following code sequence:

          <set-var
            foo::bar=baz
            foo::array[0]=Elt-0
            foo::array[1]=Elt-1>
          
            The contents of Foo: <package-to-alist foo>
          The stripped contents: <package-to-alist foo strip=true>

     produces


            The contents of Foo: (("FOO::BAR" . "baz")("FOO::ARRAY" "Elt-0" "Elt-1"))
          The stripped contents: (("BAR" . "baz")("ARRAY" "Elt-0" "Elt-1"))


 - Simple Tag: package-vars PACKAGE-NAME [STRIP=TRUE]
     Returns a newline separated list of the fully qualified variable
     names found in the package named by PACKAGE-NAME.  When STRIP=TRUE
     is supplied, the returned variable names have the package prefix
     stripped off, making them not fully qualified.  The names are not
     returned in any significant order.  Because the list is  newline
     separated, the results can easily be assigned to an array variable:

            <set-var foo::bar=baz>
            <set-var foo::baz=bar>
            <set-var names[]=<package-vars foo>>
            <get-var names[1]>

     Produces:

     `FOO::ARRAY'



File: metahtml.info,  Node: Flow Control

Flow Control
============

   Meta-HTML contains commands for controlling which of a set of
statements will be executed, and for repetitive execution of a set of
statements.

   Such commands constitute what is called flow control, since they
tell the Meta-HTML interpreter where or what the next statement to
interpret resides.

   All of the flow control operators in Meta-HTML take a test and some
additional statements; the closest thing to a goto statement in
Meta-HTML is the *Note redirect:: command.

 - Simple Tag: if TEST [THEN] [ELSE]
     First TEST is evaluated.  If the result is a non-whitespace only
     string, the THEN clause is evaluated, otherwise, the ELSE clause
     is evaluated.  Although Meta-HTML has an `or' function, you can
     efficiently test for the presence of any of a group of variables
     with code similar to the following:

            <if <get-var foo bar>
                "Either FOO or BAR is present"
              "Neither FOO nor BAR is present">


 - Simple Tag: ifeq THIS THAT [THEN] [ELSE] [CASELESS=TRUE]
     The THIS and THAT clauses are evaluated.  If the results are
     text-wise identical, then the THEN clause is evaluated, otherwise,
     the ELSE clause is evaluated.  If CASELESS=TRUE is given, the
     text-wise comparison of the values is done with no regard to upper
     and lower case distinctions.


 - Simple Tag: redirect URL
     Immediately return the HTTP Location directive with URL.  This
     command is extremely useful in conjunction with *Note var-case::;
     in effect, that usage creates a dispatch table.


 - Complex Tag: server-push
     This command will be made obsolete.

     Its functionality is available other, cleaner ways, specifically
     through the use of *Note with-open-stream:: and the variable
     `*standard-output*'.

     Just write it as a *Note defmacro::.


 - Simple Tag: var-case [NAME=VALUE] [CONSEQUENT]
     For each "NAME=VALUE" pair, the value of NAME is looked up in the
     current package, and compared with value of VALUE.  If they are
     equal, then CONSEQUENT is evaluated, and no further cases are
     checked.


 - Complex Tag: when TEST
     Evaluate TEST.  If the result is a non-empty string, then execute
     the BODY statements.  This is a cleaner way to handle optional
     multiple statement execution rather than dealing with quoting
     everything inside of an *Note if:: form.


 - Complex Tag: while TEST
     TEST is evaluated.  If the result is a non-empty string, then the
     BODY statements are evaluated, and the process is repeated.



File: metahtml.info,  Node: Language Operators

Convenience Primitives
======================

   Meta-HTML provides various functions and variables which are used to
operate on or within the language environment itself, rather than
within the application environment.

   Such constructs make it possible to create self-modifying code, to
change the way in which a builtin function operates, and other such
language dependent features.

 - Simple Tag: %%eval [EXPRESSION]
     Internal function which performs evaluation.

     If you think that you need this in your program, you probably are
     doing something wrong.


 - Simple Tag: %%read [EXPRESSION]
     Internal function which performs Meta-HTML reading.

     If you think that you need this in your program, you probably are
     doing something wrong.


 - Simple Tag: concat [ARG1] [...] [ARGN]
     Concatenate all of the arguments given, creating a single token
     with no intervening whitespace.  This is quite useful for those
     situations where intervening whitespace would look bad in the
     output, but the input source would be unreadable without any.

     For example:

           <concat <textarea name=label rows=10 cols=40>
                   <get-var-once label>
                   </textarea>>


 - Simple Tag: date [EPOCH-SECONDS]
     Returns the local date as a string of 24 characters.

     The output looks like `Sat Nov  9 15:05:37 1996'.

     Given the optional argument EPOCH-SECONDS, this number is treated
     as the number of seconds since 12 midnight, December 31st, 1969,
     and is converted into the current date.

     Also see the *Note time:: function.


 - Simple Tag: debugging-on [FUNCTION-NAME=LEVEL]
     Turns on debugging for the FUNCTION-NAMEs mentioned, setting the
     level of output to LEVEL.  LEVEL is a number between `0' (the
     least amount of debugging info) and `10' (the maximum amount of
     debugging info).

     The output is placed into the Meta-HTML internal debugger buffer,
     and can be placed into an output page by simply placing the tag
     <*Note DEBUGGING-OUTPUT::> somewhere in the page.


 - Simple Tag: DEBUGGING-OUTPUT
     By placing the `<DEBUGGING-OUTPUT>' tag somewhere in the page, you
     mark the location at which the Meta-HTML engine, server, or
     standalone processer should place any debugging statements which
     have been collected during the processing of the statements in the
     current page.

     Without the presence of this tag, no debugging information will be
     displayed as part of the final output.

     We recommend that you always place this tag somewhere in the
     output page, whenever that output is an HTML document, as opposed
     to a standalone script.


 - Simple Tag: function-def NAME
     Returns the Meta-HTML readable form of the function body stored in
     the user-defined function NAME.

     User-defined functions are made using *Note defmacro::, *Note
     defsubst::, or *Note defun::.


 - Simple Tag: page-debug BODY
     Cause BODY to be inserted into the debugger output.

     This output shows up as the result of placing the special tag
     <*Note DEBUGGING-OUTPUT::> somewhere in the page.


 - Simple Tag: pid
     Returns the current process ID on those systems which have process
     ID's.


 - Simple Tag: prog CODE...
     Combine all of the material passed into a single Meta-HTML
     statement.  This is the primitive for grouping multiple statements
     where only a single statement is expected.

     For example:

          <if <eq this that>
             <prog <h2> This is equal to That </h2>>
            <prog <h2> This is not equal to That </h2>>>

     Although *Note prog:: is a primitive in Meta-HTML, it could have
     been defined as:

          <defsubst prog>%body</defsubst>


 - Simple Tag: symbol-info SYMBOL
     Returns information about the symbol SYMBOL.

     The information is two lines:

       1. The type of the symbol, either STRING, BINARY, or FUNCTION.

       2. The "size" of the symbol.

     For STRING variables, the size value is the number of elements in
     the array.

     For BINARY variables, the size value is the number of bytes of
     binary data stored within.

     The size value is zero for all other variable types.


 - Simple Tag: SYSTEM-ERROR-OUTPUT
     By placing the `<SYSTEM-ERROR-OUTPUT>' tag somewhere in the page,
     you mark the location at which the Meta-HTML engine, server, or
     standalone processer should place any error statements which have
     been collected during the processing of the statements in the
     current page.

     Without the presence of this tag, no system error information will
     be displayed as part of the final output.

     We recommend that you place this tag somewhere in the page while
     you are building and testing your application, or, if you are
     having confusing behavior from an existing application.

     Commands which manipulate files may place information about the
     underlying cause of the error condition here.


 - Simple Tag: time
     Returns the current local time, as measured in seconds since the
     epoch (12 midnight, December, 1969).

     This is often useful as input to the *Note date:: operator.  Here
     is how one might find out the printable date for the time 10 hours
     from now.

             <date> ==> Wed Jul  3 17:14:53 1996
             <date <add <time> <mul 60 <mul 10 60>>>>
                    ==> Thu Jul  4 03:14:57 1996



File: metahtml.info,  Node: Strings and Numbers,  Next: Input and Output,  Prev: Essential Language Features,  Up: Top

Strings and Numbers
*******************


File: metahtml.info,  Node: String Operators

String Operators
================

   There is a single function in Meta-HTML which performs pattern
matching, substring extraction, and substring deletion.  For
convenience, a blind substring extraction function is supplied as well.
Three functions perform the three most common case changes.  Finally,
the *Note pad:: function allows alignment of fixed-width text.

 - Simple Tag: capitalize STRING
     Changes the case of each character in STRING to uppercase or
     lowercase depending on the surrounding characters.

             <capitalize "This is a list">

     produces

             This Is A List

     Also see *Note downcase::, and *Note upcase::.


 - Simple Tag: downcase STRING
     Converts all of the uppercase characters in STRING to lowercase.

             <downcase "This is Written in Meta-HTML">

     produces

             this is written in meta-html

     Also see *Note upcase::, and *Note capitalize::.


 - Simple Tag: match STRING REGEXP
          [ACTION=(REPORT|DELETE|EXTRACT|STARTPOS|ENDPOS|LENGTH)]
     Matches REGEXP against STRING and then performs ACTION. The
     default ACTION is `report'; when the expression matches the string
     `match' returns the text `true'.

     Here are some examples:

            <match "foobar" ".*">                 ==> "true"
            <match "foobar" "foo">                ==> "true"
            <match "foobar" "foo" action=extract> ==> "foo"
            <match "foobar" "oob" action=delete>  ==> "far"
            <match "foobar" "oob" action=startpos>==> "1"
            <match "foobar" "oob" action=endpos>  ==> "4"
            <match "foobar" "oob" action=length>  ==> "3"
            <match "foobar" "[0-9]*">             ==> ""


 - Simple Tag: pad STRING TOTAL-SIZE [ALIGN=(RIGHT|LEFT|MIDDLE)]
          [TRUNCATE]
     Pads STRING to a length of TOTAL-SIZE.  ALIGN can be one of
     `LEFT', `MIDDLE', or `RIGHT' (the default).

     `PAD' inserts the correct number of spaces to make the input
     argument take the desired number of spaces (presumably for use in
     a   `<pre> ... </pre>' statement).

     The optional arg `TRUNCATE' says to force the string to be the
     specified length.

     Before any padding is done, leading and trailing whitespace is
     removed from STRING.

     Examples:

            <pad "Hello" 10>              ==> "     Hello"
            <pad "Hello" 10 align=left>   ==> "Hello     "
            <pad "Hello" 10 align=middle> ==> "  Hello   "
            <pad "  Heckle  " 4 truncate> ==> "Heck"


 - Complex Tag: plain-text [FIRST-CHAR=EXPR] [NOBR=TRUE]
     Performs the following steps:

       1. Replace occurrences of pairs of newline characters with a
          single   `<P>' tag.

       2. Applies the function EXPR to the first character of every
          paragraph, and inserts the closing tag after that character.

     The output will start with a   `<P>' tag, unless the optional
     argument NOBR=TRUE is given.

          <plain-text first-char=<font size="+1"> nobr=true>
            This is line 1.
          
            This is line 2.
          </plain-text>

     produces

            This is line 1.
          
            This is line 2.


 - Simple Tag: small-caps [UPPER=SIZE] [LOWER=SIZE] [OTHER=SIZE]
     Modify the characters in BODY raising lower-case characters to
     upper-case, and changing the size of fonts as directed.  For
     example, this is how "HELLO THERE" can be produced:

            <small-caps lower=-1>Hello There</small-caps>


 - Simple Tag: string-eq STRING1 STRING2 [CASELESS=TRUE]
     Compare STRING1 to STRING2 and return the string `"true"' if they
     are character-wise identical.

     The optional keyword argument CASELESS=TRUE indicates that no
     consideration should be given to the case of the characters during
     comparison.

             <string-eq "foo" "FOO">               ==>
             <string-eq "foo" "foo">               ==>true
             <string-eq <upcase "foo"> "FOO">      ==>true
             <string-eq "foo" "FOO" caseless=true> ==>true


 - Simple Tag: subst-in-string STRING REGEXP REPLACEMENT [REGEXP]
          [REPLACEMENT] [...]
     Replaces all occurrences of REGEXP with REPLACEMENT in STRING.

     REGEXP can be any regular expression allowed by POSIX extended
     regular expression matching.

             <set-var foo="This is a list">
             <subst-in-string <get-var foo> "is" "HELLO">
                  ==> "ThHELLO HELLO a lHELLOt"
          
             <subst-in-string "abc" "([a-z])" "\\1 "> ==> "a b c "


 - Simple Tag: substring STRING START [END]
     Extracts the substring of STRING whose first character starts at
     offset START, and whose last character ends at offset END. The
     indexing is zero-based, so that:

            <substring "Hello" 1 2> ==> "e"

     This function is useful when you know in advance which part of the
     string you would like to extract, and do not need the pattern
     matching facilities of *Note match::.


 - Simple Tag: upcase STRING
     Converts all of the lowercase characters in STRING to uppercase.

             <upcase "This is a list">

     produces

             THIS IS A LIST

     Also see *Note downcase:: and *Note capitalize::.


 - Simple Tag: word-wrap STRING [WIDTH=CHARWIDTH]
     Produce paragraphs of text from the string STRING with the text
     filled to a width of CHARWIDTH.

     This is provided for convenience only, and is of use when you need
     to present some free form text in pre-formatted fashion, such as
     when sending an E-mail message, or the like.



File: metahtml.info,  Node: Arithmetic Operators

Arithmetic Operators
====================

   Meta-HTML contains a small set of commands for operating on
numerical quantities.

   All of the arithmetic operators described in this section can accept
a number, or simply the name of a variable, which is then looked up as
if it had been written with   `<get-var ...>'.

   That is to say:

        <set-var total = <add <get-var subtotals[0]>
                              <get-var subtotals[current]>>>

   can be written as:

        <set-var total = <add subtotals[0] subtotals[current]>>

   The binary arithmetic operators always expect two arguments, and
will produce a warning message in *Note DEBUGGING-OUTPUT:: when given
too few arguments.

   You can perform floating point arithmetic if one or both of the
arguments is already a floating point number:

       <div 10 3>    ==> 3
       <div 10.0 3>  ==> 3.33

 - Simple Tag: add ARG1 ARG2
     Returns the sum of ARG1 and ARG2.


 - Simple Tag: decrement VARNAME [BY=AMOUNT]
     Subtract AMOUNT (default 1) from the contents of the variable
     named by VARNAME.

             <set-var foo=1>
             <get-var foo> ==> 1
             <decrement foo>
             <get-var foo> ==> 0

     Also see *Note increment::.


 - Simple Tag: div ARG1 ARG2
     Returns the quotient of ARG1 and ARG2.

              <div 12 2> ==> 6
              <div 10 3> ==> 3


 - Simple Tag: increment VARNAME [BY=AMOUNT]
     Add AMOUNT (default 1) to the contents of the variable named by
     VARNAME.

             <set-var foo=1>
             <get-var foo> ==> 1
             <increment foo>
             <get-var foo> ==> 2

     Also see *Note decrement::.


 - Simple Tag: mod ARG1 ARG2
     Returns the remainder of ARG1 and ARG2.

              <mod 12 2> ==> 0
              <mod 10 3> ==> 1


 - Simple Tag: mul ARG1 ARG2
     Returns the product of ARG1 and ARG2.

              <mul 12 2> ==> 24


 - Simple Tag: random [ARG]
     Returns a pseudo-random number between 0 and ARG -1.  The
     distribution is pretty good; calling   `<random 2>' returns 0 50%
     of the time, and 1 the other 50%.

     Also see *Note randomize::.


 - Simple Tag: randomize [ARG]
     Sets the pseudo-random number generator seed to ARG.  The next
     call to `random' uses this seed value to find the next
     pseudo-random number.  There is no return value.

              <randomize 10>
              <random 100> ==> 28
              <random 100> ==> 15
              <randomize 10>
              <random 100> ==> 28


 - Simple Tag: sub ARG1 ARG2
     Returns the difference of ARG1 and ARG2.

              <sub 12 2> ==> 10



File: metahtml.info,  Node: Relational Operators

Relational Operators
====================

   Relational operators in Meta-HTML return information about the
relationship between two items.  There are three logical operators,
*Note and::, *Note or::, and *Note not::.

   There are several other operators which compare numeric values; the
section *Note Arithmetic Operators:: cover those in detail.

 - Simple Tag: and EXPR [...]
     Evaluates the EXPRs until one of them results in the empty string,
     or they are all exhausted.

     The result of this expression is the last value evaluated.


 - Simple Tag: eq ARG1 ARG2
     Returns the string `"true"' when the number value of ARG1 is equal
     to the number value of ARG2.


 - Simple Tag: gt ARG1 ARG2
     Returns the string `"true"' when the numeric value of ARG-1 is
     greater than the numeric value of ARG-2.


 - Simple Tag: lt ARG1 ARG2
     Returns the string `"true"' when the numeric value of ARG-1 is
     less than the numeric value of ARG-2.


 - Simple Tag: not [BODY]
     BODY is evaluated.  If the result is the empty string, then the
     string "true" is returned, otherwise, nothing is returned.  The
     BODY is simply the entire contents of the simple tag, without the
     word "not" in it. Thus, in typical usage, one might write:

            <when <not <get-var foo>>>
               <comment> Complain that FOO is missing. </comment>
            </when>


 - Simple Tag: or EXPR [...]
     Evaluates the EXPRs until one of them results in a non-empty
     value, or they are all exhausted.

     The result of this expression is the last value evaluated.



File: metahtml.info,  Node: Input and Output,  Next: Defining New Tags,  Prev: Strings and Numbers,  Up: Top

Input and Output
****************


File: metahtml.info,  Node: File Operators

File Operators
==============

   There are several types of commands in Meta-HTML for dealing with
files.

   Some of these commands operate directly on an open files, while
others operate on streams, which may be connected to files or network
data.

   The functions allow you to *Note include:: the contents of, open,
create, read, or write various data sources, or to replace the contents
of page with another file.  Commands such as *Note
get-file-properties:: may return additional information on some
systems; this is documented with each function where that is the case.

   Also see *Note Stream Operators::.

 - Simple Tag: cgi-exec PATHNAME [ARG1] [...] [ARGN] [OUTPUT=VARNAME]
          [ERRORS=VARNAME]
     Execute the system function named by <var path>, perhaps passing
     it arguments <var arg1 ... argn>.

     If <var output=varname> is supplied, then <var varname> receives
     the output of the system function.  Otherwise, the resultant
     output is placed in the page.


 - Simple Tag: directory-contents PATH [PACKAGE-NAME] [MATCHING=PATTERN]
     Returns a newline separated list of association lists for the
     files matching PATTERN.

     When PACKAGE-NAME is supplied, each variable in PACKAGE-NAME is
     the name of a file in PATH, and the value of each variable is the
     association list for that file.


 - Simple Tag: get-file-properties PATH
     Return an association-list containing operating system information
     about the file or directory named by PATH. PATH must be given
     fully; it is not relative to Web space in any way.

     If the file exists and is accessible, the members of the returned
     association-list which are guaranteed to be present are:
     Member 	Value 	Description

     	 NAME 	welcome.mhtml 		  The name of the file or directory,
     without any of the path 	  information.

     	FULL-NAME 	/www/site/docs/welcome.mhtml 		  The name of the
     file or directory, with full path 	  information.  This should be
     identical to PATH as 	  received by `get-file-properties'.

     	 SIZE 	2188 		  The size of the file in bytes.

     	TYPE 	FILE 		  The type of the file.  This will either be
     `FILE' or `DIRECTORY'.

     		  In addition to the above fields, the following fields appear
     on Unix based systems.

     	CREATED 	6 29 96 10 3 24 		  The date on which this file was
     created.  The value is an 	  array, with ordered values
     being: month, day, year, hours, 	  minutes, and seconds.

     	WRITTEN 	6 29 96 10 3 24 		  The date on which this file was
     last written.  The value is an 	  array, with ordered values being:
     month, day, year, hours, 	  minutes, and seconds.

     	READ 	6 30 96 19 27 51 		  The date on which this file was
     last read.  The value is an 	  array, with ordered values being:
     month, day, year, hours, 	  minutes, and seconds.

     	CREATOR 	bfox 		  The system identifier of the user
     who created this file.


 - Simple Tag: include FILENAME [ALT=CODE] [VERBATIM]
     Insert the contents of the file named by FILENAME into     the
     document at the point where the `include' form was     read.  If
     the positional argument VERBATIM is given, then     the contents
     of the file are not executed, only inserted.  Otherwise,
     execution resumes at the point where the file was inserted.

     FILENAME can be given as an absolute pathname, or a     relative
     pathname.  If the path is relative, it is considered to be
     relative to the location of the document which contains the
     `include' form.  If the path given is not relative, it is
     appended to the directory found in MHTML::INCLUDE-PREFIX.

     If the named file could not be found on the server, and an     ALT
     value is given, then that value is placed into the     page
     instead.


 - Simple Tag: require STEM
     `require' tries hard to locate the source or library file
     specified by STEM, and then loads that file if it hasn't already
     been loaded.

     If the variable `mhtml::require-directories' is present, then it
     is an array of directory names (without trailing slashes) relative
     to Web space that should be searched through, in the order that
     they appear in the array.

     `require' understands the following extensions:

        * .mhtml, or .src: A Meta-HTML source file.

        * .lib: A Meta-HTML library file.

     `require' loads the newest version of the file that it finds, and
     records the complete pathname of the loaded file in the array
     variable `mhtml::require-loaded'.



File: metahtml.info,  Node: Stream Operators

Stream Operators
================

   A stream is a data object upon which various input and output
operations may be performed.

   Meta-HTML provides commands for creating, opening, reading from, and
writing to, stream objects.  The referenced underlying object may
either be a file, or a network connection.

 - Simple Tag: stream-get STREAM [STOP-AT=CHARACTER]
     Reads a chunk of data from STREAM and returns it.  STREAM is read
     until the character value specified by CHARACTER (defaulting to a
     newline) is reached, and that data upto and including the final
     CHARACTER is returned.  One way to read all of the available data
     is to supply the empty string as the value of STOP-AT:

            <with-open-stream stream www.ua.com:80 type=tcp mode=read-write>
              <stream-put stream "GET /welcome.mhtml HTTP/1.0\n\n">
              <set-var the-page=<stream-get stream stop-at="">>
            </with-open-stream>


 - Simple Tag: stream-get-contents STREAM VAR
     Reads the contents of the stream STREAM into the binary variable
     VAR.  You had better understand binary variables before you use
     this. However, you can easily use this in conjunction with *Note
     stream-put-contents::, and *Note coerce-var::.


 - Simple Tag: stream-put STREAM STRING
     Writes STRING to STREAM.


 - Simple Tag: stream-put-contents STREAM VAR
     Writes the contents of the binary variable VAR to STREAM.  You had
     better understand binary variables before you use this.  However,
     you can easily use this in conjunction with *Note
     stream-get-contents::.


 - Simple Tag: stream-readable STREAM
     Returns `"true"' if STREAM is an open stream which was opened with
     a mode of `read' or `read-write', or nothing otherwise.


 - Simple Tag: stream-shutdown STREAM
     Only for use with network streams, this tells the underlying
     operating system (and the other end of the network connection)
     that no additional input or output will be done using this object.
     In effect, it immediately closes the stream.

     When used in conjunction with `', this can be used to close the
     HTTP connection to the client, and yet continue processing data.


 - Simple Tag: stream-writable STREAM
     Returns `"true"' if STREAM is an open stream which was opened with
     a mode of `write', `append', `write-create' or `read-write', or
     nothing otherwise.


 - Complex Tag: with-open-stream VAR NAME [TYPE=(FILE|TCP)]
          [MODE=OPEN-MODE]
     Create an environment in which VAR is bound to the indicator of an
     open stream, named by NAME.

     The stream is either of type `FILE', or `TCP', in which case it is
     an open network connection.  When TYPE is `TCP', NAME specifies
     the host and port to connect to, in the form
     `Hostname:Port-Number'.  PORT-NUMBER can either be a symbolic name
     which is widely recognized (e.g., `SMTP'), or the digits which
     make up the port number, (e.g., `25').  The possible values for
     MODE are:

        * `READ':

          The stream is opened for reading only.  The underlying object
          must already exist.

        * `WRITE':

          The stream is opened for writing only.  The underlying object
          must already exist.

        * `READ-WRITE':

          The stream is opened for both reading and writing.  The
          underlying object must already exist.

        * `APPEND':

          The stream is opened for writing only.  If the underlying
          object did not already exist, it is created.  Information
          written to this stream appears after any information that was
          already present in the underlying object.

        * `WRITE-CREATE':

          The stream is opened for writing only.  The underlying object
          is created fresh, even if it had already existed.



File: metahtml.info,  Node: Defining New Tags,  Next: Managing the Page,  Prev: Input and Output,  Up: Top

Defining New Tags
*****************


File: metahtml.info,  Node: Macro Commands

Macro Commands
==============

   Meta-HTML contains a powerful macro facility, which allows you to
define your own commands.  Such commands are first-class objects in
Meta-HTML; they may even supersede the compiled in definitions.

   There are two types of macros that you can define.  One type is a
complex-tag; it consists of an opening tag, a body, and a closing tag.
The other type is a simple-tag; it only has an opening tag.

   You create a macro by using one of the macro-defining commands.  In
the body of the definition, special keywords can be placed, which
affect what is produced when the macro is invoked.  As a macro writer,
you have logical access to the arguments passed to the macro in the
opening tag, and for complex-tags, you have access to the body which
appears between the opening and closing tags.

 - Complex Tag: define-container NAME [NAMED-PARAMETER...]
          [PACKAGE=PACKAGE-NAME] [WHITESPACE=DELETE]
     Define NAME as a complex tag.  Within BODY, the values of
     `%0...%9' are defined to be the positional arguments that were
     found in the opening tag of the invocation, and `%body' is the
     material that appeared between the opening and closing tags.

     If any NAMED-PARAMETERs are supplied, the values that were passed
     in the opening tag are evaluated and bound to the named parameters.

     A keyword argument of PACKAGE-NAME wraps the entire body of the
     macro in an *Note in-package:: statement.

     The keyword argument WHITESPACE can be set to the string `delete'
     to remove whitespace from the starts and ends of lines in the
     macro definition before it is stored.  This effectively
     concatenates all of the lines of the macro definition into a
     single long line.


 - Complex Tag: define-function NAME [NAMED-PARAMETER...]
          [PACKAGE=PACKNAME]
     Define NAME as a simple tag.

     The only differences between *Note define-function:: and *Note
     define-tag:: are:
       1. The whitespace=delete option is assumed.

       2. The NAMED-PARAMETERs are evaluated in the context of the
          caller, not of the definition of the defun.

       3. By default, a local package is wrapped around the invocation
          of the defined function.  This can be changed by the use of
          the PACKAGE=PACKNAME keyword.

          <define-function factorial num>
             <if <lt num 2> 1
                <mul num <factorial <sub num 1>>>>
          </define-function>
          
          <factorial 5> ==> 120


 - Complex Tag: define-tag NAME [NAMED-PARAMETER...]
          [PACKAGE=PACKAGE-NAME] [WHITESPACE=DELETE]
     Define NAME as a simple tag.  Within BODY, the values of `%0...%9'
     are defined to be the positional arguments that were found in the
     opening tag of the invocation, and `%body' is all of that material
     in a single string.

     If any NAMED-PARAMETERs are supplied, the values that were passed
     in the opening tag are evaluated and bound to the named parameters.

     A keyword argument of PACKAGE-NAME wraps the entire body of the
     macro in an *Note in-package:: statement.

     The keyword argument WHITESPACE can be set to the string `delete'
     to remove whitespace from the starts and ends of lines in the
     subst definition before it is stored.  This effectively
     concatenates all of the lines of the subst definition into a
     single long line.

     Also see *Note define-function:: and *Note define-container::.


 - Complex Tag: defmacro NAME [NAMED-PARAMETER...]
          [PACKAGE=PACKAGE-NAME] [WHITESPACE=DELETE]
     A synonym for *Note define-container::.


 - Complex Tag: defsubst NAME [NAMED-PARAMETER...]
          [PACKAGE=PACKAGE-NAME] [WHITESPACE=DELETE]
     A synonym for *Note define-tag::.


 - Complex Tag: defun NAME [NAMED-PARAMETER...] [PACKAGE=PACKNAME]
     A synonym for *Note define-function::.


 - Simple Tag: undef NAME [...]
     Remove the definition of a user-defined *Note defun::, *Note
     defmacro:: or *Note defsubst::.  For every NAME that has been
     defined in this way, the definition is removed.



File: metahtml.info,  Node: Managing the Page,  Next: Working with Sessions,  Prev: Defining New Tags,  Up: Top

Managing the Page
*****************


File: metahtml.info,  Node: Page Operators

Page Operators
==============

   Meta-HTML contains a few commands which operate on the entire page
as it currently exists.

   You may find, modify, or delete text which has already been looked
at by the interpreter, as well as text which hasn't yet been looked at.

   Most of the time, you won't need to use such commands.  They can
make it hard for other people to understand the sequence of code in
your page, and they can sometimes produce unexpected results which are
difficult to debug because much of the information has been modified.

 - Simple Tag: page-insert OFFSET CONTENT
     Insert CONTENT directly into the current page at the offset
     specified by OFFSET.

     In most cases, there is never any need to do this.  For some very
     strange situations involving direct communication with both the
     Web server, and the connecting client, it is conceivably possible
     that you would use this command.

     But I doubt it.


 - Simple Tag: page-search START-OFFSET REGEX [END]
     Returns a number representing the number of characters from the
     start of the current page that REGEX appears.  If START-OFFSET is
     not zero, then the search starts from that many characters from
     the beginning of the page.

     The optional argument END says to return the position of the last
     character which matched REGEX, instead of the first.

     Why would you use this?


 - Simple Tag: replace-page FILENAME [ALT=CODE]
     Replace the entire contents of the current page with the contents
     of the file named by FILENAME.  You probably don't want to use
     this command, use *Note redirect:: instead.  In that way, the URLs
     give a consistent view to the user.  The rules for which file is
     chosen are identical to those for *Note include::.


 - Simple Tag: subst-in-page THIS WITH-THAT
     Replaces all occurrences of THIS with WITH-THAT in the current
     page.  Both THIS and WITH-THAT are evaluated before the
     replacement is done.  THIS can be any regular expression allowed
     by the POSIX extended regular expression matching.

     This command can be useful when included as part of a footer
     `include' file.  For example, you could replace all occurrences of
     `%name%' with a the value of the variable `FirstName' by writing:

            <subst-in-page %name% "<get-var forms::FirstName>">



File: metahtml.info,  Node: Page Variables

Page Variables
==============

   Several variables are predefined by Meta-HTML, and made available to
the page writer.  In addition to the contents of the Unix environment
(which includes the server-side variables `ENV::SERVER_NAME',
`ENV::PATH_INFO', etc.) variables describing the location of the
current document in various ways are also defined.  The following short
list is a quick look at typical values of the most commonly referenced
page variables.

   When the URL is
"http://localhost.ua.com/meta-html/manual/make-printable.mhtml", the
following variables are set to:

   `MHTML::PATH-INFO':

   `MHTML::HTTP-TO-HOST': http://localhost.ua.com

   `MHTML::CURRENT-DOC': make-printable.mhtml

   `MHTML::INCLUDE-PREFIX': /www/localhost/docs

   `MHTML::RELATIVE-PREFIX': /meta-html/manual

   `MHTML::LOCATION': /meta-html/manual/make-printable.mhtml

   `MHTML::LOCATION-SANS-SID': /meta-html/manual/make-printable.mhtml

   `MHTML::FULL-URL':
http://localhost.ua.com/meta-html/manual/make-printable.mhtml

   `MHTML::FULL-URL-SANS-SID':
http://localhost.ua.com/meta-html/manual/make-printable.mhtml

   `MHTML::URL-TO-DIR': http://localhost.ua.com/meta-html/manual

   `MHTML::URL-TO-DIR-SANS-SID':
http://localhost.ua.com/meta-html/manual

   `MHTML::HTTP-PREFIX': http://localhost.ua.com

   `MHTML::HTTP-PREFIX-SANS-SID': http://localhost.ua.com

 - Page Variable: mhtml::current-doc
     The name of the current document, without any path information,
     query strings, etc.

     If the current URL is:

              http://www.company.com/foo/bar/doc.mhtml?this=that

     then `MHTML::CURRENT-DOC' is:

              doc.mhtml


 - Page Variable: mhtml::current-url
     A synonym for `mhtml::location'.


 - Page Variable: mhtml::current-url-sans-sid
     A synonym for `mhtml::location-sans-sid'.


 - Page Variable: mhtml::full-url
     The URL used to connect to the current document, including
     protocol, host information, session ID, path-information, and
     query strings.

            <get-var mhtml::full-url>

     produces

            http://localhost.ua.com/meta-html/manual/make-printable.mhtml


 - Page Variable: mhtml::full-url-sans-sid
     The URL used to connect to the current document, including
     protocol, host information, path-information, and query strings,
     but excluding the session ID.

            <get-var mhtml::full-url-sans-sid>

     produces

            http://localhost.ua.com/meta-html/manual/make-printable.mhtml


 - Page Variable: mhtml::http-prefix
     The portion of the current URL which contains the protocol, host
     information, and the session ID.

              <get-var mhtml::http-prefix>

     produces

              http://localhost.ua.com


 - Page Variable: mhtml::http-prefix-sans-sid
     The portion of the current URL which contains the protocol, host
     information, but excluding the session ID.

              <get-var mhtml::http-prefix-sans-sid>

     produces

              http://localhost.ua.com


 - Page Variable: mhtml::http-to-host
     A synonym for `mhtml::http-prefix'.


 - Page Variable: mhtml::location
     The URL used to connect to the current document, including path
     information and query strings, but without the protocol or host
     information.

            <get-var mhtml::location>

     produces

            /meta-html/manual/make-printable.mhtml


 - Page Variable: mhtml::location-sans-sid
     The URL used to connect to the current document, including path
     information and query strings, but without the protocol, host
     information, or Session ID.

            <get-var mhtml::location-sans-sid>

     produces

            /meta-html/manual/make-printable.mhtml


 - Page Variable: mhtml::relative-prefix
     The sub-portion of the document path which appears after
     `mhtml::include-prefix'.

     If the document path was:

          /meta-html/manual/make-printable.mhtml

     then the value of `mhtml::relative-prefix' is:

          /meta-html/manual

     Useful when constructing new URLs based on the current URL.


 - Page Variable: mhtml::url-to-dir
     The complete URL to the directory containing the current document.
     This includes protocol, host, session ID, and relative prefix
     information.

              <get-var mhtml::url-to-dir>

     produces

              http://localhost.ua.com/meta-html/manual


 - Page Variable: mhtml::url-to-dir-sans-sid
     The complete URL to the directory containing the current document.
     This includes protocol, host, and relative prefix information,
     but excludes the session ID if one were present.

              <get-var mhtml::url-to-dir-sans-sid>

     produces

              http://localhost.ua.com/meta-html/manual



File: metahtml.info,  Node: Block Commands

Block Commands
==============

   The block commands operate on a specific area of the page, and tend
to manipulate the interpreter pointer position as a result.  This
commands differ from the commands in the <section-ref pages> section of
this manual because their scope is limited only to the block of
statements that they surround.

 - Complex Tag: comment
     Simply discard the BODY.  No processing is done, and no output is
     produced.

     A shorthand for commenting source on a single line exists; when
     the sequence of 3 semicolon character is seen
     (<samp>;</samp><samp>;;</samp>), then the text from this sequence
     to the end of the line inclusive is discarded.


 - Complex Tag: verbatim [QUOTE]
     Insert BODY verbatim, avoiding doing any processing on the
     contents.  If the positional argument QUOTE is given, occurrences
     of characters with special meaning to HTML are replaced with the
     HTML code to produce that character in the output page.

     Contrast this with *Note comment::.



File: metahtml.info,  Node: Working with Sessions,  Next: Working with Databases,  Prev: Managing the Page,  Up: Top

Working with Sessions
*********************


File: metahtml.info,  Node: Session Operators

Session Operators
=================

   Meta-HTML solves the problem of keeping state for a particular
session, and it does it in a server and browser independent manner. Our
method requires no additional CGI programs to be written, and you don't
have to be a programmer to take advantage of it.

   The basic essence of sessions is the session database.  An entry in
the session database can have exactly one of three possible states:
present, missing, or timed out.  Using the session commands, you can:

   * Create a session.

     This generates a unique entry in the session database, and returns
     that information as a session identifier (SID).  You can associate
     a special key with the session at creation time, and you can
     decide whether the key must be unique or not.  Session information
     can be located by either the SID or the key.

   * Delete a session.

     This removes the entry in the database associated with a specific
     SID, thus placing the session in the "missing" state.

   * Change a session's timeout value.

     With each session there is an associated timeout value, which is
     the number of minutes the session can live without any activity on
     the part of the user.  When the session is created, a default
     timeout is installed; currently this is five minutes.  Using
     `set-session-timeout', you can change this value. A special signal
     value of "0" causes the session to live forever (or until it is
     deleted with *Note delete-session::).

   * Require a session to be present.

     Using the *Note require-session:: form allows you to check the
     state of the session, and optionally execute code for the cases
     where it is missing or timed out.

   * Manipulate persistent variables.

     Commands exist to associate a name with a value in the session
     database, to retrieve the value associated with a name in the
     session database, and to store and retrieve a group of
     associations at once from the session database.

 - Simple Tag: create-session [VAR1[=MISSING-CODE]] [...]
          [VARN=[MISSING-CODE]] [ALT=ALTCODE] [ALLOW-MULTIPLE]
     Create a session, and place the session identifier in the variable
     `SID'.  The key for the session is created by concatenating the
     values of the VARs together, separated by hyphens (`-').  If a VAR
     doesn't have a value, but does have an optional MISSING-CODE
     assignment, then the session is not created, and the MISSING-CODE
     for that variable is evaluated.  If all of the variables have
     values in the page (or have no missing action), and the session
     could not be created, then ALTCODE is evaluated if it is present.

     Finally, if ALLOW-MULTIPLE is present, it indicates that the key
     does not have to be unique; it is enough that the session is
     created and a session ID returned.


 - Simple Tag: delete-session
     Immediately end the current session.  This never returns anything.
     The current session is indicated by the value of the variable
     `SID',  so you can delete sessions other than your own by setting
     that variable.  Also see *Note sessions-of-key::.


 - Simple Tag: get-session-var [NAME...]
     Get the value for NAME from the session database record associated
     with the current session.


 - Simple Tag: require-session [MISSING=MISSING-CODE]
          [TIMEOUT=TIMEOUT-CODE]
     Check that the current session is valid and not timed out.  If
     either of those things are true, the respective code is evaluated.
     Usually, the targets of TIMEOUT and MISSING are a *Note redirect::
     command which points to a page explaining the problem.

     You could force an anonymous session with the following code:

            <set-var anonymous="Anonymous Session">
            <require-session
              missing="<create-session anonymous allow-multiple>
                       <redirect <get-var SID>/<get-var mhtml::current-doc>"
              timeout=<redirect /timed-out.mhtml>>

     In the real world, additional care should be taken when returning
     new URLs.  The variable MHTML::COOKIE-COMPATIBLE is `true' when
     the attached browser/server combination is capable of handling
     HTTP Cookies.  In this case, it is preferable to use the HTTP
     Cookie handling facilities instead of returning the session ID in
     the URL.  Here is how one might write the above example to handle
     both cases:

          <set-var anonymous="Anonymous Session" session-timeout=60>
          <require-session
           missing = <prog
                       <create-session anonymous allow-multiple>
                       <set-session-timeout <get-var session-timeout>>
                       <when <not <get-var mhtml::cookie-compatible>>>
                       <redirect <concat
                                  <get-var mhtml::http-to-host>/
                                  <get-var SID><get-var mhtml::relative-prefix>/
                                  <get-var mhtml::current-doc>>>
                       </when>>
           timeout = <prog
                       <set-var SID="">
                       <if <get-var mhtml::cookie-compatible>
                           <replace-page
                            <get-var mhtml::relative-prefix>/timedout.mhtml>
                         <redirect
                          <get-var mhtml::url-to-dir-sans-sid>/timedout.mhtml>>>>

     For more detail on the built-in variables provided by the Meta-HTML
     Server and CGI Engine, see *Note Server Variables::.


 - Simple Tag: session-export PACKAGE [TO-PACKAGE]
     Save the package variables of PACKAGE in the current session.  If
     PREFIX is supplied, it indicates a new  package name to assign to
     each variable from PACKAGE that is saved.

     This function is quite useful when you wish to save all of the
     variables that were posted from the previous  URL (presumably,
     that URL contained a form whose action pointed to the current URL)
     in the session database record for the current session.  For
     example, if the previous URL posted the variables `FOO' and `BAR',
     then executing

             <session-export posted blue>

     results in the session database containing values for `blue::FOO'
     and `blue::BAR'.  These values can either be looked up directly,
     or retrieved as a group (see *Note session-import:: for more
     information).


 - Simple Tag: session-import PACKAGE [TO-PACKAGE]
     Get the values of the session variables which belong to PACKAGE
     and set their values in the current package. If TO-PACKAGE is
     supplied, it is the name of the package which will receive the
     variable values. Thus, if the session data for the current session
     contains

     `((BLUE::FOO . bar))', and then at a later time in the same
     session the command:

             <session-import blue>

     is given, then the variable `FOO' in the current package will be
     set to `bar'.  This is extremely useful when bouncing back and
     forth between forms, see *Note session-export::.


 - Simple Tag: sessions-of-key [KEY]
     Returns a newline separated list of the session ID's whose key
     matches KEY.  If KEY is not specified, or if it contains only
     whitespace, all session ID's in the session database are returned.
     Since the list is newline separated, it is suitable for assignment
     to an array, as in:

            <set-var sids[]=<sessions-of-key "On-Line Shopping">>


 - Simple Tag: set-session-timeout VALUE
     Make the current session time out after VALUE minutes.  You cannot
     supply the value of (`0'); that is accomplished with *Note
     delete-session::.


 - Simple Tag: set-session-var [NAME=VALUE...]
     Give the NAMEs the associated VALUEs in the session database
     record associated with the current session.


 - Simple Tag: unset-session-var [NAME] [...]
     Make NAMEs have no value in the session database record associated
     with the current session.


 - Complex Tag: with-locked-session
     Executes BODY in an environment where access to the current
     session is blocked.  This allows concurrency (such as might be
     required when multiple `GET's are being processed for a single
     user) to take place without introducing any race conditions for
     access to the current session record of the session database.



File: metahtml.info,  Node: Working with Databases,  Next: Working with the Server,  Prev: Working with Sessions,  Up: Top

Working with Databases
**********************


File: metahtml.info,  Node: Database Commands

Standard Database Commands
==========================

   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: *Note with-open-database::.  All of the remaining
database commands only have an effect when executed within the scope of
this function.

   *Note 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 *Note SYSTEM-ERROR-OUTPUT:: when they do not.

 - Simple Tag: database-delete-record DBVAR KEY
     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>


 - Simple Tag: database-first-key DBVAR
     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 argument is always
     suitable input to *Note database-next-key::.


 - Simple Tag: database-load-record DBVAR KEY [PREFIX=PACKAGE-NAME]
     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>


 - Simple Tag: database-next-key DBVAR AFTER-KEY
     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>


 - Simple Tag: database-query DBVAR EXPR [FORMAT=FEXPR] [KEYS=VARNAME]
          [SORT=FIELD1] [FIELD2...]
     Select records from the database referenced by DBVAR, based on
     EXPR, and optionally format them with 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 *Note 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.
     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 a 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
              <and <match <get-var job> "carpent">
                   <gt <get-var age> 20>
                   <lt <get-var 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>


 - Simple Tag: database-save-package DBVAR KEY PACKAGE [STRIP=TRUE]
     Save the variables from the package PACKAGE in the database
     referenced by DBVAR and 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


 - Simple Tag: database-save-record DBVAR KEY [VAR1...VARN]
          [PACKAGE=PACKAGE-NAME]
     Save the variables VAR1...VARN in the database referenced by DBVAR
     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 *Note database-save-package::, and *Note
     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>


 - Simple Tag: database-unique-key DB [SUGGESTION]
     Return a key which is gauranteed 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.


 - Simple Tag: dbm::first-key DBVAR
     Returns the "first" key in the database referenced by DBVAR.


 - Simple Tag: dbm::get-var DBVAR VARNAME
     Returns the value associated with VARNAME in the open database
     referenced by DBVAR.


 - Simple Tag: dbm::next-key DBVAR AFTERKEY
     Returns the "next" key in the database referenced by DBVAR
     starting after the key AFTERKEY.


 - Simple Tag: dbm::set-var DBVAR [NAME=VALUE...]
     Sets the association for NAME to be VALUE in the open database
     referenced by DBVAR.  Multiple NAME=VALUE pairs may be given.


 - Simple Tag: dbm::unset-var DBVAR
     Deletes any association for NAME in the open database referenced
     by DBVAR.


 - Complex Tag: dbm::with-open-database DBVAR DBNAME [MODE=OPEN-MODE]
     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.

     Only the DBM commands are meaningful within this environment.
     This function is designed to allow access to legacy dbm, gdbm, or
     ndbm databases; it won't work on anything else.

     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.


 - Complex Tag: with-open-database DBVAR DBNAME [MODE=OPEN-MODE]
     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.



File: metahtml.info,  Node: Msql Database Extensions

MSQL Database Extensions
========================

   Meta-HTML can optionally be compiled with the MSQL database
interface library (by supplying `--with-msql' to the ``configure''
command).  These extensions allow true SQL database interaction at many
levels, providing a clean and flexible abstraction to an MSQL database.

 - Simple Tag: msql::database-delete-record DBVAR KEY [TABLE=TABLENAME]
          [KEYNAME=FIELDNAME]
     Deletes the specified record in the database referenced by DBVAR.
     The record to delete is specified by KEY.

     You must supply TABLENAME and FIELDNAME, where <fieldname> is the
     name of the primary key field.


 - Simple Tag: msql::database-exec-query DBVAR QUERY-STRING
          [CURSOR=VARNAME]
     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 *Note
     msql::database-next-record::, *Note msql::number-of-rows::, and
     *Note msql::set-row-position::.

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


 - Simple Tag: msql::database-field-info DBVAR TABLE FIELDNAME
     Returns an alist of properties of the specified column  FIELDNAME
     in the SQL table named TABLE:

          ((name . "column_name") (length . "max byte length") (type . "sqlDatatype")
              (is_primary_key . "true") (is_not_null . "true"))

     The returned sqlDatatype value is one of
          GSQL_CHAR
          GSQL_NUMERIC
          GSQL_DECIMAL
          GSQL_INTEGER
          GSQL_SMALLINT
          GSQL_FLOAT
          GSQL_REAL
          GSQL_DOUBLE
          GSQL_VARCHAR


 - Simple Tag: msql::database-load-record DBVAR KEY
          [PACKAGE=PACKAGENAME] [TABLE=TABLENAME] [KEYNAME=FIELDNAME]
     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.


 - Simple Tag: msql::database-next-record CURSORVAR [COLNAMES=NAMELIST]
          [PACKAGE=PACKAGENAME]
     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.

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


 - Simple Tag: msql::database-query DBVAR EXPR QUERY
          [COLNAMES=NAMELIST] [QUERY=QUERY-STRING] [FORMAT=FEXPR]
          [KEYS=VARNAME] [KEYNAME=FIELDNAME]
     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.

            <msql::with-open-database rdb database=rolodex
          			    host=localhost>
            <table border=1>
              <tr><th>Name</th><th>Age</th></tr>
            <msql::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>
            </msql::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.

           <msql::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>
          >>


 - Simple Tag: msql::database-save-package DBVAR KEY PACKAGE
          [KEYNAME=FIELDNAME] [TABLE=TABLENAME]
     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.

     *Note :: 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=<msql::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.


 - Simple Tag: msql::database-save-record DB KEY TABLE KEYNAME [VAR...]
          [TABLE=TABLENAME] [KEYNAME=FIELDNAME]
     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 msql::msql-error-message[]


 - Simple Tag: msql::database-table-fields DBVAR TABLENAME
          [RESULT=VARNAME]
     List all the fieldnames for a table. This must be done with a
     database already open, i.e., within the scope of a
     `<msql::with-open-database>'.

     Returns an array of column names, or sets the value of VARNAME if
     supplied.


 - Simple Tag: msql::database-tables DBVAR [RESULT=VARNAME]
     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
     `<with-open-database>'.


 - Simple Tag: msql::host-databases [HOSTNAME] [RESULT=VARNAME]
     Return the names of the databases available on HOST as a newline
     separated list of strings.  If VARNAME is supplied, it is the name
     of a variable which should receive the values.


 - Simple Tag: msql::number-of-rows CURSORVAR
     Returns the number of rows which were found as a result of the
     last query issued for CURSORVAR.


 - Simple Tag: msql::set-row-position CURSORVAR INDEX
     Sets the current row number position in the result referenced by
     CURSORVAR to INDEX.

     Subsequent calls to   `<msql::database-next-record>' will begin
     with the record at INDEX.


 - Complex Tag: msql::with-open-database DBVAR [DSN=DSN]
          [DATABASE=DBNAME] [HOST=HOSTNAME]
     Create an environment in which other MSQL 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:

           <msql::with-open-database rdb database=rolodex
          			    host=localhost>
          ...
          </msql::with-open-database>

     For compatibility with ODBC, the host/database information can
     optionally be given in a ODBC style DSN string.
          DSN="host=localhost;database=rolodex"


 - Simple Tag: msqlc::cursor-get-column CURSOR COLUMN-NUMBER
     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).



File: metahtml.info,  Node: Odbc Database Extensions

ODBC Database Extensions
========================

   Meta-HTML PRO is delivered with the ODBC database interface
extensions. These extensions allow true SQL database interaction at
many levels, providing a clean and flexible abstraction to an ODBC
compliant SQL database.  The ODBC engine is known to work with the
Oracle(tm), Sybase(tm), MicroSoft SQL Server(tm), and Illustra(tm)
databases among others.

 - Simple Tag: msql::database-set-options DBVAR
          [SQL-ESCAPE-CHARACTER-CODE=INT] [SQL-TRUNCATE-COLUMNS=BOOLEAN]
     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.


 - Simple Tag: odbc::cursor-get-column CURSOR COLUMN-NUMBER
     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).


 - Simple Tag: odbc::database-delete-record DBVAR KEY TABLE KEYNAME
          [TABLE=TABLENAME] [KEYNAME=FIELDNAME]
     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.


 - Simple Tag: odbc::database-exec-query DBVAR QUERY-STRING
          [CURSOR=VARNAME]
     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 *Note
     odbc::database-next-record::, *Note odbc::number-of-rows::, and
     *Note odbc::set-row-position::.

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


 - Simple Tag: odbc::database-field-info DBVAR TABLE FIELDNAME
     Returns an alist of properties of the specified column  FIELDNAME
     in the SQL table named TABLE:

          ((name . "column_name") (length . "max byte length") (type . "sqlDatatype")
              (is_primary_key . "true") (is_not_null . "true"))

     The returned sqlDatatype value is one of
          GSQL_CHAR
          GSQL_NUMERIC
          GSQL_DECIMAL
          GSQL_INTEGER
          GSQL_SMALLINT
          GSQL_FLOAT
          GSQL_REAL
          GSQL_DOUBLE
          GSQL_VARCHAR


 - Simple Tag: odbc::database-load-record DBVAR KEY
          [PACKAGE=PACKAGENAME] [TABLE=TABLENAME] [KEYNAME=FIELDNAME]
     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.


 - Simple Tag: odbc::database-next-record CURSORVAR
          [PACKAGE=PACKAGENAME]
     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.


 - Simple Tag: odbc::database-query DBVAR EXPR QUERY
          [COLNAMES=NAMELIST] [QUERY=QUERY-STRING] [FORMAT=FEXPR]
          [KEYS=VARNAME] [KEYNAME=FIELDNAME]
     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>
          >>


 - Simple Tag: odbc::database-save-package DBVAR KEY PACKAGE
          [KEYNAME=FIELDNAME] [TABLE=TABLENAME]
     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.

     *Note :: 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.


 - Simple Tag: odbc::database-save-record DB KEY TABLE KEYNAME [VAR...]
          [TABLE=TABLENAME] [KEYNAME=FIELDNAME]
     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[]


 - Simple Tag: odbc::database-set-options DBVAR
          [SQL-ESCAPE-CHARACTER-CODE=INT] [SQL-TRUNCATE-COLUMNS=BOOLEAN]
     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.


 - Simple Tag: odbc::database-table-fields DBVAR TABLENAME
          [RESULT=VARNAME]
     List all the fieldnames for a table. This must be done with a
     database already open, i.e., within the scope of a *Note
     odbc::with-open-database::.

     Returns an array of column names, or sets the value of VARNAME if
     supplied.


 - Simple Tag: odbc::database-tables DBVAR [RESULT=VARNAME]
     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 *Note
     odbc::with-open-database::.


 - Simple Tag: odbc::number-of-rows CURSORVAR
     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 *Note
     odbc::database-exec-query::.


 - Simple Tag: odbc::query-get-column COLUMN-NUMBER
     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).


 - Complex Tag: odbc::with-open-database DBVAR [DSN=DSN-STRING]
     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>



File: metahtml.info,  Node: Working with the Server,  Next: Installation Guide,  Prev: Working with Databases,  Up: Top

Working with the Server
***********************


File: metahtml.info,  Node: Server Variables

Server Variables
================

   The Meta-HTML server (`mhttpd') is configured by reading a file of
Meta-HTML code.  This allows arbitrary programming of the server
process, and means that you don't have to learn a new configuration
language in order to modify the server.

   Included with the server is a set of administration pages; these
pages can be made accessible by telling the server where they are, and
by instructing the server to listen for requests on a specific port.

   There are many variables which are important both to the engine and
the server.  Many of them are created on a per-page access basis by
either the engine or the server, and others are used to control the
server's behavior.

 - Server Variable: env::http_authorization
     The `Basic Authorization' string, as received by the server.  By
     the time that you see this string, the user has already been
     authorized.


 - Server Variable: mhtml::access-log
     The complete path to the file where the MHTTPD server should keep
     the per-page access information.

     The access log contains lines written in W3c's Common Logfile
     Format.


 - Server Variable: mhtml::cacheable
     The variable MHTML::CACHEABLE, when set to a non-null value,
     indicates to the engine or server that the expiration date of the
     current page should be in the future (currently, about 10 days in
     the future).


 - Server Variable: mhtml::cgi-directories
     This array is a list of physical paths relative to the document
     root which are directories containing CGI programs.

     The paths are checked after path translation has been performed.
     The final slash for each directory must be specified.

             <get-var mhtml::cgi-directories[0]> ==> /cgi-bin/


 - Server Variable: mhtml::cgi-extensions
     An array of file name extensions that specifies to the MHTTPD
     server the file name extensions which indicate that the file is
     really a CGI program to be executed.

            <set-var mhtml::cgi-extensions[0]=".pl">


 - Server Variable: mhtml::debug-log
     The complete path to the file where the MHTTPD server should write
     server specific debugging information.  Generally, this only needs
     to be defined when you are debugging the server itself.

             <get-var mhtml::debug-log>

     produces



 - Server Variable: mhtml::error-log
     MHTML::ERROR-LOG is the full path to a file to which the server
     logs errors.

              <get-var mhtml::error-log>

     produces



 - Server Variable: mhtml::metahtml-extensions
     An array of file name extensions which indicate that the document
     to be fetched contains Meta-HTML code.

     Normally, this variable is set in the server process.

          <get-var mhtml::metahtml-extensions[]>

     produces

          .mhtml


 - Server Variable: mhtml::mhttpd-pages
     MHTML::MHTTPD-PAGES is the directory containing various pages used
     by the server for displaying error conditions, directory files,
     etc.  This is a complete path to the directory, without the
     trailing slash.

             <get-var mhtml::mhttpd-pages>

     produces

             /www/localhost/mhttpd-pages


 - Server Variable: mhtml::raw-content-data
     Contains exactly what the client browser sent in its `POST'
     request.

     For wizard's use only!


 - Server Variable: mhttpd::admin-port
     MHTTPD::ADMIN-PORT is the port number on which the Meta-HTML
     server should listen for administration requests.  The default
     port is generally set to 8008.

     If no such port is specified, then the server will not listen for
     administration requests at all.

              <get-var mhttpd::admin-port>

     produces



 - Server Variable: mhttpd::admin-root
     MHTTPD::ADMIN-ROOT is the complete path to the directory which
     contains server administration pages.  Usually set to
     `".../conf/admin"'.

              <get-var mhttpd::admin-root>

     produces



 - Server Variable: mhttpd::get-remote-ident
     MHTTPD::GET-REMOTE-IDENT, when set, says to use the IDENT protocol
     to attempt to find out the username associated with the connecting
     browser.  This only has a minor effect on server performance, but
     isn't especially useful for non-Meta-HTML sites.


 - Server Variable: mhttpd::session-database-file
     The complete path to the file in which the server or engine stores
     session information, keyed by session ID.

     If this variable is not set, then the default value of
     `"/tmp/sessions.db"' is used.

     If the server or engine cannot access this file, no session state
     information may be saved or retrieved.



File: metahtml.info,  Node: Installation Guide,  Next: Installing the Server,  Prev: Working with the Server,  Up: Top

Installation Guide
******************


File: metahtml.info,  Node: Installing the Server

Installing the Server
=====================

General Instructions for Installation
.....................................

   There are distribution specific instructions located in the
directories Server, Engine, and Processor.  You   may have only one of
these directories if you elected to obtain only   the Server, Engine,
or Stand-Alone Processor, or, you may have all   of them if you
received the Meta-HTML Tools Suite distribution.

Installing Your First Web Server
................................

   Installing the Meta-HTML Server is quite straight-forward, and only
requires you to have the most minimal knowledge of Unix-like systems.
 For those of you who can't wait, the following sequence is sufficient
 to install the Meta-HTML Server on a machine that is not already
running a web server:

  1. Choose a directory under which your server will be installed,
     say, "/usr/www".  We will call this directory   `<wwwroot>':

              (mkdir /usr/www)

  2. Create   `<wwwroot>/bin',   `<wwwroot>/docs',   `<wwwroot>/conf',
     and   `<wwwroot>/logs'.

              (mkdir /usr/www/bin /usr/www/docs /usr/www/conf /usr/www/logs)

  3. Copy `"Server/mhttpd"' and `"Utilities/*"' to     `<wwwroot>/bin'.

              (cp Server/mhttpd /usr/www/bin)

  4. Copy `"Documentation"' to   `<wwwroot>/docs'.

              (cp -r Documentation /usr/www/docs)

  5. Copy `"Server/mhttpd.conf"' to   `<wwwroot>/conf'.

              (cp Server/mhttpd.conf /usr/www/conf)

  6. Change `"www.myhost.com"' to the name of your host in the
     configuration file   `<wwwroot>/conf/mhttpd.conf'.  You   can do
     this by either editing the file with your favorite editor (say,
     emacs), or by `"sed"'ing the original file:

              (cat Server/mhttpd.conf | sed -e "s/www.myhost.com/`hostname`/"
          		>/usr/www/conf/mhttpd.conf)

  7. As the superuser, start the server from the   `  <wwwroot>'
     directory:

              (cd /usr/www; su -c bin/mhttpd)


   Congratulations, you are now running the Meta-HTML Server, and you
have a Web site!  You can now go to your first URL:

   Start a browser, and connect to
`"http://<your-host>/Documentation"', where   `"<your-host>'" should be
replaced with the name of   your machine.

Co-habitating the Meta-HTML Server with an Existing Server
..........................................................

   You may run the Meta-HTML Server on a non-standard port (such as
8080), or   under an aliased IP address for your machine.  The Server
tightly binds to   the address and port that it finds in the
configuration file.  The newly   installed server may serve the same
documents that you are already serving   with another server, or, may
be configured to serve a different set of   documents.

   If you are installing the Server with its own set of documents to
serve, and   its own IP address, simply follow the instructions given
under `Installing   Your First Web Server'.

   Otherwise, the intructions are almost identical; but you must
manually   edit the `mhttpd.conf' file and change the port number to
8080.  You   do this by changing the line which reads:

         <set-var mhtml::server-port = <if <get-var mhttpd::ssl-server> 443 80>>

   to read:

         <set-var mhtml::server-port = 8080>

   Then start the server as described above.  The documents are served
from the directory specified in ``MHTML::DOCUMENT-ROOT''.


File: metahtml.info,  Node: Configuring the Apache Server

Configuring the Apache Server
=============================

   There are three possibilities to choose from when configuring your
Apache server to work with Meta-HTML files:

  1.  You can run every document on your     server through the
     Meta-HTML CGI Engine.  While there is     nothing horribly wrong
     with this, it is essentially equivalent to     running the
     Meta-HTML server itself, so we do not highly     recommend it.

  2.  You can run only Meta-HTML     documents through the Meta-HTML
     CGI Engine, foregoing the     ability to use statefull sessions
     with non-cookie capable     browsers.  If you never use statefull
     sessions, or, if you only     have cookie-capable clients
     connecting to your server (e.g.,     Netscape, MSIE), this
     solution is completely reasonable, and     totally painless.

  3.  You can run only Meta-HTML     documents through the Meta-HTML
     CGI Engine, handling the     case of non-cookie capable browsers
     co-existing with statefull     sessions.  This is our recommended
     configuration.


Step 1: Install the Engine:
...........................

   In order for the Engine to operate under Apache, you must place it
in your `cgi-bin' directory, and make it executable.  For   example, if
your `srm.conf' file contained:
        ScriptAlias /cgi-bin/ /www/htdocs/cgi-bin/
     then you would copy the Engine and its config file to that
directory:
        user@host$ cp engine/engine /www/htdocs/cgi-bin/nph-engine
        user@host$ cp engine/engine.conf /www/htdocs/cgi-bin/

Step 2: Edit the `engine.conf' file:
....................................

   Now edit the `engine.conf' file in   `/www/htdocs/cgi-bin', simply
by reading the comments.    For most installations, you won't actually
need to change any of the   parameters defined within - the saavy site
administrator may wish   to add special behaviour, or to modify the
existing behaviour.

Step 3: Edit the Apache `srm.conf' file:
........................................

   Now edit the `srm.conf' for your Apache server.    There are two
possible edits:

  1. Running Every Document Through the Engine

     Add the following line before all of your other `ScriptAlias'
     lines:
               ScriptAlias / /cgi-bin/nph-engine

  2. Running Only Meta-HTML Documents Through the Engine

     Add the following lines to the `srm.conf' file, before     all
     other `ScriptAlias' lines:
               AddType metahtml/interpreted .mhtml
               Action metahtml/interpreted /cgi-bin/nph-engine


Step 4: Compiling Apache 1.1.1 With the Meta-HTML "mini-module":
................................................................

   If you want to make sure that non-cookie capable browsers can have
statefull sessions, you will need to recompile your 1.1.1 server   with
the Meta-HTML mini-module installed.  Here is how to do that:

  1.      Place the following line in `src/Configuration' (in     your
     Apache 1.1.1 source tree)
               Module mhtml_module           mod_mhtml.o

  2.      Copy the `mod_mhtml.c' file to the `src'     directory of
     your Apache 1.1.1 source tree.

  3.      Reconfigure the compilation of your server by typing
     `./Configure' from the `src' directory of     your Apache 1.1.1
     source tree.

  4.      Recompile the Apache server by typing `make', and then
     copy the `httpd' file to whereever you have installed     the
     previous version of the Apache server.


That's it!
..........

   Congratulations!  You have configured the Meta-HTML Engine to work
with your Apache server!

   So that you can see exactly what the mini-module does, I have
included the source code below:

       /* mod_mhtml.c: -*- C -*-  Apache mini-module code for Meta-HTML. */
     
       #include "httpd.h"
       #include "http_config.h"
       #include "http_request.h"
       #include "http_core.h"
       #include "http_protocol.h"
       #include "http_log.h"
       #include "http_main.h"
       #include "util_script.h"
     
       /* If the URI starts with a string of digits, leave them there, but
          make the filename be everything after it. */
       static int
       translate_filename (struct request_rec *req)
       {
         register int i;
         int result = DECLINED;
     
         if ((req-uriuri[0] == '/') && (isdigit (req->uri[1]))))
           {
             for (i = 1; isdigit (req->uri[i]); i++);
     
             /* If the URI contains a cookie, then gobble it, stuff it into
                req->subprocess_env, and move along. */
             if (req->uri[i] == '\0' || req->uri[i] == '/')
               {
                 register int j;
                 char *value = (char *)palloc (req->pool, 1 + i);
                 table *page_env = req->subprocess_env;
     
                 strncpy (value, req->uri + 1, i - 1);
                 value[i - 1] = '\0';
     
                 for (j = 0; req->uri[i] != '\0'; j++, i++)
                   req->uri[j] = req->uri[i];
     
                 req->uri[j] = '\0';
     
                 /* Now stuff the value into a meaningful environment variable. */
                 table_add (req->subprocess_env, "METAHTML_URL_COOKIE", value);
               }
           }
     
         return (result);
       }
     
       module mhtml_module =
       {
          STANDARD_MODULE_STUFF,
          NULL,                      /* initializer */
          NULL,                      /* dir config creater */
          NULL,                      /* dir merger --- default is to override */
          NULL,                      /* server config */
          NULL,                      /* merge server config */
          NULL,                      /* command table */
          NULL,                      /* handlers */
          translate_filename,        /* filename translation */
          NULL,                      /* check_user_id */
          NULL,                      /* check auth */
          NULL,                      /* check access */
          NULL,                      /* type_checker */
          NULL,                      /* fixups */
          NULL                               /* logger */
       };


File: metahtml.info,  Node: Configuring the Netscape Server

Configuring the Netscape Server
===============================

   At the time of this document, Netscape did not provide a way   to
use their browser based admin interface to configure either the
Commerce or Communications server to execute the Meta-HTML   Engine for
every document reference (this is required to handle   the passing of
cookies to and from non-cookie capable browsers).

   In addition, calling technical support at Netscape resulted in the
answer, "Oh, you can't do that."

   So, here is how you do it:

   * Locate the configuration directory for the server in question.
     Let's say that this is
     `/usr/ns-home/httpd-80.127.0.0.1/config'

   * Locate the actual directory containing your WWW documents.
     Let's say it is `/usr/www/docs'

   * Manually edit the obj.conf file you     found in the config
     directory, happily ignoring the warning not to     do so at the
     top of the file.  Here is what you do:

       1. Make sure that you have the Object which is named       cgi.
          The entry should look like this:

                     <Object name="cgi">
                     ObjectType fn="force-type" type="magnus-internal/cgi"
                     Service fn="send-cgi"
                     </Object>

       2. In the default Object, add the following       NameTrans line:

                     NameTrans from="" fn="pfx2dir" method=".*" dir="/usr/www/docs/cgi-bin/nph-engine" name="cgi"

       3. Save this file.  Remember, you have manually edited
          this file, so it is probably wise to save at least one extra
              copy of it that won't be overwritten by the Netscape
          admin       pages.


   * Copy the Meta-HTML Engine to the file that you     specified in
     the NameTrans entry:

     ` cp engine /usr/www/docs/cgi-bin/nph-engine '

   * Tell the Engine where the document root directory is.  You do
     this in the usual way, by placing the following into
     `/usr/www/docs/cgi-bin/engine.conf':

     `<set-var mhtml::document-root = /usr/www/docs>'

   * Restart your server.

   Here is a sample obj.conf file from a working site.

     # This file was automatically generated by the server.
     # Edit at your own risk.
     
     <Object name="default">
     NameTrans fn="home-page" path="index.html"
     NameTrans from="" fn="pfx2dir" method=".*" dir="/usr/www/docs/cgi-bin/nph-boxtop-engine" name="cgi"
     NameTrans from="/mc-icons" fn="pfx2dir" dir="/usr/ns-home/mc-icons"
     NameTrans from="/cgi-local" fn="pfx2dir" dir="/usr/www/docs/cgi-bin" name="cgi"
     NameTrans from="/cgi-bin" fn="pfx2dir" dir="/www/cgi-bin" name="cgi"
     NameTrans fn="unix-home" from="/~" subdir="public_html"
     NameTrans root="/www/tvcopsdev/site" fn="document-root"
     PathCheck fn="unix-uri-clean"
     PathCheck fn="find-pathinfo"
     PathCheck index-names="index.html,home.html" fn="find-index"
     ObjectType fn="type-by-extension"
     ObjectType fn="force-type" type="text/plain"
     ObjectType fn="shtml-hacktype"
     Service fn="imagemap" method="(GET|HEAD)" type="magnus-internal/imagemap"
     Service fn="index-common" method="(GET|HEAD)" type="magnus-internal/directory"
     Service fn="send-cgi" type="magnus-internal/cgi"
     Service fn="parse-html" method="(GET|HEAD)" type="magnus-internal/parsed-html"
     Service fn="send-file" method="(GET|HEAD)" type="*~magnus-internal/*"
     <Client ip="*~204.119.208.*">
     AddLog iponly="1" fn="common-log"
     </Client>
     </Object>
     
     <Object name="cgi">
     ObjectType fn="force-type" type="magnus-internal/cgi"
     Service fn="send-cgi"
     </Object>


File: metahtml.info,  Node: Configuring the NCSA Server

Configuring the NCSA Server
===========================

     ScriptAlias / /usr/www/docs/cgi-bin/nph-engine/


File: metahtml.info,  Node: Configuring the CERN Server

Configuring the CERN Server
===========================

   In your server configuration file:
     Map	/*		/cgi-bin/nph-engine/*
     Exec	/cgi-bin/*	<your-document-root>/cgi-bin/*

   CERN/3.0A Bug

   The Meta-HTML Engine tries hard to figure out where your document
root is.  It starts out by looking in `argv[0]' to see   which
directory the program is running from.  By convention,   programs which
call `fork()' and `exec()'   place the  complete path to the program to
execute in   `argv[0]'.

   But, does CERN do this?  No.  In fact, there are no variables in the
 environment, nor in `argv[]', from which this information   can be
gleaned!

   So, the Meta-HTML Engine cannot find a local configuration file, and
 cannot determine the location of the document root directory from
the information supplied by the CERN server.

   Meta-HTML Workaround

   There is a workaround for this bug in the CERN server.  If the
Meta-HTML Engine cannot find a configuration file in the normal   way,
then it looks in the contents of the environment variable
`METAHTML_ENGINE_CONFIG_FILE', and tries to treat that   value as the
location for the configuration file.  If that fails,   then finally the
file `"/www/bin/engine.conf"' is looked   for, and configuration is
attempted from that file.

   Try copying the `engine.conf' file in your   `/cgi-bin' directory to
 `/www/bin/engine.conf', or start your server with the   environment
variable `METAHTML_ENGINE_CONFIG_FILE' set to   the location of the
`engine.conf' file that came with   your distribution.


File: metahtml.info,  Node: Configuring the PLEXUS Server

Configuring the PLEXUS Server
=============================

   This configuration material comes from Marc Tamsky
(tamsky@as.ucsb.edu).    Although Marc is running the full Meta-HTML
Server, he also likes to   use the Plexus server, and placed the
following lines in his   `local.conf' file:

     map     __get_default__  cgi.pl                           \
           {                                                   \
             if ($path =~ m~\.mhtml$~)                         \
               {                                               \
                 local($tt) = 'mhtml';                         \
                 if (length($path))                            \
                   {                                           \
                     $tt = $tt . '/' . $path                   \
                   } ;                                         \
                 &cgi'cgi('../mhtml/cgi-bin',$tt,$query);      \
               }                                               \
             else                                              \
              {                                                \
                &retrieve($path,$query);                       \
              }                                                \
           }
     
     # Way-winning CGI
     load    cgi.pl
     map  mhtml   cgi.pl   &cgi'cgi('../mhtml/cgi-bin','engine/' .$rest,$query)


File: metahtml.info,  Node: Defined Meta-HTML Variables,  Next: Function Index,  Prev: Configuring the PLEXUS Server,  Up: Top

Defined Meta-HTML Variables
***************************

 - Variable: env::exec-path
     The list of directories that *Note cgi-exec:: will search when
     looking up the location of a command.

     Each component is a path to a directory, without the final
     trailing slash, separated from its neighbors by a colon character
     (`:').

     For example:

             <set-var env::path="/www/bin:/www/docs/cgi-bin">


 - Variable: env::http_authorization
     The `Basic Authorization' string, as received by the server.  By
     the time that you see this string, the user has already been
     authorized.


 - Variable: env::http_referer
     A synonym for `mhtml::referer'.


 - Variable: env::http_user_agent
     The name that the connecting client browser passed as the value of
     the `User-Agent' MIME header.

     For example:

             You are connected using: <get-var env::http_user_agent>

     produces

             You are connected using: Mozilla/3.0 (X11; U; Linux 1.3.20 i386)


 - Variable: env::query_string
     The raw query string which was passed in this URL.  In many cases,
     Meta-HTML can create variables in the `POSTED' package based upon
     the contents of this string.  In some cases, the string doesn't
     contain any variable assignments (e.g., when the URL is an
     imagemap target).  For such cases, you may need direct access to
     the query string.

              <get-var env::query_string>

     produces



 - Variable: env::remote_addr
     The Internet Protocol address of the connecting client host, in
     "dot" notation.  You may wish to use `env::remote_host' instead.

              <get-var env::remote_addr>

     produces

              127.0.0.1


 - Variable: env::remote_host
     The host name of the connecting client.  In cases where the
     connecting client does not have a host name which can be looked up
     by the use of DNS, this variable contains the host's Internet
     Protocol address, in "dot" notation.

              <get-var env::remote_host>

     produces

              nirvana.datawave.net


 - Variable: env::server_port
     The port on which the current web server is listening for
     connections.

             <get-var env::server_port>

     produces

             80


 - Variable: mhtml::access-log
     The complete path to the file where the MHTTPD server should keep
     the per-page access information.

     The access log contains lines written in W3c's Common Logfile
     Format.


 - Variable: mhtml::cacheable
     The variable MHTML::CACHEABLE, when set to a non-null value,
     indicates to the engine or server that the expiration date of the
     current page should be in the future (currently, about 10 days in
     the future).


 - Variable: mhtml::cgi-directories
     This array is a list of physical paths relative to the document
     root which are directories containing CGI programs.

     The paths are checked after path translation has been performed.
     The final slash for each directory must be specified.

             <get-var mhtml::cgi-directories[0]> ==> /cgi-bin/


 - Variable: mhtml::cgi-extensions
     An array of file name extensions that specifies to the MHTTPD
     server the file name extensions which indicate that the file is
     really a CGI program to be executed.

            <set-var mhtml::cgi-extensions[0]=".pl">


 - Variable: mhtml::cookie-compatible
     Indicates whether or not the current client/server pair can pass
     HTTP Cookies back and forth.

     When such communication is possible, this variable is set to
     `"true"'.


 - Variable: mhtml::current-doc
     The name of the current document, without any path information,
     query strings, etc.

     If the current URL is:

              http://www.company.com/foo/bar/doc.mhtml?this=that

     then `MHTML::CURRENT-DOC' is:

              doc.mhtml


 - Variable: mhtml::current-url
     A synonym for `mhtml::location'.


 - Variable: mhtml::current-url-sans-sid
     A synonym for `mhtml::location-sans-sid'.


 - Variable: mhtml::debug-log
     The complete path to the file where the MHTTPD server should write
     server specific debugging information.  Generally, this only needs
     to be defined when you are debugging the server itself.

             <get-var mhtml::debug-log>

     produces



 - Variable: mhtml::decimal-places
     Controls the number of decimal places which arithmetic functions
     produce.  The default value of this variable is `2', but for times
     when you need greater resolution in your calculations, you may
     wish to set it higher.

              <set-var mhtml::decimal-places = 10>
              9 / 3.0 = <div 9 3.0>
             10 / 3.0 = <div 10 3.0>
              9 / 3   = <div 9 3>
             10 / 3   = <div 10 3>
              <unset-var mhtml::decimal-places>
              9 / 3.0 = <div 9 3.0>
             10 / 3.0 = <div 10 3.0>
              9 / 3   = <div 9 3>
             10 / 3   = <div 10 3>

     produces


              9 / 3.0 = 3.0000000000
             10 / 3.0 = 3.3333333333
              9 / 3   = 3.0000000000
             10 / 3   = 3.3333333333
          
              9 / 3.0 = 3.00
             10 / 3.0 = 3.33
              9 / 3   = 3
             10 / 3   = 3


 - Variable: mhtml::default-filenames
     An array specifying the file names that should be looked up when
     the URL to fetch ends in a directory, instead of a document
     specifier.  The files are searched for in the order in which they
     appear in this array.

          <get-var mhtml::default-filenames[]>

     produces



 - Variable: mhtml::document-root
     The complete path to the directory from which your documents are
     to be served.  The final slash should not be present.

             <get-var mhtml::document-root>

     produces

             /www/localhost/docs


 - Variable: mhtml::epilogue-document
     Specifies a per-connection file of code to be appended to the page
     just before processing any Meta-HTML document.

             <get-var mhtml::epilogue-document>

     produces

             /www/localhost/epilogue.mhtml


 - Variable: mhtml::error-log
     MHTML::ERROR-LOG is the full path to a file to which the server
     logs errors.

              <get-var mhtml::error-log>

     produces



 - Variable: mhtml::exec-path
     MHTML::EXEC-PATH is what gets passed in the environment to CGI
     programs as PATH.  Choose carefully.

     The default value of this variable in the Mhttpd server is:

             <set-var mhtml::exec-path =
               <concat <get-var mhtml::server-root>/bin:/bin
                       :<get-var mhtml::document-root>/cgi-bin
                       :/usr/bin:/usr/local/bin:/usr/ucb>>


 - Variable: mhtml::full-url
     The URL used to connect to the current document, including
     protocol, host information, session ID, path-information, and
     query strings.

            <get-var mhtml::full-url>

     produces

            http://localhost.ua.com/meta-html/manual/make-printable.mhtml


 - Variable: mhtml::full-url-sans-sid
     The URL used to connect to the current document, including
     protocol, host information, path-information, and query strings,
     but excluding the session ID.

            <get-var mhtml::full-url-sans-sid>

     produces

            http://localhost.ua.com/meta-html/manual/make-printable.mhtml


 - Variable: mhtml::http-prefix
     The portion of the current URL which contains the protocol, host
     information, and the session ID.

              <get-var mhtml::http-prefix>

     produces

              http://localhost.ua.com


 - Variable: mhtml::http-prefix-sans-sid
     The portion of the current URL which contains the protocol, host
     information, but excluding the session ID.

              <get-var mhtml::http-prefix-sans-sid>

     produces

              http://localhost.ua.com


 - Variable: mhtml::http-to-host
     A synonym for `mhtml::http-prefix'.


 - Variable: mhtml::inhibit-comment-parsing
     When this variable is set to a non-empty value, the triple
     semi-colon comment feature is disabled.

     You may need this for complex applications where you are
     deliberately shipping the source of a Meta-HTML document to the
     client.


 - Variable: mhtml::location
     The URL used to connect to the current document, including path
     information and query strings, but without the protocol or host
     information.

            <get-var mhtml::location>

     produces

            /meta-html/manual/make-printable.mhtml


 - Variable: mhtml::location-sans-sid
     The URL used to connect to the current document, including path
     information and query strings, but without the protocol, host
     information, or Session ID.

            <get-var mhtml::location-sans-sid>

     produces

            /meta-html/manual/make-printable.mhtml


 - Variable: mhtml::metahtml-extensions
     An array of file name extensions which indicate that the document
     to be fetched contains Meta-HTML code.

     Normally, this variable is set in the server process.

          <get-var mhtml::metahtml-extensions[]>

     produces

          .mhtml


 - Variable: mhtml::mhttpd-pages
     MHTML::MHTTPD-PAGES is the directory containing various pages used
     by the server for displaying error conditions, directory files,
     etc.  This is a complete path to the directory, without the
     trailing slash.

             <get-var mhtml::mhttpd-pages>

     produces

             /www/localhost/mhttpd-pages


 - Variable: mhtml::prologue-document
     MHTML::PROLOGUE-DOCUMENT is a per-connection file of code to be
     run just before processing any Meta-HTML document.

              <get-var mhtml::prologue-document>

     produces

              /www/localhost/prologue.mhtml


 - Variable: mhtml::raw-content-data
     Contains exactly what the client browser sent in its `POST'
     request.

     For wizard's use only!


 - Variable: mhtml::referer
     The value of the `HTTP' Referer MIME header which the client
     browser sent along in it's request.

     You might use this variable, if it is present, as the target of an
     anchor:

              <a href="<get-var mhtml::referer>">
               <b>Back</b> to referring document.
              </a>


 - Variable: mhtml::relative-prefix
     The sub-portion of the document path which appears after
     `mhtml::include-prefix'.

     If the document path was:

          /meta-html/manual/make-printable.mhtml

     then the value of `mhtml::relative-prefix' is:

          /meta-html/manual

     Useful when constructing new URLs based on the current URL.


 - Variable: mhtml::remote-ident
     The value of the environment variable `ENV::REMOTE_IDENT' as
     received by the server.

     In the Meta-HTML server, you can turn on the feature of asking the
     connecting host for the username of the individual running the
     client browser by setting `MHTTPD::GET-REMOTE-IDENT'.

     There is never any gaurantee that the client will allow the server
     to find this information out, so you should not write code which
     relies on the presence of this variable.  However, if it is
     present, it can be useful to present a default value.  For example:

             <when <not <get-var e-mail>>>
               <set-var e-mail = <get-var mhtml::remote-ident>>
             </when>


 - Variable: mhtml::remote-user
     The value of the environment variable `ENV::REMOTE_USER' as
     received by the server.

     When `Basic Authorization' is supplied by a client, this variable
     contains the username which the connected user supplied.  Do NOT
     confuse this with ENV::REMOTE_IDENT!


 - Variable: mhtml::require-directories
     An array of directory names to be searched through in order by
     *Note require::.  The directories should be specified without the
     trailing slash.


 - Variable: mhtml::require-loaded
     The list of pathnames which have already been loaded through *Note
     require::.


 - Variable: mhtml::server-name
     MHTML::SERVER-NAME is the name that this server should advertise.
     If you do not set it, the value of the current host's name is
     used.  On Unix systems, this is the result of calling
     `gethostname()'.

              <get-var mhtml::server-name>

     produces

              localhost.ua.com


 - Variable: mhtml::server-port
     MHTML::SERVER-PORT is the port on which this server should answer
     HTTP requests.  If you do not set it, the value is `80'.

              <get-var mhtml::server-port>

     produces



 - Variable: mhtml::server-root
     MHTML::SERVER-ROOT is the root location for your server.  You
     might store the configuration, logging, and server specific files
     there, for example.  You currently cannot store your CGIs there,
     because that directory must be underneath `MHTML::DOCUMENT-ROOT'.

     The pathname should not end in a slash.

              <get-var mhtml::server-root>

     produces



 - Variable: mhtml::sid-prefix
     When this variable is present, the `PATH' component of a returned
     `Set-Cookie' MIME header is set to its value.  Normally, the value
     of `MHTML::RELATIVE-PREFIX' is used.

     If you need to use `MHTML::SID-PREFIX', you probably have a very
     complex directory structure, and the need for every page access to
     have a cookie associated with it.  In this case, setting
     `MHTML::SID-PREFIX' will have the effect of flattening your
     directory structure in the browser's view.

     Generally, correctly written Meta-HTML applications do not need to
     use this variable, and it might be used in only the most
     complicated of Web sites, with multiple sessions per connectee,
     etc.

     The explanation of HTTP Cookies is beyond the scope of this
     document.  Reference information on Cookies can be found through
     this link.


 - Variable: mhtml::unparsed-headers
     When set to true, indicates to the Meta-HTML Engine that the
     server is expecting the engine to produce all of the `HTTP'
     results, and not just the `HTML' results.

     This variable is automatically set in the Meta-HTML server, and
     when the Engine is run under a name beginning with `"nph-"'.

     You can turn this variable on or off during the invocation of a
     specific page to control the behavior of both the server and
     engine.

              <get-var mhtml::unparsed-headers>

     produces



 - Variable: mhtml::url-to-dir
     The complete URL to the directory containing the current document.
     This includes protocol, host, session ID, and relative prefix
     information.

              <get-var mhtml::url-to-dir>

     produces

              http://localhost.ua.com/meta-html/manual


 - Variable: mhtml::url-to-dir-sans-sid
     The complete URL to the directory containing the current document.
     This includes protocol, host, and relative prefix information,
     but excludes the session ID if one were present.

              <get-var mhtml::url-to-dir-sans-sid>

     produces

              http://localhost.ua.com/meta-html/manual


 - Variable: mhtml::version
     Contains the version identification of the currently running
     interpreter.  This variable is available whereever the interpreter
     is running, including the Meta-HTML server, Engine, and in `mdb'.

              <get-var mhtml::version>

     produces

              5.01


 - Variable: mhttpd::admin-port
     MHTTPD::ADMIN-PORT is the port number on which the Meta-HTML
     server should listen for administration requests.  The default
     port is generally set to 8008.

     If no such port is specified, then the server will not listen for
     administration requests at all.

              <get-var mhttpd::admin-port>

     produces



 - Variable: mhttpd::admin-root
     MHTTPD::ADMIN-ROOT is the complete path to the directory which
     contains server administration pages.  Usually set to
     `".../conf/admin"'.

              <get-var mhttpd::admin-root>

     produces



 - Variable: mhttpd::get-remote-ident
     MHTTPD::GET-REMOTE-IDENT, when set, says to use the IDENT protocol
     to attempt to find out the username associated with the connecting
     browser.  This only has a minor effect on server performance, but
     isn't especially useful for non-Meta-HTML sites.


 - Variable: mhttpd::session-database-file
     The complete path to the file in which the server or engine stores
     session information, keyed by session ID.

     If this variable is not set, then the default value of
     `"/tmp/sessions.db"' is used.

     If the server or engine cannot access this file, no session state
     information may be saved or retrieved.


 - Variable: sid
     This variable contains the current session ID.

     The session ID is passed to and from the browser by either the use
     of HTTP Cookies, or in the URL, as the first element of the path.

     Normally, you never need to reference this variable directly,
     since the various internal functions which deal with sessions know
     how to set, get, and/or modify it without your help.

     Related functions: *Note create-session::, *Note delete-session::,
     *Note set-session-var::, etc.



File: metahtml.info,  Node: Function Index,  Next: Variable Index,  Prev: Defined Meta-HTML Variables,  Up: Top

Function Index
**************

* Menu:

* %%eval:                               Language Operators.
* %%read:                               Language Operators.
* %%read-package-file:                  Packages.
* %%write-package-file:                 Packages.
* add:                                  Arithmetic Operators.
* alist-to-package:                     Packages.
* and:                                  Relational Operators.
* capitalize:                           String Operators.
* cgi-decode:                           Variables.
* cgi-encode:                           Variables.
* cgi-exec:                             File Operators.
* coerce-var:                           Variables.
* comment:                              Block Commands.
* concat:                               Language Operators.
* copy-var:                             Variables.
* create-session:                       Session Operators.
* database-delete-record:               Database Commands.
* database-first-key:                   Database Commands.
* database-load-record:                 Database Commands.
* database-next-key:                    Database Commands.
* database-query:                       Database Commands.
* database-save-package:                Database Commands.
* database-save-record:                 Database Commands.
* database-unique-key:                  Database Commands.
* date:                                 Language Operators.
* dbm::first-key:                       Database Commands.
* dbm::get-var:                         Database Commands.
* dbm::next-key:                        Database Commands.
* dbm::set-var:                         Database Commands.
* dbm::unset-var:                       Database Commands.
* dbm::with-open-database:              Database Commands.
* debugging-on:                         Language Operators.
* DEBUGGING-OUTPUT:                     Language Operators.
* decrement:                            Arithmetic Operators.
* decrypt:                              Variables.
* define-container:                     Macro Commands.
* define-function:                      Macro Commands.
* define-tag:                           Macro Commands.
* defmacro:                             Macro Commands.
* defsubst:                             Macro Commands.
* defun:                                Macro Commands.
* delete-session:                       Session Operators.
* directory-contents:                   File Operators.
* div:                                  Arithmetic Operators.
* downcase:                             String Operators.
* encrypt:                              Variables.
* eq:                                   Relational Operators.
* function-def:                         Language Operators.
* get-file-properties:                  File Operators.
* get-session-var:                      Session Operators.
* get-var:                              Variables.
* get-var-once:                         Variables.
* gt:                                   Relational Operators.
* if:                                   Flow Control.
* ifeq:                                 Flow Control.
* in-package:                           Packages.
* include:                              File Operators.
* increment:                            Arithmetic Operators.
* lt:                                   Relational Operators.
* match:                                String Operators.
* mod:                                  Arithmetic Operators.
* msql::database-delete-record:         Msql Database Extensions.
* msql::database-exec-query:            Msql Database Extensions.
* msql::database-field-info:            Msql Database Extensions.
* msql::database-load-record:           Msql Database Extensions.
* msql::database-next-record:           Msql Database Extensions.
* msql::database-query:                 Msql Database Extensions.
* msql::database-save-package:          Msql Database Extensions.
* msql::database-save-record:           Msql Database Extensions.
* msql::database-set-options:           Odbc Database Extensions.
* msql::database-table-fields:          Msql Database Extensions.
* msql::database-tables:                Msql Database Extensions.
* msql::host-databases:                 Msql Database Extensions.
* msql::number-of-rows:                 Msql Database Extensions.
* msql::set-row-position:               Msql Database Extensions.
* msql::with-open-database:             Msql Database Extensions.
* msqlc::cursor-get-column:             Msql Database Extensions.
* mul:                                  Arithmetic Operators.
* not:                                  Relational Operators.
* odbc::cursor-get-column:              Odbc Database Extensions.
* odbc::database-delete-record:         Odbc Database Extensions.
* odbc::database-exec-query:            Odbc Database Extensions.
* odbc::database-field-info:            Odbc Database Extensions.
* odbc::database-load-record:           Odbc Database Extensions.
* odbc::database-next-record:           Odbc Database Extensions.
* odbc::database-query:                 Odbc Database Extensions.
* odbc::database-save-package:          Odbc Database Extensions.
* odbc::database-save-record:           Odbc Database Extensions.
* odbc::database-set-options:           Odbc Database Extensions.
* odbc::database-table-fields:          Odbc Database Extensions.
* odbc::database-tables:                Odbc Database Extensions.
* odbc::number-of-rows:                 Odbc Database Extensions.
* odbc::query-get-column:               Odbc Database Extensions.
* odbc::with-open-database:             Odbc Database Extensions.
* or:                                   Relational Operators.
* package-delete:                       Packages.
* package-names:                        Packages.
* package-to-alist:                     Packages.
* package-vars:                         Packages.
* pad:                                  String Operators.
* page-debug:                           Language Operators.
* page-insert:                          Page Operators.
* page-search:                          Page Operators.
* pid:                                  Language Operators.
* plain-text:                           String Operators.
* prog:                                 Language Operators.
* random:                               Arithmetic Operators.
* randomize:                            Arithmetic Operators.
* redirect:                             Flow Control.
* replace-page:                         Page Operators.
* require:                              File Operators.
* require-session:                      Session Operators.
* server-push:                          Flow Control.
* session-export:                       Session Operators.
* session-import:                       Session Operators.
* sessions-of-key:                      Session Operators.
* set-session-timeout:                  Session Operators.
* set-session-var:                      Session Operators.
* set-var:                              Variables.
* small-caps:                           String Operators.
* sort:                                 Variables.
* stream-get:                           Stream Operators.
* stream-get-contents:                  Stream Operators.
* stream-put:                           Stream Operators.
* stream-put-contents:                  Stream Operators.
* stream-readable:                      Stream Operators.
* stream-shutdown:                      Stream Operators.
* stream-writable:                      Stream Operators.
* string-eq:                            String Operators.
* sub:                                  Arithmetic Operators.
* subst-in-page:                        Page Operators.
* subst-in-string:                      String Operators.
* subst-in-var:                         Variables.
* substring:                            String Operators.
* symbol-info:                          Language Operators.
* SYSTEM-ERROR-OUTPUT:                  Language Operators.
* time:                                 Language Operators.
* undef:                                Macro Commands.
* unset-session-var:                    Session Operators.
* unset-var:                            Variables.
* upcase:                               String Operators.
* var-case:                             Flow Control.
* var-exists:                           Variables.
* verbatim:                             Block Commands.
* when:                                 Flow Control.
* while:                                Flow Control.
* with-locked-session:                  Session Operators.
* with-open-database:                   Database Commands.
* with-open-stream:                     Stream Operators.
* word-wrap:                            String Operators.


File: metahtml.info,  Node: Variable Index,  Prev: Function Index,  Up: Top

Variable Index
**************

* Menu:

* env::exec-path:                       Defined Meta-HTML Variables.
* env::http_authorization <1>:          Defined Meta-HTML Variables.
* env::http_authorization:              Server Variables.
* env::http_referer:                    Defined Meta-HTML Variables.
* env::http_user_agent:                 Defined Meta-HTML Variables.
* env::query_string:                    Defined Meta-HTML Variables.
* env::remote_addr:                     Defined Meta-HTML Variables.
* env::remote_host:                     Defined Meta-HTML Variables.
* env::server_port:                     Defined Meta-HTML Variables.
* mhtml::access-log <1>:                Defined Meta-HTML Variables.
* mhtml::access-log:                    Server Variables.
* mhtml::cacheable <1>:                 Defined Meta-HTML Variables.
* mhtml::cacheable:                     Server Variables.
* mhtml::cgi-directories <1>:           Defined Meta-HTML Variables.
* mhtml::cgi-directories:               Server Variables.
* mhtml::cgi-extensions <1>:            Defined Meta-HTML Variables.
* mhtml::cgi-extensions:                Server Variables.
* mhtml::cookie-compatible:             Defined Meta-HTML Variables.
* mhtml::current-doc <1>:               Defined Meta-HTML Variables.
* mhtml::current-doc:                   Page Variables.
* mhtml::current-url <1>:               Defined Meta-HTML Variables.
* mhtml::current-url:                   Page Variables.
* mhtml::current-url-sans-sid <1>:      Defined Meta-HTML Variables.
* mhtml::current-url-sans-sid:          Page Variables.
* mhtml::debug-log <1>:                 Defined Meta-HTML Variables.
* mhtml::debug-log:                     Server Variables.
* mhtml::decimal-places:                Defined Meta-HTML Variables.
* mhtml::default-filenames:             Defined Meta-HTML Variables.
* mhtml::document-root:                 Defined Meta-HTML Variables.
* mhtml::epilogue-document:             Defined Meta-HTML Variables.
* mhtml::error-log <1>:                 Defined Meta-HTML Variables.
* mhtml::error-log:                     Server Variables.
* mhtml::exec-path:                     Defined Meta-HTML Variables.
* mhtml::full-url <1>:                  Defined Meta-HTML Variables.
* mhtml::full-url:                      Page Variables.
* mhtml::full-url-sans-sid <1>:         Defined Meta-HTML Variables.
* mhtml::full-url-sans-sid:             Page Variables.
* mhtml::http-prefix <1>:               Defined Meta-HTML Variables.
* mhtml::http-prefix:                   Page Variables.
* mhtml::http-prefix-sans-sid <1>:      Defined Meta-HTML Variables.
* mhtml::http-prefix-sans-sid:          Page Variables.
* mhtml::http-to-host <1>:              Defined Meta-HTML Variables.
* mhtml::http-to-host:                  Page Variables.
* mhtml::inhibit-comment-parsing:       Defined Meta-HTML Variables.
* mhtml::location <1>:                  Defined Meta-HTML Variables.
* mhtml::location:                      Page Variables.
* mhtml::location-sans-sid <1>:         Defined Meta-HTML Variables.
* mhtml::location-sans-sid:             Page Variables.
* mhtml::metahtml-extensions <1>:       Defined Meta-HTML Variables.
* mhtml::metahtml-extensions:           Server Variables.
* mhtml::mhttpd-pages <1>:              Defined Meta-HTML Variables.
* mhtml::mhttpd-pages:                  Server Variables.
* mhtml::prologue-document:             Defined Meta-HTML Variables.
* mhtml::raw-content-data <1>:          Defined Meta-HTML Variables.
* mhtml::raw-content-data:              Server Variables.
* mhtml::referer:                       Defined Meta-HTML Variables.
* mhtml::relative-prefix <1>:           Defined Meta-HTML Variables.
* mhtml::relative-prefix:               Page Variables.
* mhtml::remote-ident:                  Defined Meta-HTML Variables.
* mhtml::remote-user:                   Defined Meta-HTML Variables.
* mhtml::require-directories:           Defined Meta-HTML Variables.
* mhtml::require-loaded:                Defined Meta-HTML Variables.
* mhtml::server-name:                   Defined Meta-HTML Variables.
* mhtml::server-port:                   Defined Meta-HTML Variables.
* mhtml::server-root:                   Defined Meta-HTML Variables.
* mhtml::sid-prefix:                    Defined Meta-HTML Variables.
* mhtml::unparsed-headers:              Defined Meta-HTML Variables.
* mhtml::url-to-dir <1>:                Defined Meta-HTML Variables.
* mhtml::url-to-dir:                    Page Variables.
* mhtml::url-to-dir-sans-sid <1>:       Defined Meta-HTML Variables.
* mhtml::url-to-dir-sans-sid:           Page Variables.
* mhtml::version:                       Defined Meta-HTML Variables.
* mhttpd::admin-port <1>:               Defined Meta-HTML Variables.
* mhttpd::admin-port:                   Server Variables.
* mhttpd::admin-root <1>:               Defined Meta-HTML Variables.
* mhttpd::admin-root:                   Server Variables.
* mhttpd::get-remote-ident <1>:         Defined Meta-HTML Variables.
* mhttpd::get-remote-ident:             Server Variables.
* mhttpd::session-database-file <1>:    Defined Meta-HTML Variables.
* mhttpd::session-database-file:        Server Variables.
* sid:                                  Defined Meta-HTML Variables.



Tag Table:
Node: Top95
Node: Welcome To Meta-HTML766
Node: The Purpose of Meta-HTML2410
Node: Implementation Design5316
Node: Language Syntax6947
Node: Essential Language Features10146
Node: Variables10324
Node: Arrays15752
Node: Packages17404
Node: Flow Control21541
Node: Language Operators24173
Node: Strings and Numbers29703
Node: String Operators29866
Node: Arithmetic Operators35531
Node: Relational Operators38218
Node: Input and Output39872
Node: File Operators40019
Node: Stream Operators44662
Node: Defining New Tags48567
Node: Macro Commands48714
Node: Managing the Page52879
Node: Page Operators53031
Node: Page Variables55449
Node: Block Commands60250
Node: Working with Sessions61331
Node: Session Operators61496
Node: Working with Databases69963
Node: Database Commands70136
Node: Msql Database Extensions80443
Node: Odbc Database Extensions90542
Node: Working with the Server101324
Node: Server Variables101496
Node: Installation Guide106242
Node: Installing the Server106403
Node: Configuring the Apache Server109874
Node: Configuring the Netscape Server116154
Node: Configuring the NCSA Server119853
Node: Configuring the CERN Server120023
Node: Configuring the PLEXUS Server121641
Node: Defined Meta-HTML Variables123114
Node: Function Index140615
Node: Variable Index149612

End Tag Table
