OS/2 Shareware BBS: 35 Internet/35-Internet.zip/goinf252.zip/GoServe.INF

OS/2 Help File | 2001-07-24 | 116KB | 3,101 lines

ΓòÉΓòÉΓòÉ 1. Credits ΓòÉΓòÉΓòÉ

                   GoServe -- A Web and Gopher Server for OS/2
                   """""""""""""""""""""""""""""""""""""""""""
                                      GoServe 2.52

        Copyright (c) IBM Corporation, 1993, 1998.  All rights reserved.
                       Mike Cowlishaw, IBM UK Laboratories
                                 [e-mail]
                                    - - - - -

About


ΓòÉΓòÉΓòÉ 2. Introduction ΓòÉΓòÉΓòÉ

Two popular protocols for providing information on the Internet are the
HyperText Transfer Protocol (HTTP, used by World Wide Web clients) and Gopher
(used by both Web and Gopher clients).

'GoServe' is a multi-purpose server for OS/2 which supports both these
protocols.  The emphasis in the design of GoServe has been to make it easy to
become an information provider for the Internet, while not inhibiting full use
of the protocols by sophisticated users.

Providing that you already have TCP/IP installed, GoServe can be running and
serving files across a network in minutes; no re-boot or editing of
configuration files is necessary.  The GoServe package includes 'quick start'
instructions and working samples for both Web and Gopher servers.

GoServe processes requests from Web or Gopher clients using a Rexx script to
allow for customization.  A server can handle requests from many clients, using
OS/2 threads and script caching for efficiency. Multiple servers can be started
(using different ports), and an audit trail of requests and actions can be
recorded.  When running as a Web server, much of the complexity of the Web
protocol is handled automatically; many GoServe users will only need to be
concerned about the data being provided, and need not be concerned about the
mechanism.

