;;;
<set-var title="Meta-HTML FAQ">
<include ../header.mhtml>

<p>
<center>
  <h2><Meta-HTML> FAQ:</h2>
  <i>Frequently Asked Questions</i>
</center>
<p>

<defmacro faqpage>
  <set-var questions[]="" question-index=0>
  %body
  <set-var i=0>
  <ul>
    <while <lt i question-index>>
      <li> <a href="#q<add i 1>">
	<add i 1>) </a> <get-var questions[i]>
      <p>
      <increment i>
    </while>
  </ul>
  <p>
  <hr width=60%>
  <p>
  <set-var i=0>
  <while <lt i question-index>>
    <a name="q<add i 1>"></a>
    <b><add i 1>) <get-var questions[i]></b><br>
    <ul><get-var answers[i]></ul>
    <p>
    <increment i>
  </while>
</defmacro>

<defmacro question>
  <set-var questions[question-index] = <prog %attributes>>
  <set-var answers[question-index] = <prog %body>>
  <increment question-index>
</defmacro>

<defmacro mformat><code>&lt;%body&gt;</code></defmacro>
<defsubst file><code>%attributes</code></defsubst>

<defun manual-loc>
  <subst-in-string <get-var mhtml::url-to-dir> "/[^/]+$" "">/meta-html/manual
</defun>

<defun fundoc key>
  <a href="<manual-loc>/man-page.mhtml?<cgi-encode key>">
    <mformat><get-var key></mformat>
  </a>
</defun>

<faqpage>
<question Where can I get <Meta-HTML>?>
  <a href="ftp://ftp.metahtml.com">ftp://ftp.metahtml.com</a>
  always contains the latest releases of the source distribution, as
  well as example applications, tagsets, and helper applications.

  <Meta-HTML> is free software -- you can get a copy of it from
  <a href="ftp://prep.ai.mit.edu/pub/gnu/metahtml-5.01.tar.gz">
    ftp://prep.ai.mit.edu/pub/gnu/metahtml-5.01.tar.gz
  </a> and other <a href="http://www.gnu.ai.mit.edu/order/ftp.html">
  FTP sites for GNU/free software</a>.
</question>

<question What is the latest release of <Meta-HTML>?>
  The current release version is 5.01.
</question>

<question Who do I contact for support?>
<a href="mailto:info@ua.com">Universal Access Inc</a> provides free support
for <Meta-HTML> servers and <Meta-HTML> applications through our
mailing lists and online documentation. Developer subscriptions and
paid support packages are also available -- see the
<a href="http://www.metahtml.com"><Meta-HTML> Web Site</a> for
more details.
</question>

<question Will my copy of <Meta-HTML> expire?>
  No.  Unlike other vendors, <a href="http://www.ua.com/">Universal
  Access Inc.</a> is supplying <Meta-HTML> as <a
  href="free.mhtml"><i>Free Software</i></a>.  It will not expire.
</question>

<question Do the server and engine support the Common Log File format?>
  Yes. And the Engine can log requests independent of the host Web
  server.  Just add an entry to the <file engine.conf> file which gives
  the location of the logs you want to generate. 
  <p>
  Examples:
<pre>
<verbatim quote>
;;; MHTML::ACCESS-LOG is the full path to a file to which the server
;;; logs document accesses.
<set-var mhtml::access-log = "/www/mysite/logs/access_log">

;;; MHTML::ERROR-LOG is the full path to a file to which the server
;;; logs errors.
<set-var mhtml::error-log = "/www/mysite/logs/error_log">
</verbatim>
</pre>
</question>

<question Can I use <Meta-HTML> to manage my non-mSQL SQL database?>
You can use <Meta-HTML> PRO to insert, delete, and modify records and
tables in ODBC compliant non-mSQL databases.

Although you can create new tables within a database, you cannot do
general maintenance on these databases -- you must use the vendor
supplied software for this.
</question>

