("DYNAMIC-MODULES" (("KEYWORDS" . "dynamic; load-module")("SHORT-DESC" . "You can now write C language code to implement your own built-in <Meta-HTML> functions!  Such functions are first-class objects, and can manipulate the <Meta-HTML> environment directly, easily reset the parser pointer, manage hardware devices or talk on proprietery networks, or anything else that you can do in C.

It works by supplying you with the necessary <Meta-HTML> header files and a Makefile for building modules on your system.  Using our supplied Makefile provides you with a resultant <i>dynamically loadable</i> module, which can be loaded into the Server, Engine, or a single page with the
<a href=\"/documentation/manual/man-page.mhtml?key=LOAD-MODULE\">
<code>&lt;load-module&gt;</code></a> function.

See the <code>modules</code> directory of the distribution for more details.")("LONG-DESC" . "")("SECTION" . "DYNAMIC-MODULES")))("ARRAYS" (("KEYWORDS" . "variables; arrays; multiple values")("SHORT-DESC" . "<meta-html> allows the use of <i>array</i> 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.
")("LONG-DESC" . "Array variable values are referenced by placing the array index directly after the variable name, enclosed in square brackets (<b>[</b> and <b>]</b>).  Thus, a reference to the 3rd element of the array <var foo> looks like:

<example>
   foo[3]
</example>

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 <var foo>, you would write:

<example>
   <get-var foo[]>
</example>

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 <example code><get-var VAR></example>.  Finally, multiple values may be given in a <funref variables set-var> command by separating those values with newline characters.  The following sequence of commands illustrates the typical use of array variables.

<complete-example>
<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>
</complete-example>
")("SECTION" . "ARRAYS")))("DIRECT-DBM-ACCESS" (("KEYWORDS" . "database; perl")("SHORT-DESC" . "There are times when it is desirable to directly access DBM, NDBM, or GDBM databases, for example, when reading or writing values to a database created with a different tool, such as Perl or TCL.

<Meta-HTML> provides low-level access primitives for such databases in addition to a higher-level, more generally useful abstraction (which is detailed in <secref DATABASE-COMMANDS>.
")("LONG-DESC" . "")("SECTION" . "DIRECT-DBM-ACCESS")))("BLOCK-COMMANDS" (("KEYWORDS" . "verbatim; comments")("SHORT-DESC" . "The <b>block</b> commands operate on a specific area of the page, and tend to manipulate the interpreter pointer position as a result.
")("LONG-DESC" . "These 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.
")("SECTION" . "BLOCK-COMMANDS")))("PAGE-VARIABLES" (("KEYWORDS" . "")("SHORT-DESC" . "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 <varref ENV::SERVER_NAME>, <varref ENV::PATH_INFO>, etc.) variables describing the location of the current document in various ways are also defined.
")("LONG-DESC" . "The following short list is a quick look at typical values of the most commonly referenced page variables.

When the URL is ``<i><get-var mhtml::full-url></i>'', the following variables are set to:

<defun showvar var>
  <tr>
    <td align=right> <varref <upcase <get-var var>>>: </td>
    <td align=left>
      <i><get-var <get-var var>></i><br>
    </td>
  </tr>
</defun>

<table>
  <showvar mhtml::path-info>
  <showvar mhtml::http-to-host>
  <showvar mhtml::current-doc>
  <showvar mhtml::include-prefix>
  <showvar mhtml::relative-prefix>
  <showvar mhtml::location>
  <showvar mhtml::location-sans-sid>
  <showvar mhtml::full-url>
  <showvar mhtml::full-url-sans-sid>
  <showvar mhtml::url-to-dir>
  <showvar mhtml::url-to-dir-sans-sid>
  <showvar mhtml::http-prefix>
  <showvar mhtml::http-prefix-sans-sid>
</table>
")("SECTION" . "PAGE-VARIABLES")))("PAGE-OPERATORS" (("KEYWORDS" . "page commands; page search; search; insert; modify page")("SHORT-DESC" . "<meta-html> contains a few commands which operate on the entire <i>page</i> 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.
")("LONG-DESC" . "")("SECTION" . "PAGE-OPERATORS")))("STREAM-OPERATORS" (("KEYWORDS" . "files; streams; reading; writing; creating")("SHORT-DESC" . "A <i>stream</i> 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.")("LONG-DESC" . "There are three special names which can be used with <funref stream-operators with-open-stream>, these are <code>*standard-input*</code>, <code>*standard-output*</code>, and <code>*standard-error*</code>.

<code>*standard-input*</code> always names the stream that  from which input was being read at the time the engine, server, or <code>mhc</code> invoked.  <code>*standard-output*</code> always names the stream to which output is being written by the engine, server or <code>mhc</code>.

<code>*standard-error*</code> always names the stream where error output will appear -- this stream could be the same as the one named by <code>*standard-output*</code>, but this does not have to be the case.
")("SECTION" . "STREAM-OPERATORS")))("ARITHMETIC-OPERATORS" (("KEYWORDS" . "math; addition; subtraction; artithmetic")("SHORT-DESC" . "<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 <example code><get-var ...></example>.

That is to say:

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

can be written as:

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

")("LONG-DESC" . "The binary arithmetic operators always expect two arguments, and will produce a warning message in <funref debugging 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:

<example>
  <div 10 3>    --> 3
  <div 10.0 3>  --> 3.33
</example>
")("SECTION" . "ARITHMETIC-OPERATORS")))("FILE-OPERATORS" (("KEYWORDS" . "files; disk; system")("SHORT-DESC" . "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 <a href=\"<get-var mhtml::url-to-dir>/view-section.mhtml?KEY=STREAM+COMMANDS\">streams</a>, which may be connected to files or network data.

The functions allow you to <funref \"file operators\" include> the contents of, <a href=\"<get-var mhtml::url-to-dir>/man-page.mhtml?KEY=WITH-OPEN-STREAM\">open</a>, create, read, or write various data sources, or to <a href=\"<get-var mhtml::url-to-dir>/man-page.mhtml?KEY=REPLACE-PAGE\">replace the contents of page</a> with another file.
")("LONG-DESC" . "Commands such as <funref \"file operators\" get-file-properties> may return additional information on some systems; this is documented with each function where that is the case.


Also see <secref Stream Operators>.
")("SECTION" . "FILE-OPERATORS")))("RELATIONAL-OPERATORS" (("KEYWORDS" . "boolean; relational; logical")("SHORT-DESC" . "<i>

Relational operators</i> in <meta-html> return information about the relationship between two items.  There are three logical operators, <funref \"relational operators\" and>, <funref \"relational operators\" or>, and <funref \"relational operators\" not>.

There are several other operators which compare numeric values; the section <secref Arithmetic Operators> cover those in detail.
")("LONG-DESC" . "")("SECTION" . "RELATIONAL-OPERATORS")))("SESSION-OPERATORS" (("KEYWORDS" . "")("SHORT-DESC" . "<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 <i>session database</i>.  An entry in the session database can have exactly one of three possible states: <i>present</i>, <i>missing</i>, or <i>timed out</i>.
")("LONG-DESC" . "Using the session commands, you can:

<ul>
<li> <b>Create a session.</b><br>
This generates a unique entry in the session database, and returns that information as a session identifier (<strong>SID</strong>).  You can associate a special <i>key</i> 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.

<p><li> <b>Delete a session.</b><br>
This removes the entry in the database associated with a specific SID, thus placing the session in the \"missing\" state.

<p><li> <b>Change a session's timeout value.</b><br>
With each session there is an associated <i>timeout</i> 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 <code>set-session-timeout</code>, you can change this value. A special signal value of \"0\" causes the session to live forever (or until it is deleted with <funref sessions delete-session>).

<p><li> <b>Require a session to be present.</b><br>
Using the <funref sessions 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.

<p><li> <b>Manipulate persistent variables.</b><br>
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.
</ul>
")("SECTION" . "SESSION-OPERATORS")))("VARIABLES" (("KEYWORDS" . "variables; symbols; lookup")("SHORT-DESC" . "<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 <secref packages>.")("LONG-DESC" . "<h3>Variable Types and Information</h3>

There are internal functions in <meta-html> which create <i>binary</i> 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 <funref variables symbol-info> function.


Many variables are predefined by <meta-html>, and made available to the page writer.  The <secref Page-Variables>  section of this manual documents those variables fully, while the <secref server-variables> section contains more information on variables which control, or were specifically created by, the web server.


")("SECTION" . "VARIABLES")))("FLOW-CONTROL" (("KEYWORDS" . "flow control;if statements; while; until")("SHORT-DESC" . "<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 <i>flow control</i>, 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 <b>goto</b> statement in <meta-html> is the <funref page-operators redirect> command.
")("LONG-DESC" . "")("SECTION" . "FLOW-CONTROL")))("MACRO-COMMANDS" (("KEYWORDS" . "macros; functions; new operators")("SHORT-DESC" . "<meta-html> contains a powerful <i>macro</i> 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 <i>complex-tag</i>; it consists of an opening tag, a body, and a closing tag.  The other type is a <i>simple-tag</i>; 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.
")("LONG-DESC" . "")("SECTION" . "MACRO-COMMANDS")))("LANGUAGE-OPERATORS" (("KEYWORDS" . "self-modif; language; self-referential")("SHORT-DESC" . "<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.
")("LONG-DESC" . "")("SECTION" . "LANGUAGE-OPERATORS")))("PACKAGES" (("KEYWORDS" . "variables; module; package; group")("SHORT-DESC" . "<i>Packages</i> 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 <i>prefix</i>.  When the prefix is not supplied, the symbol is looked up in the current package.

")("LONG-DESC" . "For example, a full reference to the symbol <var bar> stored in the <var foo> package looks like: 

<example>
   FOO::BAR
</example>

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.

<example>
   <set-var foo::bar = \"Hello\">
</example>

This has the effect of creating the package <var foo> if it didn't already exist.
")("SECTION" . "PACKAGES")))("STRING-OPERATORS" (("KEYWORDS" . "strings; characters; changing case")("SHORT-DESC" . "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 <funref \"string operators\" pad> function allows alignment of fixed-width text.
")("LONG-DESC" . "")("SECTION" . "STRING-OPERATORS")))("DATABASE-COMMANDS" (("KEYWORDS" . "")("SHORT-DESC" . "<meta-html> contains commands for performing operations on a database. A database created by <meta-html> contains <i>records</i> stored by <i>key</i>, where each record consists of a set of <i>name/value</i> pairs.

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

<funref \"database commands\" 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 <code>\"true\"</code> when they succeed, and store an error message in <funref Language-Operators SYSTEM-ERROR-OUTPUT> when they do not.
")("LONG-DESC" . "")("SECTION" . "DATABASE-COMMANDS")))("ODBC-DATABASE-OPERATORS" (("KEYWORDS" . "ODBC; database; records")("SHORT-DESC" . "<Meta-HTML> PRO is optionally delivered with a complete ODBC compliant database module, providing a useful set of database commands for operating on commercial databases, such as ORACLE or SyBase. These extensions allow true SQL database interaction at many levels, providing a clean and flexible abstraction.")("LONG-DESC" . "")("SECTION" . "ODBC-DATABASE-OPERATORS")))("MSQL-DATABASE-EXTENSIONS" (("KEYWORDS" . "database; SQL; Minerva")("SHORT-DESC" . "<Meta-HTML> can optionally be compiled with the MSQL
database interface library (by supplying <code>--with-msql</code> to the `<code>configure</code>' command).  These extensions allow true SQL database interaction at many levels, providing a clean and flexible abstraction to an MSQL database. 
")("LONG-DESC" . " ")("SECTION" . "MSQL-DATABASE-EXTENSIONS")))("SERVER-VARIABLES" (("KEYWORDS" . "server; mhttpd; variables")("SHORT-DESC" . "The <meta-html> server (<code>mhttpd</code>) 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.
")("LONG-DESC" . "")("SECTION" . "SERVER-VARIABLES")))