While running, a graphical display of GoServe activity is shown (the "Graphical
Webspinner Interface"?), with optional response-time graphing and audible
indication of connections.  For control, various restrictions may be employed
to limit the load on the server machine. GoServe operations can be controlled
remotely, if desired, using any Web client (or an OS/2 CMD program).

GoServe is a 32-bit OS/2 application, which requires OS/2 2.x or OS/2 Warp.
GoServe requires IBM TCP/IP for OS/2, or equivalent, to be installed and
operational (either on a real network or using the loopback driver).  GoServe
may be used as both a Web server and a Gopher server on the same server
machine, on one or more ports for each, if required.


ΓòÉΓòÉΓòÉ 3. Getting started ΓòÉΓòÉΓòÉ

This document describes all aspects of the use of GoServe as a Web or Gopher
server.  If you are a new user, you should first read one of:

     GoHTTP.doc -- for getting started setting up a Web server

     GoGopher.doc -- for getting started setting up a Gopher server.

 Both of these guide you through setting up a working server.  It's recommended
 that you do this before reading more of the technical details in this
 document.  This document assumes that you are familiar with Web or Gopher
 concepts, and have access to (and know how to use) a Web or Gopher client.


ΓòÉΓòÉΓòÉ 3.1. --- Resources --- ΓòÉΓòÉΓòÉ

This document, the latest GoServe package, and other relevant links,
information, and programs are available at the GoServe Web page at:
http://www2.hursley.ibm.com/goserve/

Several GoServe users have contributed some very useful extensions to GoServe,
and there's a mailing list too.  See, for example:

     Don Meyer's CGI, Image Map, and forms support for GoServe, at:
        http://w3.ag.uiuc.edu/DLM/GoHTTP/GoHTTP.html

     Lew Waber's mail support and other enhancements, at:
        http://lwaber.swmed.edu/goserve.htm

     Daniel Hellerstein's SRE-http filter, with CGI, redirection, server side
      includes, multiple realms and hosts, HTTP 1.1 support, etc., at:
        http://rpbcam.econ.ag.gov/srefilter

     The OS/2 Forum Austria Extended GoServe Filter, at:
        http://www.os2forum.or.at/software/local/ofaegf/

     Ken Kavanagh's GoServe mailing list; the place to 'meet' other GoServe
      users and share GoServe hints and tips; for details, see:
        http://www.lionsgate.com/lists/goserve/

 All of these are linked from the main GoServe page.


ΓòÉΓòÉΓòÉ 4. How GoServe is used ΓòÉΓòÉΓòÉ

GoServe is an ordinary 32-bit OS/2 application program (it has no special
privileges, and uses only public interfaces to OS/2 and to TCP/IP).  When
starting GoServe, you should specify as a parameter the protocol that the
server is to use (HTTP or GOPHER).

Once started, GoServe sets up a TCP/IP socket on the 'well-known' port for the
protocol selected (this can be altered using a different startup parameter),
then waits for requests from clients.  When a request from a client arrives, it
is recorded in the audit file (if desired) and then the GoServe filter for the
port is called.

The GoServe filter is a program written in Rexx, which is given details of the
client and the request string.  The filter decides on the information (usually
a file, containing a document or other data) to be sent to the client, and
returns details to GoServe.  GoServe then sends the HTTP response and the data
to the client and closes the TCP/IP connection.

Each incoming request is given a new OS/2 thread for communication, filter
processing, and response.  GoServe handles all the details of threads and
TCP/IP communications, so you need only be concerned with the filter (which can
often simply be the sample filter, unchanged) and the data (documents, images,
etc.).

GoServe is designed to perform well, even on inexpensive hardware.  Some of the
default settings, however, are chosen for safety rather than best performance.
To maximise performance and throughput, you may wish to turn on File command
caching, Connection maintenance, and Lazy auditing (see below for details).
GoServe also runs faster with its display window minimized.


ΓòÉΓòÉΓòÉ 5. Installation ΓòÉΓòÉΓòÉ

If you followed either of the 'getting started' documents, you will have
already installed GoServe.  In general, only two files (plus data) are needed
to run GoServe as a Web or Gopher server: the GOSERVE.EXE program file, and the
appropriate Rexx filter.  The default filter name has filename GOFILTER, with
an extension that is the TCP/IP port number to be used (for example,
'GOFILTER.80' for the filter for a default Web server, or 'GOFILTER.70' for the
filter for a Gopher server).  The filter must be in the working directory for
GoServe.

It is recommended that GOSERVE.EXE and the Rexx filter be placed in one
directory (for example, 'D:\GoServe'), and data for the server be placed in a
different directory.  By default, the latter is expected to be on the same
drive as the GoServe directory, and named '\gohttp' for a Web server or
'\gogopher' for a Gopher server.

Both the data directory and the filter name can easily be changed by using the
GoServe options notebook or by a command line option, if required.

In all cases, the Rexx filter must be in the working directory for GoServe.
The working directory is also used by GoServe for the GOSERVE.INI file (which
holds user settings, such as window position and audit selections), and for any
Audit and Audit Archive files.

When you unzip the GOSERV.ZIP file, you should find the following files:

 goserve.doc    -- this document
 gohttp.doc     -- how to get started as a Web server
 gogopher.doc   -- how to get started as a Gopher server
 goserve.exe    -- the server program
 gofilter.80    -- sample (working) filter for HTTP
 gofilter.70    -- sample filter for Gopher
 goremote.80    -- sample filter for WWW remote control of GoServe
 moveaud.cmd    -- sample remote control command
 makeicon.cmd   -- installation aid
 gohttp.zip     -- sample pages, etc., for a Web server [unzip to a separate
                directory, perhaps D:\GoHTTP].  This also includes the GoServe
                Web documentation in HTML.
 gogopher.zip   -- sample menus, etc., for a Gopher server [unzip to a separate
                directory, perhaps D:\GoGopher]
 license.txt    -- IBM license agreement for OS/2 Tools

 Please see the 'how to get started' documents for step-by-step instructions
 for installation.


ΓòÉΓòÉΓòÉ 5.1. --- Uninstalling GoServe --- ΓòÉΓòÉΓòÉ

To uninstall GoServe, it is only necessary to delete the directories used by
GoServe, with their contents.  No changes are made to the OS/2 system.  (Note
that prior to version 1.74, GoServe saved settings in OS2.INI.  Later versions
automatically migrate this information to the GoServe working directory.)


ΓòÉΓòÉΓòÉ 5.2. --- Requirements --- ΓòÉΓòÉΓòÉ

GoServe is a 32-bit OS/2 application, which requires OS/2 2.x or OS/2 Warp.
For OS/2 Warp, version 1.31 (or later) of GoServe is needed.  GoServe requires
TCP/IP for OS/2, or equivalent, to be installed and operational (either on a
real network or using the loopback driver). Only the TCP/IP base kit should be
needed, or the OS/2 Warp Internet Access Kit from the Bonuspak.  Over time,
CSDs for TCP/IP become available--if TCP/IP problems are suspected, always try
the latest CSD.


ΓòÉΓòÉΓòÉ 5.3. --- Running GoServe 'stand-alone' --- ΓòÉΓòÉΓòÉ

GoServe and Web Explorer can be run on a stand-alone machine that is not
connected to a network, provided that TCP/IP is installed and the loopback
driver is started.  This is especially useful for developing Web pages offline,
or for demonstrations.  To do this, two additions are needed to a standard
TCP/IP installation (such as the OS/2 Warp Internet Access Kit):

   1. To the file called 'HOSTS' (no extension) in your \TCPIP\ETC directory
      add the line:

                   127.0.0.1  loopy

      where 'loopy' is the name by which you want your machine to be known when
      using the loopback connection.  This name can be a single word (e.g.,
      'loopy'), or an internet-style name (e.g., 'loopy.my.org').  It's a good
      idea to have both formats, on two lines:

                   127.0.0.1  loopy.my.org
                   127.0.0.1  loopy

      Note:  if you are running Warp Connect, the directory should be
      \MPTN\ETC.  In general, check the value of the ETC environment variable
      to find out where the HOST file should be placed.

      If there is no \xxx\ETC\HOSTS file, create one.

   2. Before running GoServe, execute the command:

                   ifconfig lo 127.0.0.1

      This only needs to be run once, so can be run from STARTUP.CMD or from
      any command referenced in your Startup folder.  Note that the second word
      is the lowercase of the two letters 'L' and 'O'.

 Once set up, you can then connect to GoServe on your own machine using (for
 example) the URL:

    http://loopy

 With recent TCP/IP versions you can carry out step 2 above using the TCP/IP
 configuration notebook.  On the 'Network' page, click on 'loopback interface',
 then check 'Enable interface' and 'Manually, using', then enter '127.0.0.1' as
 the 'IP address'.

 The loopback address will be active even when connected to a network, so you
 can always connect to GoServe running on the same machine using the loopback
 name that you chose, provided that your browser does not have a proxy or SOCKS
 server enabled (the proxy won't be able to find your local loopback address).

 Even if you are not connected to a network, your browser should not have a
 proxy or SOCKS server enabled (or it will try and use the network to find it
 before checking the HOSTS file).


ΓòÉΓòÉΓòÉ 6. Filter programs ΓòÉΓòÉΓòÉ

Filter programs are written in Rexx.  Based on the arguments they are passed,
they decide on the document or other data to be sent to the client and then
issue a command or return a result that defines that data (usually a file) to
the server.  GoServe then handles the transmission of the data to the client.

All requests are passed to the Rexx filter, so for every request you have full
control over the response by modifying the filter as required. By default,
GoServe will never send data to a client without the filter being involved.

The filter is cached (that is, it and its tokenized version are only read from
disk when changed) and is executed on the same thread as the incoming request
(not as a separate process).  This is very efficient; informal measurements
suggest that only a small percentage of the total response time of a simple
request is spent in running the filter.  For example, the total time to run the
sample filter on a 486/50MHz PC has been measured under OS/2 2.11 and OS/2 Warp
to be as little as 11ms.

For examples of filters and forms processing, please see the sample filters in
the GoHTTP or GoGopher collections.  The following is specific technical
information on how the filters work.  Three argument strings are passed to the
filter:

   1. The source of the request.  This has five words [more words could be
      added at the end in the future], separated by one or more blanks:

          the Internet address of the server for this request (in numeric
           form).  This is normally constant, unless you have more than one
           network defined; for example, a 'real' network and a loopback
           configuration, or more than one network adapter card.

          the server's port number used for the connection.

          the transaction number (a number, incremented for each new
           connection, that starts at 0 when GoServe is started).

          the Internet address of the client (in numeric form).  Note that
           this may not be the address of the end-user's machine, if the
           connection is made through a proxy or firewall.

          the client's port number used for the connection.

                           Example: "9.15.11.189 80 101 9.20.25.65 1987"

   2. The request string.

          For a Web server, this string is the HTTP request string, exactly as
           received from the client.  This comprises three words: the request
           verb (e.g., 'GET'), the URI (Universal Resource Identifier) or
           partial URI, and the HTTP protocol identifier (e.g., 'HTTP/1.0').
           The third word may be absent when older (HTTP/0.9) clients connect.
           A URI of just '/' indicates the initial contact from a client, and
           the filter would normally respond with a default document ("home
           page").

           Partial URIs are (or should be) the request string from a Web 'href'
           attribute previously sent to the client, unchanged [except that
           extra data, such as incoming data from forms, may be suffixed, and a
           leading slash, '/', may be added].  For more information on URIs,
           see the technical details available on the Web.  A good place to
           start is the Web information based at 'http://www.w3.org/'.

          For a Gopher server, the request string is any data received from
           the client up to (but not including) a Tab, Carriage Return, or Line
           Feed.  An empty request string indicates the initial contact from a
           client, and the filter would normally respond with a default Gopher
           menu.  Otherwise, it will (or should) be the request string from a
           Gopher menu line previously sent to the client, unchanged.

      You have complete freedom in setting request strings in Web documents and
      Gopher menus, and in deciding how the filter should respond depending on
      the string received.  Very often, the name of a file is used, and that
      file is sent to the client.  [Note: it is recommended that fully
      qualified filenames NOT be used for request strings.]

   3. The extended request string.

          For an HTTP server, this string is the "packed" URI or partial URI.
           This is the second word of the request string, with escape sequences
           (e.g., '%7e') converted to a single byte, and with any leading slash
           ('/'), if present, removed.

          For a Gopher server, this is the 'Gopher+' data.  Some Gopher
           clients can add additional information to a request, attached to the
           request string after a Tab character.  GoServe discards the Tab
           character and presents the remainder as the third argument to the
           filter.  See Gopher protocol documents for more information on how
           the extended selector string is used.

 The filter can specify that GoServe send either a file or a single string to
 the client, or request certain other GoServe operations. All these operations
 are effected in the usual Rexx way, by using commands, which are described
 later in this document.  Other commands allow more detailed control of the
 server.

 The filter may also return a result string to GoServe; this, too, is treated
 as a command.  [In early versions of GoServe, this was the only way to execute
 a GoServe command, so early GoServe filters only use that mechanism.]

 In addition to the commands, GoServe provides several special-purpose
 functions for dealing with incoming requests.  For example, the PACKUR(string)
 function takes a string which has been encoded for safe transmission, and
 reduces escape sequences (such as '%7E') to the character encoding that they
 represent (in this case, '~').

 Any failure of the filter (such as a syntax error) is considered catastrophic
 and will cause GoServe to end, to reduce the risk of unauthorized data
 transmission by a buggy filter.  Notes:

   1. Remember that GoServe will run multiple copies of the filter at once, on
      different threads, if more than one client connects at the same time.  If
      building temporary files, use the transaction number (or request number)
      and port as part of the file name.

   2. The results of SAY instructions (or tracing) in the filter program may be
      seen using the PMprintf package.  However, Rexx interactive tracing is
      not supported.  PMprintf should be available from the same source as
      GoServe, or from the GoServe Web page at:
      http://www2.hursley.ibm.com/goserve/

   3. You may change the name of the filter when starting GoServe or by using
      the 'Filter selection' options page.  The filter must always be in the
      working directory for GoServe.  If you make changes to the default
      filter, it's a good idea to change its name, too, so if you install a new
      version of GoServe your filter will not be overwritten by the new default
      filter.

   4. External subroutines, written in Rexx, are easily called from the filter
      simply by using their name in a CALL instruction or function call.  The
      names should not match that of a Rexx built-in function, and the routine
      should normally be in a file with the same extension (e.g, '.80') as the
      filter and in the same directory.

   5. You can execute OS/2 commands from the filter using the Address CMD
      instruction, for example:

                   address cmd
                   'start e foo.bar'
                   'call d:\foobar\test.cmd argstring'

      Use caution when calling external programs before the response is
      complete: any slowness directly affects the response time to the client
      and its user.  Note also that separate processes (including external
      commands) are not terminated automatically by GoServe if a connection
      times out.

      Finally, when executing commands, do not build any part of the command
      string from data received from the client; this could allow execution of
      arbitrary commands on your server (for example, if an '&' command
      separator character were included in the data).

   6. By default, each copy of a filter may have up to five files open at once.
      This limit may be increased using the Limits selection dialog (see "The
      Limits options pages").

   7. A new version of the filter is only cached (loaded) when GoServe is idle,
      and has been idle for 5-10 seconds.  Therefore, if you change the filter
      while GoServe is running, the changes may not be used until the first
      client connects after a time when there have been no clients connected
      for ten seconds.

   8. For more information on Rexx, try connecting to the Rexx Language page
      at:
      http://rexx.hursley.ibm.com/rexx/

   9. For more information on OS/2, start at the IBM home page
      (http://www.ibm.com), and use the Search option to search for OS/2.

      Links to these and other useful pages may be found on the GoServe home
      page at:
      http://www2.hursley.ibm.com/goserve/


ΓòÉΓòÉΓòÉ 7. Filter commands ΓòÉΓòÉΓòÉ

Commands may be executed by GoServe filters at any time, using the usual Rexx
command syntax (a clause that is just an expression).  In addition, any string
returned by the filter will be executed as a command.

For simplicity and efficiency, most requests can be satisfied by executing a
single command which sends some data (often a file) to the client and then
closes the connection (unless it is persistent, see below).  These commands
(CLOSE, CONTROL, FILE, NODATA, STRING, and VAR) are known as 'completion
commands'; that is, after executing the command, the response to the client
will have been sent and will be complete.

Only one completion command may be executed for each request received; once a
completion command has been executed, no further commands (except CLOSE) will
be accepted for the transaction until a new request is received, which can only
occur if the connection is persistent.

In some situations, it is useful to be able to build up the response from more
than one data source; in this case, the SEND command is used to start the
sending of the response.  One or more of the completion commands are then used
to send the data (in this case, the connection is not closed after the
commands), and then the connection is closed by using the SEND COMPLETE
command.

When completion commands are executed, GoServe (actually, TCP/IP) will normally
collect the data from them in a buffer and send packets of data when enough has
been collected.  GoServe can be made to send the data immediately the commands
are executed by using the command SET NETBUFFER OFF.

If the filter ends without error or sending any data and without executing or
returning any completion command, the server will generate one (currently
"String [No information available]").

Errors and failures in commands are reported by a non-zero return code (which
is placed in the Rexx variable RC), and also may raise the ERROR or FAILURE
condition if enabled by SIGNAL ON or CALL ON in the filter. Command errors are
also audited unless Error auditing has been turned off.  For details on the
possible return codes, see "Command return codes".

The total length of a command is limited to 1000 characters.

The most important commands are the completion commands, though there are
others which will be useful to filter writers.  The commands follow in
alphabetical order; note that keywords and file specifications may be in lower,
upper, or mixed case.


ΓòÉΓòÉΓòÉ 7.1. AUDIT command ΓòÉΓòÉΓòÉ

Syntax:

  AUDIT string

The string supplied will be written to the Audit file as a 'user audit' line.
See "The audit mechanism" for a description of auditing.


ΓòÉΓòÉΓòÉ 7.2. CLOSE command ΓòÉΓòÉΓòÉ

Syntax:

  CLOSE

This command will cause GoServe to end, with return code set to 1, when all
current connections have been completed.  No new connections will be accepted.

CLOSE is permitted after a completion command, so a response may be sent before
the close.  If one has not been sent, an acknowledgement is sent to the client,
and the connection is then closed, so CLOSE is then a completion command.


ΓòÉΓòÉΓòÉ 7.3. CONTROL command ΓòÉΓòÉΓòÉ

Syntax:

  CONTROL [NOWAIT] [VAR varname] options

A GoServe control action (such as moving the audit file, resetting counters, or
requesting statistics) is initiated, and a result string is either placed in a
Rexx variable or returned to the client.

This is used for controlling the GoServe server from the filter, either
directly or on request from a remote client or from another process on the same
machine -- for information on ways to do this, see "Remote control of GoServe".
The possible options are:

     MOVEAUDIT

 The audit file is copied to the archive file (just as though the 'Move audit
 to archive' Actions menu item had been selected).

     RESET [BYTES] [PEAK] [RESPONSE] [TRANSACTIONS] [LIMITS] [ERRORS] [ALL]

 The specified GoServe counters and statistics are reset (after auditing, if
 appropriate).  Any or all of the keywords may be given, in any order.  Each
 works in the same way as the corresponding Actions menu item; RESPONSE refers
 to the response time record.

 If ALL is used, all of the items are reset, and a record of the time is kept;
 this time will be shown on the display window and in any statistics requests.

     SAY string

 The given string is returned; this can be used as a simple 'Loopback test'.

     STATISTICS

 Current statistics and settings are returned.  These include:

   1. Transaction, error, limits, byte, and client counts, with response time
      averages

   2. Certain settings and options (not including audit selections)

   3. The local time of certain events (if an event has not occurred, it is
      shown as the GoServe start time).

 The result of a CONTROL command is a single string, which may include multiple
 lines, separated by Carriage Return-Line Feed (CR-LF, ASCII '0d0a'x)
 sequences.  The exact format is not defined.  The result string is either
 placed in a variable or returned to the client:

     If 'VAR varname' was specified, the result string is placed in the named
      Rexx variable.  The name of the variable is used just as if it appeared
      in the filter program (for example, the name 'local.j' might have the
      value of J substituted in the name).

     If 'VAR' was not specified, a document containing the string is returned
      to the client (just as though the STRING command were used), so in this
      case, CONTROL is a completion command.

 The NOWAIT keyword may be used to force the current connection to be closed
 after any response is sent, even if a persistent connection had been
 requested.


ΓòÉΓòÉΓòÉ 7.4. EXTRACT command ΓòÉΓòÉΓòÉ

Syntax:

  EXTRACT items

Extracts the state of one or more GoServe settings for use in a Rexx filter.
'items' is a list of one or more keywords, as specified in the QUERY and SET
commands.  The values of the specified items are placed into Rexx variables of
the same name.

For example:

  'extract diag diag2'
  say 'DIAG flag is' diag', DIAG2 flag is' diag2
  'set diag2 invert'
  'extract diag2'
  say 'DIAG2 flag is now' diag2


ΓòÉΓòÉΓòÉ 7.5. FILE command ΓòÉΓòÉΓòÉ

Syntax:

  FILE [ERASE] [NOWAIT] [TYPE content-type] [BINARY|TEXT] [NOCACHE] NAME filespec

The file named by 'filespec' will be sent to the client.  'filespec' should
normally be a fully qualified name (if it is not, GoServe would look for it in
the GoServe working directory).  Either forward or backward slashes may be used
as directory separators; the OS/2 file systems accept either.

After this command has ended, the connection to the client is closed, so this
is a completion command.

The optional keywords may be specified, in any order, and have the following
effects:

     ERASE -- the file is a temporary file, and should be erased after being
      sent.  [The transaction or request number and port can be used for
      generating a safe name for a temporary file.]

     NOWAIT -- forces the current connection to be closed after any response
      is sent, even if a persistent connection had been requested.

     TYPE -- [HTTP protocol only] the file will be prefixed by an HTTP "OK"
      response line and an HTTP header, including the content length derived
      from measuring the file.  The value of the TYPE option ('content-type')
      should be a Internet Media Type such as "text/html" or "image/gif", of up
      to 120 characters and with no embedded spaces. See notes below for more
      information.

      The TYPE option may only be used if GoServe is started with the HTTP
      parameter (HTTP headers are not used by Gopher), and should normally
      always be used when running as a Web server.

     BINARY -- [default for HTTP] the file is a binary file, and form the
      entire response to the client.  GoServe will close the TCP/IP connection
      as soon as the complete file has been sent.

      A Gopher server should use this option for all files that are not simple
      text or menus, for example ".ZIP" files, etc.

     TEXT -- [default for Gopher] the file is a text file: any trailing DOS
      end-of-file character will not be sent to the client.

      If running as a Gopher server, a Gopher terminator line (just a period)
      will be sent at the end of the document, before the connection is closed.

     NOCACHE -- prevents this FILE command being cached (that is, this command
      will not be associated with a request).  See "File command cache" for
      more details.

 Here are some examples:

   1. Returning an HTML file to a Web client:

               file type text/html name d:/gohttp/index.htm

   2. Returning a temporary image file to a Web client:

               file erase type image/gif name d:/gohttp/$7681.80

   3. Returning a .ZIP file to a Gopher client:

               file binary name d:/gogopher/gogopher.zip

 Notes:

   1. The filespec may not include an 'upwards reference' sequence ("..\" or
      "../"), as such a sequence could possibly allow clients access to any
      file on the server machine.

   2. All data sent to a client with an HTTP header should be described by a
      Content-Type field in the header; GoServe will therefore only generate a
      header automatically if the TYPE option was specified or the HEADER
      command has been used to add header lines.  In this latter case, it is
      the responsibility of the filter to supply the Content-Type field if the
      TYPE option was not used.

   3. Internet Media Types were formerly known as MIME (Multipurpose Internet
      Mail Extensions) Content Types.  MIME is described in RFC 1521 and RFC
      1522.  The media types are used in the HTTP protocol so that clients can
      determine how to process data received from servers.  Some common types
      are listed in the sample filter.


ΓòÉΓòÉΓòÉ 7.6. HEADER command ΓòÉΓòÉΓòÉ

Syntax:

  HEADER [NOAUTO|NOTIME] [{ADD|DROP} value]

Adds a header line to the HTTP response header, or drops one already added.
Header lines added by this command are sent to the client after header lines
generated automatically by GoServe.  They are all sent before any data; all
HEADER commands must precede any commands that send data.  For example:

  HEADER ADD Title: My own title

Blanks following the keyword ADD or DROP are removed by GoServe, so
continuation header lines must be started with the tab ('09'x) character.

If DROP is used, only the field identifier (up to and including the colon)
should be specified.  The first header line that matches (of the lines added
using HEADER ADD) is dropped, together with any following continuation lines;
automatically generated header lines are not affected.  A case-insensitive
comparison is used for determining a match.

NOAUTO may be used either alone on the command or in conjunction with the ADD
or DROP form.  If any HEADER command specifies NOAUTO, no header lines will be
automatically generated by GoServe (except the final empty line); all lines
must be explicitly defined using HEADER ADD.  For example:

  HEADER NOAUTO ADD Server: Special/0.01
  HEADER        ADD Title: Two-line header

NOTIME may be used either alone on the command or in conjunction with the ADD
or DROP form.  If any HEADER command specifies NOTIME, no header lines that
start with 'Expires:' or 'Last-Modified:' will be automatically generated by
GoServe.  For example:

  HEADER NOTIME
  HEADER NOTIME ADD Last-Modified: Mon, 23 Dec 1996 19:40:20 GMT

At least one keyword must be used on the HEADER command.  The HEADER command
has no effect under the Gopher protocol (though the command syntax is checked).
It also has no effect if the incoming request uses HTTP/0.9 -- in this case,
the protocol does not permit a header to be returned, as it would be treated as
part of the data.


ΓòÉΓòÉΓòÉ 7.7. NODATA command ΓòÉΓòÉΓòÉ

Syntax:

  NODATA [NOWAIT] [NORESPONSE]

No data are to be sent; the response is complete.  For an HTTP/1.0 or later
request, only a response line and header will be sent.  For a Gopher (or
HTTP/0.9) request, the connection will simply be closed (unless it is
persistent, see below).  This command is intended to be used when only a
header, or nothing at all, is to be returned to the client.

If NORESPONSE is specified, then no response line and header will be sent
either, even for an HTTP/1.0 or later request; the connection will be closed
(unless persistent).  This option could be used for testing, or if (say) a
faulty client was sending repeat messages.

The NOWAIT keyword may be used to force the current connection to be closed
after any response is sent, even if a persistent connection had been requested.

NODATA is a completion command.


ΓòÉΓòÉΓòÉ 7.8. QUERY command ΓòÉΓòÉΓòÉ

Syntax:

  QUERY items

Queries the state of various GoServe settings.  'items' is a list of one or
more keywords.  The name and value of each item is displayed using PMprintf; to
see the results the PMprintf console must be active. PMprintf should be
available from the same source as GoServe, or from the GoServe Web page at
http://www2.hursley.ibm.com/goserve/

Any item that can be set by the SET command may also be queried.  The value of
any item that may be set or queried may also be obtained by a Rexx filter,
using the EXTRACT command to place the values in Rexx variables.  PMprintf is
not needed in order to use the EXTRACT command.

Valid items are:

     BYTESREAD -- the number of bytes received from the network, so far during
      the current transaction.

     BYTESREADTOTAL -- the total number of bytes received from the network.
      You may need to increase the Rexx NUMERIC DIGITS setting if you wish to
      do arithmetic on this count.  16 digits should be sufficient.

     BYTESSENT -- the number of bytes sent to the network, so far during the
      current transaction.

     BYTESSENTTOTAL -- the total number of bytes sent to the network. You may
      need to increase the Rexx NUMERIC DIGITS setting if you wish to do
      arithmetic on this count.  16 digits should be sufficient.

     CLIENTADDR -- the client's address used for the connection, in numeric
      form (for example, 12.34.56.78).  For a symbolic name for the address,
      see the CLIENTNAME function.

     CLIENTMETHOD -- the method (verb) being invoked by the client (on the
      HTTP request, or "GET" if a Gopher request).  For example, "GET" or
      "POST".

     CLIENTPORT -- the client's port number used for the connection.

     CLIENTPROTOCOL -- the protocol being used by the client (on the HTTP
      request, or "GOPHER" if a Gopher request).  For example, "HTTP/1.0".

     CLIENTS -- the number of clients currently connected.

     ELAPSED -- the elapsed time, in seconds, since the current transaction
      started (that is, when the network connection was accepted).  Any decimal
      part will not have trailing zeroes.

     ERRORS -- the count of errors detected.

     GMTOFFSET -- the GMT offset (in seconds).  If GMTSET is OFF, this will be
      0.

     GMTSET -- GMT is available [ON if available, else OFF].

     LASTACCEPT -- timestamp of the last accepted connection [format:
      yyyy.mm.dd hh:mm:ss].

     LASTIDLE -- timestamp of when GoServe last entered an idle state, with no
      connections [format: yyyy.mm.dd hh:mm:ss].

     LASTRESET -- timestamp of the last CONTROL RESET ALL command [format:
      yyyy.mm.dd hh:mm:ss].

     LASTSECOND -- time now, in the same format [yyyy.mm.dd hh:mm:ss] as the
      other LASTxxxx items.

     LASTSTART -- timestamp of when this instance of GoServe was started
      [format: yyyy.mm.dd hh:mm:ss].

     LIMITS -- the count of limits exceeded (that is, the count of
      transactions that were ended due to a limit being exceeded).  The limits
      counted are the total connection timeout (LIMITTIMETOTAL), the incoming
      data measures (LIMITBODY and LIMITHEADER), and maximum clients exceeded
      (LIMITCLIENTS).  The latter is only counted once for each non-idle burst
      of connections.

     PEAKCLIENTS -- the maximum number of clients that were connected
      simultaneously.

     READWAITTIME -- average read wait time (seconds).

     REQUEST -- the unique number for this HTTP request.  This is incremented
      as each HTTP request is read.  This can differ from the TRANSACTION
      (connection) number if a connection fails to send a request, or if there
      is more than one request in a transaction.

     REQUESTS -- the number of HTTP requests read since GoServe was started,
      or since the last CONTROL RESET ALL or CONTROL RESET TRANSACTIONS.

     RESPONSEOVER -- number of connections over which RESPONSETIME and
      READWAITTIME have been averaged.

     RESPONSETIME -- average response time (seconds).

     SELECTOR -- the selector string (Universal Resource Indicator, for HTTP).

     SERVERADDR -- the server's address used for the connection, in numeric
      form (for example, 11.22.33.44).  For a symbolic name for the address,
      see the SERVERNAME function.

     SERVERPORT -- the server's port number used for the connection (for
      example, 80 for default HTTP).

     SERVERPROTOCOL -- the protocol understood by the server (for example,
      "HTTP/1.0", or "GOPHER" if running as a Gopher server).

     SERVERSOFTWARE -- the level of the server software (for example
      "GoServe/2.40").  This is the same as returned by the function call
      SERVER("HTTP").

     TRANSACTION -- the unique number for this transaction (connection). This
      is incremented as each client connects to the server.  This can differ
      from the REQUEST number if a connection fails to send a request, or if
      there is more than one request in a transaction. Note that a filter may
      be called more than once during one connection (though not concurrently).

     TRANSACTIONS -- the number of transactions since GoServe was started, or
      since the last CONTROL RESET ALL or CONTROL RESET TRANSACTIONS.


ΓòÉΓòÉΓòÉ 7.9. READ command ΓòÉΓòÉΓòÉ

Syntax:

  READ [BODY|HEADER|CHUNK size] {VAR varname | FILE [APPEND] NAME filespec}

Reads (receives) information from an HTTP client.  Either the header lines (if
HEADER is specified) or the body data are read (if BODY or CHUNK is specified).
The default source is BODY.

If CHUNK is specified, the keyword must be followed by a non-negative integer
size, and this is the number of bytes that will be read from the body.  If BODY
is specified, the size is taken from the Content-Length field in the header.
Then:

     If 'VAR varname' was specified, the header or body data are placed in the
      named Rexx variable, as a single string.  The name of the variable is
      used just as if it appeared in the filter program (for example, the name
      'local.j' might have the value of J substituted in the name).

     If 'FILE NAME filespec' was specified, the data are written directly to
      the file named by 'filespec'.  'filespec' should normally be a fully
      qualified name (if it is not, GoServe will write the file in its working
      directory).  'filespec' may not include an 'upwards reference' sequence
      ("..\" or "../"), as such a sequence could possibly allow clients to
      modify any file on the server machine.

      The named file is overwritten unless APPEND is specified (in which case
      the data are written following the end of any existing data).

 The READ command has no effect under the Gopher protocol, or if the client did
 not send an HTTP/1.0 or later request (though in both cases the command syntax
 is checked).


ΓòÉΓòÉΓòÉ 7.10. RESPONSE command ΓòÉΓòÉΓòÉ

Syntax:

  RESPONSE responseline

Specify an explicit HTTP response (status) line.  This replaces the default
'OK' response generated by GoServe, and should be of the form "HTTP/v.v nnn
description", where 'v.v' refers to the HTTP version, 'nnn' is a 3-digit
response code number, and 'description' is text (for example, the default is
"HTTP/1.0 200 OK").

HTTP only allows certain code numbers to be used, so refer to the HTTP
specification before using this command.  The text should be short, and is
rarely seen, so GoServe will truncate the response line to 100 characters if
necessary.  If RESPONSE is executed more than once, the last-executed command
value is used.

The RESPONSE command has no effect under the Gopher protocol (though the
command syntax is checked).  It also has no effect if the incoming request uses
HTTP/0.9 -- in this case, the protocol does not permit a response line to be
returned, as it would be treated as part of the data.  If used, it must precede
any commands that send data.


ΓòÉΓòÉΓòÉ 7.11. SEND command ΓòÉΓòÉΓòÉ

Syntax:

  SEND [TYPE content-type] [BINARY|TEXT] [AS name]
  SEND COMPLETE [NOWAIT]

SEND and SEND COMPLETE are used to start and end a response which is composed
of more than one piece of data.  The response is started by the SEND command
(without the COMPLETE keyword) and, if using HTTP, the HTTP header is sent at
that point.

After a SEND command, the completion commands (FILE, VAR, STRING, etc.) no
longer cause the response to be completed, nor do they have any HTML wrapper or
HTTP header, etc., added.  Instead, the plain data generated by the command (or
the response to CLOSE or CONTROL, or nothing for NODATA) is sent to the client.

Following any data commands, SEND COMPLETE is used to indicate that the
response is complete, and will write a 'C' audit line if the appropriate
auditing is in effect (see "The audit mechanism").  The NOWAIT keyword may be
used on SEND COMPLETE to force the current connection to be closed after any
response is sent, even if a persistent connection had been requested.

SET NETBUFFER can be used to control whether data are buffered (collected into
packets) before being sent or are sent immediately. NETBUFFER is ON by default.

The optional keywords on the SEND command to start the response may be
specified in any order, and have the following effects:

     TYPE -- [HTTP protocol only] the data will be prefixed by an HTTP "OK"
      response line and an HTTP header.  The value of the TYPE option
      ('content-type') should be a Internet Media Type such as "text/html" or
      "image/gif", of up to 120 characters and with no embedded spaces. See the
      notes under "FILE command" for more information.

      The TYPE option may only be used if GoServe is started with the HTTP
      parameter (HTTP headers are not used by Gopher), and should normally
      always be used when running as a Web server.

     BINARY -- [default for HTTP] the data that follow are to be used 'as-is'.
      A Gopher server should use this option for all data that are not simple
      text or menus.

     TEXT -- [default for Gopher] the data are text.  If running as a Gopher
      server, a Gopher terminator line (just a period) will be sent at the end
      of the document, when SEND COMPLETE is executed.

     AS -- the 'name' given should be used in the audit file when SEND
      COMPLETE is executed.  This can be used to create a more meaningful audit
      record.  The 'name' must be a single word (no embedded blanks) of up to
      50 characters.

 Here is an example of returning an HTML document to a Web client, including a
 file in the middle.

    /* This is Rexx code */
    'send type text/html as MultiDoc'
    'string <!doctype html public "-//IETF//DTD HTML 2.0//EN">'
    'string <html><head><title>Multiple...</title></head>'
    'string <body><h2>Here is a test file:</h2><hr>'
    'file name test.dat'
    'string <hr></body></html>'
    'send complete'               /* complete and audit the send */

 See GOFILTER.80 for an example of a more dynamic document, in the DOPUSH
 function.

 Notes:

   1. All data sent to a client with an HTTP header should be described by a
      Content-Type field in the header; GoServe will therefore only generate a
      header automatically if the TYPE option was specified or the HEADER
      command has been used to add header lines.  In this latter case, it is
      the responsibility of the filter to supply the Content-Type field if the
      TYPE option was not used.

   2. The TYPE and AS options are associated with the SEND command, not the
      included data (as the header is sent immediately).  Therefore, TYPE and
      AS are not allowed on the FILE or VAR commands once SEND has been used.

   3. BINARY and TEXT are, however, permitted on FILE and VAR after a SEND (for
      example, a file included may be a text file with a trailing DOS
      end-of-file character, and another might be binary). A gopher server will
      add a terminating period line only if the most recent specification was
      TEXT (on SEND, FILE, or VAR).

   4. A 'C' audit line indicates normal completion (see "The audit mechanism"),
      and once SEND has been used it is only written when SEND COMPLETE is
      executed.  If no SEND COMPLETE is executed. GoServe will close the
      connection automatically, but no 'C' audit line will be written.


ΓòÉΓòÉΓòÉ 7.12. SET command ΓòÉΓòÉΓòÉ

Syntax:

  SET item newvalue

Changes the state of various GoServe settings.  'item' is one of the listed
keywords.  The value of any item that can be set by the SET command can also be
queried using the QUERY command, or obtained by a Rexx filter using the EXTRACT
command.

Flags (items that are either ON or OFF) can also be set to INVERT, which
changes the state of the flag from ON to OFF or vice versa.

Valid items are:

     AUDITACCEPT -- Audit accepted connections [ON/OFF].  See "The audit
      mechanism" for more details on this and the other audit settings.

     AUDITCOMPLETE -- Audit completed connections [ON/OFF].

     AUDITERROR -- Audit errors (for example, in commands) [ON/OFF].

     AUDITFAIL -- Audit errors that stop the server [ON/OFF].

     AUDITGMT -- Use GMT in the audit file [ON/OFF].  This may only be set ON
      if GMT is available (that is, GMTSET is ON).

     AUDITINFO -- Audit informational lines, such as statistics [ON/OFF].

     AUDITLAZY -- Lazy audit, for fewer writes to the audit file [ON/OFF].

     AUDITLIMIT -- Audit limits lines, when transactions are halted due to a
      timeout, an incoming data limit exceeded, or maxmium clients exceeded.
      The latter is only audited once for each non-idle burst of connections
      [ON/OFF].

     AUDITSELECT -- Audit selectors (this is the request string, as is passed
      as the second argument to the filter) [ON/OFF].

     AUDITUSER -- Audit user audit lines, from the AUDIT command [ON/OFF].

     DATADIR -- data directory name (path).  This must be a path (including a
      drive specification) that refers to an existing directory.  When changed,
      this takes effect immediately; that is, subsequent calls to the DATADIR
      function (or the use of QUERY DATADIR or EXTRACT DATADIR) in this and
      other transactions will return the new directory information.

     DIAG -- diagnostic tracing [ON/OFF].

     DIAG2 -- verbose diagnostic tracing [ON/OFF].

     DIAGMSG -- diagnostic PM message tracing [ON/OFF].

     FASTFILE -- file command cache enable [ON/OFF].  When ON, the file
      command cache is active (see "File command cache").

     FASTFILTER -- file command cache filter control [ON/OFF].  When ON, the
      GoServe filter will be called even if a cached FILE command was used (see
      "File command cache").

     FILTER -- the name of the Rexx filter.  This must be a filename with no
      path referring to a file in the GoServe working directory; a default
      extension of PORT will be added if needed.  When changed, the new filter
      will be used for subsequent transactions.

     HIDDEN -- main window state [ON/OFF].  If HIDDEN is changed from OFF to
      ON, the GoServe main window is minimized.  If changed from ON to OFF, the
      main window is restored and surfaced.

     LIMITBODY -- maximum size (in thousands of bytes) of body data that will
      be accepted [0 through 1E+6].

     LIMITCLIENTS -- maximum number of client connections allowed concurrently
      [1 through 1E+6].

     LIMITFILES -- maximum number of open files allowed, per client connection
      [1 through 100].

     LIMITHEADER -- maximum size (in thousands of bytes) of header data that
      will be accepted [1 through 1E+6].

     LIMITSTARTWAIT -- maximum time, in seconds, for which GoServe will wait
      on startup for TCP/IP to become operational, while retrying appropriate
      TCP/IP calls as necessary [0 through 1E+9].

     LIMITTIMEINACTIVE -- maximum time, in seconds, for which GoServe will
      allow a client to remain connected but inactive (that is, without sending
      or reading data) [0 through LIMITTIMETOTAL].

     LIMITTIMETOTAL -- maximum time, in seconds, for which GoServe will allow
      a client to remain connected, even if active [LIMITTIMEINACTIVE through
      1E+9].

     LIMITTIMEWAIT -- maximum time, in seconds, for which GoServe will keep a
      client connection open waiting for a new request after the client has
      sent a 'Connection: keep-alive' header with the previous request [0
      through 1E+9].

     LIMITWARNING -- the percentage of maximum clients over which the GoServe
      main window bar chart will show a visible warning [0 through 100].

     MENUBAR -- show menu bar on GoServe main window [ON/OFF].

     NETBUFFER -- turns network buffering on or off for the current
      transaction (the default is ON); see "SEND command" for more details
      [ON/OFF].  Currently, SET NETBUFFER may be used to change the setting
      only once per transaction.

     RESPONSEGOAL -- sets the response time goal, in seconds.  This affects
      the coloring of the response time graph, etc. [0 through 1.000].

     RESPONSEGOALSHOW -- if set, the response time shown on the GoServe main
      window will be colored green if it is less than or equal to RESPONSEGOAL,
      yellow/orange if less than or equal to twice that, or red otherwise
      [ON/OFF].

     SOUNDS -- audible indication of incoming connections [ON/OFF].

     SOUNDALL -- sounds for all connections.  If ON, give audible indication
      of all incoming connections; if OFF, only indicate when leaving the idle
      state.  The SOUNDS setting must be ON for any sounds to be generated.

     SURFACE -- surface GoServe main window on startup [ON/OFF].

     TRACE -- copy audit lines to PMprint window [ON/OFF].

     TEST -- enable test or experimental functions [ON/OFF].


ΓòÉΓòÉΓòÉ 7.13. STRING command ΓòÉΓòÉΓòÉ

Syntax:

  STRING string

The single string is returned to the client, with suitable preamble and
termination, depending on the protocol being used.

The STRING command can be used to return a simple message to the client.
Multiple lines can be sent, if necessary, by embedding a CR-LF sequence
('0d0a'x) to separate lines.  A CR-LF is not needed at the end of the string,
as CR-LF is always added by the STRING command.

After this command has ended, the connection to the client is closed, so this
is a completion command.


ΓòÉΓòÉΓòÉ 7.14. VAR command ΓòÉΓòÉΓòÉ

Syntax:

  VAR [NOWAIT] [TYPE content-type] [BINARY|TEXT] [AS name] NAME varname

The contents of the Rexx variable named by 'varname' will be sent to the
client.  'varname' is a symbolic name, as it would be written in the filter,
and should be no more than 50 characters long.  The variable named must have
been assigned a value, or an error will be returned.

After this command has ended, the connection to the client is closed, so this
is a completion command.

The optional keywords may be specified, in any order, and have the following
effects:

     NOWAIT -- forces the current connection to be closed after any response
      is sent, even if a persistent connection had been requested.

     TYPE -- [HTTP protocol only] the data will be prefixed by an HTTP "OK"
      response line and an HTTP header, including the length of the variable.
      The value of the TYPE option ('content-type') should be a Internet Media
      Type such as "text/html" or "image/gif", of up to 120 characters and with
      no embedded spaces.  See the notes under "FILE command" for more
      information.

      The TYPE option may only be used if GoServe is started with the HTTP
      parameter (HTTP headers are not used by Gopher), and should normally
      always be used when running as a Web server.

     BINARY -- [default for HTTP] the data are binary, and form the entire
      response to the client.  GoServe will close the TCP/IP connection to
      indicate that all the data have been sent.

      A Gopher server should use this option for all data that are not simple
      text or menus.

     TEXT -- [default for Gopher] the data are text.  If running as a Gopher
      server, a Gopher terminator line (just a period) will be sent at the end
      of the document, before the connection is closed.

     AS -- the 'name' given should be used in the audit file instead of the
      name of the variable.  This can be used to create a more meaningful audit
      record when (for example) the variable contains a modified version of a
      file.  The 'name' must be a single word (no embedded blanks) of up to 50
      characters.

 Here are some examples (see also GOREMOTE.80):

   1. Returning an HTML document to a Web client:

                   /* This is Rexx code */
                   doc='<html> .... </html>'          /* may be large */
                   'var type text/html name doc'      /* return the data */
                   return

   2. Returning some binary data to a Web client:

                   /* This is Rexx code */
                   data='001122334455'x               /* may be large, '00'x is OK */
                   'var type application/octet-stream name data'  /* this sends it */
                   return

 Notes:

   1. The filter must be active when the VAR command is executed (or the
      variable will not exist).  Therefore this command cannot be passed back
      to the server by a RETURN instruction for later execution.

   2. All data sent to a client with an HTTP header should be described by a
      Content-Type field in the header; GoServe will therefore only generate a
      header automatically if the TYPE option was specified or the HEADER
      command has been used to add header lines.  In this latter case, it is
      the responsibility of the filter to supply the Content-Type field if the
      TYPE option was not used.


ΓòÉΓòÉΓòÉ 7.15. WAIT command ΓòÉΓòÉΓòÉ

Syntax:

  WAIT SECONDS time

The WAIT SECONDS command may be used to pause a transaction for up to
999999.999 seconds.  'time' is the wait time in seconds; it may have a decimal
part of up to three digits.

If a limit (such as a timeout) is exceeded during a WAIT, the command will
return immediately.  Except in this case, WAIT will not return without error in
less than the requested time, but may take longer if some other activity on the
computer delays it.


ΓòÉΓòÉΓòÉ 8. Command return codes ΓòÉΓòÉΓòÉ

When commands end, they report any errors or failures by setting the Rexx
variable RC.  A value of zero indicates normal execution (no error or failure
was found), a positive value indicates an error, and a negative value a
failure.  All command errors and failures are audited with audit type 'E' (if
auditing of errors is enabled).

The possible values for command return codes follow.

Errors

Failures


ΓòÉΓòÉΓòÉ 8.1. --- Errors --- ΓòÉΓòÉΓòÉ

Errors indicate that the command was in error (perhaps a syntax error) or the
data it processed was in error.  The following errors may occur:

 [11]      Response already completed
 [12]      Command not allowed now
 [21]      Missing keyword in command
 [22]      Bad keyword in command
 [23]      Bad value in command
 [24]      Junk on end of command
 [25]      Header key not found
 [26]      Unknown SET/QUERY/EXTRACT item
 [31]      Unable to open file
 [32]      Unable to read file
 [33]      Unable to write file
 [34]      Unable to write audit
 [40]      Bad variable name
 [41]      Could not set variable
 [42]      Could not get variable
 [50]      Missing Content-Length
 [51]      Bad Content-Length
 [52]      Zero Content-Length
 [53]      Multiple READ BODY requested


ΓòÉΓòÉΓòÉ 8.2. --- Failures --- ΓòÉΓòÉΓòÉ

Failures are indicated when a command encounters an unexpected or serious
condition, such as a failure of the TCP/IP network or some limit being
exceeded.  The following failures may be reported:

 [-1]      Inactive timeout exceeded
 [-2]      Total timeout exceeded
 [-3]      Header bytes limit exceeded
 [-4]      Body bytes limit exceeded
 [-5]      Out of memory
 [-6]      Failure reading from network
 [-7]      Failure sending to network
 [-8]      Unknown command


ΓòÉΓòÉΓòÉ 9. Filter functions ΓòÉΓòÉΓòÉ

In addition to GoServe commands, filters may use certain routines provided by
GoServe.  These may be invoked either as functions or by the CALL instruction,
and are listed in the following sections.


ΓòÉΓòÉΓòÉ 9.1. CACHED function ΓòÉΓòÉΓòÉ

Syntax:

  CACHED([option])

This returns information about any previous cached command.  If 'option' is
omitted or begins with the character 'N' (either case) then this returns '1' if
a cached FILE command was executed for the current request before the filter
was invoked, or '0' otherwise.

If 'option' begins with the character 'R' (either case) then this returns the
returncode from the cached command that was executed, or zero if none was
executed (cached()=0).  For example:

  say cached() cached('rc')

might display "1 31" if the cached command failed to find the file.


ΓòÉΓòÉΓòÉ 9.2. CLIENTNAME function ΓòÉΓòÉΓòÉ

Syntax:

  CLIENTNAME()

This returns the primary host name of the client (for example,
'roman.therenet.org'), or if that should not be available, the name in numeric
form (e.g., 12.34.56.78).

Note that determining the client name may involve a significant delay while the
network is asked to resolve it.  To minimize response time to the user, it is
best to ask for the client name after sending the response data.  Note also
that the client name will not be that of the user agent if the user connects
through a 'proxy' server or firewall.


ΓòÉΓòÉΓòÉ 9.3. COMPLETED function ΓòÉΓòÉΓòÉ

Syntax:

  COMPLETED()

This returns '1' if a completion command that closed the connection to the
client has already been executed successfully during this transaction, or '0'
otherwise.


ΓòÉΓòÉΓòÉ 9.4. DATADIR function ΓòÉΓòÉΓòÉ

Syntax:

  DATADIR()

This returns the data directory name (e.g., 'd:/gohttp/') set up by using the
DATADIR option when starting GoServe or by using the DataDir options page.
(Once changed, GoServe records the data directory associated with each port.)

The directory name will always end in a '/', and will use '/' as the directory
separator, "URI-style".


ΓòÉΓòÉΓòÉ 9.5. EXTRACT function ΓòÉΓòÉΓòÉ

Syntax:

  EXTRACT(item)

This returns the value of a GoServe setting.  'item' should be a single word,
which could be used as an item in the EXTRACT (or QUERY) commands. The value of
the item is returned (instead of setting a variable of the same name, as with
the EXTRACT command).  If the item is not a single word or is not a known
GoServe setting, then it is returned unchanged.


ΓòÉΓòÉΓòÉ 9.6. GMTOFFSET function ΓòÉΓòÉΓòÉ

Syntax:

  GMTOFFSET()

This returns the current offset from Greenwich Mean Time (GMT), in seconds.  A
positive result indicates that your local time is ahead of GMT by that amount.

If GMT cannot be computed because the TZ environment variable was not set, the
function returns a question mark (the character '?').  See "Setting the TZ
environment variable" for more information.


ΓòÉΓòÉΓòÉ 9.7. PACKUR function ΓòÉΓòÉΓòÉ

Syntax:

  PACKUR(string)

Takes a single string, expressed according to the Universal Resource (UR)
specification (RFC 1630), as an argument and returns a packed string.  That is,
hexadecimal escape sequences (such as '%7E') are reduced to the character
encoding that they represent (in this case, '~').

PACKUR is especially useful for processing the incoming data from a form, in
which UR encoding is used.  See the sample GOFILTER.80 for an example of this
use.


ΓòÉΓòÉΓòÉ 9.8. PACK64 function ΓòÉΓòÉΓòÉ

Syntax:

  PACK64(string)

Takes a single string, expressed according to the MIME "Base64" specification
(in RFC 1521), as an argument and returns the decoded (packed) string.  Each
four bytes in 'string' is packed to three bytes in the result (except possibly
for the last four bytes); 'string' must be a multiple of 4 bytes.  If any
deviation from these specifications (or from the RFC 1521 "Base64" character
set) is found, the null string is returned.

PACK64 is useful for processing the incoming user/password data encoded for the
HTTP 'basic access authentication scheme' -- see the HTTP documentation for
details.


ΓòÉΓòÉΓòÉ 9.9. REQFIELD function ΓòÉΓòÉΓòÉ

Syntax:

  REQFIELD(identifier [, count])

Searches the HTTP request header for a line that starts with the specified
identifier, and returns the value for that identifier. Continuations are
included in the value (if the continuation was indicated by the tab character,
the tab character is replaced with a space).

The identifier may optionally end with a colon, and the search is
case-insensitive.  If no matching identifier is found (or if there is no HTTP
request header), the null string is returned.

The second, optional, argument determines which value is returned if more than
one line starts with the given identifier: if no count is given, the last
matching line is used.  If a count is given, then it identifies which of the
values is to be returned.  For example,

  reqfield("accept", 3)

would return the value of the third 'Accept:' line in the header (perhaps
"text/html"); if there was no third 'Accept:' line, then the null string would
be returned.


ΓòÉΓòÉΓòÉ 9.10. SERVER function ΓòÉΓòÉΓòÉ

Syntax:

  SERVER([option])

This returns the name of the server software.  If 'option' is omitted or begins
with the character 'N' (either case) then this is the full name of the server
software, followed by a comma, the word 'version', and the version number of
the server.  For example, 'GoServe for OS/2, version 1.88'.

If 'option' begins with the character 'H' (either case) then the HTTP short
name is returned, for example, 'GoServe/1.88'.  This is the same as the value
returned in the HTTP header field "Server:".


ΓòÉΓòÉΓòÉ 9.11. SERVERNAME function ΓòÉΓòÉΓòÉ

Syntax:

  SERVERNAME()

This returns the primary host name of the server (for example,
'fred.mynet.org'), or if that should not be available, the name in numeric form
(e.g., 12.34.56.78).

If the latter case, your TCP/IP installation probably needs adjustment. For
example, if running in loopback mode and not on a real network, your HOSTS file
in TCPIP\ETC should contain your host name.  Check also to see what your TCP/IP
HOSTNAME command (from an OS/2 prompt) returns; again, it should be a full
symbolic name (not the numeric form).  (This may not work on Warp Connect.)

Note that determining the server name may involve a significant delay if the
network has to be asked to resolve it.  It may vary from transaction to
transaction if multiple networks are connected to the server.


ΓòÉΓòÉΓòÉ 10. Running GoServe ΓòÉΓòÉΓòÉ

GoServe may be started in any of the usual ways, such as from an OS/2 command
line or from a Program Reference object.  You should always specify the
protocol to be used (HTTP or GOPHER) as a parameter to the command.  GoServe
defaults to the Gopher protocol at present.

This section describes first the user interface to GoServe, and then details
the parameters that may be used when starting GoServe.


ΓòÉΓòÉΓòÉ 10.1. The GoServe window ΓòÉΓòÉΓòÉ

Once GoServe has started, a PM window should appear.  By default, a menu bar is
displayed giving access to the 'Options' notebook and an 'Actions' drop-down
menu.  Access to these is also provided at all times by a pop-up menu if you
click on the window with the context menu mouse button (usually button 2).

To change the background color of the window, select the color of your choice
from the OS/2 color palette, drag it to the GoServe window, and drop it.  The
color should change immediately.

The window is used to display a summary of the current and past activity of
GoServe.  If it is large enough, it will include at the top a bar display that
shows any client activity (the full width of the bar corresponds to the maximum
number of clients allowed).  A half-height grey bar indicates the peak activity
seen since GoServe was started. This may be reset to zero by selecting 'Reset
peak indicator' from the Actions menu, and will be shown in purple if any
errors have been counted.  The second line of the window gives the total number
of transactions (connections) initiated since GoServe started, and the average
response time of the last 100 transactions.  The color of this number changes
to indicate whether the response time goal is being attained; you can change
the goal (or turn off the coloring in the main window) using the 'Response'
page of the Options notebook.  The response time is replaced by a count of
limits exceeded, or a count of errors, if any of these have occurred.

If room, the second line shows on the right the instantaneous count of
connected clients and the peak number recorded since GoServe started (if more
than one).

The transaction count may be reset to zero by selecting 'Reset transaction
count' from the Actions menu).  Similarly, the response time record, error
count, limits count, and peak count may also be reset to zero.

The third line shows the number of bytes, thousands of bytes, or millions of
bytes sent and received since GoServe started.  These counts may be reset to
zero by selecting 'Reset byte counts' from the Actions menu.  The Actions menu
also offers 'Reset all counts', which resets all of the counters.

The fourth line of the window displays two timestamps; on the left is shown the
time when GoServe last entered the 'idle' state (that is, was waiting for
clients).  On the right is the time when GoServe was started (or when the last
'Reset All' was done).

Some or all of these items will be omitted if the window is too small for
satisfactory display.


ΓòÉΓòÉΓòÉ 10.2. The Options notebook ΓòÉΓòÉΓòÉ

If 'Options' is selected from the menu bar or pop-up menu, the Options notebook
is opened.  This has the following pages:

   1. 'Response' shows response time statistics, and lets you control the
      display and coloring of the statistics.

      At the top of the page, a bar chart shows the distribution of the
      response times for recent requests, and (if there have been any requests)
      the average response time.  This bar chart is redrawn automatically
      whenever the number of connections returns to idle, or you can refresh it
      manually by clicking on (selecting) the chart.

      You can change the time-scale of this chart using the buttons at the
      bottom right of the box.  Any measurements that would be "off-scale" (to
      the right of the chart) are included in the bar at the far right of the
      chart.

      The lower part of the page lets you set a response time goal using a
      slider control; responses made within the specified time are displayed on
      the bar chart in green; responses made within twice that time are shown
      in an orangey-brown, and responses outside that limit are shown in a
      medium-dark red.  The exact colors used will depend on your display.

      The average response time shown on the page is colored according to the
      the same rules, as is the less precise average response time shown on the
      main window, if 'Color on main window' is checked.

      See "Response time recording" for more details.

   2. 'General' lets you change certain aspects of the appearance of the main
      window, and control sounds made by the server.

      Two 'Main Window' check-boxes are provided:

          'Show menu bar' controls whether the menu bar is included in the
           display.  To make menu selections when there is no menu bar, click
           anywhere on the GoServe window with the context menu button, in the
           usual Workplace Shell manner (this works even if the menu bar is
           visible).

          'Surface on startup' lets you choose whether GoServe surfaces its
           window when started (if not minimized when shut down).

      The 'Sounds on connections' checkbox requests that sounds be made (using
      the PC speaker) when a client browser connects to the server.  Radio
      buttons let you choose whether to hear a note (on an ascending scale,
      depending on the number of connections) for every connection, or to hear
      a note only when the server moves from being idle to being busy (one or
      more connections).

      The 'File command cache' controls are used for a performance
      optimization.  See "File command cache" for details before using this
      option.

   3. 'Audit' lets you control the auditing of transactions (which events are
      to be audited, whether timestamps in the file are in local time or GMT,
      and how frequently the audit file is to be written). See "The audit
      mechanism" for more details.

   4. 'Limits' (two pages) is used to control the operating limits of the
      server.  See "The Limits options pages" for details.

   5. 'DataDir' lets you specify a new data directory name (path).  This name
      is made available to the Rexx filter via the DataDir() function, and may
      be used by the filter to find the data to be served.  (But note that the
      filter may ignore this information, if appropriate.)

      GoServe will convert backslashes ('\') in the name to URI form (forward
      slashes, '/'), and will add a trailing '/' if one is not present.  For
      example, entering 'd:\myhome' would result in the directory specification
      'd:/myhome/' being passed to the filter via the DATADIR() function.  This
      page checks that a drive is specified so it is not accidentally omitted.

   6. 'Filter' lets you specify a new filter name.  This must be a simple
      filename and extension (the extension will default to the port number, if
      omitted).

      The filter must be in the GoServe working (current) directory, so no
      drive or directory path should be specified.  For example, if you enter
      'myfilter.80', this would result in the filter 'd:\goserve\myfilter.80'
      being used, if 'd:\goserve' is the working directory.  The filter must
      exist in the GoServe working directory in order for a new name to be
      accepted.


ΓòÉΓòÉΓòÉ 10.3. --- The Apply button --- ΓòÉΓòÉΓòÉ

The 'Limits', 'DataDir', and 'Filter' pages let you choose when to apply the
change or changes that you make, by clicking on the 'Apply' button (or pressing
the Enter key).  The Apply button is only enabled when you have made a change
and all fields on the page are valid.  If you leave a page (or close the
notebook) when the Apply button is enabled, the changes will be applied
automatically at that time.


ΓòÉΓòÉΓòÉ 10.4. The Limits options pages ΓòÉΓòÉΓòÉ

The 'Limits' pages in the Options notebook let you change various limits which
apply to running GoServe.  The limits are grouped into three sets: limits
affecting clients, timeouts, and (on the second page) limits restricting
incoming data.


ΓòÉΓòÉΓòÉ 10.5. --- Clients limits --- ΓòÉΓòÉΓòÉ

The 'Clients' set has three limits:

   1. 'Maximum at once' -- the maximum number of client connections allowed
      concurrently [default 20].  Additional requests for connection will be
      refused.  This count lets you limit the maximum load on your server,
      which is especially useful if it is also being used as a personal
      workstation.  Note that some Web clients, such as Web Explorer, may make
      four or more connections at the same time, to download inline graphics in
      parallel.

      This limit, when exceeded, is only counted and audited once for each
      non-idle burst of connections.

   2. 'Show warning at' -- the percentage at which the bar chart will show a
      red warning indicator [default 75%].  This gives a visual indication of
      heavy use of your server at a given instant (the peak use is also shown
      on the bar display).

   3. 'Open files per client' -- the maximum number of open files allowed, per
      client filter [default 5].  Increase this if you expect your GoServe
      filter to have more than five files open at a time.


ΓòÉΓòÉΓòÉ 10.6. --- Timeouts --- ΓòÉΓòÉΓòÉ

The 'Timeouts' set has four limits; the first two timeout settings control the
time at which any uncompleted response may be terminated automatically by
GoServe's "watchdog" thread, the third controls how long GoServe will wait (if
requested) for additional requests on a persistent connection, and the last
determines how long GoServe will wait, on startup, for TCP/IP to become
available:

   1. 'End client after inactive' -- the "inactive timeout", in seconds. A
      connection will be closed if the specified time passes without any data
      being received or transmitted over the connection.  The default is 60
      seconds.

   2. 'End client after total' -- the "total timeout", in seconds.  A
      connection will be closed if the specified time passes since the client
      connected to the port, even if there appears to be activity. This value
      must not be less than the inactive timeout, and defaults to 1200 seconds.
      As a rule of thumb, this timeout might be set to a number of seconds
      equal to or larger than the size of your largest data file, expressed in
      kilobytes.  This allows for transmission of the file over a slow link
      running at one kilobyte per second.  Multiply this by three or four if
      network delays are common.

   3. 'Connection maintain' -- the "wait timeout", in seconds.  This is is the
      time for which GoServe will wait for a new request after responding to a
      request that included a 'Connection: keep-alive' header.  Note that
      expiry of this timeout, when a request is not received, is considered
      normal; it is therefore not audited as a limit exceeded or an error.

      The default is 0 seconds, which means that GoServe will never accept more
      than one request per connection.  To accept multiple requests per
      connection, set this to a non-zero value.  Suggested values might be
      10-15 seconds (to handle most cases of embedded images in HTML pages, for
      example) or 60-120 seconds (to handle most cases of multiple pages being
      requested by the same client).

   4. 'Wait for TCP/IP start' -- the "start timeout", in seconds.  This is the
      time for which GoServe will wait on startup for TCP/IP to become
      operational, while retrying appropriate TCP/IP calls as necessary
      [default 600 seconds].  This allows asynchronous starting of TCP/IP and
      GoServe.  A value of 0 seconds means immediate timeout (that is, no
      retrys are performed, and GoServe will not start if an error is found).
      No TCP/IP retry is attempted if the requested port is in use (that is, it
      is likely that another copy of GoServe is already running).

 Notes on timeouts:

   1. For the first two timeouts, a value of zero seconds may be specified to
      indicate an indefinite time (that is, the timeout check is not made).
      You should only set both timeouts to zero if the filter is trusted, the
      data it accesses is always available locally, and all clients used with
      the server have a timeout mechanism.

   2. Also for the first two timeouts, when the timeout takes place there may
      be some delay (typically up to 10 seconds) before the transaction is
      interrupted.  If the Rexx filter is still running, it will have the HALT
      condition raised during this process; the HALT condition may be trapped
      by CALL ON HALT or SIGNAL ON HALT for necessary cleanup which should
      normally be followed by an immediate EXIT.


ΓòÉΓòÉΓòÉ 10.7. --- Incoming data --- ΓòÉΓòÉΓòÉ

The 'Incoming data' set is on the second Limits page (use the rightmost button
at the bottom of the first page, or Alt+Page Down, to get to it). It has two
limits which restrict how much incoming data will be accepted by the server
(per request):

   1. 'Header size' -- the maximum size (in thousands of bytes) of header that
      will be accepted in one request.  The transaction will be ended if a
      header is received that exceeds the specified size; this gives some
      protection against a client that sends an invalid or never-ending header.
      This limit is used whenever a header is read, either automatically or
      because of the READ command.  The default is 10 thousand bytes (10kB).

   2. 'Body data size' -- the maximum size (in thousands of bytes) of body data
      that will be accepted in one request.  The transaction will be ended if a
      client sends data that exceeds the specified size, and an attempt is made
      to read it using the READ command. The default is 50 thousand bytes
      (50kB).


ΓòÉΓòÉΓòÉ 10.8. Parameters on the GoServe command ΓòÉΓòÉΓòÉ

Keyword parameters may be used when starting GoServe to set the protocol (one
only) and the TCP/IP port used, the default data directory, the action taken
after a serious failure, and reuse of a port.  They may be specified in any
order:

     The 'HTTP' parameter

      This indicates that GoServe is being used as a World Wide Web server,
      using the Hypertext Transfer Protocol (HTTP).  When this is specified,
      the default port number is 80, the well-known port for HTTP (this may be
      overridden as usual by the PORT parameter), and other enhancements are
      enabled, including:

        -  The TYPE option may (and should) be used on FILE responses from the
           filter.

        -  Automatic processing of both incoming and outgoing HTTP headers is
           enabled (see "Automatic HTTP processing").

        -  Tab characters have no special significance in request strings; the
           third argument passed to the filter is a 'clean' URI (see "Filter
           programs").

        -  STRING and CONTROL command responses are returned as HTML documents.

     The 'GOPHER' parameter

      This indicates that GoServe is being used as a Gopher server, using the
      Gopher Protocol.  When this is specified, the default port number is 70,
      the well-known port for Gopher (this may be overridden as usual by the
      PORT parameter).  The Gopher termination sequence (a line containing just
      a single '.') is added to TEXT files and STRING and CONTROL responses.

     The 'PORT n' parameter

      The default port number for the selected protocol may be changed for
      special applications by using the PORT parameter when starting GoServe,
      for example:

                  start goserve http port 801

      Servers started with different ports are independent; they use different
      filter programs, and maintain a different collection of options, window
      position information, audit file, etc.

      Note that the port number is used as the required or default file
      extension for some files, such as the filter, programs called from the
      filter, and the audit/log files.  This is so that the files for different
      ports don't conflict when in the same directory. Therefore, if you use
      port numbers greater than 999, you must be sure that the working
      directory for GoServe is on a disk that supports extensions of more than
      three characters (for example, an HPFS disk).

     The 'DATADIR d' parameter

      This sets the data directory name (path) that will be used for this port
      from the word following the keyword DATADIR.  This name will be used
      until the name is changed using the 'DataDir' Options notebook page or by
      starting GoServe with a different DATADIR parameter.  The name should
      normally include the drive on which the data are to be found.

      The data directory name is not used directly by GoServe, but is made
      available to the filter program via the DataDir() function--hence
      allowing one filter to handle different data directories without
      "hard-coding" their names in the filter.

      GoServe will convert backslashes ('\') in the name to URI form (forward
      slashes, '/'), and will add a trailing '/' if one is not present.  For
      example,

                  start goserve http datadir d:\myhome

      would result in the directory specification 'd:/myhome/' being passed to
      the filter via the DATADIR() function.

     The 'FILTER f' parameter

      This sets the filter name that will be used for this port from the word
      following the keyword FILTER.  This name will be used until the name is
      changed using the 'Filter' options notebook page or by starting GoServe
      with a different FILTER parameter.  The filter must be in the GoServe
      working (current) directory, so no drive or directory path should be
      specified.  For example:

                  start goserve http filter myfilter.80

      would result in the filter 'd:\goserve\myfilter.80' being used, if
      'D:\goserve' is the working directory.  If no file extension is specified
      (that is, no period is found in the name), the port will be added as the
      extension.

     The 'QUIETFAIL' parameter

      Certain "catastrophic" errors (such as memory allocation errors, or a
      syntax error in the Rexx filter) are considered failures by GoServe; that
      is, they cause a message dialog to be displayed on the screen--once the
      message is acknowledged, GoServe ends.

      The QUIETFAIL parameter can be used to prevent the failure message dialog
      being displayed:

                  start goserve http quietfail

      In this case, GoServe will end immediately after a failure (after
      attempting to audit the failure, as usual).

     The 'REUSE' parameter

      This allows reuse of the requested port, even if some other application
      (or TCP/IP) has not released it.  TCP/IP may hold on to a port for two or
      three minutes after an application (or GoServe itself) releases it.

 GoServe also accepts some experimental keyword parameters:

     'TRACE' copies audit information to the PMprintf window (without GoServe
      timestamps); this does not affect auditing to the audit file.  This lets
      you watch a trace of incoming requests, actions, and errors as they
      happen without needing to look at the audit file itself.

     'TEST' controls experimental features (such as sending a Message-ID
      header) and also adds an extra Test page to the options notebook. The
      Test features are undefined (that is, they may be removed in future
      versions of GoServe).

     'DIAG' shows TRACE information together with additional details of
      GoServe operation (also using PMprintf).  This diagnostic information is
      intended for development use and may change over time.  If you are
      observing unexpected GoServe behaviour, the DIAG option may show helpful
      information.  'DIAG2' and 'DIAGMSG' may provide even more verbose
      diagnostic information.  'DIAG' implies 'REUSE'.

 Any number of GoServe parameters may be specified, in any order.  If a
 parameter with a value is specified more than once, the last value is used.


ΓòÉΓòÉΓòÉ 10.9. GoServe return codes ΓòÉΓòÉΓòÉ

When GoServe ends, a return code is returned to the caller (for example, when
invoked from a Rexx program, this return code is placed in the Rexx variable
RC).  The value is restricted by the operating environment to be in the range 0
through 255; GoServe uses one of three possible values:

 [0]       Normal completion (user action or OS/2 shutdown).
 [1]       GoServe was ended by the CLOSE filter command.
 [8]       Abnormal completion (failure), such as a syntax error in the filter.


ΓòÉΓòÉΓòÉ 11. Greenwich Mean Time (GMT) ΓòÉΓòÉΓòÉ

The HTTP protocol (like most international networking protocols) requires that
dates and times, where used, be quoted in GMT.  The personal computers on which
OS/2 runs, however, do not require that a GMT clock be available--instead, the
clock is usually set to local time.

Various mechanisms are used in OS/2 to indicate and calculate the current
offset from GMT.  The most common is to use an OS/2 environment variable named
'TZ', and for many people running GoServe this will already be set (for example
to 'EST5EDT' for the USA East Coast).  See the separate section on setting the
value of the TZ variable.

If TZ is not set, GoServe will only use local time (and HTTP protocols and
header fields that require GMT will not be used or generated).

If the TZ variable is set, GoServe will convert from local time to GMT as
appropriate.  It will also detect a clock dislocation (that is, when the
time-of-day clock is changed by more than 10 seconds) automatically, and record
and re-calculate the GMT offset when this occurs--such as when you change your
clock for daylight-savings time.

Notes:

   1. You can see the offset that GoServe has computed by using the CONTROL
      STATISTICS command or the GMTOFFSET() function.

   2. Inevitably, for a few seconds between when you change the time and when
      GoServe detects that it has been changed, incoming transactions may be
      processed with anomalous time data; to avoid this, stop GoServe before
      making large time adjustments and restart it afterwards.

   3. Files in the PC-DOS and OS/2 FAT and HPFS file systems are timestamped
      with the local time of creation or last modification. The time-zone and
      daylight savings regime of that zone (and hence the GMT offset) are not
      available.  GoServe therefore calculates the GMT timestamp of a file by
      using the current GMT offset.

   4. If you are running a machine as a dedicated Web server, you may wish to
      set its clock to GMT and leave it set that way all year; in this case,
      set TZ to 'GMT0'.


ΓòÉΓòÉΓòÉ 12. Response time recording ΓòÉΓòÉΓòÉ

GoServe records the response times of the most recent one hundred completed
requests.

'Response time', here, means the time from when the client connection is
accepted to when the first data bytes are sent for the first request in a
transaction, or (for subsequent requests during a connection) the time from
when the previous request was completed to when the first data bytes are sent
for the current request.

The response time may include the time to receive some or all of the request
data from the client, but excludes any time taken waiting for data to become
available at the server.  It never includes the time taken to send the response
(which may be very large, and dependent on network delays).  Response times of
transactions ended due to a timeout or other limit being exceeded are not
recorded.

The average response time of those recorded, to the nearest 0.01 second, is
shown on the main GoServe window, next to the transactions count (unless an
error has occurred).  A more precise figure, along with the number of
transactions over which it was recorded, is included in the CONTROL STATISTICS
response (this figure will not reflect the response time of the transaction
that initiates the CONTROL STATISTICS command). The same, more precise, figure
is also shown on the 'Response' page of the Options notebook.

The average read wait time (the time taken waiting for data to become available
at the server during response time measurement) is also shown on the CONTROL
STATISTICS result.  The sum of this and the average response time gives the
average total elapsed response time, as observed by the server.

The GoServe response time directly affects the response time seen by the person
using the client browser, so it is desirable to keep this as low as possible;
the 'Response goal' setting in the Options notebook is provided to make it
easier to judge the performance of your server setup.  The read wait times are
not included in response times so that the graph and averages only reflect
delays that are under the control of the server.

The response times record may be reset using CONTROL RESET RESPONSE (or the
Actions menu item 'Reset response times').


ΓòÉΓòÉΓòÉ 13. Automatic HTTP processing ΓòÉΓòÉΓòÉ

GoServe automates several aspects of the HTTP/1.0 protocol. (For full details
of the protocol, please see the HTTP specification.)  When an HTTP/1.0 request
is received, the HTTP header lines are read automatically (if needed).  The
Content-Length and If-Modified-Since values are extracted as appropriate.

When a completion command is processed, GoServe will (if the incoming request
was HTTP/1.0) generate an appropriate response line and HTTP header.  For
example, for a FILE command with a given file TYPE, this will include the
following header lines:

   1. 'Server:'  The name and version of the server (e.g., 'GoServe/1.88').

   2. 'Date:'  The message origination date and time (only if GMT can be
      determined).

   3. 'Message-ID:'  A unique identifier for the message.  For example,
      '<19950101121030.80.123@12.34.56.78>', which is the local date and time
      that the server was started, the port which it is serving, and the
      transaction number, followed by the primary host address.  This header is
      not required by the HTTP protocol, and so is only sent if the GoServe
      TEST parameter is in effect.

   4. 'Content-Type:'  The value set by the TYPE parameter.

   5. 'Content-Length:'  The length of the file (less 1, if TEXT was  specified
      and the file ends in an EOF character).

   6. 'Content-Transfer-Encoding:'  Currently always 'binary'.

   7. 'Expires:'  Set to the current time (only if GMT is available and  ERASE
      was specified on the FILE command).

   8. 'Last-Modified:'  Set to the timestamp of the file, converted to GMT
      (only if GMT is available and ERASE was not specified).

 Finally, GoServe will not actually send the body of the file if the request
 verb was HEAD or (if the verb was not HEAD) if the 'Last-Modified' date is
 older or the same as the first 'If-Modified-Since' date found in the request
 header (if any).  In this latter case, the response line will be 'HTTP/1.0 304
 Not Modified'.

 Notes:

   1. If the response line has been set explicitly by the RESPONSE command,
      this overrides any possible "Not Modified" response, and so the
      'If-Modified-Since' check does not take place (that is, the body of the
      response will be sent).

   2. If the client does not send the header within a short time after the
      request string, the 'If-Modified-Since' check may be bypassed. This
      bypass is to allow for some older clients that are not fully HTTP/1.0
      compliant, and may be removed later.

   3. GoServe supports and automatically generates, where appropriate, the
      experimental 'Connection: keep-alive' headers used for handling multiple
      requests over one connection.  See "Persistent connections" for more
      details.

   4. GoServe does not automatically send a "MIME-Version" header field, as it
      can make no guarantee that the message as a whole is MIME-compliant (and
      in most cases it will not be).

   5. The 'HEADER NOTIME' command may be used to inhibit the sending of the
      'Expires:' or 'Last-Modified:' header lines.

 As described elsewhere, GoServe also supports limited features of the HTTP/1.1
 protocol, though most of the (normally automatic) actions will have to be
 performed by the filter.


ΓòÉΓòÉΓòÉ 14. File command cache ΓòÉΓòÉΓòÉ

GoServe includes an optional performance optimization that may be useful for
heavily loaded servers or for applications where response time is critical.
You should only use this option if (a) you are already allowing access to all
files in your GoServe data directory, as when using the sample filter, or (b)
you have read and understood the remainder of this section.

If the file command cache is made active (by selecting the 'Active' checkbox in
the 'File command cache' box on the 'General' page of the options notebook),
then eligible FILE commands will be associated with the current HTTP or Gopher
request.  If the identical request line is received later, the FILE command
will be executed immediately, without invoking the filter.

This caching avoids the overhead of calling the filter.  For the sample filter,
this is small (less than 15ms on a 486/50MHz PC), but with more complex filters
this can be significant.

Eligible file commands are those which do not specify ERASE or NOCACHE (see
below), do not follow a SEND command, and which are issued in response to an
HTTP GET request or any Gopher request.

Note, however, that if the file command cache is used, there is no filtering of
the request, and so the file will be sent unconditionally (that is, no security
checking will take place, for example). Therefore, if file caching is to be
used, FILE commands referring to sensitive files should be protected by
specifying the NOCACHE option on the command.  This prevents them being cached,
and so requests for those files will always be processed by the filter.

The intent of the file command cache is to minimize the response time to the
client and the load on the server by avoiding the call to the filter.  You may,
however, request that the filter still be called (after the cached FILE command
has been executed) by selecting the 'Call filter anyway' radio button on the
'General' page or by executing 'SET FASTFILTER ON.  This may be useful when
specialized logging is being carried out, for example.  The filter can detect
whether a cached FILE command has already been successfully executed by using
the COMPLETED() function call.


ΓòÉΓòÉΓòÉ 15. The audit mechanism ΓòÉΓòÉΓòÉ

GoServe includes a built-in audit mechanism that records events in an audit
file while GoServe is running.  This maintains a record of usage, and also
records any errors or failures of the server.

By default, all audit information (see details below) except selectors is
recorded.  Choose the 'Audit' page of the Options notebook for detailed control
over which audit information will be written to the audit file.  You should
only select auditing of 'Selectors' if the recording of selectors (request
strings) would not compromise confidentiality or privacy.

The audit file has a fixed filename (GOAUDIT), with an extension that is the
TCP/IP port number used (for example, 'GOAUDIT.80').  It is written in the
working directory for GoServe.  The audit file may be read but not altered
while GoServe is running.

For reliability, the audit file is written directly to disk and not cached by
the file system (though GoServe caches some informational lines briefly to
improve response time).  You can select the 'Lazy audit' option for caching of
up to five seconds, which will improve server throughput under load.

Each line in the audit file starts with three words, separated by one or more
blanks: the time (hhmmss), the audit type (one character), and the transaction
number (a number, incremented for each connection accepted, that begins at 0
when GoServe is started).  Additional information follows, depending on the
audit type:

 A (Accept)       - addresses of the client and (if non-prime) server (n.n.n.n)
 C (Complete)     - response time (seconds), and description of action
 D (Day/Time)     - current day (yyyymmdd), and description of adjustment
 E (Error)        - description of an error in processing (e.g., timeout)
 F (Failure)      - description of the failure (terminating error)
 I (Information)  - description of information (statistics, etc.)
 L (Limit)        - description of limit that has been exceeded
 N (Network)      - description of how network or client ended transaction
 P (Primary)      - primary server address and port (n.n.n.n nn)
 S (Selector)     - selector received from client for each new request
 U (User)         - description of event from User (filter) command

 The 'A' audit line includes the address of the server only if this is
 different from the primary server address shown on the 'P' line.  This may
 occur if more than one network is active (perhaps a real network and a
 loopback configuration, or more than one active network adapter cards).

 The times (and dates) recorded in the audit file may be in GMT (the default)
 or in local time (the default for GoServe 1.41 and earlier). The default may
 be altered using the 'Audit Selection' dialog, but note that use of GMT is
 only possible if GMT times are available (that is, the TZ environment variable
 was set when GoServe was started or when a time dislocation was detected).  If
 GMT is in use, the word 'GMT' is added after the current day on 'D' audit
 lines.

 Additional audit types may be added later.  The format of any "description" in
 the above is not strictly defined, except that all Carriage Return, Line Feed,
 and End of File characters (ASCII '0d'x, '0a'x, and '1a'x) are translated to
 '[', ']' and '#' respectively to ensure audit file lines are well defined.

 For example:

    103701 D 0 19950620 GMT ----- GoServe 2.40 -----
    103701 P 0 9.20.1.20 80
    103726 A 1 9.20.5.59
    103726 S 1 GET / HTTP/1.0
    103727 C 1 0.9 Sent file "d:/gohttp/index.htm" [979 bytes in 0.02s]
    103727 A 2 9.20.5.59
    103727 S 2 GET /pmglobe.gif HTTP/1.0
    103728 C 2 0.95 Sent file "d:/gohttp/pmglobe.gif" [2154 bytes in 0.043s]
    103737 A 3 9.20.5.59
    103737 S 3 GET /globe?22,40 HTTP/1.0
    103738 C 3 0.9 Sent string "You clicked on the globe" [423 bytes in 0.07s]
    103745 A 4 9.20.5.59
    103745 S 4 GET /samptest.htm HTTP/1.0
    103746 C 4 1 Sent file "d:/gohttp/samptest.htm" [664 bytes in 0.012s]
    103750 A 5 9.20.5.59
    103750 S 5 GET /!statistics HTTP/1.0
    103750 C 5 0.8 Sent response "CONTROL STATISTICS" [708 bytes in 0.017s]
    103808 I 5 Bytes sent 4928 received 3045
    103808 I 5 Close

 Most requests will end normally, with a 'C' line in the audit file.  If an
 error occurs, there may be one or more 'E' lines in the audit file instead.
 If a transaction is ended by the client or network, than an 'N' line is used,
 which is not recorded as an error.  Similarly, when a chosen limit is exceeded
 (such as a timeout) an 'L' line is used, which also is not recorded as an
 error.  A persistent-connection timeout is considered an uninteresting event
 and is not audited.

 The response time recorded on 'C' lines is rounded down to the nearest
 millisecond below, and measures the total elapsed time from receiving the
 request to the first send of data to the client.  This excludes any time spent
 waiting for the network, but includes any time taken to receive data from the
 network and so depends on the network as well as the speed of the processor
 and the work done by the filter.  (See also "Response time recording" for more
 details.)

 The 'bytes' count on 'C' lines is the total number of bytes sent to the client
 (including any overhead demanded by the protocol in use), and the time shown
 after the bytes count is the total elapsed time for sending the response
 (rounded down to the nearest millisecond below).  This latter depends on the
 speed and activity of the server, client, and the network between the two.  It
 is likely to be rather variable.


ΓòÉΓòÉΓòÉ 15.1. --- Viewing or archiving the audit file --- ΓòÉΓòÉΓòÉ

To look at an 'active' audit file, use a program or command that allows shared
reading of files.  TYPE is one such command; its output may be redirected to a
file to take a snapshot copy of the audit file.  For example:

  type goaudit.80 > snapshot.log

In addition, the Actions pull down menu has an item 'Move audit to archive'.
This closes the audit file, appends it to the GoServe archive file in the
current working directory, then erases and re-opens the audit file.  The
GoServe filter can also initiate this action, by returning "control
moveaudit"--see "CONTROL command" for details.

The GoServe archive file has a fixed filename (GOARCH), with an extension that
is the TCP/IP port number used (for example, 'GOARCH.80').  It is only touched
by GoServe during a "Move audit to archive", so is readily copied, edited, or
renamed.


ΓòÉΓòÉΓòÉ 16. Remote control of GoServe ΓòÉΓòÉΓòÉ

GoServe filters (see "Filter programs") can request that GoServe perform
certain actions, instead of just returning files or other data.  These requests
may be used to control GoServe remotely (from another machine or from another
process on the same machine).  Control requests can return a document
containing one or more response lines, either showing successful completion of
the request or indicating an error.

Specifically, if the CONTROL command is used without the VAR option (either
from within the filter program or by being returned by the filter) then the
command action is performed and the result string is returned to the client as
a document.

More sophisticated control is possible by using the EXTRACT and SET commands to
inspect and alter a wide variety of GoServe's internal settings.

The sample pages (GOR*.HTM) and the remote control filter (GOREMOTE.80) filters
included in the package use these commands to duplicate the functions available
locally via the Options settings notebook.  All the information and settings
available in the Options notebook (except the response time graph) are
available remotely.

Please note that for the Apply button to work on the remote control settings
pages, you must first provide and enable a password in the "authorize:"
subroutine in the main GOFILTER.80.  See that subroutine for instructions.

The sample main filter also includes examples of using control commands
initiated from standard menus or documents; these actions can be triggered
remotely using a Gopher or Web client, as appropriate.  Rexx programs can also
use the OS/2 TCP/IP RxSock library (included in the UN64092 CSD, August 1994,
and also available from most OS/2 software sources) to send a specific request
to a GoServe server.  A sample command, MOVEAUD.CMD, is included in the GoServe
package as an indication of how this is used.

The filter mechanism provides flexibility in how control requests are accepted
and passed to GoServe, including the possibility of modification so that only
clients with certain addresses would be able to use these options.  The sample
Web filter includes an example of how this might be done, and the sample
GOREMOTE.80 shows a mostly-generic example of forms processing.


ΓòÉΓòÉΓòÉ 17. Persistent connections ΓòÉΓòÉΓòÉ

GoServe 2.41 (and later versions) supports an experimental implementation of
persistent connections (discussed in detail in the HTTP working group mailing
list in July-August 1995, and also in IETF draft form).  In brief, a client may
request (by including the HTTP header 'Connection:' with value 'keep-alive' or
'maintain') that a server not close the connection after sending a response.

The server may choose to ignore this, or it may hold the connection open for a
period of time (typically 15 to 30 seconds), to allow the client to send
further HTTP requests over the same connection.  In the latter case, the client
is informed by the inclusion of a matching 'Connection:' header in the
response.  At any time, the transaction can be concluded by either the client
or server closing the connection or no longer using the 'Connection:' header in
the request or response header.

This persistent connection protocol is handled automatically by GoServe, under
the control of the LIMITTIMEWAIT (connection maintain) setting. This setting
limits the time that GoServe will wait for a new request after being asked to
do so; it may be set to zero to force GoServe to accept only one request per
connection; for the time being, this is the default setting.

Notes:

   1. 'Transactions' in GoServe is a count of connections, not HTTP requests.
      The latter count is available in the CONTROL STATISTICS response (if
      different from the transactions count) or by using QUERY REQUESTS or
      EXTRACT REQUESTS.  The number of requests corresponds to the number of
      'hits' in a World Wide Web context.

   2. Clients connecting to a proxy instead of directly to a server must use
      the 'Proxy-Connection: keep-alive' header instead, if a persistent
      connection is being requested.

   3. Suggested values for LIMITTIMEWAIT might be 15-30 seconds (which would
      handle most cases of embedded images in HTML pages, for example) or
      60-120 seconds (to handle most cases of multiple pages, with their
      embedded images, being requested by the same client).

   4. [Nov95] Current browsers use the value 'keep-alive' rather than
      'maintain' in the connection header (the latter, from the HTTP working
      group, is therefore probably obsolete).  For the time being, GoServe
      supports both values and will respond with the value as received.

   5. Once a connection is being maintained, GoServe will automatically SET
      NETBUFFER OFF, so that all parts of a data stream will be sent to the
      client immediately.

   6. [Apr98] GoServe 2.52 and later versions support the HTTP 1.1 convention:
      connections for an HTTP/1.1 request are assumed persistent, unless a
      'Connection: close' header line is found or LIMITTIMEWAIT is 0.


ΓòÉΓòÉΓòÉ 18. Why not CGI? ΓòÉΓòÉΓòÉ

Many Web servers support a protocol known as the Common Gateway Interface (CGI)
for attaching and supporting scripts.  GoServe does not yet support this
interface directly due to a number of difficulties with the design, of which
the most significant (in no particular order) are:

     The primary means of communicating information to scripts is by the use
      of environment variables.  These all have to be set before the script is
      called, and as the number of these grow the overhead approaches or
      exceeds the cost of interpreting the script (GoServe has dozens of state
      variables available to scripts).

      For GoServe, Rexx variables could be set on startup -- but a clearer and
      more efficient way of retrieving information is to use specialized
      function calls (such as GoServe's REQFIELD) or general commands (such as
      GoServe's EXTRACT, READ, and CONTROL).  With these mechanisms, data are
      moved only when required.

     Environment variables are a per-process resource in OS/2; GoServe's
      scripts run on a per-thread basis (the script runs on the same thread
      that handles the incoming connection, with no process overhead or
      resource cleanup required).

     The piping of the incoming data to the script would often mean that data
      are read even when unused, hence increasing the load on the server (and,
      in some cases, on the network and client browser).

     For some servers, the output sent to the client is dependent on the name
      of the script (for example, scripts whose name begins with "nph-" may
      have their output treated differently from other scripts).  This means
      that arbitrary script names cannot be supported.

     Server directives (commands sent to the server) are sent using the same
      namespace (header lines) as the header information being sent to the
      client.  Separating this information, as in GoServe, leads to a more
      reliable and extensible protocol.

     CGI binary executables are loaded from .EXEs rather than as functions in
      a DLL (which would be at least twenty times faster).

     CGI does not define a channel between the script and the server while the
      script is running.  Hence, dynamic information (such as connections and
      load) known to the server cannot be made available to the script during
      processing.

     Standard output is used as a data channel to the server; this means that
      the only data channel to the user (Webspinner) is standard error, which
      is inappropriate for informative or status information, often used while
      developing scripts.  It also means that data are processed more often
      than needed.

 For these reasons, it seemed unlikely that CGI scripts could be supported with
 acceptable efficiency by GoServe.  GoServe's filters provide equivalent
 function, and the processing logic will be essentially unchanged, so ports of
 the algorithms required are easy.

 If necessary (for example, to use an existing CGI script), the CGI interface
 can be simulated by a GoServe filter.  Porting the script will, however, give
 much better response times in many cases.


ΓòÉΓòÉΓòÉ 19. Setting the TZ environment variable ΓòÉΓòÉΓòÉ

GoServe currently computes GMT from the local time-of-day clock (set by the
TIME and DATE commands) and the setting of the TZ environment variable.  The
simple form of the value of TZ (which is suitable for use in the USA or other
countries that change to and from daylight savings time at the same time as the
USA) is as shown in:

  SET TZ=EST5EDT

where EST is the standard time zone name (this must be exactly three
characters), EDT is the daylight savings time zone name (also exactly three
characters), and 5 is the difference between the standard time zone and GMT,
measured in hours West of GMT.  The second time zone name can be omitted if no
daylight savings adjustment is used.

The format of the GMT offset is

  [+|-]hh[:mm[:ss]]

that is, the sign (and minutes and seconds) are optional.

Note that the sign of the GMT offset used in the TZ variable is opposite to
that used for calculating the local time, given GMT, as returned by the GoServe
GMTOFFSET() function.

The simple form of TZ setting assumes the USA default of 1 hour daylight
savings change which starts at 01:00 on the first Sunday in April, and ends at
02:00 on the last Sunday of October.

For other countries, the full form of the TZ value has to be used.  More
formally, this is:

  SET TZ=SSS[+|-]hh[:mm[:ss]]DDD,sm,sw,sd,st,em,ew,ed,et,shift

Where 'SSS', 'hh', 'mm', 'ss', and 'DDD' are the values as in the simple form.
In the long form, all the other values must be specified, as follows.

'sm', 'sw', 'sd', and 'st' define the start time for daylight savings
adjustment, where:

     'sm' is the starting month (1 to 12)

     'sw' is the starting week (1 to 4 counting from the beginning, or -1 to
      -4 counting from the end).  0 indicates that a particular day of the
      month is to be specified

     'sd' is the starting day (0 to 6 [where 0 is Sunday] if 'sw' is non-zero,
      or 1 to 31 if 'sw' is 0)

     'st' is the starting time in seconds from midnight (e.g., 3600 for
      01:00).
 'em', 'ew', 'ed', and 'et' define the end time for daylight savings, and take
 the same values.

 'shift' is the shift in daylight time change, in seconds (e.g., 3600 if one
 hour is to be added during daylight savings time).

 For example, for the UK in 1997, the setting was:

    SET TZ=GMT0BST,3,0,30,3600,10,0,26,7200,3600

 Note that there appears to be no provision for time zone names of more than
 three characters (blanks are allowed, so fewer than three characters are OK).


ΓòÉΓòÉΓòÉ 20. --- GoHTTP.doc --- ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 20.1. Credits ΓòÉΓòÉΓòÉ

                   How to start using GoServe as a Web server
                   """""""""""""""""""""""""""""""""""""""""""
                                      GoServe 2.52

        Copyright (c) IBM Corporation, 1994, 1997.  All rights reserved.
                       Mike Cowlishaw, IBM UK Laboratories
                                [e-mail]
                                    - - - - -

About


ΓòÉΓòÉΓòÉ 20.2. Introduction ΓòÉΓòÉΓòÉ

'GoServe' is a multi-purpose server for OS/2, which supports the HyperText
Transfer Protocol (HTTP), used by the World-Wide Web (often known as 'the Web'
or 'WWW').

Providing that you already have TCP/IP installed and started, GoServe can be
running and serving documents and other files across a network in minutes.
There are no configuration files to be edited first.

This document describes how to use GoServe as a Web server, and includes
instructions on how to set up your own home page.  GOHTTP.ZIP includes a
working home page and customization filter, together with several other sample
pages.  The GoServe Web documentation is also included, linked to the sample
home page.

Note:  It is assumed that you have some familiarity with the Web, and have (and
know how to use) a Web client, such as Web Explorer.


ΓòÉΓòÉΓòÉ 20.3. Quick start ΓòÉΓòÉΓòÉ

Assuming you have unzipped GOSERV.ZIP into the directory of your choice (for
example, D:\GOSERVE), then:

   1. Open an OS/2 window

   2. Unzip the included file GOHTTP.ZIP to a different directory.  To use the
      default setup, put this 'data directory' on the same drive as the first
      directory, and call it GOHTTP (for example, D:\GOHTTP).

   3. Change your current directory back to the GoServe directory (for example,
      D:\GOSERVE)

   4. Start GoServe with the parameter "http", for example using:

                   start goserve http

 You should then see a GoServe window (titled 'GoServe [HTTP]') appear. If
 there are no error messages, the server is now active, and you should be able
 to connect to the sample pages with any Web browser (available as a separate
 program).  For example, if the name of your machine is "fred.hursley.ibm.com"
 (use the "hostname" command, while connected to your network, to find it out
 if you don't know it) then specifying a URL of "http://fred.hursley.ibm.com/"
 should display the sample home page.


ΓòÉΓòÉΓòÉ 20.3.1. --- Setting up an icon for GoServe --- ΓòÉΓòÉΓòÉ

To set up an icon (program reference object) for a GoServe Web server and
(optionally) ensure that GoServe is started automatically when OS/2 is booted:

   1. With your current directory being the GoServe directory (for example,
      D:\GOSERVE), run the command:

                   makeicon http

      This should make an icon called 'GoServe - Web' appear on the Desktop.
      You can Move or drag it to another folder if you wish. The server can now
      be started by clicking on the new icon (you may want to check that this
      works).

   2. Open the Startup folder (this may be on the Desktop or in the 'OS/2
      System' folder).

   3. Make a shadow of the GoServe icon in the Startup folder.  To do this,
      hold down the Ctrl+Shift keys and then drag the icon to the Startup
      folder, drop it, and release Ctrl+Shift.  (See the OS/2 documentation if
      you need more details.)

 With the shadow in the Startup folder, the server will be started
 automatically whenever OS/2 is booted or rebooted.


ΓòÉΓòÉΓòÉ 20.4. Your own home page ΓòÉΓòÉΓòÉ

The sample filter can be used to serve files such as HTML documents, images,
and so on, without any changes or programming.  All you need to do is change
the data files.

Here's what you need to do to set up your own 'home page', given that the
sample page above works:

   1. Make a new directory for your own World-Wide Web data (for example,
      called D:\WWWHOME).

   2. Copy the file D:\GOHTTP\INDEX.HTM to your new directory, and modify it to
      make your 'home page'.  To start with, to see if it works, it's probably
      best to change a few words only.  For example, change the line

                   Welcome to this sample home page.

      to something different.

      If you leave any references in it to any of the other sample files,
      you'll need to copy those over, too, for the links to work.

   3. If GoServe is not already running, start it as before (don't forget the
      'HTTP' parameter, if starting from a command prompt).

      Choose 'Directory selection' from the 'Options' menu, and use the dialog
      there to change the data directory to be your new directory (for example,
      to D:\WWWHOME).

   4. Try your favourite WWW client, connecting to your machine as before, and
      it should now display your new home page.

   5. All you have to do now is modify the home page to your liking. Most of
      the tags needed (<h1> indicates Header level 1, etc.) are quite simple to
      use, but you'll probably want to find an introduction to the tag language
      (HTML, the HyperText Markup Language).  A good place to start is the Web
      "home" at CERN: http://info.cern.ch/

 All of the details above can be customized if you wish, but you will probably
 need to learn more about GoServe and Rexx to change things effectively.
 Please see GOSERVE.DOC for more information.

 This document, the latest GoServe package, and other relevant links,
 information, and programs are available at the GoServe Web page at
 http://www2.hursley.ibm.com/goserve/


ΓòÉΓòÉΓòÉ 20.5. An overview on how GoServe works ΓòÉΓòÉΓòÉ

(To make sense of this, you may need to read GOSERVE.DOC too.)

Whenever a client connects to your machine, it sends a 'request string'.
GoServe receives the string and passes it to a 'filter'.  This filter (a
program, written in Rexx) checks that the request is valid, and normally
responds with a file (such as an HTML document or a GIF image file).  It is the
filter's responsibility to choose or create the file, given the incoming
request string.

A sample filter (GoFilter.80) is provided--see commentary in that program for
details.  In brief, it asks the server for the name of the data directory,
checks for certain errors, and then processes the request according to the verb
(method) specified in the request.  Notes:

   1. The sample filter gets the root, or home, directory for the data it is to
      serve by calling the DATADIR() function.  The value this returns is set
      by GoServe (which, in turn, is derived from the GoServe startup parameter
      or the Directory Selection dialog).

   2. Only the most common verbs are handled by the sample filter:

          GET is the most common ('send me some data') request.  In most
           cases, this sends back a file to the client, using the GoServe FILE
           command.

          HEAD is the same as GET, except that the data are not sent back to
           the client.  GoServe automatically ensures that only 'header' lines,
           which describe the data, are sent.  HTTP requires that all servers
           handle both GET and HEAD verbs.

          POST is used by a client when data are to be sent to the server (for
           example, text filled in for a Form, or a "post" to a newsgroup).
           When the data is known to be short (fewer than 250 characters), GET
           may be used instead; the specification of which method to use is
           included in the <form ...> tag of the source document.

   3. A default document is provided if none is specified. Conventionally, this
      is called 'index.htm' or 'index.html'; a sample 'index.htm' is provided
      (you can rename this to 'index.html' if you are using an HPFS disk).

   4. The TYPE option, where specified on a FILE response, indicates that the
      server should prefix an HTTP 'OK' response and header to the beginning of
      the file returned.  The TYPE option is followed by the MIME type (e.g.,
      text/html or image/gif) of the file being returned.  Web servers should
      normally always specify a TYPE on a FILE command.

   5. Requests should be specified in URI form in that forward slashes should
      be used instead of backslashes to indicate directories.  For example,
      with the sample setup, the tag <a href="fred/%7Edata.htm"> would cause
      the filter to receive the URI '/fred/%7Edata.htm'.  The packed URI (third
      argument string) would then be 'fred/~data.htm'. The filter then prefixes
      the home directory name, resulting in a file specification such as
      'd:/gohttp/fred/~data.htm'.  This would refer to the OS/2 file
      'd:\gohttp\fred\~data.htm'.  GoServe (actually the OS/2 I/O routines)
      will make the appropriate '/' to '\' adjustments.

   6. Errors are signalled to the client by sending back files that start with
      the appropriate HTTP header line; these are generated by an internal
      subroutine, which can be modified for more detailed or personal error
      messages.  This subroutine could be made external if the TEMPFILE value
      is passed as an argument when it is called.

   7. The sample 'globemap' routine shows how the coordinates of a click on an
      active image can be processed.  This particular routine returns the
      coordinates as a percentage of half the image size, relative to the
      middle and with map-style coordinates (X is positive to the East, Y is
      positive to the North).

   8. Certain special 'test and control' requests are supported by the sample
      filter (for example, return server statistics).  In the sample filter,
      these are only allowed from a client with the same address as the server.
      Other possibilities include allowing 'ANY' as the allowed name [so anyone
      can use them], or, conversely, using a privately-selected URL for the
      controls--which would act as a password.  See GOSERVE.DOC for more
      information on control options.

   9. HTTP defines a simple 'basic' access control mechanism, and an example of
      using this is included in the filter and sample pages. When used, the
      person using the browser is prompted for a userid and password; the
      filter checks the validity of this.


ΓòÉΓòÉΓòÉ 20.6. Data organization and setup ΓòÉΓòÉΓòÉ

It is recommended that the control and execution files be placed in a directory
separate from your data, perhaps called GOSERVE.  This may be the same
directory as is already being used for running a Gopher server, as the control
files (Filter, audit files, etc.) will normally have a different extension
(.80).

Note that the filter must be in the working directory for GoServe, though you
may change its name (an extension matching the port is recommended).  If you
make changes to the default filter, it's a good idea to change its name, too,
so if you install a new version of GoServe your filter will not be overwritten
by the new default filter.

The sample filter assumes that the data are held in a tree starting at the
directory known by GoServe as the data directory (by default, GoServe assumes
that is the directory '\gohttp' on the same drive as the working directory).
You should normally change this, using GoServe, to point to a different
subdirectory tree that holds your own data.  This tree can be on any drive and
start at any depth (it may even start at the root directory of a disk).

Note that the sample filter allows unrestricted access to all files in the
subtree starting at your data directory.

For more details, see GOSERVE.DOC.


ΓòÉΓòÉΓòÉ 21. --- GoGopher.doc --- ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 21.1. Credits ΓòÉΓòÉΓòÉ

                  How to start using GoServe as a Gopher server
                 """"""""""""""""""""""""""""""""""""""""""""""
                                      GoServe 2.52

        Copyright (c) IBM Corporation, 1994, 1995.  All rights reserved.
                       Mike Cowlishaw, IBM UK Laboratories
                                [e-mail]
                                    - - - - -

About


ΓòÉΓòÉΓòÉ 21.2. Introduction ΓòÉΓòÉΓòÉ

'GoServe' is a multi-purpose server for OS/2, which supports the 'Gopher'
client-server protocol (as well as the World-Wide Web protocol).  The Gopher
protocol is described in documents distributed by the University of Minnesota
Microcomputer and Workstation Networks Center.

Providing that you already have TCP/IP installed and started, GoServe can be
running and serving files across a network in minutes.

This document describes how to use GoServe as a Gopher server, and includes
instructions on how to set up your own main menu.  GOGOPHER.ZIP includes a
working sample main menu and customization filter, together with other sample
data.

Note:  It is assumed that you have some familiarity with Gopher, and have (and
know how to use) a Gopher client.


ΓòÉΓòÉΓòÉ 21.3. Quick start ΓòÉΓòÉΓòÉ

Assuming you have unzipped GOSERV.ZIP into the directory of your choice (for
example, D:\GOSERVE), then:

   1. Open an OS/2 window

   2. Unzip the included file GOGOPHER.ZIP to a different directory.  To use
      the default setup, put this 'data directory' on the same drive as the
      first directory, and call it GOGOPHER (for example, D:\GOGOPHER).

   3. The sample files include two menu templates; you must generate working
      menu files from these which include your network address. To do this, run
      the GOSMENU.CMD command against the two templates, using these two
      commands:

                    gosmenu mainmenu.men
                    gosmenu test.men

      Assuming no errors were reported there should now be two new files in the
      directory (MAINMENU.70 and TEST.70).

   4. Change your current directory back to the GoServe directory (for example,
      D:\GOSERVE)

   5. Start GoServe with the parameter "gopher", for example using:

                   start goserve gopher

 You should then see a GoServe window (titled 'GoServe [Gopher]') appear. If
 there are no error messages, the server is now active, and you should be able
 to connect to the sample pages with any Gopher client.  For example, if the
 name of your machine is "fred.hursley.ibm.com", specify this as the name for
 Gopher to use.  The OS/2 Gopher client (available separately) may be started
 with this name as a command line parameter, thus:

    start gopher fred.hursley.ibm.com

 If GOPHER.EXE is neither in the current directory nor is in a directory on
 your PATH, you will need to include its directory information in the command,
 for example:

    start e:\tools\gopher fred.hursley.ibm.com

 Alternatively, you should be able to use a World-Wide Web client by, for
 example, specifying a URL of "gopher://fred.hursley.ibm.com/".

 If you don't know the name of your machine, try the command "hostname" from an
 OS/2 prompt.


ΓòÉΓòÉΓòÉ 21.3.1. --- Setting up an icon for GoServe --- ΓòÉΓòÉΓòÉ

To set up an icon (program reference object) for a GoServe gopher server and
(optionally) ensure that GoServe is started automatically when OS/2 is booted:

   1. With your current directory being the GoServe directory (for example,
      D:\GOSERVE), run the command:

                   makeicon gopher

      This should make an icon called 'GoServe - Gopher' appear on the Desktop.
      You can Move or drag it to another folder if you wish. The server can now
      be started by clicking on the new icon (you may want to check that this
      works).

   2. Open the Startup folder (this may be on the Desktop or in the 'OS/2
      System' folder).

   3. Make a shadow of the GoServe icon in the Startup folder.  To do this,
      hold down the Ctrl+Shift keys and then drag the icon to the Startup
      folder, drop it, and release Ctrl+Shift.  (See the OS/2 documentation if
      you need more details.)

 With the shadow in the Startup folder, the server will be started
 automatically whenever OS/2 is booted or rebooted.


ΓòÉΓòÉΓòÉ 21.4. Your own main menu ΓòÉΓòÉΓòÉ

The sample filter can be used to serve different menus and files without any
changes or programming.  All you need to do is change the data files.

Here's what you need to do to set up your own 'main menu', given that the
sample described above works:

   1. Make a new directory for your own Gopher data (for example, called
      D:\GODATA).

   2. Copy the files from the sample directory to your new directory, using
      (for example):

                   copy d:\gogopher\*.* d:\godata

      This leaves the original files unchanged, as a backup.

   3. Modify the file ABOUT.DOC in your new directory, to refer to your own
      address and so on.  To start with, to see if it works, it's probably best
      to change a few words only.  For example, change the line

                   Administrator: Your Name Here

      to something more helpful.

   4. If GoServe is not already running, start it as before (don't forget the
      'GOPHER' parameter, if starting from a command prompt).  Choose
      'Directory selection' from the 'Options' menu, and use the dialog there
      to change the data directory to be your new directory (for example, to
      D:\GODATA).

   5. Try your favourite Gopher client, connecting to your machine as before,
      and it should now display your main menu; selecting 'About this Gopher
      server' should then display your new ABOUT.DOC.

   6. All you have to do now is modify the data to your liking. To add
      documents or menus to the main menu, you will need to edit the file
      MAINMEN.MEN -- see below for details of the format.

 All of the details above can be customized if you wish, but you will probably
 need to learn more about GoServe and Rexx to change things effectively.
 Please see GOSERVE.DOC for more information.


ΓòÉΓòÉΓòÉ 21.5. An overview on how GoServe works ΓòÉΓòÉΓòÉ

(To make sense of this, you may need to read GOSERVE.DOC too.)

Whenever a client connects to your machine, it sends a 'request string'.
GoServe receives the string and passes it to a 'filter'.  This filter (a
program, written in Rexx) checks that the request is valid, and normally
responds with a file (such as an document or a menu file).  It is the filter's
responsibility to choose or create the file, given the incoming request string.

A sample filter (GoFilter.70) is provided--see commentary in that program for
details.  In brief, it asks the server for the name of the data directory,
checks for certain errors, and then processes the request according to the
contents of the request string.

Notes:

   1. The sample filter gets the root, or home, directory for the data it is to
      serve by calling the DATADIR() function.  The value this returns is set
      by GoServe (which, in turn, is derived from the GoServe startup parameter
      or the Directory Selection dialog).

   2. A default menu is provided if none is specified.  Conventionally, this is
      called 'mainmenu.70' (you can change this if you wish). A sample
      'mainmenu.men', from which 'mainmenu.70' can be generated, is provided.

   3. Certain special 'test and control' selectors are supported by the sample
      filter (for example, return server statistics).  In the sample filter,
      these are only allowed from a client with the same address as the server,
      or those listed in the filter.  Other possibilities include not checking
      the client's address [so anyone can use them], or, conversely, using a
      privately-selected selector string for the controls--which would act as a
      password.  See GOSERVE.DOC for more information on control options.

   4. File names in selectors or the FILE command can be specified with either
      forward slashes or backslashes as directory separators. Forward slashes
      are recommended, as some Unix-based clients may not correctly handle
      backslashes.


ΓòÉΓòÉΓòÉ 21.6. Data organization and setup ΓòÉΓòÉΓòÉ

It is recommended that the control and execution files be placed in a directory
separate from your data, perhaps called GOSERVE.  This may be the same
directory as is already being used for running a Web server, as the control
files (Filter, audit files, etc.) will have a different extension (.70).

Note that the filter must be in the working directory for GoServe, though you
may change its name (an extension matching the port is recommended).  If you
make changes to the default filter, it's a good idea to change its name, too,
so if you install a new version of GoServe your filter will not be overwritten
by the new default filter.

The sample filter assumes that the data are held in a tree starting at the
directory known by GoServe as the data directory (by default, GoServe assumes
that is the directory '\gogopher' on the same drive as the working directory).
You should normally change this, using GoServe, to point to a different
subdirectory tree that holds your own data. This tree can be on any drive and
start at any depth (it may even start at the root directory of a disk).

Note that the sample filter allows unrestricted access to all files in the
subtree starting at your data directory.

For more details, see GOSERVE.DOC.


ΓòÉΓòÉΓòÉ 21.7. GOSMENU.CMD ΓòÉΓòÉΓòÉ

The GoServe package includes a simple utility in the GoGopher collection that
makes it easier to create 'canonical' Gopher menu files.  See the start of
GOSMENU.CMD for details.  A 'menu template' file, perhaps called MAINMENU.MEN,
might look like this:

  Sample main menu
  ; rexx.central.edu 70
  0 About this Gopher server; about.doc
  1 IBM Almaden Gopher server;; index.almaden.ibm.com
  1 Test and control menu; test.70

The first line is a description; the second gives the field separator character
(which will become Tab in the generated menu), together with the default server
address and port.  (If the last two are not specified, GOSMENU will try and
determine the address from TCP/IP, and will assume the port is 70.)

Subsequent lines are menu lines, as required by the Gopher protocol. Lines
whose first character is a blank are ignored (that is, they are not included in
the menu file).  If the first character is a 0, the menu line refers to a
document; a 1 indicates a menu is expected; 9 indicates a binary file (such as
a Zip file), and so on.

Running GOSMENU against this file (with a different output filename) like this:

  gosmenu mainmenu.men mainmenu.70

will create a 'canonical' menu file, with real tab characters instead of
semicolons, address and port added where required, and extra blanks removed.
The Gopher protocol suggests that the first (description) field be no more than
70 characters, and requires that the entire menu line (including address and
port) fit within 255 characters.

Notes:

   1. The default output filename for GOSMENU.CMD is constructed by replacing
      the extension of the input filename by '70', so the sample command could
      have been simply:

                   gosmenu mainmenu.men

      Or, of course, the file MAINMENU.MEN could simply have been dropped on a
      Program Reference object that starts GOSMENU.CMD

   2. It is recommended that 'active' menu files be identified by an extension
      which is the Gopher port for which they are to be used.


ΓòÉΓòÉΓòÉ 22. License ΓòÉΓòÉΓòÉ

  *********************************************************************


                  IBM License Agreement for OS/2 Tools
       -----------------------------------------------------------------


       IF YOU DOWNLOAD OR USE THIS PROGRAM YOU AGREE TO THESE TERMS.

       International Business Machines Corporation grants you a license
       to use the Program only in the country where you acquired it. The
       Program is copyrighted and licensed (not sold). We do not
       transfer title to the Program to you. You obtain no rights other
       than those granted you under this license.

       Under this license, you may:

       1. use the Program on one or more machines at a time;
       2. make copies of the Program for use or backup purposes within
          your Enterprise;
       3. modify the Program and merge it into another program; and
       4. make copies of the original file you downloaded and distribute
          it, provided that you transfer a copy of this license to the
          other party. The other party agrees to these terms by its
          first use of the Program.

       You must reproduce the copyright notice and any other legend of
       ownership on each copy or partial copy, of the Program.

       You may NOT:

       1. sublicense, rent, lease, or assign the Program; and
       2. reverse assemble, reverse compile, or otherwise translate the
          Program.

       We do not warrant that the Program is free from claims by a third
       party of copyright, patent, trademark, trade secret, or any other
       intellectual property infringement.

       Under no circumstances are we liable for any of the following:

       1. third-party claims against you for losses or damages;
       2. loss of, or damage to, your records or data; or
       3. economic consequential damages (including lost profits or
          savings) or incidental damages, even if we are informed of
          their possibility.

       Some jurisdictions do not allow these limitations or exclusions,
       so they may not apply to you.

       We do not warrant uninterrupted or error free operation of the
       Program. We have no obligation to provide service, defect
       correction, or any maintenance for the Program. We have no
       obligation to supply any Program updates or enhancements to you
       even if such are or later become available.


       IF YOU DOWNLOAD OR USE THIS PROGRAM YOU AGREE TO THESE TERMS.

       THERE ARE NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING THE
       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
       PARTICULAR PURPOSE.

       Some jurisdictions do not allow the exclusion of implied
       warranties, so the above exclusion may not apply to you.

       You may terminate this license at any time. We may terminate this
       license if you fail to comply with any of its terms. In either
       event, you must destroy all your copies of the Program.

       You are responsible for the payment of any taxes resulting from
       this license.

       You may not sell, transfer, assign, or subcontract any of your
       rights or obligations under this license. Any attempt to do so is
       void.

       Neither of us may bring a legal action more than two years after
       the cause of action arose.

       If you acquired the Program in the United States, this license is
       governed by the laws of the State of New York. If you acquired
       the Program in Canada, this license is governed by the laws of
       the Province of Ontario. Otherwise, this license is governed by
       the laws of the country in which you acquired the Program.

       3/92

---------------------------------------------------------------------------


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ


With the exception of very minor changes to the arrangement of whitespace and
slight grammatical corrections (indicated by blue-on-red text), the source for
this copy of the GoServe documentation is the exact text from the (.doc)
documents supplied with the GoServe v2.52 distribution (see Credits section at
start of the document).  I have simply compiled the text as a native OS/2 Book
document (.inf file).  The source code has been provided to the credited author
of GoServe.  I can be contacted via eMail to [e-mail].
Please do so if you find any deviation from the original documention.
Version history:

     8-Mar-2001 . v 2001.01 : Initial compilation
     24-Jul-2001 . v 2001.02 : Updated contact eMail address