<question I've made a soft-link from `/www/bin/engine' to
	  `/www/webdir/docs/cgi-bin/nph-engine' and configured my
	  Apache server according to the instructions, but the server
	  refuses to run the engine.>
  Your Apache server may be configured to only run CGI programs if they
  are not soft-links.  This is easy enough to test: simply install the
  engine directly into your cgi-bin directory, instead of using a
  soft-link.
</question>

<question Why don't the <mformat>form-to-email</mformat>, and
	  <mformat>form-to-database</mformat> tags work?>
  You need to load each of the tagsets into your page before
  using them. This can be done with the <mformat>require ...</mformat>
  function.

  You need to have the tagset files in a place that
  <mformat>require</mformat> will be able to find them.
  A good place is the <code>/tagsets</code> directory, in your document 
  root directory. Please see the documentation for <fundoc require>.

  Example: In your page put <mformat>require form-to-email</mformat>
  before trying to use <mformat>form-to-email</mformat>.
</question>

<question My mhttpd binary crashes on Linux.>
  If you can't run Netscape 3.0b on your machine, it is likely you do
  not have have ELF binary support. Download the <b>aout</b> binary or
  recompile from <Meta-HTML> source.
</question>

<question The engine executes, but always tells me "Document Not Found"?>
  You probably have no <file engine.conf> (configuration) file. Or your
  <file engine.conf> does not set the document-root directory.  Here
  is a minimal <file engine.conf>:
<pre>
<verbatim quote>
<set-var mhtml::document-root=/www/webdist/docs>
<set-var mhtml::cgi-directories[0]=/cgi-bin/>
</verbatim>
</pre>
The <file engine.conf> file should be placed in your server's CGI directory
where the <file nph-engine> program lives. 
</question>

<question My mhttpd server runs but all documents are passed through and not
	  interpreted as MHTML.>
  You must specify the location of the <file mhttpd.conf> server
  configuration file, using the <code>--config</code> argument:
<pre>
/www/bin/mhttpd --config /www/mysite/conf/mhttpd.conf
</pre>
</question>

<question When I run the engine, browsers which don't support cookies can't
	  use session variables.>
  If you want to use sessions with non-cookie compatible browsers,
  the session-ID (SID) will be passed as the first pathname component of
  every URL, so you must configure your server to run *ALL* documents
  through the engine. See the Engine configuration instructions
  specific to your server.
  <p>
  Here is an example of the relevant portion of the <file srm.conf>
  file for Apache Web servers:
<pre>
ScriptAlias / /www/mysite/docs/cgi-bin/nph-engine/
</pre>
<p>
This maps all URLS through the <Meta-HTML> engine, transparently.
</question>

<question Sessions don't work.>
  Perhaps your server can't write its <file sessions.db> file.
  Permissions on the directory where the session file lives
  (<file /tmp/sessions.db> by default) must allow write access by the
  user which your server is running as.
  <p>
  The following entry in your <file mhttpd.conf> file sets the sessions
  db file location for a server:
  <pre>
<verbatim quote>
;;; MHTTPD::SESSION-DATABASE-FILE is a complete path to the file which
;;; will be used to store per-session information for users which have
;;; sessions.  If it is not set, it defaults to `/tmp/sessions.db'.
<set-var mhttpd::session-database-file =
   <get-var mhtml::server-root>/sessions.db>
</verbatim>
</pre>
</question>

<question OnLine-Shopping or other database applications shows no
	  data in the database.>
  You need to unpack the <file db.packed> files, using the
  <code>dbpack</code> utiltity.  This will convert from the portable
  db format to create native format database files.  If you build and
  install <meta-html> in the normal way, you shouldn't run into this
  problem, so please let us know if you do.
</question>

<question I've installed all the utilities but can't run any of the
	  programs.>
  You need to put the name of the directory where you have installed
  the utility programs in your path.  For example, if you installed
  the programs into <file/www/bin> (the default) then
<p>
<code>Bash</code>, <code>ksh</code>, and <code>sh</code> users should type:
<pre>
   export PATH=$PATH:/www/bin
</pre>
while <code>tcsh</code> and <code>csh</code> users should type:
<pre>
   setenv path = ($path /www/bin)
</pre>
</question>

<question  I run the server but get errors like this:
<pre>
/www/bin/mhttpd: Cannot bind socket to socket address
Error returned in errno: 13: Permission denied</pre>>
To use a restricted port like TCP port 80, you must have superuser
privileges.  Please start the server as the <code>root</code> user.
</question>

<question I run the server but get errors like this:
<pre>
/www/bin/mhttpd: Cannot bind socket to socket address
Error returned in errno: 48: Address already in use</pre>>
  This indicates that something is already using the port that the
  server wishes to use. It is likely that you already have another
  server running.
</question>

<question I configured my engine exactly as in the manual, but it
	  doesn't run.>
  You may already have a mapping in your web server config file
  which interferes with the mapping to the <Meta-HTML> engine.
  Check your <file srm.conf>, on Apache servers, for other
  <code>Scriptalias</code> mappings. 
</question>


<question How do I get include files to work in <code>mdb</code>?>
You can start <code>mdb</code> with your server configuration file
<pre>
mdb --config [path to mhttpd.conf or engine.conf]
</pre>
You can also set the location of your document root directory explicitly 
by writing <mformat>set-var mhtml::include-prefix =
"/www/pixis/docs"</mformat> into the configuration file.
</question>

