home *** CD-ROM | disk | FTP | other *** search
/ Mega Top 1 / os2_top1.zip / os2_top1 / APPS / DATACOM / INTERNET / GOSERV / GOSERVE.DOC < prev    next >
Text File  |  1995-02-14  |  72KB  |  1,630 lines
  1.                                                                GoServe 2.00
  2. GoServe -- A Web and Gopher Server for OS/2
  3. """""""""""""""""""""""""""""""""""""""""""
  4.  
  5. Copyright (c) International Business Machines Corporation, 1993, 1995.
  6. All rights reserved.
  7.  
  8.  
  9. Introduction
  10. """"""""""""
  11. Two popular protocols for providing information on the Internet are the
  12. HyperText Transfer Protocol (HTTP, used by World-Wide Web clients) and
  13. Gopher (used by both Web and Gopher clients).
  14.  
  15. 'GoServe' is a multi-purpose server for OS/2 which supports both these
  16. protocols.  The emphasis in the design of GoServe has been to make it
  17. easy to become an information provider for the Internet, while not
  18. inhibiting full use of the protocols by sophisticated users.
  19.  
  20. Providing that you already have TCP/IP installed, GoServe can be running
  21. and serving files across a network in minutes; no reboot or editing of
  22. configuration files is necessary.  The GoServe package includes 'quick
  23. start' instructions and working samples for both Web and Gopher servers.
  24.  
  25. GoServe processes requests from Web or Gopher clients using a Rexx
  26. script to allow for customization.  A server can handle requests from
  27. many clients, using OS/2 threads and script caching for efficiency.
  28. Multiple servers can be started (using different ports), and an audit
  29. trail of requests and actions can be recorded.  When running as a Web
  30. server, much of the complexity of the Web protocol is handled
  31. automatically; many GoServe users will only need to be concerned about
  32. the data being provided, and need not be concerned about the mechanism.
  33.  
  34. While running, a graphical display of GoServe activity is shown (the
  35. "Graphical Webspinner Interface"?), with optional response-time graphing
  36. and an audible indication of connections.  For control, various
  37. restrictions may be employed to limit the load on the server machine.
  38. Certain GoServe operations can be controlled remotely, if desired, using
  39. any Web or Gopher client (or an OS/2 CMD program).
  40.  
  41. GoServe is a 32-bit OS/2 application, which requires OS/2 2.x or OS/2
  42. Warp.  GoServe requires TCP/IP for OS/2, or equivalent, to be installed
  43. and operational (either on a real network or using the loopback driver).
  44. A single copy of GoServe may be used as both a Web server and a Gopher
  45. server at the same time, if required.
  46.  
  47. - - - - -
  48.  
  49. Mike Cowlishaw, IBM UK Laboratories
  50. mfc@vnet.ibm.com
  51.  
  52.  
  53. Getting started
  54. """""""""""""""
  55. This document describes all aspects of the use of GoServe as a Web or
  56. Gopher server.  If you are a new user, you should first read one of:
  57.  
  58.   o GoHTTP.doc -- for getting started setting up a Web server
  59.  
  60.   o GoGopher.doc -- for getting started setting up a Gopher server.
  61.  
  62. Both of these guide you through setting up a working server.  It's
  63. recommended that you do this before reading more of the technical
  64. details in this document.  This document assumes that you are familiar
  65. with Web or Gopher concepts, and have access to (and know how to use) a
  66. Web or Gopher client.
  67.  
  68.  
  69. How GoServe is used
  70. """""""""""""""""""
  71. GoServe is an ordinary 32-bit OS/2 application program (it has no
  72. special privileges, and uses only public interfaces to OS/2 and to
  73. TCP/IP).  When started, you should specify as a parameter the protocol
  74. that the server is to use (HTTP or GOPHER).
  75.  
  76. When started, GoServe sets up a TCP/IP socket on the 'well-known' port
  77. for the protocol selected (this can be altered using a different startup
  78. parameter), then waits for requests from clients.  When a request from a
  79. client arrives, it is recorded in the audit file (if desired) and then
  80. the GoServe filter for the port is called.
  81.  
  82. The GoServe filter is a program written in Rexx, which is given details
  83. of the client and the request string.  The filter decides on the
  84. information (usually a file, containing a document or other data) to be
  85. sent to the client, and returns details to GoServe.  GoServe then sends
  86. the HTTP response and the data to the client and closes the TCP/IP
  87. connection.
  88.  
  89. Each incoming request is given a new OS/2 thread for communication,
  90. filter processing, and response.  GoServe handles all the details of
  91. threads and TCP/IP communications, so you need only be concerned with
  92. the filter (which can be very simple, perhaps just the sample filter)
  93. and the data (documents, images, etc.).
  94.  
  95.  
  96. Installation
  97. """"""""""""
  98. If you followed either of the 'getting started' documents, you will have
  99. already installed GoServe.  In general, only two files (plus data) are
  100. needed to run GoServe as a Web or Gopher server: the GOSERVE.EXE program
  101. file, and the appropriate Rexx filter.  The default filter name has
  102. filename GOFILTER, with an extension that is the TCP/IP port number to
  103. be used (for example, 'GOFILTER.80' for the filter for a default Web
  104. server, or 'GOFILTER.70' for the filter for a Gopher server).  The
  105. filter must be in the working directory for GoServe.
  106.  
  107. It is recommended that GOSERVE.EXE and the Rexx filter be placed in one
  108. directory (for example, 'D:\GoServe'), and data for the server be placed
  109. in a different directory.  By default, the latter is expected to be
  110. on the same drive as the GoServe directory, and named '\gohttp' for a
  111. Web server or '\gogopher' for a Gopher server.
  112.  
  113. Both the data directory and the filter name can easily be changed by
  114. using the GoServe options notebook or by a command line option, if
  115. required.
  116.  
  117. In all cases, the Rexx filter must be in the working directory for
  118. GoServe.  The working directory is also used by GoServe for the
  119. GOSERVE.INI file (which holds user settings, such as window position and
  120. audit selections), and for any Audit and Audit Archive files.
  121.  
  122. When you unzip the GOSERV.ZIP file, you should find the following files:
  123.  
  124.    goserve.doc  -- this document
  125.    gohttp.doc   -- how to get started as a Web server
  126.    gogopher.doc -- how to get started as a Gopher server
  127.    goserve.exe  -- the server program
  128.    gofilter.80  -- sample (working) filter for HTTP
  129.    gofilter.70  -- sample (working) filter for Gopher
  130.    moveaud.cmd  -- sample (working) remote control command
  131.    makeicon.cmd -- installation aid
  132.  
  133.    gohttp.zip   -- sample pages, etc., for a Web server [unzip to a
  134.                    separate directory, perhaps D:\GoHTTP].  This also
  135.                    includes the GoServe Web documentation in HTML.
  136.    gogopher.zip -- sample menus, etc., for a Gopher server [unzip to a
  137.                    separate directory, perhaps D:\GoGopher]
  138.  
  139.    license.txt  -- IBM license agreement for OS/2 Tools
  140.  
  141. Please see the 'how to get started' documents for step-by-step
  142. instructions for installation.
  143.  
  144. --- Uninstalling GoServe ---
  145.  
  146. To uninstall GoServe, it is only necessary to delete the directories
  147. used by GoServe, with their contents.  No changes are made to the OS/2
  148. system.  (Note that prior to version 1.74, GoServe saved settings in
  149. OS2.INI.  Later versions automatically migrate this information to the
  150. GoServe working directory.)
  151.  
  152. --- Requirements ---
  153.  
  154. GoServe is a 32-bit OS/2 application, which requires OS/2 2.x or OS/2
  155. Warp.  For OS/2 Warp, version 1.31 (or later) of GoServe is needed.
  156. GoServe requires TCP/IP for OS/2, or equivalent, to be installed and
  157. operational (either on a real network or using the loopback driver).
  158. Over time, CSDs for TCP/IP become available--if TCP/IP problems are
  159. suspected, always try the latest CSD.
  160.  
  161.  
  162. Filter programs
  163. """""""""""""""
  164. Filter programs are written in Rexx.  Based on the arguments they are
  165. passed, they decide on the document or other data to be sent to the
  166. client and then issue a command or return a result that defines that
  167. data (usually a file) to the server.  GoServe then handles the
  168. transmission of the data to the client.
  169.  
  170. All requests are passed to the Rexx filter, so for every request you
  171. have full control over the response by modifying the filter as required.
  172. GoServe will never send data to a client without the filter being
  173. involved.
  174.  
  175. The filter is cached (that is, it and its tokenized version are only
  176. read from disk when changed) and is executed on the same thread as the
  177. incoming request (not as a separate process).  This is very efficient;
  178. informal measurements suggest that only a small percentage of the total
  179. response time of a simple request is spent in running the filter.  For
  180. example, the total time to run the sample filter on a 486/50MHz PC has
  181. been measured under OS/2 2.11 to be as little as 11ms.
  182.  
  183. For examples of filters, please see the sample filters in the GoHTTP or
  184. GoGopher collections.  The following is specific technical information
  185. on how the filters work.
  186.  
  187. Three argument strings are passed to the filter:
  188.  
  189.   1. The source of the request.  This has four words [more words could
  190.      be added at the end in the future], separated by one or more
  191.      blanks:
  192.  
  193.        o the Internet address (primary host identifier) of the server's
  194.          machine or cluster (in numeric form)
  195.  
  196.        o the server's port number used for the connection
  197.  
  198.        o the transaction number (a number, incremented for each new
  199.          request, that starts at 0 when GoServe is started)
  200.  
  201.        o the Internet address of the client (in numeric form).
  202.  
  203.      Example: "9.15.11.189 80 101 9.20.25.65"
  204.  
  205.   2. The request string.
  206.  
  207.        o For a Web server, this string is the HTTP request string,
  208.          exactly as received from the client.  This comprises three
  209.          words: the request verb (e.g., 'GET'), the URI (Universal
  210.          Resource Identifier) or partial URI, and the HTTP protocol
  211.          identifier (e.g., 'HTTP/1.0').  The third word may be absent
  212.          when older (HTTP/0.9) clients connect.  A URI of just '/'
  213.          indicates the initial contact from a client, and the filter
  214.          would normally respond with a default document ("home page").
  215.  
  216.          Partial URIs are (or should be) the request string from a Web
  217.          'href' attribute previously sent to the client, unchanged
  218.          [except that extra data, such as incoming data from forms, may
  219.          be suffixed, and a leading slash, '/', may be added].  For
  220.          more information on URIs, see the technical details available
  221.          on the Web.  A good place to start is the Web information
  222.          based at 'http://info.cern.ch/'.
  223.  
  224.        o For a Gopher server, the request string is any data received
  225.          from the client up to (but not including) a Tab, Carriage
  226.          Return, or Line Feed.  An empty request string indicates the
  227.          initial contact from a client, and the filter would normally
  228.          respond with a default Gopher menu.  Otherwise, it will (or
  229.          should) be the request string from a Gopher menu line
  230.          previously sent to the client, unchanged.
  231.  
  232.      You have complete freedom in setting request strings in Web documents
  233.      and Gopher menus, and in deciding how the filter should respond
  234.      depending on the string received.  Very often, the name of a file is
  235.      used, and that file is sent to the client.  [Note: it is recommended
  236.      that fully qualified filenames NOT be used for request strings.]
  237.  
  238.   3. The extended request string.
  239.  
  240.        o For an HTTP server, this string is the "packed" URI or partial
  241.          URI.  This is the second word of the request string, with
  242.          escape sequences (e.g., '%7e') converted to a single byte, and
  243.          with any leading slash ('/'), if present, removed.
  244.  
  245.        o For a Gopher server, this is the 'Gopher+' data.  Some Gopher
  246.          clients can add additional information to a request, attached
  247.          to the request string after a Tab character.  GoServe discards
  248.          the Tab character and presents the remainder as the third
  249.          argument to the filter.  See Gopher protocol documents for
  250.          more information on how the extended selector string is used.
  251.  
  252. The filter can specify that GoServe send either a file or a single
  253. string to the client, or request certain other GoServe operations.
  254. All these operations are effected in the usual Rexx way, by using
  255. commands, which are described later in this document.  Other commands
  256. allow more detailed control of the server.
  257.  
  258. The filter may also return a result string to GoServe; this, too, is
  259. treated as a command.  [In early versions of GoServe, this was the only
  260. way to execute a GoServe command, so early GoServe filters only use that
  261. mechanism.]
  262.  
  263. In addition to the commands, GoServe provides several special-purpose
  264. functions for dealing with incoming requests.  For example, the
  265. PACKUR(string) function takes a string which has been encoded for safe
  266. transmission, and reduces escape sequences (such as '%7E') to the
  267. character encoding that they represent (in this case, '~').
  268.  
  269. Any failure of the filter (such as a syntax error) is considered
  270. catastrophic and will cause GoServe to end.
  271.  
  272. Notes:
  273.  
  274.   1. Remember that GoServe will run multiple copies of the filter at
  275.      once, on different threads, if more than one client connects at the
  276.      same time.  If building temporary files, use the transaction number
  277.      and port as part of the file name.
  278.  
  279.   2. The results of SAY instructions (or tracing) in the filter program
  280.      may be seen using the PMprintf package.  However, Rexx interactive
  281.      tracing is not supported.  PMprintf should be available from the
  282.      same source as GoServe.
  283.  
  284.   3. You may change the name of the filter when starting GoServe or by
  285.      using the 'Filter selection' options page.  The filter must always
  286.      be in the working directory for GoServe.  If you make changes to
  287.      the default filter, it's a good idea to change its name, too, so if
  288.      you install a new version of GoServe your filter will not be
  289.      overwritten by the new default filter.
  290.  
  291.   4. External subroutines, written in Rexx, are easily called from the
  292.      filter simply by using their name in a CALL instruction or function
  293.      call.  The names should not match that of a Rexx built-in function,
  294.      and the routine should normally be in a file with the same
  295.      extension (e.g, '.80') as the filter and in the same directory.
  296.  
  297.   5. You can execute OS/2 commands from the filter using the Address CMD
  298.      instruction, for example:
  299.  
  300.        address cmd
  301.        'start e foo.bar'
  302.        'call d:\foobar\test.cmd argstring'
  303.  
  304.      Use caution when calling external programs before the response is
  305.      complete: any slowness directly affects the response time to the
  306.      client and its user.  Note also that separate processes (including
  307.      external commands) are not terminated automatically by GoServe if a
  308.      connection times out.
  309.  
  310.      Finally, when executing commands, do not build any part of the
  311.      command string from data received from the client; this could allow
  312.      execution of arbitrary commands on your server (for example, if an
  313.      '&' command separator character were included in the data).
  314.  
  315.   6. By default, each copy of a filter may have up to five files open at
  316.      once.  This limit may be increased using the Limits selection
  317.      dialog (see elsewhere).
  318.  
  319.   7. A new version of the filter is only cached (loaded) when GoServe is
  320.      idle; therefore, if you change the filter while GoServe is running,
  321.      the changes will not be used until the first client connects after
  322.      a time when there have been no clients connected.
  323.  
  324.   8. For more information on Rexx, try connecting to the Rexx Language
  325.      page at: http://rexx.hursley.ibm.com/rexx
  326.  
  327.   9. For more information on OS/2, try connecting to the IBM Almaden
  328.      Research Center server, at index.almaden.ibm.com.  Both Web and
  329.      Gopher clients are supported (the server runs GoServe).  The IBM
  330.      home page (http://www.ibm.com) is another good starting point for
  331.      OS/2 information.
  332.  
  333.  
  334. Filter commands
  335. """""""""""""""
  336. Commands may be executed by GoServe filters at any time, using the usual
  337. Rexx command syntax (a clause that is just an expression).  In addition,
  338. any string returned by the filter will be executed as a command.
  339.  
  340. Certain commands (CLOSE, CONTROL, FILE, NODATA, and STRING) can be
  341. 'completion commands'; that is, after executing the command, the
  342. response to the client will have been sent and will be complete.  Only
  343. one completion command may be executed for each request received; once a
  344. completion command has been executed, no further commands will be
  345. accepted.
  346.  
  347. If the filter ends without error and without executing or returning any
  348. completion command, the server will generate one (currently "String [No
  349. information available]").
  350.  
  351. Errors and failures in commands are reported by a non-zero return code
  352. (which is placed in the Rexx variable RC), and also may raise the ERROR
  353. or FAILURE condition if enabled by SIGNAL ON or CALL ON in the filter.
  354. Command errors are also audited unless Error auditing has been turned
  355. off.  For details on the possible return codes, see "Command return
  356. codes".
  357.  
  358. The total length of a command is limited to 1000 characters.
  359.  
  360. The most important commands are the completion commands, though there
  361. are others which will be useful to filter writers.  The commands follow
  362. in alphabetical order; note that keywords and file specifications may be
  363. in lower, upper, or mixed case.
  364.  
  365.  
  366. AUDIT command
  367. '''''''''''''
  368. Syntax:
  369.  
  370.   AUDIT string
  371.  
  372. The string supplied will be written to the Audit file as a 'user audit'
  373. line.  See "The audit mechanism" for a description of auditing.
  374.  
  375. CLOSE command
  376. '''''''''''''
  377. Syntax:
  378.  
  379.   CLOSE
  380.  
  381. This command will cause GoServe to end, with return code set to 1, when
  382. all current connections have been completed.  No new connections will be
  383. accepted.  An acknowledgement is sent to the client, and the connection
  384. is then closed, so this is a completion command.
  385.  
  386. CONTROL command
  387. ''''''''''''''''
  388. Syntax:
  389.  
  390.   CONTROL [VAR varname] options
  391.  
  392. A GoServe control action (such as moving the audit file, resetting
  393. counters, or requesting statistics) is initiated, and a result string is
  394. either placed in a Rexx variable or returned to the client.
  395.  
  396. This is used for controlling the GoServe server from the filter, either
  397. directly or on request from a remote client or from another process on
  398. the same machine -- for information on ways to do this, see "Remote
  399. control of GoServe".
  400.  
  401. The possible options are:
  402.  
  403.   o MOVEAUDIT
  404.  
  405.     The audit file is copied to the archive file (just as though the
  406.     'Move audit to archive' Actions menu item had been selected).
  407.  
  408.   o RESET [BYTES] [PEAK] [RESPONSE] [TRANSACTIONS] [ERRORS] [ALL]
  409.  
  410.     The specified GoServe counters and statistics are reset (after
  411.     auditing, if appropriate).  Any or all of the keywords may be given,
  412.     in any order.  Each works in the same way as the corresponding
  413.     Actions menu item; RESPONSE refers to the response time record.
  414.  
  415.     If ALL is used, all of the items are reset, and a record of the time
  416.     is kept; this time will be shown on the display window and in any
  417.     statistics requests.
  418.  
  419.   o SAY string
  420.  
  421.     The given string is returned; this can be used as a simple 'Loopback
  422.     test'.
  423.  
  424.   o STATISTICS
  425.  
  426.     Current statistics and settings are returned.  These include:
  427.  
  428.       1. Transaction, error, byte, and client counts, with a brief
  429.          response time analysis
  430.  
  431.       2. Certain settings and options (not including audit selections)
  432.  
  433.       3. The local time of certain events (if an event has not occurred,
  434.          it is shown as the GoServe start time).
  435.  
  436. The result of a CONTROL command is a single string, which may include
  437. multiple lines, separated by Carriage Return-Line Feed (CR-LF, ASCII
  438. '0d0a'x) sequences.  The exact format is not defined.  The result string
  439. is either placed in a variable or returned to the client:
  440.  
  441.   o If 'VAR varname' was specified, the result string is placed in the
  442.     named Rexx variable.  The name of the variable is used just as if it
  443.     appeared in the filter program (for example, the name 'local.j'
  444.     might have the value of J substituted in the name).
  445.  
  446.   o If 'VAR' was not specified, a document containing the string is
  447.     returned to the client (just as though the STRING command were
  448.     used), so in this case, CONTROL is a 'completion command'.
  449.  
  450.  
  451. FILE command
  452. ''''''''''''
  453. Syntax:
  454.  
  455.   FILE [ERASE] [TYPE content-type] [BINARY|TEXT] NAME filespec
  456.  
  457. The file named by 'filespec' will be sent to the client.  'filespec'
  458. should normally be a fully qualified name (if it is not, GoServe would
  459. look for it in the GoServe working directory).  Either forward or
  460. backward slashes may be used as directory separators; the OS/2 file
  461. systems accept either.
  462.  
  463. After this command has ended, the connection to the client is closed, so
  464. this is a 'completion command'.
  465.  
  466. The optional keywords may be specified, in any order, and have the
  467. following effects:
  468.  
  469.   o ERASE -- the file is a temporary file, and should be erased after
  470.     being sent.  [The transaction number and port can be used for
  471.     generating a safe name for a temporary file.]
  472.  
  473.   o TYPE -- [HTTP protocol only] the file will be prefixed by an HTTP
  474.     "OK" response line and an HTTP header, including the content length
  475.     derived from measuring the file.  The value of the TYPE option
  476.     ('content-type') should be a Internet Media Type such as "text/html"
  477.     or "image/gif".  See notes below for more information.
  478.  
  479.     The TYPE option may only be used if GoServe is started with the HTTP
  480.     parameter (HTTP headers are not used by Gopher), and should normally
  481.     always be used when running as a Web server.
  482.  
  483.   o BINARY -- [default for HTTP] the file is a binary file, and forms
  484.     the entire response to the client.  GoServe will close the TCP/IP
  485.     connection as soon as the complete file has been sent.
  486.  
  487.     A Gopher server should use this option for all files that are not
  488.     simple text or menus, for example ".ZIP" files, etc.
  489.  
  490.   o TEXT -- [default for Gopher] the file is a text file: any trailing
  491.     DOS end-of-file character will not be sent to the client.
  492.  
  493.     If running as a Gopher server, a Gopher terminator line (just a
  494.     period) will be sent at the end of the document, before the
  495.     connection is closed.
  496.  
  497. Here are some examples:
  498.  
  499.   1. Returning an HTML file to a Web client:
  500.  
  501.        file type text/html name d:/gohttp/index.htm
  502.  
  503.   2. Returning a temporary image file to a Web client:
  504.  
  505.        file erase type image/gif name d:/gohttp/$7681.80
  506.  
  507.   3. Returning a .ZIP file to a Gopher client:
  508.  
  509.        file binary name d:/gogopher/gogopher.zip
  510.  
  511. Notes:
  512.  
  513.   1. The filespec may not include an 'upwards reference' sequence ("..\"
  514.      or "../"), as such a sequence could possibly allow clients access
  515.      to any file on the server machine.
  516.  
  517.   2. All data sent to a client with an HTTP header should be described
  518.      by a Content-Type field in the header; GoServe will therefore only
  519.      generate a header automatically if the TYPE option was specified or
  520.      the HEADER command has been used to add header lines.  In this
  521.      latter case, it is the responsibility of the filter to supply the
  522.      Content-Type field if the TYPE option was not used.
  523.  
  524.   3. Internet Media Types were formerly known as MIME (Multipurpose
  525.      Internet Mail Extensions) Content Types.  MIME is described in RFC
  526.      1521 and RFC 1522.  The media types are used in the HTTP protocol
  527.      so that clients can determine how to process data received from
  528.      servers.  Some common types are listed in the sample filter.
  529.  
  530.  
  531. HEADER command
  532. ''''''''''''''
  533. Syntax:
  534.  
  535.   HEADER [NOAUTO] [{ADD|DROP} value]
  536.  
  537. Adds a header line to the HTTP response header, or drops one already
  538. added.  Header lines added by this command are sent to the client after
  539. header lines generated automatically by GoServe.  For example:
  540.  
  541.   HEADER ADD Title: My own title
  542.  
  543. Blanks following the keyword ADD or DROP are removed by GoServe, so
  544. continuation header lines must be started with the tab ('09'x)
  545. character.
  546.  
  547. If DROP is used, only the field identifier (up to and including the
  548. colon) should be specified.  The first header line that matches (of the
  549. lines added using HEADER ADD) is dropped, together with any following
  550. continuation lines; automatically generated header lines are not
  551. affected.  A case-insensitive comparison is used for determining a
  552. match.
  553.  
  554. NOAUTO may be used either alone on the command or in conjunction with
  555. the ADD or DROP form.  If any HEADER command specifies NOAUTO, no header
  556. lines will be automatically generated by GoServe (except the final empty
  557. line); all lines must be explicitly defined using HEADER ADD.  For
  558. example:
  559.  
  560.   HEADER NOAUTO ADD Server: Special/0.01
  561.   HEADER        ADD Title: Two-line header
  562.  
  563. At least one keyword must be used on the HEADER command.  The HEADER
  564. command has no effect under the Gopher protocol (though the command
  565. syntax is checked).  It also has no effect if the incoming request uses
  566. HTTP/0.9 -- in this case, the protocol does not permit a header to be
  567. returned, as it would be treated as part of the data.
  568.  
  569.  
  570. NODATA command
  571. ''''''''''''''
  572. Syntax:
  573.  
  574.   NODATA [NORESPONSE]
  575.  
  576. No data is to be sent; the response is complete.  For an HTTP/1.0
  577. request, only a response line and header will be sent.  For a Gopher (or
  578. HTTP/0.9) request, the connection will simply be closed.  This command
  579. is intended to be used when only a header, or nothing at all, is to be
  580. returned to the client.
  581.  
  582. If NORESPONSE is specified, then no response line and header will be
  583. sent either, even for an HTTP/1.0 request; the connection will be
  584. closed.  This option could be used for testing, or if (say) a faulty
  585. client was sending repeat messages.
  586.  
  587. NODATA is a 'completion command'.
  588.  
  589.  
  590. READ command
  591. ''''''''''''
  592. Syntax:
  593.  
  594.   READ [BODY|HEADER] {VAR varname | FILE [APPEND] NAME filespec}
  595.  
  596. Reads (receives) information from an HTTP client.  Either the header
  597. lines or the body data are read, depending on whether HEADER or BODY was
  598. specified, respectively.  The default action is to read the body.
  599. Then:
  600.  
  601.   o If 'VAR varname' was specified, the header or body data are placed
  602.     in the named Rexx variable, as a single string.  The name of the
  603.     variable is used just as if it appeared in the filter program (for
  604.     example, the name 'local.j' might have the value of J substituted in
  605.     the name).
  606.  
  607.   o If 'FILE NAME filespec' was specified, the data are written directly
  608.     to the file named by 'filespec'.  'filespec' should normally be a
  609.     fully qualified name (if it is not, GoServe will write the file in
  610.     its working directory).  'filespec' may not include an 'upwards
  611.     reference' sequence ("..\" or "../"), as such a sequence could
  612.     possibly allow clients to modify any file on the server machine.
  613.  
  614.     The named file is overwritten unless APPEND is specified (in which
  615.     case the data are written following the end of any existing data).
  616.  
  617. The READ command has no effect under the Gopher protocol, or if the
  618. client did not send an HTTP/1.0 request (though in both cases the
  619. command syntax is checked).
  620.  
  621.  
  622. RESPONSE command
  623. ''''''''''''''''
  624. Syntax:
  625.  
  626.   RESPONSE responseline
  627.  
  628. Specify an explicit HTTP response (status) line.  This replaces the
  629. default 'OK' response generated by GoServe, and should be of the form
  630. "HTTP/v.v nnn description", where 'v.v' refers to the HTTP version,
  631. 'nnn' is a 3-digit response code number, and 'description' is text (for
  632. example, the default is "HTTP/1.0 200 OK").
  633.  
  634. HTTP only allows certain code numbers to be used, so refer to the HTTP
  635. specification before using this command.  The text should be short, and
  636. is rarely seen, so GoServe will truncate the response line to 100
  637. characters if necessary.  If RESPONSE is executed more than once, the
  638. last-executed command value is used.
  639.  
  640. The RESPONSE command has no effect under the Gopher protocol (though the
  641. command syntax is checked).  It also has no effect if the incoming
  642. request uses HTTP/0.9 -- in this case, the protocol does not permit a
  643. response line to be returned, as it would be treated as part of the
  644. data.
  645.  
  646.  
  647. STRING command
  648. ''''''''''''''
  649. Syntax:
  650.  
  651.   STRING string
  652.  
  653. The single string is returned to the client, with suitable preamble and
  654. termination, depending on the protocol being used.
  655.  
  656. The STRING command can be used to return a simple message to the client.
  657. Multiple lines can be sent, if necessary, by embedding a CR-LF sequence
  658. ('0d0a'x) to separate lines.  A CR-LF is not needed at the end of the
  659. string.
  660.  
  661. After this command has ended, the connection to the client is closed, so
  662. this is a 'completion command'.
  663.  
  664. Command return codes
  665. ''''''''''''''''''''
  666. When commands end, they report any errors or failures by setting the
  667. Rexx variable RC.  A value of zero indicates normal execution (no error
  668. or failure was found), a positive value indicates an error, and a
  669. negative value a failure.  All command errors and failures are audited
  670. with audit type 'E' (if auditing of errors is enabled).
  671.  
  672. The possible values for command return codes follow.
  673.  
  674. --- Errors ---
  675.  
  676. Errors indicate that the command was in error (perhaps a syntax error)
  677. or the data it processed was in error.  The following errors may occur:
  678.  
  679.   [11] Response already completed
  680.   [21] Missing keyword in command
  681.   [22] Bad keyword in command
  682.   [23] Bad value in command
  683.   [24] Junk on end of command
  684.   [25] Header key not found
  685.   [31] Unable to open file
  686.   [32] Unable to read file
  687.   [33] Unable to write file
  688.   [34] Unable to write audit
  689.   [40] Bad variable name
  690.   [41] Could not set variable
  691.   [50] Missing Content-Length
  692.   [51] Bad Content-Length
  693.   [52] Zero Content-Length
  694.   [53] Multiple READ BODY requested
  695.  
  696. --- Failures ---
  697.  
  698. Failures are indicated when a command encounters an unexpected or
  699. serious condition, such as a failure of the TCP/IP network or some limit
  700. being exceeded.  The following failures may be reported:
  701.  
  702.   [-1] Inactive timeout exceeded
  703.   [-2] Total timeout exceeded
  704.   [-3] Header bytes limit exceeded
  705.   [-4] Body bytes limit exceeded
  706.   [-5] Out of memory
  707.   [-6] Failure reading from network
  708.   [-7] Failure sending to network
  709.   [-8] Unknown command
  710.  
  711.  
  712. Filter functions
  713. """"""""""""""""
  714. In addition to GoServe commands, filters may use certain routines
  715. provided by GoServe.  These may be invoked either as functions or by the
  716. CALL instruction, and are listed in the following sections.
  717.  
  718.  
  719. DATADIR function
  720. ''''''''''''''''
  721. Syntax:
  722.  
  723.   DATADIR()
  724.  
  725. This returns the data directory name (e.g., 'd:/gohttp/') set up by
  726. using the DATADIR option when starting GoServe or by using the DataDir
  727. options page.  (Once changed, GoServe records the data directory
  728. associated with each port.)
  729.  
  730. The directory name will always end in a '/', and will use '/' as the
  731. directory separator, "URI-style".
  732.  
  733.  
  734. GMTOFFSET function
  735. ''''''''''''''''''
  736. Syntax:
  737.  
  738.   GMTOFFSET()
  739.  
  740. This returns the current offset from Greenwich Mean Time (GMT), in
  741. seconds.  A positive result indicates that your local time is ahead of
  742. GMT by that amount.
  743.  
  744. If GMT cannot be computed because the TZ environment variable was not
  745. set, the function returns a question mark (the character '?').  See
  746. "Setting the TZ environment variable" for more information.
  747.  
  748.  
  749. PACKUR function
  750. '''''''''''''''
  751. Syntax:
  752.  
  753.   PACKUR(string)
  754.  
  755. Takes a single string, expressed according to the Universal Resource
  756. (UR) specification (RFC 1630), as an argument and returns a packed
  757. string.  That is, hexadecimal escape sequences (such as '%7E') are
  758. reduced to the character encoding that they represent (in this case,
  759. '~').
  760.  
  761. PACKUR is especially useful for processing the incoming data from a
  762. form, in which UR encoding is used.  See the sample GOFILTER.80 for an
  763. example of this use.
  764.  
  765.  
  766. PACK64 function
  767. '''''''''''''''
  768. Syntax:
  769.  
  770.   PACK64(string)
  771.  
  772. Takes a single string, expressed according to the MIME "Base64"
  773. specification (in RFC 1521), as an argument and returns the decoded
  774. (packed) string.  Each four bytes in 'string' is packed to three bytes
  775. in the result (except possibly for the last four bytes); 'string' must
  776. be a multiple of 4 bytes.  If any deviation from these specifications
  777. (or from the RFC 1521 "Base64" character set) is found, the null string
  778. is returned.
  779.  
  780. PACK64 is useful for processing the incoming user/password data encoded
  781. for the HTTP 'basic access authentication scheme' -- see the HTTP
  782. documentation for details.
  783.  
  784.  
  785. REQFIELD function
  786. '''''''''''''''''
  787. Syntax:
  788.  
  789.   REQFIELD(identifier [, count])
  790.  
  791. Searches the HTTP request header for a line that starts with the
  792. specified identifier, and returns the value for that identifier.
  793. Continuations are included in the value (if the continuation was
  794. indicated by the tab character, the tab character is replaced with a
  795. space).
  796.  
  797. The identifier may optionally end with a colon, and the search is
  798. case-insensitive.  If no matching identifier is found (or if there is no
  799. HTTP request header), the null string is returned.
  800.  
  801. The second, optional, argument determines which value is returned if
  802. more than one line starts with the given identifier: if no count is
  803. given, the last matching line is used.  If a count is given, then it
  804. identifies which of the values is to be returned.  For example,
  805.  
  806.   reqfield("accept", 3)
  807.  
  808. would return the value of the third 'Accept:' line in the header
  809. (perhaps "text/html"); if there was no third 'Accept:' line, then the
  810. null string would be returned.
  811.  
  812.  
  813. SERVER function
  814. '''''''''''''''
  815. Syntax:
  816.  
  817.   SERVER([option])
  818.  
  819. The returns the name of the server software.  If 'option' is omitted or
  820. begins with the character 'N' (either case) then this is the full name
  821. of the server software, followed by a comma, the word 'version', and the
  822. version number of the server.  For example, 'GoServe for OS/2, version
  823. 1.88'.
  824.  
  825. If 'option' begins with the character 'H' (either case) then the HTTP
  826. short name is returned, for example, 'GoServe/1.88'.  This is the same
  827. as the value returned in the HTTP header field "Server:".
  828.  
  829.  
  830. SERVERNAME function
  831. '''''''''''''''''''
  832. Syntax:
  833.  
  834.   SERVERNAME()
  835.  
  836. This returns the primary host name of the server (for example,
  837. 'fred.mynet.org'), or if that should not be available, the name in
  838. numeric form (e.g., 12.34.56.78).
  839.  
  840. If the latter case, your TCP/IP installation probably needs adjustment.
  841. For example, if running in loopback mode and not on a real network, your
  842. HOSTS file in TCPIP\ETC should contain your host name.  Check also to
  843. see what your TCP/IP HOSTNAME command (from an OS/2 prompt) returns;
  844. again, it should be a full symbolic name (not the numeric form).
  845.  
  846.  
  847. Running GoServe
  848. """""""""""""""
  849. GoServe may be started in any of the usual ways, such as from an OS/2
  850. command line or from a Program Reference object.  You should always
  851. specify the protocol to be used (HTTP or GOPHER) as a parameter to the
  852. command.  GoServe defaults to the Gopher protocol at present.
  853.  
  854. This section describes first the user interface to GoServe, and then
  855. details the parameters that may be used when starting GoServe.
  856.  
  857. The GoServe window
  858. ''''''''''''''''''
  859. Once GoServe has started, a PM window should appear.  By default, a menu
  860. bar is displayed giving access to the 'Options' notebook and an
  861. 'Actions' drop-down menu.  Access to these is also provided at all times
  862. by a pop-up menu if you click on the window with the context menu mouse
  863. button (usually button 2).
  864.  
  865. To change the background color of the window, select the color of your
  866. choice from the OS/2 color palette, drag it to the GoServe window, and
  867. drop it.  The color should change immediately.
  868.  
  869. The window is used to display a summary of the current and past activity
  870. of GoServe.  If it is large enough, it will include at the top a bar
  871. display that shows any client activity (the full width of the bar
  872. corresponds to the maximum number of clients allowed).  A half-height
  873. grey bar indicates the peak activity seen since GoServe was started.
  874. This may be reset to zero by selecting 'Reset peak indicator' from the
  875. Actions menu, and will be shown in purple if any errors have been
  876. counted.
  877.  
  878. The second line of the window gives the total number of transactions
  879. initiated since GoServe started, and the average response time of the
  880. last 100 transactions.  The color of this number changes to indicate
  881. whether the response time goal is being attained; you can change the
  882. goal (or turn off the coloring in the main window) using the 'Response'
  883. page of the Options notebook.  The response time is replaced by a count
  884. of errors, if any have occurred.
  885.  
  886. If room, the second line shows on the right the instantaneous count of
  887. connected clients and the peak number recorded since GoServe started (if
  888. more than one).
  889.  
  890. The transaction count may be reset to zero by selecting 'Reset
  891. transaction count' from the Actions menu).  Similarly, the response time
  892. record, error count, and peak count may also be reset to zero.
  893.  
  894. The third line shows the number of bytes, thousands of bytes, or
  895. millions of bytes sent and received since GoServe started.  These counts
  896. may be reset to zero by selecting 'Reset byte counts' from the Actions
  897. menu.  The Actions menu also offers 'Reset all counts', which resets
  898. all of the counters.
  899.  
  900. The fourth line of the window displays two timestamps; on the left is
  901. shown the time when GoServe last entered the 'idle' state (that is, was
  902. waiting for clients).  On the right is the time when GoServe was
  903. started (or when the last 'Reset All' was done).
  904.  
  905. Some or all of these items will be omitted if the window is too small
  906. for satisfactory display.
  907.  
  908. The Options notebook
  909. ''''''''''''''''''''
  910. If 'Options' is selected from the menu bar or pop-up menu, the Options
  911. notebook is opened.  This has the following pages:
  912.  
  913.   1. 'Response' shows response time statistics, and lets you control
  914.      the display and coloring of the statistics.
  915.  
  916.      At the top of the page, a bar chart shows the distribution of the
  917.      response times for recent requests, and (if there have been any
  918.      requests) the average response time.  This bar chart is redrawn
  919.      automatically whenever the number of connections returns to idle,
  920.      or you can refresh it manually by clicking on (selecting) the
  921.      chart.
  922.  
  923.      You can change the time-scale of this chart using the buttons at
  924.      the bottom right of the box.  Any measurements that would be
  925.      "off-scale" (to the right of the chart) are included in the
  926.      bar at the far right of the chart.
  927.  
  928.      The lower part of the page lets you set a response time goal using
  929.      a slider control; responses made within the specified time are
  930.      displayed on the bar chart in green; responses made within twice
  931.      that time are shown in an orangey-brown, and responses outside that
  932.      limit are shown in a medium-dark red.  The exact colors used will
  933.      depend on your display.
  934.  
  935.      The average response time shown on the page is colored according to
  936.      the the same rules, as is the less precise average response time
  937.      shown on the main window, if 'Color on main window' is checked.
  938.  
  939.      See "Response time recording" for more details.
  940.  
  941.   2. 'General' lets you change certain aspects of the appearance of the
  942.      main window, and control sounds made by the server.
  943.  
  944.      Two 'Main Window' check-boxes are provided:
  945.  
  946.        o 'Show menu bar' controls whether the menu bar is included in
  947.          the display.  To make menu selections when there is no menu
  948.          bar, click anywhere on the GoServe window with the context menu
  949.          button, in the usual Workplace Shell manner (this works even if
  950.          the menu bar is visible).
  951.  
  952.        o 'Surface on startup' lets you choose whether GoServe surfaces
  953.          its window when started (if not minimized when shut down).
  954.  
  955.      The 'Sounds on connections' checkbox requests that sounds be made
  956.      (using the PC speaker) when a client browser connects to the
  957.      server.  Radio buttons let you choose whether to hear a note (on a
  958.      ascending scale, depending on the number of connections) for every
  959.      connection, or to hear a note only when the server moves from being
  960.      idle to being busy (one or more connections).
  961.  
  962.   3. 'Audit' lets you control the auditing of transactions (which events
  963.      are to be audited, and whether timestamps in the file are in local
  964.      time or GMT).  See "The Audit mechanism" for more details.
  965.  
  966.   4. 'Limits' (two pages) is used to control the operating limits of the
  967.      server.  See "The Limits options pages" for details.
  968.  
  969.   5. 'DataDir' lets you specify a new data directory name (path).  This
  970.      name is made available to the Rexx filter via the DataDir()
  971.      function, and may be used by the filter to find the data to be
  972.      served.  (But note that the filter may ignore this information, if
  973.      appropriate.)
  974.  
  975.      GoServe will convert backslashes ('\') in the name to URI form
  976.      (forward slashes, '/'), and will add a trailing '/' if one is not
  977.      present.  For example, entering 'd:\myhome' would result in the
  978.      directory specification 'd:/myhome/' being passed to the filter via
  979.      the DATADIR() function.  This page checks that a drive is specified
  980.      so it is not accidentally omitted.
  981.  
  982.   6. 'Filter' lets you specify a new filter name.  This must be a simple
  983.      filename and extension (the extension will default to the port
  984.      number, if omitted).
  985.  
  986.      The filter must be in the GoServe working (current) directory, so
  987.      no drive or directory path should be specified.  For example, if
  988.      you enter 'myfilter.80', this would result in the filter
  989.      'd:\goserve\myfilter.80' being used, if 'd:\goserve' is the working
  990.      directory.  The filter must exist in the GoServe working directory
  991.      in order for a new name to be accepted.
  992.  
  993. --- The Apply button ---
  994.  
  995. The 'Limits', 'DataDir', and 'Filter' pages let you choose when to apply
  996. the change or changes that you make, by clicking on the 'Apply' button
  997. (or pressing the Enter key).  The Apply button is only enabled when you
  998. have made a change and all fields on the page are valid.  If you leave a
  999. page (or close the notebook) when the Apply button is enabled, the
  1000. changes will be applied automatically at that time.
  1001.  
  1002.  
  1003. The Limits options pages
  1004. ''''''''''''''''''''''''
  1005. The 'Limits' pages in the Options notebook let you change various limits
  1006. which apply to running GoServe.  The limits are grouped into three sets:
  1007. limits affecting clients, timeouts, and (on the second page) limits
  1008. restricting incoming data.
  1009.  
  1010. --- Clients limits ---
  1011.  
  1012. The 'Clients' set has three limits:
  1013.  
  1014.   1. 'Maximum at once' -- the maximum number of client connections
  1015.      allowed concurrently [default 20].  Additional requests for
  1016.      connection will be refused.  This count lets you limit the maximum
  1017.      load on your server, which is especially useful if it is also being
  1018.      used as a personal workstation.  Note that some Web clients, such
  1019.      as Web Explorer, may make four or more connections at the same
  1020.      time, to download inline graphics in parallel.
  1021.  
  1022.   2. 'Show warning at' -- the percentage at which the bar chart will
  1023.      show a red warning indicator [default 75%].  This gives a visual
  1024.      indication of heavy use of your server at a given instant (the peak
  1025.      use is also shown on the bar display).
  1026.  
  1027.   3. 'Open files per client' -- the maximum number of open files
  1028.      allowed, per client filter [default 5].  Increase this if you expect
  1029.      your GoServe filter to have more than five files open at a time.
  1030.  
  1031. --- Timeouts ---
  1032.  
  1033. The 'Timeouts' set also has three limits; the first two timeout settings
  1034. control the time at which any uncompleted response may be terminated
  1035. automatically by GoServe's "watchdog" thread, and the third determines
  1036. how long GoServe will wait, on startup, for TCP/IP to become available:
  1037.  
  1038.   1. 'End client after inactive' -- the "inactive timeout", in seconds.
  1039.      A connection will be closed if the specified time passes without
  1040.      any data being received or transmitted over the connection.  The
  1041.      default is 60 seconds.
  1042.  
  1043.   2. 'End client after total' -- the "total timeout", in seconds.  A
  1044.      connection will be closed if the specified time passes since the
  1045.      client connected to the port, even if there appears to be activity.
  1046.      This value must not be less than the inactive timeout, and defaults
  1047.      to 600 seconds.  As a rule of thumb, this timeout might be set to a
  1048.      number of seconds equal to or larger than the size of your largest
  1049.      data file, expressed in kilobytes.  This allows for transmission of
  1050.      the file over a slow link running at one kilobyte per second.
  1051.  
  1052.   3. 'Wait for TCP/IP start' -- the "start timeout", in seconds.  This
  1053.      is the time for which GoServe will wait on startup for TCP/IP to
  1054.      become operational, while retrying appropriate TCP/IP calls as
  1055.      necessary [default 600 seconds].  This allows asynchronous starting
  1056.      of TCP/IP and GoServe.  A value of 0 seconds means immediate
  1057.      timeout (that is, no retrys are performed, and GoServe will not
  1058.      start if an error is found).  No TCP/IP retry is attempted if the
  1059.      requested port is in use (that is, it is likely that another copy
  1060.      of GoServe is already running).
  1061.  
  1062. Notes on timeouts:
  1063.  
  1064.   1. For the first two timeouts, a value of zero seconds may be
  1065.      specified to indicate an indefinite time (that is, the timeout
  1066.      check is not made).  You should only set both timeouts to zero if
  1067.      the filter is trusted, the data it accesses is always available
  1068.      locally, and all clients used with the server have a timeout
  1069.      mechanism.
  1070.  
  1071.   2. When the timeout takes place there may be some delay (typically up
  1072.      to 15 seconds) before the transaction is interrupted.  If the Rexx
  1073.      filter is still running, it will have the HALT condition raised
  1074.      during this process; the HALT condition may be trapped by CALL ON
  1075.      HALT or SIGNAL ON HALT for necessary cleanup which should normally
  1076.      be followed by an immediate EXIT.
  1077.  
  1078. --- Incoming data ---
  1079.  
  1080. The 'Incoming data' set is on the second Limits page (use the rightmost
  1081. button at the bottom of the first page, or Alt+Page Down, to get to it).
  1082. It has two limits which restrict how much incoming data will be accepted
  1083. by the server:
  1084.  
  1085.   1. 'Header size' -- the maximum size (in thousands of bytes) of header
  1086.      that will be accepted.  The transaction will be ended if a header
  1087.      is received that exceeds the specified size; this gives some
  1088.      protection against a client that sends an invalid or never-ending
  1089.      header.  This limit is used whenever a header is read, either
  1090.      automatically or because of the READ command.  The default is 10
  1091.      thousand bytes (10kB).
  1092.  
  1093.   2. 'Body data size' -- the maximum size (in thousands of bytes) of
  1094.      body data that will be accepted.  The transaction will be ended if
  1095.      a client sends data that exceeds the specified size, and an attempt
  1096.      is made to read it using the READ command.  The default is 50
  1097.      thousand bytes (50kB).
  1098.  
  1099. Parameters on the GoServe command
  1100. '''''''''''''''''''''''''''''''''
  1101. Keyword parameters may be used when starting GoServe to set the protocol
  1102. (one only) and the TCP/IP port used, the default data directory, and the
  1103. action taken after a serious failure:
  1104.  
  1105.   o The 'HTTP' parameter
  1106.  
  1107.     This indicates that GoServe is being used as a World-Wide Web
  1108.     server, using the Hypertext Transfer Protocol (HTTP).  When this is
  1109.     specified, the default port number is 80, the well-known port for
  1110.     HTTP (this may be overridden as usual by the PORT parameter), and
  1111.     other enhancements are enabled, including:
  1112.  
  1113.       o The TYPE option may (and should) be used on FILE responses from
  1114.         the filter.
  1115.  
  1116.       o Automatic processing of both incoming and outgoing HTTP headers
  1117.         is enabled (see "Automatic HTTP processing").
  1118.  
  1119.       o Tab characters have no special significance in request strings;
  1120.         the third argument passed to the filter is a 'clean' URI (see
  1121.         "Filter programs").
  1122.  
  1123.       o STRING and CONTROL command responses are returned as HTML
  1124.         documents.
  1125.  
  1126.   o The 'GOPHER' parameter
  1127.  
  1128.     This indicates that GoServe is being used as a Gopher server, using
  1129.     the Gopher Protocol.  When this is specified, the default port
  1130.     number is 70, the well-known port for Gopher (this may be overridden
  1131.     as usual by the PORT parameter).  The Gopher termination sequence (a
  1132.     line containing just a single '.') is added to TEXT files and STRING
  1133.     and CONTROL responses.
  1134.  
  1135.   o The 'PORT n' parameter
  1136.  
  1137.     The default port number for the selected protocol may be changed for
  1138.     special applications by using the PORT parameter when starting
  1139.     GoServe, for example:
  1140.  
  1141.       start goserve http port 801
  1142.  
  1143.     Servers started with different ports are independent; they use
  1144.     different filter programs, and maintain a different collection of
  1145.     options, window position information, audit file, etc.
  1146.  
  1147.     Note that the port number is used as the required file extension for
  1148.     some files--for port numbers greater than 999 you must therefore be
  1149.     sure that the working directory for GoServe is on a disk that
  1150.     supports extensions of more than three characters (for example, an
  1151.     HPFS disk).
  1152.  
  1153.   o The 'DATADIR d' parameter
  1154.  
  1155.     This sets the data directory name (path) that will be used for this
  1156.     port from the word following the keyword DATADIR.  This name will be
  1157.     used until the name is changed using the 'DataDir' Options notebook
  1158.     page or by starting GoServe with a different DATADIR parameter.  The
  1159.     name should normally include the drive on which the data is to be
  1160.     found.
  1161.  
  1162.     The data directory name is not used directly by GoServe, but is made
  1163.     available to the filter program via the DataDir() function--hence
  1164.     allowing one filter to handle different data directories without
  1165.     "hard-coding" their names in the filter.
  1166.  
  1167.     GoServe will convert backslashes ('\') in the name to URI form
  1168.     (forward slashes, '/'), and will add a trailing '/' if one is not
  1169.     present.  For example,
  1170.  
  1171.       start goserve http datadir d:\myhome
  1172.  
  1173.     would result in the directory specification 'd:/myhome/' being passed
  1174.     to the filter via the DATADIR() function.
  1175.  
  1176.   o The 'FILTER f' parameter
  1177.  
  1178.     This sets the filter name that will be used for this port from the
  1179.     word following the keyword FILTER.  This name will be used until the
  1180.     name is changed using the 'Filter' options notebook page or by
  1181.     starting GoServe with a different FILTER parameter.  The filter must
  1182.     be in the GoServe working (current) directory, so no drive or
  1183.     directory path should be specified.  For example:
  1184.  
  1185.       start goserve http filter myfilter.80
  1186.  
  1187.     would result in the filter 'd:\goserve\myfilter.80' being used, if
  1188.     'D:\goserve' is the working directory.
  1189.  
  1190.     If no file extension is specified (that is, no period is found in
  1191.     the name), the port will be added as the extension.
  1192.  
  1193.   o The 'QUIETFAIL' parameter
  1194.  
  1195.     Certain "catastrophic" errors (such as memory allocation errors, or
  1196.     a syntax error in the Rexx filter) are considered failures by
  1197.     GoServe; that is, they cause a message dialog to be displayed on the
  1198.     screen--once the message is acknowledged, GoServe ends.
  1199.  
  1200.     The QUIETFAIL parameter can be used to prevent the failure message
  1201.     dialog being displayed:
  1202.  
  1203.       start goserve http quietfail
  1204.  
  1205.     In this case, GoServe will end immediately after a failure (after
  1206.     attempting to audit the failure, as usual).
  1207.  
  1208. GoServe also accepts some experimental keyword parameters:
  1209.  
  1210.   o 'TRACE' copies audit information to the PMprintf window (without
  1211.     GoServe timestamps); this does not affect auditing to the audit
  1212.     file.  This lets you watch a trace of incoming requests, actions,
  1213.     and errors as they happen without needing to look at the audit file
  1214.     itself.
  1215.  
  1216.   o 'REUSE' allows reuse of the port, even if some other application (or
  1217.     TCP/IP) has not released it.
  1218.  
  1219.   o 'DIAG' shows TRACE information together with additional details of
  1220.     GoServe operation (also using PMprintf).  This diagnostic
  1221.     information is intended for development use and may change over
  1222.     time.  If you are observing unexpected GoServe behaviour, the DIAG
  1223.     option may show helpful information.  'DIAG2' and 'DIAGMSG' may
  1224.     provide even more verbose diagnostic information.  'DIAG' implies
  1225.     'REUSE'.
  1226.  
  1227. Any number of GoServe parameters may be specified; the parameters may be
  1228. in any order.  If a parameter with a value is specified more than once,
  1229. the last value is used.
  1230.  
  1231. GoServe return codes
  1232. ''''''''''''''''''''
  1233. When GoServe ends, a return code is returned to the caller (for example,
  1234. when invoked from a Rexx program, this return code is placed in the Rexx
  1235. variable RC).  The value is restricted by the operating environment to
  1236. be in the range 0 through 255; GoServe uses one of three possible
  1237. values:
  1238.  
  1239.   [0] Normal completion (user action or OS/2 shutdown).
  1240.   [1] GoServe was ended by the CLOSE filter command.
  1241.   [8] Abnormal completion (failure), such as a syntax error in the filter.
  1242.  
  1243.  
  1244. Greenwich Mean Time (GMT)
  1245. """""""""""""""""""""""""
  1246. The HTTP protocol (like most international networking protocols)
  1247. requires that dates and times, where used, be quoted in GMT.  The
  1248. personal computers on which OS/2 runs, however, do not require that a
  1249. GMT clock be available--instead, the clock is usually set to local time.
  1250.  
  1251. Various mechanisms are used in OS/2 to indicate and calculate the
  1252. current offset from GMT.  The most common is to use an OS/2 environment
  1253. variable named 'TZ', and for most people running GoServe this will
  1254. already be set (for example to 'EST5EDT' for the USA East Coast).  See
  1255. the separate section on the value of the TZ variable.
  1256.  
  1257. If TZ is not set, GoServe will only use local time (and HTTP protocols
  1258. and header fields that require GMT will not be used or generated).
  1259.  
  1260. If the TZ variable is set, GoServe will convert from local time to GMT
  1261. as appropriate.  It will also detect a clock dislocation (that is, when
  1262. the time-of-day clock is changed by more than 10 seconds) automatically,
  1263. and record and re-calculate the GMT offset when this occurs--such as
  1264. when you change your clock for daylight-savings time.
  1265.  
  1266. Notes:
  1267.  
  1268.   1. You can see the offset that GoServe has computed by using the
  1269.      CONTROL STATISTICS command or the GMTOFFSET() function.
  1270.  
  1271.   2. For a few seconds between when you change the time and when GoServe
  1272.      detects that it has been changed, incoming transactions may be
  1273.      processed with anomalous time data; to avoid this, stop GoServe
  1274.      before making large time adjustments and restart it afterwards.
  1275.  
  1276.   3. Files in the PC-DOS and OS/2 FAT and HPFS file systems are
  1277.      timestamped with the local time of creation or last modification.
  1278.      The time-zone and daylight savings regime of that zone (and hence
  1279.      the GMT offset) are not available.  GoServe therefore calculates
  1280.      the GMT timestamp of a file by using the current GMT offset.
  1281.  
  1282.   4. If you're running your machine as a dedicated Web server, you may
  1283.      want to set the clock to GMT and leave it set that way all year; in
  1284.      this case, set TZ to 'GMT0'.
  1285.  
  1286.  
  1287. Response time recording
  1288. """""""""""""""""""""""
  1289. GoServe records the response times of up to one hundred transactions.
  1290.  
  1291. 'Response time', here, means the time from when the client connection is
  1292. accepted to when the first data bytes are sent.  It may include the time
  1293. to receive some or all data from the client, but does not include the
  1294. time taken to send the response (which may be very large, and dependent
  1295. of network delays).  Response times of transactions ended due to a
  1296. timeout or other limit being exceeded are not recorded.
  1297.  
  1298. The average response time, to the nearest 0.01 second, is shown on the
  1299. main GoServe window, next to the transactions count (unless an error has
  1300. occurred).  A more precise figure, along with the number of transactions
  1301. over which it was recorded, is included in the CONTROL STATISTICS
  1302. response (this figure will not reflect the response time of the
  1303. transaction that initiates the CONTROL STATISTICS command).  The same,
  1304. more precise, figure is also shown on the 'Response' page of the Options
  1305. notebook.
  1306.  
  1307. The GoServe response time directly affects the response time seen by the
  1308. person using the client browser, so it is desirable to keep this as low
  1309. as possible; the 'Response goal' setting in the Options notebook is
  1310. provided to make it easier to judge the performance of your server
  1311. setup.
  1312.  
  1313. The response times record may be reset using CONTROL RESET RESPONSE (or
  1314. the Actions menu item 'Reset response times').
  1315.  
  1316.  
  1317. Automatic HTTP processing
  1318. """""""""""""""""""""""""
  1319. GoServe automates several aspects of the HTTP/1.0 protocol. (For full
  1320. details of the protocol, please see the HTTP specification.)  When an
  1321. HTTP/1.0 request is received, the HTTP header lines are read
  1322. automatically (if needed).  The Content-Length and If-Modified-Since
  1323. values are extracted as appropriate.
  1324.  
  1325. When a completion command is processed, GoServe will (if the incoming
  1326. request was HTTP/1.0) generate an appropriate response line and
  1327. HTTP header.  For example, for a FILE command with a given file TYPE,
  1328. this will include the following header lines:
  1329.  
  1330.   1. 'Server:'  The name and version of the server (e.g., 'GoServe/1.88').
  1331.  
  1332.   2. 'Date:'  The message origination date and time (only if GMT can be
  1333.       determined).
  1334.  
  1335.   3. 'Message-ID:'  A unique identifier for the message.  For example,
  1336.      '<19950101121030.80.123@my.host.name>', which is the local date and
  1337.      time that the server was started, the port which it is serving, and
  1338.      the transaction number, followed by the primary host name.
  1339.  
  1340.   4. 'Content-Type:'  The value set by the TYPE parameter.
  1341.  
  1342.   5. 'Content-Length:'  The length of the file (less 1, if TEXT was
  1343.      specified and the file ends in an EOF character).
  1344.  
  1345.   6. 'Content-Transfer-Encoding:'  Currently always 'binary'.
  1346.  
  1347.   7. 'Expires:'  Set to the current time (only if GMT is available and
  1348.      ERASE was specified on the FILE command).
  1349.  
  1350.   8. 'Last-Modified:'  Set to the timestamp of the file, converted to
  1351.      GMT (only if GMT is available and ERASE was not specified).
  1352.  
  1353. Finally, GoServe will not actually send the body of the file if the
  1354. request verb was HEAD or if the 'Last-Modified' date is older or the same
  1355. as the first 'If-Modified-Since' date found in the request header (if
  1356. any).  In this latter case, the response line will be 'HTTP/1.0 304 Not
  1357. Modified'.
  1358.  
  1359. Notes:
  1360.  
  1361.   1. If the response line has been set explicitly by the RESPONSE
  1362.      command, this overrides any possible "Not Modified" response, and
  1363.      so the 'If-Modified-Since' check does not take place (that is, the
  1364.      body of the response will be sent).
  1365.  
  1366.   2. If the client does not send the header within a short time after
  1367.      the request string, the 'If-Modified-Since' check may be bypassed.
  1368.      This bypass is to allow for some older clients that are not fully
  1369.      HTTP/1.0 compliant, and may be removed later.
  1370.  
  1371.   3. GoServe does not automatically send a "MIME-Version" header field,
  1372.      as it can make no guarantee that the message as a whole is
  1373.      MIME-compliant (and in most cases it will not be).
  1374.  
  1375.  
  1376. The audit mechanism
  1377. """""""""""""""""""
  1378. GoServe includes a built-in audit mechanism that records events in an
  1379. audit file while GoServe is running.  This maintains a record of usage,
  1380. and also records any errors or failures of the server.
  1381.  
  1382. By default, all audit information (see details below) except selectors
  1383. is recorded.  Choose the 'Audit' page of the Options notebook for
  1384. detailed control over which audit information will be written to the
  1385. audit file.  You should only select auditing of 'Selectors' if the
  1386. recording of selectors (request strings) would not compromise
  1387. confidentiality or privacy.
  1388.  
  1389. The audit file has a fixed filename (GOAUDIT), with an extension that is
  1390. the TCP/IP port number used (for example, 'GOAUDIT.80').  It is written
  1391. in the working directory for GoServe.
  1392.  
  1393. For reliability, the audit file is written directly to disk and not
  1394. cached by the file system (though GoServe caches some informational
  1395. lines briefly to optimize response time).  The audit file may be read
  1396. but not altered while GoServe is running.
  1397.  
  1398. Each line in the audit file starts with three words, separated by one or
  1399. more blanks: the time (hhmmss), the audit type (one character), and the
  1400. transaction number (a number, incremented for each request accepted,
  1401. that begins at 0 when GoServe is started).  Additional information
  1402. follows, depending on the audit type:
  1403.  
  1404.   A (Accept)      - the numeric TCP/IP address of the client (n.n.n.n)
  1405.   C (Complete)    - response time (secs), and description of action
  1406.   D (Day/Time)    - the current day (yyyymmdd), and description of adjustment
  1407.   E (Error)       - description of an error in processing (e.g., timeout)
  1408.   F (Failure)     - description of the failure (terminating error)
  1409.   I (Information) - description of information (statistics, etc.)
  1410.   N (Network)     - description of how network or client ended transaction
  1411.   P (Port)        - server identity and port (n.n.n.n nn)
  1412.   S (Selector)    - selector received from client
  1413.   U (User)        - description of event from User (filter) command
  1414.  
  1415. The times (and dates) recorded in the audit file may be in GMT (the
  1416. default) or in local time (the default for GoServe 1.41 and earlier).
  1417. The default may be altered using the 'Audit Selection' dialog, but note
  1418. that use of GMT is only possible if GMT times are available (that is,
  1419. the TZ environment variable was set when GoServe was started or when a
  1420. time dislocation was detected).  If GMT is in use, the word 'GMT' is
  1421. added after the current day on 'D' audit lines.
  1422.  
  1423. Additional audit types may be added later.  The format of any
  1424. "description" in the above is not strictly defined, except that all
  1425. Carriage Return, Line Feed, and End of File characters (ASCII '0d'x,
  1426. '0a'x, and '1a'x) are translated to '[', ']' and '#' respectively to
  1427. ensure audit file lines are well defined.
  1428.  
  1429. For example:
  1430.  
  1431.   103701 D 0 19941225 GMT ----- GoServe 1.71 -----
  1432.   103701 P 0 9.20.5.59 80
  1433.   103726 A 1 9.20.5.59
  1434.   103726 S 1 GET / HTTP/1.0
  1435.   103727 C 1 0.9 Sent file "d:/gohttp/index.htm" [879 bytes]
  1436.   103727 A 2 9.20.5.59
  1437.   103727 S 2 GET /pmglobe.gif HTTP/1.0
  1438.   103728 C 2 0.95 Sent file "d:/gohttp/pmglobe.gif" [1956 bytes]
  1439.   103737 A 3 9.20.5.59
  1440.   103737 S 3 GET /globe?22,40 HTTP/1.0
  1441.   103738 C 3 0.9 Sent string "You clicked on the globe at [-36%, -16%]"
  1442.   103745 A 4 9.20.5.59
  1443.   103745 S 4 GET /samptest.htm HTTP/1.0
  1444.   103746 C 4 1 Sent file "d:/gohttp/samptest.htm" [461 bytes]
  1445.   103750 A 5 9.20.5.59
  1446.   103750 S 5 GET /!statistics HTTP/1.0
  1447.   103750 C 5 0.8 Control STATISTICS successful
  1448.   103808 I 5 Bytes sent 5676 received 3045
  1449.   103808 I 5 Close
  1450.  
  1451. Most transactions will end normally, with a 'C' line in the audit file.
  1452. If an error occurs, there may be one or more 'E' lines in the audit file
  1453. instead.  If a transaction is ended by the client or network, than an
  1454. 'N' line is used, which is not recorded as an error.
  1455.  
  1456. The response time recorded on 'C' lines is rounded down to the nearest
  1457. millisecond below, and measures the total elapsed time from receiving
  1458. the request to the first send of data to the client.  This depends on
  1459. the speed of the processor and the work done by the filter, and may also
  1460. depend on network speed if data is read by the filter.  (See "Response
  1461. time recording".)
  1462.  
  1463. After a FILE command, the time to send the data (as observed by the
  1464. server) is also included at the end of the description on the 'C' line.
  1465. This depends on the speed and activity of the server, client, and the
  1466. network between the two.  It is likely to be rather variable.
  1467.  
  1468. --- Viewing or archiving the audit file ---
  1469.  
  1470. To look at an 'active' audit file, use a program or command that allows
  1471. shared reading of files.  TYPE is one such command; its output may be
  1472. redirected to a file to take a snapshot copy of the audit file.  For
  1473. example:
  1474.  
  1475.   type goaudit.80 > snapshot.log
  1476.  
  1477. In addition, the Actions pull down menu has an item 'Move audit to
  1478. archive'.  This closes the audit file, appends it to the GoServe archive
  1479. file in the current working directory, then erases and re-opens the
  1480. audit file.  The GoServe filter can also initiate this action, by
  1481. returning "control moveaudit"--see "CONTROL command" for details.
  1482.  
  1483. The GoServe archive file has a fixed filename (GOARCH), with an
  1484. extension that is the TCP/IP port number used (for example,
  1485. 'GOARCH.80').  It is only touched by GoServe during a "Move audit to
  1486. archive", so is readily copied, edited, or renamed.
  1487.  
  1488.  
  1489. Remote control of GoServe
  1490. """""""""""""""""""""""""
  1491. GoServe filters (see "Filter programs") can request that GoServe perform
  1492. certain actions, instead of just returning files or other data.  These
  1493. requests may be used to control GoServe remotely (from another machine
  1494. or from another process on the same machine).  Control requests can
  1495. return a document containing one or more response lines, either showing
  1496. successful completion of the request or indicating an error.
  1497.  
  1498. Specifically, if the CONTROL command is used without the VAR option
  1499. (either from within the filter program or by being returned by the
  1500. filter) then the command action is performed and the result string is
  1501. returned to the client as a document.
  1502.  
  1503. The sample filters include examples of using control commands initiated
  1504. from standard menus or documents; these actions can be triggered
  1505. remotely using a Gopher or Web client, as appropriate.  Rexx programs
  1506. can also use the OS/2 TCP/IP RxSock library (included in the UN64092
  1507. CSD, August 1994) to send a specific request to a GoServe server.  A
  1508. sample command, MOVEAUD.CMD, is included in the GoServe package as an
  1509. indication of how this is used.
  1510.  
  1511. The filter mechanism provides flexibility in how control requests are
  1512. accepted and passed to GoServe, including the possibility of
  1513. modification so that only clients with certain addresses would be able
  1514. to use these options.  The sample Web filter includes an example of how
  1515. this might be done.
  1516.  
  1517.  
  1518. Why not CGI?
  1519. """"""""""""
  1520. Many Web servers support a protocol known as the Common Gateway
  1521. Interface (CGI) for attaching and supporting scripts.  GoServe does not
  1522. support this interface due to a number of difficulties with the design,
  1523. of which the most significant (in no particular order) are:
  1524.  
  1525.   o The primary means of communicating information to scripts is by the
  1526.     use of environment variables.  These all have to be set before the
  1527.     script is called, and as the number of these grow the overhead
  1528.     approaches or exceeds the cost of interpreting the script.  For
  1529.     GoServe, Rexx variables could be set on startup -- but a clearer and
  1530.     more efficient way of retrieving information is to use specialized
  1531.     function calls (such as GoServe's REQFIELD) or general commands
  1532.     (such as XEDIT's EXTRACT or GoServe's READ and CONTROL).
  1533.  
  1534.   o Environment variables are a per-process resource in OS/2; GoServe's
  1535.     scripts run on a per-thread basis (the script runs on the same
  1536.     thread that handles the incoming connection, with no process
  1537.     overhead or cleanup required).
  1538.  
  1539.   o The piping of the incoming data to the script would often mean that
  1540.     data is read even when unused, hence increasing the load on the
  1541.     server (and, in some cases, on the network and client browser).
  1542.  
  1543.   o For some servers, the output sent to the client is dependent on the
  1544.     name of the script (for example, scripts whose name begins with
  1545.     "nph-" may have their output treated differently from other
  1546.     scripts).
  1547.  
  1548.   o Server directives (commands sent to the server) are sent using the
  1549.     same namespace (header lines) as the header information being sent
  1550.     to the client.  Separating this information, as in GoServe, leads to
  1551.     a more reliable and extensible protocol.
  1552.  
  1553.   o Binary executables are loaded from .EXEs rather than as functions in
  1554.     a DLL (which would be at least twenty times faster).
  1555.  
  1556.   o Standard output is used as a data channel to the server; this means
  1557.     that the only data channel to the user (Webspinner) is standard
  1558.     error, which is inappropriate for informative or status information,
  1559.     often used while developing scripts.
  1560.  
  1561. For these reasons, it seemed unlikely that CGI scripts could be
  1562. supported directly (that is, without changes being required) with
  1563. reasonable efficiency by GoServe.  GoServe's filters provide equivalent
  1564. function, and the processing logic will be essentially unchanged, so
  1565. ports of the algorithms required are easy.
  1566.  
  1567.  
  1568. Setting the TZ environment variable
  1569. """""""""""""""""""""""""""""""""""
  1570. GoServe currently computes GMT from the local time-of-day clock (set by
  1571. the TIME and DATE commands) and the setting of the TZ environment
  1572. variable.  The simple form of the value of TZ (which is suitable for use
  1573. in the USA or other countries that change to and from daylight savings
  1574. time at the same time as the USA) is as shown in:
  1575.  
  1576.   SET TZ=EST5EDT
  1577.  
  1578. where EST is the standard time zone name (this must be exactly three
  1579. characters), EDT is the daylight savings time zone name (also exactly
  1580. three characters), and 5 is the difference between the standard time
  1581. zone and GMT, measured in hours West of GMT.
  1582.  
  1583. Note that the sign of the GMT offset used in the TZ variable is opposite
  1584. to that used for calculating the local time, given GMT, as returned by
  1585. the GoServe GMTOFFSET() function.
  1586.  
  1587. The simple form of TZ setting assumes that a 1 hour daylight savings
  1588. change starts at 01:00 on the first Sunday in April, and ends at 02:00
  1589. on the last Sunday of October.
  1590.  
  1591. For other countries, the full form of the TZ value has to be used.  More
  1592. formally, this is:
  1593.  
  1594.   SET TZ=SSS[+|-]nDDD,sm,sw,sd,st,em,ew,ed,et,shift
  1595.  
  1596. Where 'SSS', 'n', and 'DDD' are the values as in the simple form.  In
  1597. the long form, all the other values must be specified, as follows.
  1598.  
  1599. 'sm', 'sw', 'sd', and 'st' define the start time for daylight savings
  1600. adjustment, where:
  1601.  
  1602.   o 'sm' is the starting month (1 to 12)
  1603.  
  1604.   o 'sw' is the starting week (1 to 4 counting from the beginning, or -1
  1605.     to -4 counting from the end).  0 indicates that a particular day of
  1606.     the month is to be specified
  1607.  
  1608.   o 'sd' is the starting day (0 to 6 [where 0 is Sunday] if 'sw' is
  1609.     non-zero, or 1 to 31 if 'sw' is 0)
  1610.  
  1611.   o 'st' is the starting time in seconds from midnight (e.g., 3600 for
  1612.     01:00).
  1613.  
  1614. 'em', 'ew', 'ed', and 'et' define the end time for daylight savings, and
  1615. take the same values.
  1616.  
  1617. 'shift' is the shift in daylight time change, in seconds (e.g., 3600 if
  1618. one hour is to be added during daylight savings time).
  1619.  
  1620. For example, for the UK in 1995, the setting is expected to be:
  1621.  
  1622.   SET TZ=GMT0BST,3,0,26,3600,10,0,22,3600,3600
  1623.  
  1624. Note that there appears to be no provision for time zone names of more
  1625. than three characters (blanks are allowed, so fewer that three
  1626. characters are OK).  There also seems to be no provision for time zone
  1627. offsets that are not an integer number of hours.
  1628.  
  1629. []
  1630.