<question How do I pass an array to a function?>
  You can pass an entire array by referring to it with <code><b>[</b></code>
  and <code><b>]</b></code>'s.  For example to call the function
  <code>foo</code> with the array <code>bar</code>, you would write:
<pre>
<mformat>foo bar[]</mformat>
</pre>
</question>

<question When I pass an array to a function, it flattens it into
	  a single string.  What's happening?>
  To specify that an argument is an array, it must be declared
  with <code><b>[]</b></code> directly following the variable name,
  with no intervening whitespace.  For example:
<pre>
<verbatim quote>
<defun foo item[]>
  <set-var temp=<get-var item[3]>>
  ...
</defun>
</verbatim>
</pre>
</question>

<question My session database just seems to keep growing.  How can I
	  keep it under control?>

  Each <Meta-HTML> server or engine has a GDBM <i>session database</i>
  which needs to be garbage collected periodically, to remove expired
  sessions.  A UNIX cron task can be configured to run a script every
  night to clean out the sessions database. Do "man crontab" to get
  more information about how to set up cron jobs.

  <p>

  The crontab entry to gc (garbage collect) the session database at
  one minute past midnite would look like this (assuming you have the
  <Meta-HTML> utilities installed in <file /www/bin>):
<pre>
   00 01 * * *       /www/bin/gc-database
</pre>

  This line can be added to your or root's crontab, using the commands
  that your system supplies for that purpose (usually, <code>"crontab
  -e"
  </code>).

  <p>

  If you have configured your server to keep its session database in a
  place besides the default location of <file /tmp/sessions.db>, or if
  you have several <Meta-HTML> servers running, you can easily write
  a shell script to gc all of the session databases, and then call
  that script from the crontab:
<pre>
  #!/bin/bash
  PATH=/www/bin:$PATH

  cd /www/bin
  gc-database
  gc-database -f /path/to/sessions.db
  gc-database -f /path/to/another/sessions.db
    ...
    ...
</pre>

  For each <Meta-HTML> server or engine, you can set the location of
  its session database file by setting the following variable in the
  <Meta-HTML> config file using:
<pre>
<verbatim quote>
 <set-var mhttpd::session-database-file =
     /path/to/your/sessions.db>
</verbatim>
</pre>

  Here is an example of an entry in a server <file mhttpd.conf> which
  puts the session database file for that server into the server's root
  directory:
<pre>
<verbatim quote>
<set-var mhttpd::session-database-file =
  <get-var mhtml::server-root>/sessions.db>
</verbatim>
</pre>
</question>

<question The Server doesn't seem to be interpreting any of the <file .mhtml>
	  files, it just delivers them verbatim.>
  Maybe the server could not find its config file on startup.
  <p>
  Use the  <code>--config</code> arg to <file mhttpd> to specifiy the
  complete pathname of the <file mhttpd.conf> configuration file.
</question>

<question What about security?>
  You will need to read the manual for more details.  Some measures must
  be taken to turn posted data into non-executable <Meta-HTML>.

  The tagset <code><b>general.mhtml</b></code> contains a useful
  function for doing this:
<pre>
<verbatim quote>
;;; <make-innocuous [package]> turns the contents of PACKAGE into
;;; non-executable text.
<defun make-innocuous package>
  <set-var names[]=<package-vars <get-var package>>>
  <set-var i=0>
  <while <get-var-once names[i]>>
    <subst-in-var <get-var-once names[i]> "&" "&amp;" "<" "&lt;" ">" "&gt;">
    <increment i>
  </while>
</defun>
</verbatim>
</pre>
Also, you can remove all dangerous operators from your page environment
by deleting their definitions:
<pre>
<verbatim quote>
;;; Now, disable dangerous commands, so we can do substitutions
;;; of our commands into the HTML text, and then evaluate it.
<in-package *meta-html*>
  <unset-var cgi-exec with-open-database with-open-stream
	     msql::with-open-database>
</in-package>
</verbatim>
</pre>
</question>


<question How do I make my pages stay cached in the browser?>
  By default <Meta-HTML> delivers pages with expiration dates in the past
  in order to prevent them from being cached. You can override this
  by setting the variable <code>mhtml::cacheable</code>. You can set
  this in each page as needed, in a common header file, or in the site
  or engine configuration file.

  <p>Note that if you mark pages as cacheable by accident which are
  supposed to be dynamically updated every time a user visits them, it
  can cause confusing behavior to the user, because they will 
  not see new versions of the page automatically.
  <pre>
<verbatim quote>
  <set-var mhtml::cacheable=true>
</verbatim>
</pre>
</question>


</faqpage>
<include ../footer.mhtml>
