home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / gosrv250.zip / goserve.doc < prev    next >
Text File  |  1997-02-07  |  111KB  |  2,526 lines
  1.                                                                GoServe 2.50
  2. GoServe -- A Web and Gopher Server for OS/2
  3. """""""""""""""""""""""""""""""""""""""""""
  4.  
  5. Copyright (c) IBM Corporation, 1993, 1997.  All rights reserved.
  6.  
  7.  
  8. Introduction
  9. """"""""""""
  10. Two popular protocols for providing information on the Internet are the
  11. HyperText Transfer Protocol (HTTP, used by World-Wide Web clients) and
  12. Gopher (used by both Web and Gopher clients).
  13.  
  14. 'GoServe' is a multi-purpose server for OS/2 which supports both these
  15. protocols.  The emphasis in the design of GoServe has been to make it
  16. easy to become an information provider for the Internet, while not
  17. inhibiting full use of the protocols by sophisticated users.
  18.  
  19. Providing that you already have TCP/IP installed, GoServe can be running
  20. and serving files across a network in minutes; no re-boot or editing of
  21. configuration files is necessary.  The GoServe package includes 'quick
  22. start' instructions and working samples for both Web and Gopher servers.
  23.  
  24. GoServe processes requests from Web or Gopher clients using a Rexx
  25. script to allow for customization.  A server can handle requests from
  26. many clients, using OS/2 threads and script caching for efficiency.
  27. Multiple servers can be started (using different ports), and an audit
  28. trail of requests and actions can be recorded.  When running as a Web
  29. server, much of the complexity of the Web protocol is handled
  30. automatically; many GoServe users will only need to be concerned about
  31. the data being provided, and need not be concerned about the mechanism.
  32.  
  33. While running, a graphical display of GoServe activity is shown (the
  34. "Graphical Webspinner Interface"?), with optional response-time graphing
  35. and audible indication of connections.  For control, various
  36. restrictions may be employed to limit the load on the server machine.
  37. GoServe operations can be controlled remotely, if desired, using any Web
  38. client (or an OS/2 CMD program).
  39.  
  40. GoServe is a 32-bit OS/2 application, which requires OS/2 2.x or OS/2
  41. Warp.  GoServe requires IBM TCP/IP for OS/2, or equivalent, to be
  42. installed and operational (either on a real network or using the
  43. loopback driver).  GoServe may be used as both a Web server and a Gopher
  44. server on the same server machine, on one or more ports for each, if
  45. 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. --- Resources ---
  69.  
  70. This document, the latest GoServe package, and other relevant links,
  71. information, and programs are available at the GoServe Web page at
  72. http://www2.hursley.ibm.com/goserve/
  73.  
  74. Several GoServe users have contributed some very useful extensions to
  75. GoServe, and there's a mailing list too.  See, for example:
  76.  
  77.   o Don Meyer's CGI, Image Map, and forms support for GoServe, at:
  78.     http://w3.ag.uiuc.edu/DLM/GoHTTP/GoHTTP.html
  79.  
  80.   o Lew Waber's mail support and other enhancements, at:
  81.     http://lwaber.swmed.edu/goserve.htm
  82.  
  83.   o The OS/2 Forum Austria Extended GoServe Filter, at:
  84.     http://www.os2forum.or.at/software/local/ofaegf/
  85.  
  86.   o Ken Kavanagh's GoServe mailing list; the place to 'meet' other
  87.     GoServe users and share GoServe hints and tips; for details, see:
  88.     http://www.lionsgate.com/lists/goserve/
  89.  
  90. All of these are linked from the main GoServe page.
  91.  
  92.  
  93. How GoServe is used
  94. """""""""""""""""""
  95. GoServe is an ordinary 32-bit OS/2 application program (it has no
  96. special privileges, and uses only public interfaces to OS/2 and to
  97. TCP/IP).  When starting GoServe, you should specify as a parameter the
  98. protocol that the server is to use (HTTP or GOPHER).
  99.  
  100. Once started, GoServe sets up a TCP/IP socket on the 'well-known' port
  101. for the protocol selected (this can be altered using a different startup
  102. parameter), then waits for requests from clients.  When a request from a
  103. client arrives, it is recorded in the audit file (if desired) and then
  104. the GoServe filter for the port is called.
  105.  
  106. The GoServe filter is a program written in Rexx, which is given details
  107. of the client and the request string.  The filter decides on the
  108. information (usually a file, containing a document or other data) to be
  109. sent to the client, and returns details to GoServe.  GoServe then sends
  110. the HTTP response and the data to the client and closes the TCP/IP
  111. connection.
  112.  
  113. Each incoming request is given a new OS/2 thread for communication,
  114. filter processing, and response.  GoServe handles all the details of
  115. threads and TCP/IP communications, so you need only be concerned with
  116. the filter (which can often simply be the sample filter, unchanged) and
  117. the data (documents, images, etc.).
  118.  
  119. GoServe is designed to perform well, even on inexpensive hardware.  Some
  120. of the default settings, however, are chosen for safety rather than best
  121. performance.  To maximise performance and throughput, you may wish to
  122. turn on File command caching, Connection maintenance, and Lazy auditing
  123. (see below for details).  GoServe also runs faster with its display
  124. window minimized.
  125.  
  126.  
  127. Installation
  128. """"""""""""
  129. If you followed either of the 'getting started' documents, you will have
  130. already installed GoServe.  In general, only two files (plus data) are
  131. needed to run GoServe as a Web or Gopher server: the GOSERVE.EXE program
  132. file, and the appropriate Rexx filter.  The default filter name has
  133. filename GOFILTER, with an extension that is the TCP/IP port number to
  134. be used (for example, 'GOFILTER.80' for the filter for a default Web
  135. server, or 'GOFILTER.70' for the filter for a Gopher server).  The
  136. filter must be in the working directory for GoServe.
  137.  
  138. It is recommended that GOSERVE.EXE and the Rexx filter be placed in one
  139. directory (for example, 'D:\GoServe'), and data for the server be placed
  140. in a different directory.  By default, the latter is expected to be
  141. on the same drive as the GoServe directory, and named '\gohttp' for a
  142. Web server or '\gogopher' for a Gopher server.
  143.  
  144. Both the data directory and the filter name can easily be changed by
  145. using the GoServe options notebook or by a command line option, if
  146. required.
  147.  
  148. In all cases, the Rexx filter must be in the working directory for
  149. GoServe.  The working directory is also used by GoServe for the
  150. GOSERVE.INI file (which holds user settings, such as window position and
  151. audit selections), and for any Audit and Audit Archive files.
  152.  
  153. When you unzip the GOSERV.ZIP file, you should find the following files:
  154.  
  155.    goserve.doc  -- this document
  156.    gohttp.doc   -- how to get started as a Web server
  157.    gogopher.doc -- how to get started as a Gopher server
  158.    goserve.exe  -- the server program
  159.    gofilter.80  -- sample (working) filter for HTTP
  160.    gofilter.70  -- sample filter for Gopher
  161.    goremote.80  -- sample filter for WWW remote control of GoServe
  162.    moveaud.cmd  -- sample remote control command
  163.    makeicon.cmd -- installation aid
  164.  
  165.    gohttp.zip   -- sample pages, etc., for a Web server [unzip to a
  166.                    separate directory, perhaps D:\GoHTTP].  This also
  167.                    includes the GoServe Web documentation in HTML.
  168.    gogopher.zip -- sample menus, etc., for a Gopher server [unzip to a
  169.                    separate directory, perhaps D:\GoGopher]
  170.  
  171.    license.txt  -- IBM license agreement for OS/2 Tools
  172.  
  173. Please see the 'how to get started' documents for step-by-step
  174. instructions for installation.
  175.  
  176. --- Uninstalling GoServe ---
  177.  
  178. To uninstall GoServe, it is only necessary to delete the directories
  179. used by GoServe, with their contents.  No changes are made to the OS/2
  180. system.  (Note that prior to version 1.74, GoServe saved settings in
  181. OS2.INI.  Later versions automatically migrate this information to the
  182. GoServe working directory.)
  183.  
  184. --- Requirements ---
  185.  
  186. GoServe is a 32-bit OS/2 application, which requires OS/2 2.x or OS/2
  187. Warp.  For OS/2 Warp, version 1.31 (or later) of GoServe is needed.
  188.  
  189. GoServe requires TCP/IP for OS/2, or equivalent, to be installed and
  190. operational (either on a real network or using the loopback driver).
  191. Only the TCP/IP base kit should be needed, or the OS/2 Warp Internet
  192. Access Kit from the Bonuspak.
  193.  
  194. Over time, CSDs for TCP/IP become available--if TCP/IP problems are
  195. suspected, always try the latest CSD.
  196.  
  197. --- Running GoServe 'stand-alone' ---
  198.  
  199. GoServe and Web Explorer can be run on a stand-alone machine that is not
  200. connected to a network, provided that TCP/IP is installed and the
  201. loopback driver is started.  This is especially useful for developing
  202. Web pages offline, or for demonstrations.  To do this, two additions are
  203. needed to a standard TCP/IP installation (such as the OS/2 Warp Internet
  204. Access Kit):
  205.  
  206.   1. To the file called 'HOSTS' (no extension) in your \TCPIP\ETC
  207.      directory add the line:
  208.  
  209.        127.0.0.1  loopy
  210.  
  211.      where 'loopy' is the name by which you want your machine to be
  212.      known when using the loopback connection.  This name can be a
  213.      single word (e.g., 'loopy'), or an internet-style name (e.g.,
  214.      'loopy.my.org').  It's a good idea to have both formats, on two
  215.      lines:
  216.  
  217.        127.0.0.1  loopy.my.org
  218.        127.0.0.1  loopy
  219.  
  220.      Note: if you are running Warp Connect, the directory should be
  221.      \MPTN\ETC.  In general, check the value of the ETC environment
  222.      variable to find out where the HOST file should be placed.
  223.  
  224.      If there is no \xxx\ETC\HOSTS file, create one.
  225.  
  226.   2. Before running GoServe, execute the command:
  227.  
  228.        ifconfig lo 127.0.0.1
  229.  
  230.      This only needs to be run once, so can be run from STARTUP.CMD or
  231.      from any command referenced in your Startup folder.  Note that the
  232.      second word is the lowercase of the two letters 'L' and 'O'.
  233.  
  234. Once set up, you can then connect to GoServe on your own machine using
  235. (for example) the URL:
  236.  
  237.   http://loopy
  238.  
  239. With recent TCP/IP versions you can carry out step 2 above using the
  240. TCP/IP configuration notebook.  On the 'Network' page, click on
  241. 'loopback interface', then check 'Enable interface' and 'Manually,
  242. using', then enter '127.0.0.1' as the 'IP address'.
  243.  
  244. The loopback address will be active even when connected to a network, so
  245. you can always connect to GoServe running on the same machine using the
  246. loopback name that you chose, provided that your browser does not have a
  247. proxy or SOCKS server enabled (the proxy won't be able to find your
  248. local loopback address).
  249.  
  250. Even if you are not connected to a network, your browser should not have
  251. a proxy or SOCKS server enabled (or it will try and use the network to
  252. find it before checking the HOSTS file).
  253.  
  254.  
  255. Filter programs
  256. """""""""""""""
  257. Filter programs are written in Rexx.  Based on the arguments they are
  258. passed, they decide on the document or other data to be sent to the
  259. client and then issue a command or return a result that defines that
  260. data (usually a file) to the server.  GoServe then handles the
  261. transmission of the data to the client.
  262.  
  263. All requests are passed to the Rexx filter, so for every request you
  264. have full control over the response by modifying the filter as required.
  265. By default, GoServe will never send data to a client without the filter
  266. being involved.
  267.  
  268. The filter is cached (that is, it and its tokenized version are only
  269. read from disk when changed) and is executed on the same thread as the
  270. incoming request (not as a separate process).  This is very efficient;
  271. informal measurements suggest that only a small percentage of the total
  272. response time of a simple request is spent in running the filter.  For
  273. example, the total time to run the sample filter on a 486/50MHz PC has
  274. been measured under OS/2 2.11 and OS/2 Warp to be as little as 11ms.
  275.  
  276. For examples of filters and forms processing, please see the sample
  277. filters in the GoHTTP or GoGopher collections.  The following is
  278. specific technical information on how the filters work.
  279.  
  280. Three argument strings are passed to the filter:
  281.  
  282.   1. The source of the request.  This has five words [more words could
  283.      be added at the end in the future], separated by one or more
  284.      blanks:
  285.  
  286.        o the Internet address of the server for this request (in numeric
  287.          form).  This is normally constant, unless you have more than
  288.          one network defined; for example, a 'real' network and a
  289.          loopback configuration, or more than one network adapter card.
  290.  
  291.        o the server's port number used for the connection.
  292.  
  293.        o the transaction number (a number, incremented for each new
  294.          connection, that starts at 0 when GoServe is started).
  295.  
  296.        o the Internet address of the client (in numeric form).  Note
  297.          that this may not be the address of the end-user's machine, if
  298.          the connection is made through a proxy or firewall.
  299.  
  300.        o the client's port number used for the connection.
  301.  
  302.      Example: "9.15.11.189 80 101 9.20.25.65 1987"
  303.  
  304.   2. The request string.
  305.  
  306.        o For a Web server, this string is the HTTP request string,
  307.          exactly as received from the client.  This comprises three
  308.          words: the request verb (e.g., 'GET'), the URI (Universal
  309.          Resource Identifier) or partial URI, and the HTTP protocol
  310.          identifier (e.g., 'HTTP/1.0').  The third word may be absent
  311.          when older (HTTP/0.9) clients connect.  A URI of just '/'
  312.          indicates the initial contact from a client, and the filter
  313.          would normally respond with a default document ("home page").
  314.  
  315.          Partial URIs are (or should be) the request string from a Web
  316.          'href' attribute previously sent to the client, unchanged
  317.          [except that extra data, such as incoming data from forms, may
  318.          be suffixed, and a leading slash, '/', may be added].  For
  319.          more information on URIs, see the technical details available
  320.          on the Web.  A good place to start is the Web information
  321.          based at 'http://www.w3.org/'.
  322.  
  323.        o For a Gopher server, the request string is any data received
  324.          from the client up to (but not including) a Tab, Carriage
  325.          Return, or Line Feed.  An empty request string indicates the
  326.          initial contact from a client, and the filter would normally
  327.          respond with a default Gopher menu.  Otherwise, it will (or
  328.          should) be the request string from a Gopher menu line
  329.          previously sent to the client, unchanged.
  330.  
  331.      You have complete freedom in setting request strings in Web documents
  332.      and Gopher menus, and in deciding how the filter should respond
  333.      depending on the string received.  Very often, the name of a file is
  334.      used, and that file is sent to the client.  [Note: it is recommended
  335.      that fully qualified filenames NOT be used for request strings.]
  336.  
  337.   3. The extended request string.
  338.  
  339.        o For an HTTP server, this string is the "packed" URI or partial
  340.          URI.  This is the second word of the request string, with
  341.          escape sequences (e.g., '%7e') converted to a single byte, and
  342.          with any leading slash ('/'), if present, removed.
  343.  
  344.        o For a Gopher server, this is the 'Gopher+' data.  Some Gopher
  345.          clients can add additional information to a request, attached
  346.          to the request string after a Tab character.  GoServe discards
  347.          the Tab character and presents the remainder as the third
  348.          argument to the filter.  See Gopher protocol documents for
  349.          more information on how the extended selector string is used.
  350.  
  351. The filter can specify that GoServe send either a file or a single
  352. string to the client, or request certain other GoServe operations.
  353. All these operations are effected in the usual Rexx way, by using
  354. commands, which are described later in this document.  Other commands
  355. allow more detailed control of the server.
  356.  
  357. The filter may also return a result string to GoServe; this, too, is
  358. treated as a command.  [In early versions of GoServe, this was the only
  359. way to execute a GoServe command, so early GoServe filters only use that
  360. mechanism.]
  361.  
  362. In addition to the commands, GoServe provides several special-purpose
  363. functions for dealing with incoming requests.  For example, the
  364. PACKUR(string) function takes a string which has been encoded for safe
  365. transmission, and reduces escape sequences (such as '%7E') to the
  366. character encoding that they represent (in this case, '~').
  367.  
  368. Any failure of the filter (such as a syntax error) is considered
  369. catastrophic and will cause GoServe to end, to reduce the risk of
  370. unauthorized data transmission by a buggy filter.
  371.  
  372. Notes:
  373.  
  374.   1. Remember that GoServe will run multiple copies of the filter at
  375.      once, on different threads, if more than one client connects at the
  376.      same time.  If building temporary files, use the transaction number
  377.      (or request number) and port as part of the file name.
  378.  
  379.   2. The results of SAY instructions (or tracing) in the filter program
  380.      may be seen using the PMprintf package.  However, Rexx interactive
  381.      tracing is not supported.  PMprintf should be available from the
  382.      same source as GoServe, or from the GoServe Web page at
  383.      http://www2.hursley.ibm.com/goserve/
  384.  
  385.   3. You may change the name of the filter when starting GoServe or by
  386.      using the 'Filter selection' options page.  The filter must always
  387.      be in the working directory for GoServe.  If you make changes to
  388.      the default filter, it's a good idea to change its name, too, so if
  389.      you install a new version of GoServe your filter will not be
  390.      overwritten by the new default filter.
  391.  
  392.   4. External subroutines, written in Rexx, are easily called from the
  393.      filter simply by using their name in a CALL instruction or function
  394.      call.  The names should not match that of a Rexx built-in function,
  395.      and the routine should normally be in a file with the same
  396.      extension (e.g, '.80') as the filter and in the same directory.
  397.  
  398.   5. You can execute OS/2 commands from the filter using the Address CMD
  399.      instruction, for example:
  400.  
  401.        address cmd
  402.        'start e foo.bar'
  403.        'call d:\foobar\test.cmd argstring'
  404.  
  405.      Use caution when calling external programs before the response is
  406.      complete: any slowness directly affects the response time to the
  407.      client and its user.  Note also that separate processes (including
  408.      external commands) are not terminated automatically by GoServe if a
  409.      connection times out.
  410.  
  411.      Finally, when executing commands, do not build any part of the
  412.      command string from data received from the client; this could allow
  413.      execution of arbitrary commands on your server (for example, if an
  414.      '&' command separator character were included in the data).
  415.  
  416.   6. By default, each copy of a filter may have up to five files open at
  417.      once.  This limit may be increased using the Limits selection
  418.      dialog (see "The Limits options pages").
  419.  
  420.   7. A new version of the filter is only cached (loaded) when GoServe is
  421.      idle, and has been idle for 5-10 seconds.  Therefore, if you change
  422.      the filter while GoServe is running, the changes may not be used
  423.      until the first client connects after a time when there have been
  424.      no clients connected for ten seconds.
  425.  
  426.   8. For more information on Rexx, try connecting to the Rexx Language
  427.      page at: http://rexx.hursley.ibm.com/rexx/
  428.  
  429.      For more information on OS/2, start at the IBM home page
  430.      (http://www.ibm.com), and use the Search option to search for OS/2.
  431.  
  432.      Links to these and other useful pages may be found on the GoServe
  433.      home page at: http://www2.hursley.ibm.com/goserve/
  434.  
  435.  
  436. Filter commands
  437. """""""""""""""
  438. Commands may be executed by GoServe filters at any time, using the usual
  439. Rexx command syntax (a clause that is just an expression).  In addition,
  440. any string returned by the filter will be executed as a command.
  441.  
  442. For simplicity and efficiency, most requests can be satisfied by
  443. executing a single command which sends some data (often a file) to the
  444. client and then closes the connection.  These commands (CLOSE, CONTROL,
  445. FILE, NODATA, STRING, and VAR) are known as 'completion commands'; that
  446. is, after executing the command, the response to the client will have
  447. been sent and will be complete.
  448.  
  449. Only one completion command may be executed for each request received;
  450. once a completion command has been executed, no further commands will be
  451. accepted.
  452.  
  453. In some situations, it is useful to be able to build up the response
  454. from more than one data source; in this case, the SEND command is used
  455. to start the sending of the response.  One or more of the completion
  456. commands are then used to send the data (in this case, the connection is
  457. not closed after the commands), and then the connection is closed by
  458. using the SEND COMPLETE command.
  459.  
  460. When completion commands are executed, GoServe (actually, TCP/IP) will
  461. normally collect the data from them in a buffer and send packets of data
  462. when enough has been collected.  GoServe can be made to send the data
  463. immediately the commands are executed by using the command SET NETBUFFER
  464. OFF.
  465.  
  466. If the filter ends without error or sending any data and without
  467. executing or returning any completion command, the server will generate
  468. one (currently "String [No information available]").
  469.  
  470. Errors and failures in commands are reported by a non-zero return code
  471. (which is placed in the Rexx variable RC), and also may raise the ERROR
  472. or FAILURE condition if enabled by SIGNAL ON or CALL ON in the filter.
  473. Command errors are also audited unless Error auditing has been turned
  474. off.  For details on the possible return codes, see "Command return
  475. codes".
  476.  
  477. The total length of a command is limited to 1000 characters.
  478.  
  479. The most important commands are the completion commands, though there
  480. are others which will be useful to filter writers.  The commands follow
  481. in alphabetical order; note that keywords and file specifications may be
  482. in lower, upper, or mixed case.
  483.  
  484.  
  485. AUDIT command
  486. '''''''''''''
  487. Syntax:
  488.  
  489.   AUDIT string
  490.  
  491. The string supplied will be written to the Audit file as a 'user audit'
  492. line.  See "The audit mechanism" for a description of auditing.
  493.  
  494.  
  495. CLOSE command
  496. '''''''''''''
  497. Syntax:
  498.  
  499.   CLOSE
  500.  
  501. This command will cause GoServe to end, with return code set to 1, when
  502. all current connections have been completed.  No new connections will be
  503. accepted.  An acknowledgement is sent to the client, and the connection
  504. is then closed, so this is a completion command.
  505.  
  506.  
  507. CONTROL command
  508. ''''''''''''''''
  509. Syntax:
  510.  
  511.   CONTROL [VAR varname] options
  512.  
  513. A GoServe control action (such as moving the audit file, resetting
  514. counters, or requesting statistics) is initiated, and a result string is
  515. either placed in a Rexx variable or returned to the client.
  516.  
  517. This is used for controlling the GoServe server from the filter, either
  518. directly or on request from a remote client or from another process on
  519. the same machine -- for information on ways to do this, see "Remote
  520. control of GoServe".
  521.  
  522. The possible options are:
  523.  
  524.   o MOVEAUDIT
  525.  
  526.     The audit file is copied to the archive file (just as though the
  527.     'Move audit to archive' Actions menu item had been selected).
  528.  
  529.   o RESET [BYTES] [PEAK] [RESPONSE] [TRANSACTIONS] [LIMITS] [ERRORS] [ALL]
  530.  
  531.     The specified GoServe counters and statistics are reset (after
  532.     auditing, if appropriate).  Any or all of the keywords may be given,
  533.     in any order.  Each works in the same way as the corresponding
  534.     Actions menu item; RESPONSE refers to the response time record.
  535.  
  536.     If ALL is used, all of the items are reset, and a record of the time
  537.     is kept; this time will be shown on the display window and in any
  538.     statistics requests.
  539.  
  540.   o SAY string
  541.  
  542.     The given string is returned; this can be used as a simple 'Loopback
  543.     test'.
  544.  
  545.   o STATISTICS
  546.  
  547.     Current statistics and settings are returned.  These include:
  548.  
  549.       1. Transaction, error, limits, byte, and client counts, with
  550.          response time averages
  551.  
  552.       2. Certain settings and options (not including audit selections)
  553.  
  554.       3. The local time of certain events (if an event has not occurred,
  555.          it is shown as the GoServe start time).
  556.  
  557. The result of a CONTROL command is a single string, which may include
  558. multiple lines, separated by Carriage Return-Line Feed (CR-LF, ASCII
  559. '0d0a'x) sequences.  The exact format is not defined.  The result string
  560. is either placed in a variable or returned to the client:
  561.  
  562.   o If 'VAR varname' was specified, the result string is placed in the
  563.     named Rexx variable.  The name of the variable is used just as if it
  564.     appeared in the filter program (for example, the name 'local.j'
  565.     might have the value of J substituted in the name).
  566.  
  567.   o If 'VAR' was not specified, a document containing the string is
  568.     returned to the client (just as though the STRING command were
  569.     used), so in this case, CONTROL is a completion command.
  570.  
  571.  
  572. EXTRACT command
  573. '''''''''''''''
  574. Syntax:
  575.  
  576.   EXTRACT items
  577.  
  578. Extracts the state of one or more GoServe settings for use in a Rexx
  579. filter. 'items' is a list of one or more keywords, as specified in the
  580. QUERY and SET commands.  The values of the specified items are placed
  581. into Rexx variables of the same name.
  582.  
  583. For example:
  584.  
  585.   'extract diag diag2'
  586.   say 'DIAG flag is' diag', DIAG2 flag is' diag2
  587.   'set diag2 invert'
  588.   'extract diag2'
  589.   say 'DIAG2 flag is now' diag2
  590.  
  591.  
  592. FILE command
  593. ''''''''''''
  594. Syntax:
  595.  
  596.   FILE [ERASE] [TYPE content-type] [BINARY|TEXT] [NOCACHE] NAME filespec
  597.  
  598. The file named by 'filespec' will be sent to the client.  'filespec'
  599. should normally be a fully qualified name (if it is not, GoServe would
  600. look for it in the GoServe working directory).  Either forward or
  601. backward slashes may be used as directory separators; the OS/2 file
  602. systems accept either.
  603.  
  604. After this command has ended, the connection to the client is closed, so
  605. this is a completion command.
  606.  
  607. The optional keywords may be specified, in any order, and have the
  608. following effects:
  609.  
  610.   o ERASE -- the file is a temporary file, and should be erased after
  611.     being sent.  [The transaction or request number and port can be used
  612.     for generating a safe name for a temporary file.]
  613.  
  614.   o TYPE -- [HTTP protocol only] the file will be prefixed by an HTTP
  615.     "OK" response line and an HTTP header, including the content length
  616.     derived from measuring the file.  The value of the TYPE option
  617.     ('content-type') should be a Internet Media Type such as "text/html"
  618.     or "image/gif", of up to 120 characters and with no embedded spaces.
  619.     See notes below for more information.
  620.  
  621.     The TYPE option may only be used if GoServe is started with the HTTP
  622.     parameter (HTTP headers are not used by Gopher), and should normally
  623.     always be used when running as a Web server.
  624.  
  625.   o BINARY -- [default for HTTP] the file is a binary file, and form the
  626.     entire response to the client.  GoServe will close the TCP/IP
  627.     connection as soon as the complete file has been sent.
  628.  
  629.     A Gopher server should use this option for all files that are not
  630.     simple text or menus, for example ".ZIP" files, etc.
  631.  
  632.   o TEXT -- [default for Gopher] the file is a text file: any trailing
  633.     DOS end-of-file character will not be sent to the client.
  634.  
  635.     If running as a Gopher server, a Gopher terminator line (just a
  636.     period) will be sent at the end of the document, before the
  637.     connection is closed.
  638.  
  639.   o NOCACHE -- prevents this FILE command being cached (that is, this
  640.     command will not be associated with a request).  See "File command
  641.     cache" for more details.
  642.  
  643. Here are some examples:
  644.  
  645.   1. Returning an HTML file to a Web client:
  646.  
  647.        file type text/html name d:/gohttp/index.htm
  648.  
  649.   2. Returning a temporary image file to a Web client:
  650.  
  651.        file erase type image/gif name d:/gohttp/$7681.80
  652.  
  653.   3. Returning a .ZIP file to a Gopher client:
  654.  
  655.        file binary name d:/gogopher/gogopher.zip
  656.  
  657. Notes:
  658.  
  659.   1. The filespec may not include an 'upwards reference' sequence ("..\"
  660.      or "../"), as such a sequence could possibly allow clients access
  661.      to any file on the server machine.
  662.  
  663.   2. All data sent to a client with an HTTP header should be described
  664.      by a Content-Type field in the header; GoServe will therefore only
  665.      generate a header automatically if the TYPE option was specified or
  666.      the HEADER command has been used to add header lines.  In this
  667.      latter case, it is the responsibility of the filter to supply the
  668.      Content-Type field if the TYPE option was not used.
  669.  
  670.   3. Internet Media Types were formerly known as MIME (Multipurpose
  671.      Internet Mail Extensions) Content Types.  MIME is described in RFC
  672.      1521 and RFC 1522.  The media types are used in the HTTP protocol
  673.      so that clients can determine how to process data received from
  674.      servers.  Some common types are listed in the sample filter.
  675.  
  676.  
  677. HEADER command
  678. ''''''''''''''
  679. Syntax:
  680.  
  681.   HEADER [NOAUTO|NOTIME] [{ADD|DROP} value]
  682.  
  683. Adds a header line to the HTTP response header, or drops one already
  684. added.  Header lines added by this command are sent to the client after
  685. header lines generated automatically by GoServe.  They are all sent
  686. before any data; all HEADER commands must precede any commands that send
  687. data.
  688.  
  689. For example:
  690.  
  691.   HEADER ADD Title: My own title
  692.  
  693. Blanks following the keyword ADD or DROP are removed by GoServe, so
  694. continuation header lines must be started with the tab ('09'x)
  695. character.
  696.  
  697. If DROP is used, only the field identifier (up to and including the
  698. colon) should be specified.  The first header line that matches (of the
  699. lines added using HEADER ADD) is dropped, together with any following
  700. continuation lines; automatically generated header lines are not
  701. affected.  A case-insensitive comparison is used for determining a
  702. match.
  703.  
  704. NOAUTO may be used either alone on the command or in conjunction with
  705. the ADD or DROP form.  If any HEADER command specifies NOAUTO, no header
  706. lines will be automatically generated by GoServe (except the final empty
  707. line); all lines must be explicitly defined using HEADER ADD.  For
  708. example:
  709.  
  710.   HEADER NOAUTO ADD Server: Special/0.01
  711.   HEADER        ADD Title: Two-line header
  712.  
  713. NOTIME may be used either alone on the command or in conjunction with
  714. the ADD or DROP form.  If any HEADER command specifies NOTIME, no header
  715. lines that start with 'Expires:' or 'Last-Modified:' will be
  716. automatically generated by GoServe.  For example:
  717.  
  718.   HEADER NOTIME
  719.   HEADER NOTIME ADD Last-Modified: Mon, 23 Dec 1996 19:40:20 GMT
  720.  
  721. At least one keyword must be used on the HEADER command.  The HEADER
  722. command has no effect under the Gopher protocol (though the command
  723. syntax is checked).  It also has no effect if the incoming request uses
  724. HTTP/0.9 -- in this case, the protocol does not permit a header to be
  725. returned, as it would be treated as part of the data.
  726.  
  727.  
  728. NODATA command
  729. ''''''''''''''
  730. Syntax:
  731.  
  732.   NODATA [NORESPONSE]
  733.  
  734. No data are to be sent; the response is complete.  For an HTTP/1.0
  735. request, only a response line and header will be sent.  For a Gopher (or
  736. HTTP/0.9) request, the connection will simply be closed.  This command
  737. is intended to be used when only a header, or nothing at all, is to be
  738. returned to the client.
  739.  
  740. If NORESPONSE is specified, then no response line and header will be
  741. sent either, even for an HTTP/1.0 request; the connection will be
  742. closed.  This option could be used for testing, or if (say) a faulty
  743. client was sending repeat messages.
  744.  
  745. NODATA is a completion command.
  746.  
  747.  
  748. QUERY command
  749. '''''''''''''
  750. Syntax:
  751.  
  752.   QUERY items
  753.  
  754. Queries the state of various GoServe settings.  'items' is a list
  755. of one or more keywords.  The name and value of each item is displayed
  756. using PMprintf; to see the results the PMprintf console must be active.
  757. PMprintf should be available from the same source as GoServe, or from
  758. the GoServe Web page at http://www2.hursley.ibm.com/goserve/
  759.  
  760. Any item that can be set by the SET command may also be queried.  The
  761. value of any item that may be set or queried may also be obtained by a
  762. Rexx filter, using the EXTRACT command to place the values in Rexx
  763. variables.  PMprintf is not needed in order to use the EXTRACT command.
  764.  
  765. Valid items are:
  766.  
  767.   o BYTESREAD -- the number of bytes received from the network, so far
  768.     during the current transaction.
  769.  
  770.   o BYTESREADTOTAL -- the total number of bytes received from the
  771.     network.  You may need to increase the Rexx NUMERIC DIGITS setting
  772.     if you wish to do arithmetic on this count.  16 digits should be
  773.     sufficient.
  774.  
  775.   o BYTESSENT -- the number of bytes sent to the network, so far during
  776.     the current transaction.
  777.  
  778.   o BYTESSENTTOTAL -- the total number of bytes sent to the network.
  779.     You may need to increase the Rexx NUMERIC DIGITS setting if you wish
  780.     to do arithmetic on this count.  16 digits should be sufficient.
  781.  
  782.   o CLIENTADDR -- the client's address used for the connection, in
  783.     numeric form (for example, 12.34.56.78).  For a symbolic name for
  784.     the address, see the CLIENTNAME function.
  785.  
  786.   o CLIENTMETHOD -- the method (verb) being invoked by the client (on
  787.     the HTTP request, or "GET" if a Gopher request).  For example,
  788.     "GET" or "POST".
  789.  
  790.   o CLIENTPORT -- the client's port number used for the connection.
  791.  
  792.   o CLIENTPROTOCOL -- the protocol being used by the client (on the HTTP
  793.     request, or "GOPHER" if a Gopher request).  For example, "HTTP/1.0".
  794.  
  795.   o CLIENTS -- the number of clients currently connected.
  796.  
  797.   o ELAPSED -- the elapsed time, in seconds, since the current
  798.     transaction started (that is, when the network connection was
  799.     accepted).  Any decimal part will not have trailing zeroes.
  800.  
  801.   o ERRORS -- the count of errors detected.
  802.  
  803.   o GMTOFFSET -- the GMT offset (in seconds).  If GMTSET is OFF, this
  804.     will be 0.
  805.  
  806.   o GMTSET -- GMT is available [ON if available, else OFF].
  807.  
  808.   o LASTACCEPT -- timestamp of the last accepted connection [format:
  809.     yyyy.mm.dd hh:mm:ss].
  810.  
  811.   o LASTIDLE -- timestamp of when GoServe last entered an idle state,
  812.     with no connections [format: yyyy.mm.dd hh:mm:ss].
  813.  
  814.   o LASTRESET -- timestamp of the last CONTROL RESET ALL command
  815.     [format: yyyy.mm.dd hh:mm:ss].
  816.  
  817.   o LASTSECOND -- time now, in the same format [yyyy.mm.dd hh:mm:ss] as
  818.     the other LASTxxxx items.
  819.  
  820.   o LASTSTART -- timestamp of when this instance of GoServe was started
  821.     [format: yyyy.mm.dd hh:mm:ss].
  822.  
  823.   o LIMITS -- the count of limits exceeded (that is, the count of
  824.     transactions that were ended due to a limit being exceeded).  The
  825.     limits counted are the total connection timeout (LIMITTIMETOTAL),
  826.     the incoming data measures (LIMITBODY and LIMITHEADER), and maximum
  827.     clients exceeded (LIMITCLIENTS).  The latter is only counted once
  828.     for each non-idle burst of connections.
  829.  
  830.   o PEAKCLIENTS -- the maximum number of clients that were connected
  831.     simultaneously.
  832.  
  833.   o READWAITTIME -- average read wait time (seconds).
  834.  
  835.   o REQUEST -- the unique number for this HTTP request.  This is
  836.     incremented as each HTTP request is read.  This can differ from the
  837.     TRANSACTION (connection) number if a connection fails to send a
  838.     request, or if there is more than one request in a transaction.
  839.  
  840.   o REQUESTS -- the number of HTTP requests read since GoServe was
  841.     started, or since the last CONTROL RESET ALL or CONTROL RESET
  842.     TRANSACTIONS.
  843.  
  844.   o RESPONSEOVER -- number of connections over which RESPONSETIME and
  845.     READWAITTIME have been averaged.
  846.  
  847.   o RESPONSETIME -- average response time (seconds).
  848.  
  849.   o SELECTOR -- the selector string (Universal Resource Indicator, for
  850.     HTTP).
  851.  
  852.   o SERVERADDR -- the server's address used for the connection, in
  853.     numeric form (for example, 11.22.33.44).  For a symbolic name for
  854.     the address, see the SERVERNAME function.
  855.  
  856.   o SERVERPORT -- the server's port number used for the connection (for
  857.     example, 80 for default HTTP).
  858.  
  859.   o SERVERPROTOCOL -- the protocol understood by the server (for
  860.     example, "HTTP/1.0", or "GOPHER" if running as a Gopher server).
  861.  
  862.   o SERVERSOFTWARE -- the level of the server software (for example
  863.     "GoServe/2.40").  This is the same as returned by the function call
  864.     SERVER("HTTP").
  865.  
  866.   o TRANSACTION -- the unique number for this transaction (connection).
  867.     This is incremented as each client connects to the server.  This can
  868.     differ from the REQUEST number if a connection fails to send a
  869.     request, or if there is more than one request in a transaction.
  870.     Note that a filter may be called more than once during one
  871.     connection (though not concurrently).
  872.  
  873.   o TRANSACTIONS -- the number of transactions since GoServe was
  874.     started, or since the last CONTROL RESET ALL or CONTROL RESET
  875.     TRANSACTIONS.
  876.  
  877.  
  878. READ command
  879. ''''''''''''
  880. Syntax:
  881.  
  882.   READ [BODY|HEADER] {VAR varname | FILE [APPEND] NAME filespec}
  883.  
  884. Reads (receives) information from an HTTP client.  Either the header
  885. lines or the body data are read, depending on whether HEADER or BODY was
  886. specified, respectively.  The default action is to read the body.
  887. Then:
  888.  
  889.   o If 'VAR varname' was specified, the header or body data are placed
  890.     in the named Rexx variable, as a single string.  The name of the
  891.     variable is used just as if it appeared in the filter program (for
  892.     example, the name 'local.j' might have the value of J substituted in
  893.     the name).
  894.  
  895.   o If 'FILE NAME filespec' was specified, the data are written directly
  896.     to the file named by 'filespec'.  'filespec' should normally be a
  897.     fully qualified name (if it is not, GoServe will write the file in
  898.     its working directory).  'filespec' may not include an 'upwards
  899.     reference' sequence ("..\" or "../"), as such a sequence could
  900.     possibly allow clients to modify any file on the server machine.
  901.  
  902.     The named file is overwritten unless APPEND is specified (in which
  903.     case the data are written following the end of any existing data).
  904.  
  905. The READ command has no effect under the Gopher protocol, or if the
  906. client did not send an HTTP/1.0 request (though in both cases the
  907. command syntax is checked).
  908.  
  909.  
  910. RESPONSE command
  911. ''''''''''''''''
  912. Syntax:
  913.  
  914.   RESPONSE responseline
  915.  
  916. Specify an explicit HTTP response (status) line.  This replaces the
  917. default 'OK' response generated by GoServe, and should be of the form
  918. "HTTP/v.v nnn description", where 'v.v' refers to the HTTP version,
  919. 'nnn' is a 3-digit response code number, and 'description' is text (for
  920. example, the default is "HTTP/1.0 200 OK").
  921.  
  922. HTTP only allows certain code numbers to be used, so refer to the HTTP
  923. specification before using this command.  The text should be short, and
  924. is rarely seen, so GoServe will truncate the response line to 100
  925. characters if necessary.  If RESPONSE is executed more than once, the
  926. last-executed command value is used.
  927.  
  928. The RESPONSE command has no effect under the Gopher protocol (though the
  929. command syntax is checked).  It also has no effect if the incoming
  930. request uses HTTP/0.9 -- in this case, the protocol does not permit a
  931. response line to be returned, as it would be treated as part of the
  932. data.  If used, it must precede any commands that send data.
  933.  
  934.  
  935. SEND command
  936. ''''''''''''
  937. Syntax:
  938.  
  939.   SEND [TYPE content-type] [BINARY|TEXT] [AS name]
  940.   SEND COMPLETE
  941.  
  942. SEND and SEND COMPLETE are used to start and end a response which is
  943. composed of more than one piece of data.  The response is started by the
  944. SEND command (without the COMPLETE keyword) and, if using HTTP, the HTTP
  945. header is sent at that point.
  946.  
  947. After a SEND command, the completion commands (FILE, VAR, STRING, etc.)
  948. no longer cause the response to be completed, nor do they have any HTML
  949. wrapper or HTTP header, etc., added.  Instead, the plain data generated
  950. by the command (or the response to CLOSE or CONTROL, or nothing for
  951. NODATA) is sent to the client.
  952.  
  953. Following any data commands, SEND COMPLETE is used to indicate that the
  954. response is complete, and will write a 'C' audit line if the appropriate
  955. auditing is in effect (see "The audit mechanism").
  956.  
  957. SET NETBUFFER can be used to control whether data are buffered
  958. (collected into packets) before being sent or are sent immediately.
  959. NETBUFFER is ON by default.
  960.  
  961. The optional keywords on the SEND command to start the response may be
  962. specified in any order, and have the following effects:
  963.  
  964.   o TYPE -- [HTTP protocol only] the data will be prefixed by an HTTP
  965.     "OK" response line and an HTTP header.  The value of the TYPE option
  966.     ('content-type') should be a Internet Media Type such as "text/html"
  967.     or "image/gif", of up to 120 characters and with no embedded spaces.
  968.     See the notes under "FILE command" for more information.
  969.  
  970.     The TYPE option may only be used if GoServe is started with the HTTP
  971.     parameter (HTTP headers are not used by Gopher), and should normally
  972.     always be used when running as a Web server.
  973.  
  974.   o BINARY -- [default for HTTP] the data that follow are to be used
  975.     'as-is'.  A Gopher server should use this option for all data that
  976.     are not simple text or menus.
  977.  
  978.   o TEXT -- [default for Gopher] the data are text.  If running as a
  979.     Gopher server, a Gopher terminator line (just a period) will be sent
  980.     at the end of the document, when SEND COMPLETE is executed.
  981.  
  982.   o AS -- the 'name' given should be used in the audit file when SEND
  983.     COMPLETE is executed.  This can be used to create a more meaningful
  984.     audit record.  The 'name' must be a single word (no embedded blanks)
  985.     of up to 50 characters.
  986.  
  987. Here is an example of returning an HTML document to a Web client,
  988. including a file in the middle.
  989.  
  990.   /* This is Rexx code */
  991.   'send type text/html as MultiDoc'
  992.   'string <!doctype html public "-//IETF//DTD HTML 2.0//EN">'
  993.   'string <html><head><title>Multiple...</title></head>'
  994.   'string <body><h2>Here is a test file:</h2><hr>'
  995.   'file name test.dat'
  996.   'string <hr></body></html>'
  997.   'send complete'               /* complete and audit the send */
  998.  
  999. See GOFILTER.80 for an example of a more dynamic document, in the DOPUSH
  1000. function.
  1001.  
  1002. Notes:
  1003.  
  1004.   1. All data sent to a client with an HTTP header should be described
  1005.      by a Content-Type field in the header; GoServe will therefore only
  1006.      generate a header automatically if the TYPE option was specified or
  1007.      the HEADER command has been used to add header lines.  In this
  1008.      latter case, it is the responsibility of the filter to supply the
  1009.      Content-Type field if the TYPE option was not used.
  1010.  
  1011.   2. The TYPE and AS options are associated with the SEND command, not
  1012.      the included data (as the header is sent immediately).  Therefore,
  1013.      TYPE and AS are not allowed on the FILE or VAR commands once SEND
  1014.      has been used.
  1015.  
  1016.   3. BINARY and TEXT are, however, permitted on FILE and VAR after a
  1017.      SEND (for example, a file included may be a text file with a
  1018.      trailing DOS end-of-file character, and another might be binary).
  1019.      A gopher server will add a terminating period line only if the most
  1020.      recent specification was TEXT (on SEND, FILE, or VAR).
  1021.  
  1022.   4. A 'C' audit line indicates normal completion (see "The audit
  1023.      mechanism"), and once SEND has been used it is only written when
  1024.      SEND COMPLETE is executed.  If no SEND COMPLETE is executed.
  1025.      GoServe will close the connection automatically, but no 'C' audit
  1026.      line will be written.
  1027.  
  1028.  
  1029. SET command
  1030. '''''''''''
  1031. Syntax:
  1032.  
  1033.   SET item newvalue
  1034.  
  1035. Changes the state of various GoServe settings.  'item' is one of the
  1036. listed keywords.  The value of any item that can be set by the SET
  1037. command can also be queried using the QUERY command, or obtained by a
  1038. Rexx filter using the EXTRACT command.
  1039.  
  1040. Flags (items that are either ON or OFF) can also be set to INVERT,
  1041. which changes the state of the flag from ON to OFF or vice versa.
  1042.  
  1043. Valid items are:
  1044.  
  1045.   o AUDITACCEPT -- Audit accepted connections [ON/OFF].  See "The audit
  1046.     mechanism" for more details on this and the other audit settings.
  1047.  
  1048.   o AUDITCOMPLETE -- Audit completed connections [ON/OFF].
  1049.  
  1050.   o AUDITERROR -- Audit errors (for example, in commands) [ON/OFF].
  1051.  
  1052.   o AUDITFAIL -- Audit errors that stop the server [ON/OFF].
  1053.  
  1054.   o AUDITGMT -- Use GMT in the audit file [ON/OFF].  This may only be
  1055.     set ON if GMT is available (that is, GMTSET is ON).
  1056.  
  1057.   o AUDITINFO -- Audit informational lines, such as statistics [ON/OFF].
  1058.  
  1059.   o AUDITLAZY -- Lazy audit, for fewer writes to the audit file [ON/OFF].
  1060.  
  1061.   o AUDITLIMIT -- Audit limits lines, when transactions are halted due
  1062.     to a timeout, an incoming data limit exceeded, or maxmium clients
  1063.     exceeded.  The latter is only audited once for each non-idle burst
  1064.     of connections [ON/OFF].
  1065.  
  1066.   o AUDITSELECT -- Audit selectors (this is the request string, as is
  1067.     passed as the second argument to the filter) [ON/OFF].
  1068.  
  1069.   o AUDITUSER -- Audit user audit lines, from the AUDIT command
  1070.     [ON/OFF].
  1071.  
  1072.   o DATADIR -- data directory name (path).  This must be a path
  1073.     (including a drive specification) that refers to an existing
  1074.     directory.  When changed, this takes effect immediately; that is,
  1075.     subsequent calls to the DATADIR function (or the use of QUERY
  1076.     DATADIR or EXTRACT DATADIR) in this and other transactions will
  1077.     return the new directory information.
  1078.  
  1079.   o DIAG -- diagnostic tracing [ON/OFF].
  1080.  
  1081.   o DIAG2 -- verbose diagnostic tracing [ON/OFF].
  1082.  
  1083.   o DIAGMSG -- diagnostic PM message tracing [ON/OFF].
  1084.  
  1085.   o FASTFILE -- file command cache enable [ON/OFF].  When ON, the file
  1086.     command cache is active (see "File command cache").
  1087.  
  1088.   o FASTFILTER -- file command cache filter control [ON/OFF].  When ON,
  1089.     the GoServe filter will be called even if a cached FILE command was
  1090.     used (see "File command cache").
  1091.  
  1092.   o FILTER -- the name of the Rexx filter.  This must be a filename with
  1093.     no path referring to a file in the GoServe working directory; a
  1094.     default extension of PORT will be added if needed.  When changed,
  1095.     the new filter will be used for subsequent transactions.
  1096.  
  1097.   o HIDDEN -- main window state [ON/OFF].  If HIDDEN is changed from OFF
  1098.     to ON, the GoServe main window is minimized.  If changed from ON to
  1099.     OFF, the main window is restored and surfaced.
  1100.  
  1101.   o LIMITBODY -- maximum size (in thousands of bytes) of body data that
  1102.     will be accepted [0 through 1E+6].
  1103.  
  1104.   o LIMITCLIENTS -- maximum number of client connections allowed
  1105.     concurrently [1 through 1E+6].
  1106.  
  1107.   o LIMITFILES -- maximum number of open files allowed, per client
  1108.     connection [1 through 100].
  1109.  
  1110.   o LIMITHEADER -- maximum size (in thousands of bytes) of header data
  1111.     that will be accepted [1 through 1E+6].
  1112.  
  1113.   o LIMITSTARTWAIT -- maximum time, in seconds, for which GoServe will
  1114.     wait on startup for TCP/IP to become operational, while retrying
  1115.     appropriate TCP/IP calls as necessary [0 through 1E+9].
  1116.  
  1117.   o LIMITTIMEINACTIVE -- maximum time, in seconds, for which GoServe
  1118.     will allow a client to remain connected but inactive (that is,
  1119.     without sending or reading data) [0 through LIMITTIMETOTAL].
  1120.  
  1121.   o LIMITTIMETOTAL -- maximum time, in seconds, for which GoServe will
  1122.     allow a client to remain connected, even if active
  1123.     [LIMITTIMEINACTIVE through 1E+9].
  1124.  
  1125.   o LIMITTIMEWAIT -- maximum time, in seconds, for which GoServe will
  1126.     keep a client connection open waiting for a new request after the
  1127.     client has sent a 'Connection: keep-alive' header with the previous
  1128.     request [0 through 1E+9].
  1129.  
  1130.   o LIMITWARNING -- the percentage of maximum clients over which the
  1131.     GoServe main window bar chart will show a visible warning [0 through
  1132.     100].
  1133.  
  1134.   o MENUBAR -- show menu bar on GoServe main window [ON/OFF].
  1135.  
  1136.   o NETBUFFER -- turns network buffering on or off for the current
  1137.     transaction (the default is ON); see "SEND command" for more
  1138.     details [ON/OFF].  Currently, SET NETBUFFER may be used to change
  1139.     the setting only once per transaction.
  1140.  
  1141.   o RESPONSEGOAL -- sets the response time goal, in seconds.  This
  1142.     affects the coloring of the response time graph, etc. [0 through
  1143.     1.000].
  1144.  
  1145.   o RESPONSEGOALSHOW -- if set, the response time shown on the GoServe
  1146.     main window will be colored green if it is less than or equal to
  1147.     RESPONSEGOAL, yellow/orange if less than or equal to twice that, or
  1148.     red otherwise [ON/OFF].
  1149.  
  1150.   o SOUNDS -- audible indication of incoming connections [ON/OFF].
  1151.  
  1152.   o SOUNDALL -- sounds for all connections.  If ON, give audible
  1153.     indication of all incoming connections; if OFF, only indicate when
  1154.     leaving the idle state.  The SOUNDS setting must be ON for any
  1155.     sounds to be generated.
  1156.  
  1157.   o SURFACE -- surface GoServe main window on startup [ON/OFF].
  1158.  
  1159.   o TRACE -- copy audit lines to PMprint window [ON/OFF].
  1160.  
  1161.   o TEST -- enable test or experimental functions [ON/OFF].
  1162.  
  1163.  
  1164. STRING command
  1165. ''''''''''''''
  1166. Syntax:
  1167.  
  1168.   STRING string
  1169.  
  1170. The single string is returned to the client, with suitable preamble and
  1171. termination, depending on the protocol being used.
  1172.  
  1173. The STRING command can be used to return a simple message to the client.
  1174. Multiple lines can be sent, if necessary, by embedding a CR-LF sequence
  1175. ('0d0a'x) to separate lines.  A CR-LF is not needed at the end of the
  1176. string, as CR-LF is always added by the STRING command.
  1177.  
  1178. After this command has ended, the connection to the client is closed, so
  1179. this is a completion command.
  1180.  
  1181.  
  1182. VAR command
  1183. '''''''''''
  1184. Syntax:
  1185.  
  1186.   VAR [TYPE content-type] [BINARY|TEXT] [AS name] NAME varname
  1187.  
  1188. The contents of the Rexx variable named by 'varname' will be sent to the
  1189. client.  'varname' is a symbolic name, as it would be written in the
  1190. filter, and should be no more than 50 characters long.  The variable
  1191. named must have been assigned a value, or an error will be returned.
  1192.  
  1193. After this command has ended, the connection to the client is closed, so
  1194. this is a completion command.
  1195.  
  1196. The optional keywords may be specified, in any order, and have the
  1197. following effects:
  1198.  
  1199.   o TYPE -- [HTTP protocol only] the data will be prefixed by an HTTP
  1200.     "OK" response line and an HTTP header, including the length of the
  1201.     variable.  The value of the TYPE option ('content-type') should be a
  1202.     Internet Media Type such as "text/html" or "image/gif", of up to 120
  1203.     characters and with no embedded spaces.  See the notes under "FILE
  1204.     command" for more information.
  1205.  
  1206.     The TYPE option may only be used if GoServe is started with the HTTP
  1207.     parameter (HTTP headers are not used by Gopher), and should normally
  1208.     always be used when running as a Web server.
  1209.  
  1210.   o BINARY -- [default for HTTP] the data are binary, and form the
  1211.     entire response to the client.  GoServe will close the TCP/IP
  1212.     connection to indicate that all the data have been sent.
  1213.  
  1214.     A Gopher server should use this option for all data that are not
  1215.     simple text or menus.
  1216.  
  1217.   o TEXT -- [default for Gopher] the data are text.  If running as a
  1218.     Gopher server, a Gopher terminator line (just a period) will be sent
  1219.     at the end of the document, before the connection is closed.
  1220.  
  1221.   o AS -- the 'name' given should be used in the audit file instead of
  1222.     the name of the variable.  This can be used to create a more
  1223.     meaningful audit record when (for example) the variable contains a
  1224.     modified version of a file.  The 'name' must be a single word (no
  1225.     embedded blanks) of up to 50 characters.
  1226.  
  1227. Here are some examples (see also GOREMOTE.80):
  1228.  
  1229.   1. Returning an HTML document to a Web client:
  1230.  
  1231.        /* This is Rexx code */
  1232.        doc='<html> .... </html>'          /* may be large */
  1233.        'var type text/html name doc'      /* return the data */
  1234.        return
  1235.  
  1236.   2. Returning some binary data to a Web client:
  1237.  
  1238.        /* This is Rexx code */
  1239.        data='001122334455'x               /* may be large, '00'x is OK */
  1240.        'var type application/octet-stream name data'  /* this sends it */
  1241.        return
  1242.  
  1243. Notes:
  1244.  
  1245.   1. The filter must be active when the VAR command is executed (or the
  1246.      variable will not exist).  Therefore this command cannot be passed
  1247.      back to the server by a RETURN instruction for later execution.
  1248.  
  1249.   2. All data sent to a client with an HTTP header should be described
  1250.      by a Content-Type field in the header; GoServe will therefore only
  1251.      generate a header automatically if the TYPE option was specified or
  1252.      the HEADER command has been used to add header lines.  In this
  1253.      latter case, it is the responsibility of the filter to supply the
  1254.      Content-Type field if the TYPE option was not used.
  1255.  
  1256.  
  1257. WAIT command
  1258. ''''''''''''
  1259. Syntax:
  1260.  
  1261.   WAIT SECONDS time
  1262.  
  1263. The WAIT SECONDS command may be used to pause a transaction for up to
  1264. 999999.999 seconds.  'time' is the wait time in seconds; it may have a
  1265. decimal part of up to three digits.
  1266.  
  1267. If a limit (such as a timeout) is exceeded during a WAIT, the command
  1268. will return immediately.  Except in this case, WAIT will not return
  1269. without error in less than the requested time, but may take longer if
  1270. some other activity on the computer delays it.
  1271.  
  1272.  
  1273. Command return codes
  1274. ''''''''''''''''''''
  1275. When commands end, they report any errors or failures by setting the
  1276. Rexx variable RC.  A value of zero indicates normal execution (no error
  1277. or failure was found), a positive value indicates an error, and a
  1278. negative value a failure.  All command errors and failures are audited
  1279. with audit type 'E' (if auditing of errors is enabled).
  1280.  
  1281. The possible values for command return codes follow.
  1282.  
  1283. --- Errors ---
  1284.  
  1285. Errors indicate that the command was in error (perhaps a syntax error)
  1286. or the data it processed was in error.  The following errors may occur:
  1287.  
  1288.   [11] Response already completed
  1289.   [12] Command not allowed now
  1290.   [21] Missing keyword in command
  1291.   [22] Bad keyword in command
  1292.   [23] Bad value in command
  1293.   [24] Junk on end of command
  1294.   [25] Header key not found
  1295.   [26] Unknown SET/QUERY/EXTRACT item
  1296.   [31] Unable to open file
  1297.   [32] Unable to read file
  1298.   [33] Unable to write file
  1299.   [34] Unable to write audit
  1300.   [40] Bad variable name
  1301.   [41] Could not set variable
  1302.   [42] Could not get variable
  1303.   [50] Missing Content-Length
  1304.   [51] Bad Content-Length
  1305.   [52] Zero Content-Length
  1306.   [53] Multiple READ BODY requested
  1307.  
  1308. --- Failures ---
  1309.  
  1310. Failures are indicated when a command encounters an unexpected or
  1311. serious condition, such as a failure of the TCP/IP network or some limit
  1312. being exceeded.  The following failures may be reported:
  1313.  
  1314.   [-1] Inactive timeout exceeded
  1315.   [-2] Total timeout exceeded
  1316.   [-3] Header bytes limit exceeded
  1317.   [-4] Body bytes limit exceeded
  1318.   [-5] Out of memory
  1319.   [-6] Failure reading from network
  1320.   [-7] Failure sending to network
  1321.   [-8] Unknown command
  1322.  
  1323.  
  1324. Filter functions
  1325. """"""""""""""""
  1326. In addition to GoServe commands, filters may use certain routines
  1327. provided by GoServe.  These may be invoked either as functions or by the
  1328. CALL instruction, and are listed in the following sections.
  1329.  
  1330.  
  1331. CACHED function
  1332. '''''''''''''''
  1333. Syntax:
  1334.  
  1335.   CACHED([option])
  1336.  
  1337. The returns information about any previous cached command.  If 'option'
  1338. is omitted or begins with the character 'N' (either case) then this
  1339. returns '1' if a cached FILE command was executed for the current
  1340. request before the filter was invoked, or '0' otherwise.
  1341.  
  1342. If 'option' begins with the character 'R' (either case) then this
  1343. returns the returncode from the cached command that was executed, or
  1344. zero if none was executed (cached()=0).  For example:
  1345.  
  1346.   say cached() cached('rc')
  1347.  
  1348. might display "1 31" if the cached command failed to find the file.
  1349.  
  1350.  
  1351. CLIENTNAME function
  1352. '''''''''''''''''''
  1353. Syntax:
  1354.  
  1355.   CLIENTNAME()
  1356.  
  1357. This returns the primary host name of the client (for example,
  1358. 'roman.therenet.org'), or if that should not be available, the name in
  1359. numeric form (e.g., 12.34.56.78).
  1360.  
  1361. Note that determining the client name may involve a significant delay
  1362. while the network is asked to resolve it.  To minimize response time to
  1363. the user, it is best to ask for the client name after sending the
  1364. response data.  Note also that the client name will not be that of the
  1365. user agent if the user connects through a 'proxy' server or firewall.
  1366.  
  1367.  
  1368. COMPLETED function
  1369. ''''''''''''''''''
  1370. Syntax:
  1371.  
  1372.   COMPLETED()
  1373.  
  1374. This returns '1' if a completion command that closed the connection to
  1375. the client has already been executed successfully during this
  1376. transaction, or '0' otherwise.
  1377.  
  1378.  
  1379. DATADIR function
  1380. ''''''''''''''''
  1381. Syntax:
  1382.  
  1383.   DATADIR()
  1384.  
  1385. This returns the data directory name (e.g., 'd:/gohttp/') set up by
  1386. using the DATADIR option when starting GoServe or by using the DataDir
  1387. options page.  (Once changed, GoServe records the data directory
  1388. associated with each port.)
  1389.  
  1390. The directory name will always end in a '/', and will use '/' as the
  1391. directory separator, "URI-style".
  1392.  
  1393.  
  1394. EXTRACT function
  1395. ''''''''''''''''
  1396. Syntax:
  1397.  
  1398.   EXTRACT(item)
  1399.  
  1400. This returns the value of a GoServe setting.  'item' should be a single
  1401. word, which could be used as an item in the EXTRACT (or QUERY) commands.
  1402. The value of the item is returned (instead of setting a variable of the
  1403. same name, as with the EXTRACT command).  If the item is not a single
  1404. word or is not a known GoServe setting, then it is returned unchanged.
  1405.  
  1406.  
  1407. GMTOFFSET function
  1408. ''''''''''''''''''
  1409. Syntax:
  1410.  
  1411.   GMTOFFSET()
  1412.  
  1413. This returns the current offset from Greenwich Mean Time (GMT), in
  1414. seconds.  A positive result indicates that your local time is ahead of
  1415. GMT by that amount.
  1416.  
  1417. If GMT cannot be computed because the TZ environment variable was not
  1418. set, the function returns a question mark (the character '?').  See
  1419. "Setting the TZ environment variable" for more information.
  1420.  
  1421.  
  1422. PACKUR function
  1423. '''''''''''''''
  1424. Syntax:
  1425.  
  1426.   PACKUR(string)
  1427.  
  1428. Takes a single string, expressed according to the Universal Resource
  1429. (UR) specification (RFC 1630), as an argument and returns a packed
  1430. string.  That is, hexadecimal escape sequences (such as '%7E') are
  1431. reduced to the character encoding that they represent (in this case,
  1432. '~').
  1433.  
  1434. PACKUR is especially useful for processing the incoming data from a
  1435. form, in which UR encoding is used.  See the sample GOFILTER.80 for an
  1436. example of this use.
  1437.  
  1438.  
  1439. PACK64 function
  1440. '''''''''''''''
  1441. Syntax:
  1442.  
  1443.   PACK64(string)
  1444.  
  1445. Takes a single string, expressed according to the MIME "Base64"
  1446. specification (in RFC 1521), as an argument and returns the decoded
  1447. (packed) string.  Each four bytes in 'string' is packed to three bytes
  1448. in the result (except possibly for the last four bytes); 'string' must
  1449. be a multiple of 4 bytes.  If any deviation from these specifications
  1450. (or from the RFC 1521 "Base64" character set) is found, the null string
  1451. is returned.
  1452.  
  1453. PACK64 is useful for processing the incoming user/password data encoded
  1454. for the HTTP 'basic access authentication scheme' -- see the HTTP
  1455. documentation for details.
  1456.  
  1457.  
  1458. REQFIELD function
  1459. '''''''''''''''''
  1460. Syntax:
  1461.  
  1462.   REQFIELD(identifier [, count])
  1463.  
  1464. Searches the HTTP request header for a line that starts with the
  1465. specified identifier, and returns the value for that identifier.
  1466. Continuations are included in the value (if the continuation was
  1467. indicated by the tab character, the tab character is replaced with a
  1468. space).
  1469.  
  1470. The identifier may optionally end with a colon, and the search is
  1471. case-insensitive.  If no matching identifier is found (or if there is no
  1472. HTTP request header), the null string is returned.
  1473.  
  1474. The second, optional, argument determines which value is returned if
  1475. more than one line starts with the given identifier: if no count is
  1476. given, the last matching line is used.  If a count is given, then it
  1477. identifies which of the values is to be returned.  For example,
  1478.  
  1479.   reqfield("accept", 3)
  1480.  
  1481. would return the value of the third 'Accept:' line in the header
  1482. (perhaps "text/html"); if there was no third 'Accept:' line, then the
  1483. null string would be returned.
  1484.  
  1485.  
  1486. SERVER function
  1487. '''''''''''''''
  1488. Syntax:
  1489.  
  1490.   SERVER([option])
  1491.  
  1492. The returns the name of the server software.  If 'option' is omitted or
  1493. begins with the character 'N' (either case) then this is the full name
  1494. of the server software, followed by a comma, the word 'version', and the
  1495. version number of the server.  For example, 'GoServe for OS/2, version
  1496. 1.88'.
  1497.  
  1498. If 'option' begins with the character 'H' (either case) then the HTTP
  1499. short name is returned, for example, 'GoServe/1.88'.  This is the same
  1500. as the value returned in the HTTP header field "Server:".
  1501.  
  1502.  
  1503. SERVERNAME function
  1504. '''''''''''''''''''
  1505. Syntax:
  1506.  
  1507.   SERVERNAME()
  1508.  
  1509. This returns the primary host name of the server (for example,
  1510. 'fred.mynet.org'), or if that should not be available, the name in
  1511. numeric form (e.g., 12.34.56.78).
  1512.  
  1513. If the latter case, your TCP/IP installation probably needs adjustment.
  1514. For example, if running in loopback mode and not on a real network, your
  1515. HOSTS file in TCPIP\ETC should contain your host name.  Check also to
  1516. see what your TCP/IP HOSTNAME command (from an OS/2 prompt) returns;
  1517. again, it should be a full symbolic name (not the numeric form).  (This
  1518. may not work on Warp Connect.)
  1519.  
  1520. Note that determining the server name may involve a significant delay
  1521. if the network has to be asked to resolve it.   It may vary from
  1522. transaction to transaction if multiple networks are connected to the
  1523. server.
  1524.  
  1525.  
  1526. Running GoServe
  1527. """""""""""""""
  1528. GoServe may be started in any of the usual ways, such as from an OS/2
  1529. command line or from a Program Reference object.  You should always
  1530. specify the protocol to be used (HTTP or GOPHER) as a parameter to the
  1531. command.  GoServe defaults to the Gopher protocol at present.
  1532.  
  1533. This section describes first the user interface to GoServe, and then
  1534. details the parameters that may be used when starting GoServe.
  1535.  
  1536. The GoServe window
  1537. ''''''''''''''''''
  1538. Once GoServe has started, a PM window should appear.  By default, a menu
  1539. bar is displayed giving access to the 'Options' notebook and an
  1540. 'Actions' drop-down menu.  Access to these is also provided at all times
  1541. by a pop-up menu if you click on the window with the context menu mouse
  1542. button (usually button 2).
  1543.  
  1544. To change the background color of the window, select the color of your
  1545. choice from the OS/2 color palette, drag it to the GoServe window, and
  1546. drop it.  The color should change immediately.
  1547.  
  1548. The window is used to display a summary of the current and past activity
  1549. of GoServe.  If it is large enough, it will include at the top a bar
  1550. display that shows any client activity (the full width of the bar
  1551. corresponds to the maximum number of clients allowed).  A half-height
  1552. grey bar indicates the peak activity seen since GoServe was started.
  1553. This may be reset to zero by selecting 'Reset peak indicator' from the
  1554. Actions menu, and will be shown in purple if any errors have been
  1555. counted.
  1556.  
  1557. The second line of the window gives the total number of transactions
  1558. (connections) initiated since GoServe started, and the average response
  1559. time of the last 100 transactions.  The color of this number changes to
  1560. indicate whether the response time goal is being attained; you can
  1561. change the goal (or turn off the coloring in the main window) using the
  1562. 'Response' page of the Options notebook.  The response time is replaced
  1563. by a count of limits exceeded, or a count of errors, if any of these
  1564. have occurred.
  1565.  
  1566. If room, the second line shows on the right the instantaneous count of
  1567. connected clients and the peak number recorded since GoServe started (if
  1568. more than one).
  1569.  
  1570. The transaction count may be reset to zero by selecting 'Reset
  1571. transaction count' from the Actions menu).  Similarly, the response time
  1572. record, error count, limits count, and peak count may also be reset to
  1573. zero.
  1574.  
  1575. The third line shows the number of bytes, thousands of bytes, or
  1576. millions of bytes sent and received since GoServe started.  These counts
  1577. may be reset to zero by selecting 'Reset byte counts' from the Actions
  1578. menu.  The Actions menu also offers 'Reset all counts', which resets
  1579. all of the counters.
  1580.  
  1581. The fourth line of the window displays two timestamps; on the left is
  1582. shown the time when GoServe last entered the 'idle' state (that is, was
  1583. waiting for clients).  On the right is the time when GoServe was
  1584. started (or when the last 'Reset All' was done).
  1585.  
  1586. Some or all of these items will be omitted if the window is too small
  1587. for satisfactory display.
  1588.  
  1589. The Options notebook
  1590. ''''''''''''''''''''
  1591. If 'Options' is selected from the menu bar or pop-up menu, the Options
  1592. notebook is opened.  This has the following pages:
  1593.  
  1594.   1. 'Response' shows response time statistics, and lets you control
  1595.      the display and coloring of the statistics.
  1596.  
  1597.      At the top of the page, a bar chart shows the distribution of the
  1598.      response times for recent requests, and (if there have been any
  1599.      requests) the average response time.  This bar chart is redrawn
  1600.      automatically whenever the number of connections returns to idle,
  1601.      or you can refresh it manually by clicking on (selecting) the
  1602.      chart.
  1603.  
  1604.      You can change the time-scale of this chart using the buttons at
  1605.      the bottom right of the box.  Any measurements that would be
  1606.      "off-scale" (to the right of the chart) are included in the
  1607.      bar at the far right of the chart.
  1608.  
  1609.      The lower part of the page lets you set a response time goal using
  1610.      a slider control; responses made within the specified time are
  1611.      displayed on the bar chart in green; responses made within twice
  1612.      that time are shown in an orangey-brown, and responses outside that
  1613.      limit are shown in a medium-dark red.  The exact colors used will
  1614.      depend on your display.
  1615.  
  1616.      The average response time shown on the page is colored according to
  1617.      the the same rules, as is the less precise average response time
  1618.      shown on the main window, if 'Color on main window' is checked.
  1619.  
  1620.      See "Response time recording" for more details.
  1621.  
  1622.   2. 'General' lets you change certain aspects of the appearance of the
  1623.      main window, and control sounds made by the server.
  1624.  
  1625.      Two 'Main Window' check-boxes are provided:
  1626.  
  1627.        o 'Show menu bar' controls whether the menu bar is included in
  1628.          the display.  To make menu selections when there is no menu
  1629.          bar, click anywhere on the GoServe window with the context menu
  1630.          button, in the usual Workplace Shell manner (this works even if
  1631.          the menu bar is visible).
  1632.  
  1633.        o 'Surface on startup' lets you choose whether GoServe surfaces
  1634.          its window when started (if not minimized when shut down).
  1635.  
  1636.      The 'Sounds on connections' checkbox requests that sounds be made
  1637.      (using the PC speaker) when a client browser connects to the
  1638.      server.  Radio buttons let you choose whether to hear a note (on a
  1639.      ascending scale, depending on the number of connections) for every
  1640.      connection, or to hear a note only when the server moves from being
  1641.      idle to being busy (one or more connections).
  1642.  
  1643.      The 'File command cache' controls are used for a performance
  1644.      optimization.  See "File command cache" for details before using
  1645.      this option.
  1646.  
  1647.   3. 'Audit' lets you control the auditing of transactions (which events
  1648.      are to be audited, whether timestamps in the file are in local
  1649.      time or GMT, and how frequently the audit file is to be written).
  1650.      See "The audit mechanism" for more details.
  1651.  
  1652.   4. 'Limits' (two pages) is used to control the operating limits of the
  1653.      server.  See "The Limits options pages" for details.
  1654.  
  1655.   5. 'DataDir' lets you specify a new data directory name (path).  This
  1656.      name is made available to the Rexx filter via the DataDir()
  1657.      function, and may be used by the filter to find the data to be
  1658.      served.  (But note that the filter may ignore this information, if
  1659.      appropriate.)
  1660.  
  1661.      GoServe will convert backslashes ('\') in the name to URI form
  1662.      (forward slashes, '/'), and will add a trailing '/' if one is not
  1663.      present.  For example, entering 'd:\myhome' would result in the
  1664.      directory specification 'd:/myhome/' being passed to the filter via
  1665.      the DATADIR() function.  This page checks that a drive is specified
  1666.      so it is not accidentally omitted.
  1667.  
  1668.   6. 'Filter' lets you specify a new filter name.  This must be a simple
  1669.      filename and extension (the extension will default to the port
  1670.      number, if omitted).
  1671.  
  1672.      The filter must be in the GoServe working (current) directory, so
  1673.      no drive or directory path should be specified.  For example, if
  1674.      you enter 'myfilter.80', this would result in the filter
  1675.      'd:\goserve\myfilter.80' being used, if 'd:\goserve' is the working
  1676.      directory.  The filter must exist in the GoServe working directory
  1677.      in order for a new name to be accepted.
  1678.  
  1679. --- The Apply button ---
  1680.  
  1681. The 'Limits', 'DataDir', and 'Filter' pages let you choose when to apply
  1682. the change or changes that you make, by clicking on the 'Apply' button
  1683. (or pressing the Enter key).  The Apply button is only enabled when you
  1684. have made a change and all fields on the page are valid.  If you leave a
  1685. page (or close the notebook) when the Apply button is enabled, the
  1686. changes will be applied automatically at that time.
  1687.  
  1688.  
  1689. The Limits options pages
  1690. ''''''''''''''''''''''''
  1691. The 'Limits' pages in the Options notebook let you change various limits
  1692. which apply to running GoServe.  The limits are grouped into three sets:
  1693. limits affecting clients, timeouts, and (on the second page) limits
  1694. restricting incoming data.
  1695.  
  1696. --- Clients limits ---
  1697.  
  1698. The 'Clients' set has three limits:
  1699.  
  1700.   1. 'Maximum at once' -- the maximum number of client connections
  1701.      allowed concurrently [default 20].  Additional requests for
  1702.      connection will be refused.  This count lets you limit the maximum
  1703.      load on your server, which is especially useful if it is also being
  1704.      used as a personal workstation.  Note that some Web clients, such
  1705.      as Web Explorer, may make four or more connections at the same
  1706.      time, to download inline graphics in parallel.
  1707.  
  1708.      This limit, when exceeded, is only counted and audited once for
  1709.      each non-idle burst of connections.
  1710.  
  1711.   2. 'Show warning at' -- the percentage at which the bar chart will
  1712.      show a red warning indicator [default 75%].  This gives a visual
  1713.      indication of heavy use of your server at a given instant (the peak
  1714.      use is also shown on the bar display).
  1715.  
  1716.   3. 'Open files per client' -- the maximum number of open files
  1717.      allowed, per client filter [default 5].  Increase this if you expect
  1718.      your GoServe filter to have more than five files open at a time.
  1719.  
  1720. --- Timeouts ---
  1721.  
  1722. The 'Timeouts' set has four limits; the first two timeout settings
  1723. control the time at which any uncompleted response may be terminated
  1724. automatically by GoServe's "watchdog" thread, the third controls how
  1725. long GoServe will wait (if requested) for additional requests on a
  1726. persistent connection, and the last determines how long GoServe will
  1727. wait, on startup, for TCP/IP to become available:
  1728.  
  1729.   1. 'End client after inactive' -- the "inactive timeout", in seconds.
  1730.      A connection will be closed if the specified time passes without
  1731.      any data being received or transmitted over the connection.  The
  1732.      default is 60 seconds.
  1733.  
  1734.   2. 'End client after total' -- the "total timeout", in seconds.  A
  1735.      connection will be closed if the specified time passes since the
  1736.      client connected to the port, even if there appears to be activity.
  1737.      This value must not be less than the inactive timeout, and defaults
  1738.      to 1200 seconds.  As a rule of thumb, this timeout might be set to
  1739.      a number of seconds equal to or larger than the size of your
  1740.      largest data file, expressed in kilobytes.  This allows for
  1741.      transmission of the file over a slow link running at one kilobyte
  1742.      per second.  Multiply this by three or four if network delays are
  1743.      common.
  1744.  
  1745.   3. 'Connection maintain' -- the "wait timeout", in seconds.  This is
  1746.      is the time for which GoServe will wait for a new request after
  1747.      responding to a request that included a 'Connection: keep-alive'
  1748.      header.  Note that expiry of this timeout, when a request is not
  1749.      received, is considered normal; it is therefore not audited as a
  1750.      limit exceeded or an error.
  1751.  
  1752.      The default is 0 seconds, which means that GoServe will never
  1753.      accept more than one request per connection.  To accept multiple
  1754.      requests per connection, set this to a non-zero value.  Suggested
  1755.      values might be 10-15 seconds (to handle most cases of embedded
  1756.      images in HTML pages, for example) or 60-120 seconds (to handle
  1757.      most cases of multiple pages being requested by the same client).
  1758.  
  1759.   4. 'Wait for TCP/IP start' -- the "start timeout", in seconds.  This
  1760.      is the time for which GoServe will wait on startup for TCP/IP to
  1761.      become operational, while retrying appropriate TCP/IP calls as
  1762.      necessary [default 600 seconds].  This allows asynchronous starting
  1763.      of TCP/IP and GoServe.  A value of 0 seconds means immediate
  1764.      timeout (that is, no retrys are performed, and GoServe will not
  1765.      start if an error is found).  No TCP/IP retry is attempted if the
  1766.      requested port is in use (that is, it is likely that another copy
  1767.      of GoServe is already running).
  1768.  
  1769. Notes on timeouts:
  1770.  
  1771.   1. For the first two timeouts, a value of zero seconds may be
  1772.      specified to indicate an indefinite time (that is, the timeout
  1773.      check is not made).  You should only set both timeouts to zero if
  1774.      the filter is trusted, the data it accesses is always available
  1775.      locally, and all clients used with the server have a timeout
  1776.      mechanism.
  1777.  
  1778.   2. Also for the first two timeouts, when the timeout takes place there
  1779.      may be some delay (typically up to 10 seconds) before the
  1780.      transaction is interrupted.  If the Rexx filter is still running,
  1781.      it will have the HALT condition raised during this process; the
  1782.      HALT condition may be trapped by CALL ON HALT or SIGNAL ON HALT for
  1783.      necessary cleanup which should normally be followed by an immediate
  1784.      EXIT.
  1785.  
  1786. --- Incoming data ---
  1787.  
  1788. The 'Incoming data' set is on the second Limits page (use the rightmost
  1789. button at the bottom of the first page, or Alt+Page Down, to get to it).
  1790. It has two limits which restrict how much incoming data will be accepted
  1791. by the server (per request):
  1792.  
  1793.   1. 'Header size' -- the maximum size (in thousands of bytes) of header
  1794.      that will be accepted in one request.  The transaction will be
  1795.      ended if a header is received that exceeds the specified size; this
  1796.      gives some protection against a client that sends an invalid or
  1797.      never-ending header.  This limit is used whenever a header is read,
  1798.      either automatically or because of the READ command.  The default
  1799.      is 10 thousand bytes (10kB).
  1800.  
  1801.   2. 'Body data size' -- the maximum size (in thousands of bytes) of
  1802.      body data that will be accepted in one request.  The transaction
  1803.      will be ended if a client sends data that exceeds the specified
  1804.      size, and an attempt is made to read it using the READ command.
  1805.      The default is 50 thousand bytes (50kB).
  1806.  
  1807. Parameters on the GoServe command
  1808. '''''''''''''''''''''''''''''''''
  1809. Keyword parameters may be used when starting GoServe to set the protocol
  1810. (one only) and the TCP/IP port used, the default data directory, the
  1811. action taken after a serious failure, and reuse of a port.  They may be
  1812. specified in any order:
  1813.  
  1814.   o The 'HTTP' parameter
  1815.  
  1816.     This indicates that GoServe is being used as a World-Wide Web
  1817.     server, using the Hypertext Transfer Protocol (HTTP).  When this is
  1818.     specified, the default port number is 80, the well-known port for
  1819.     HTTP (this may be overridden as usual by the PORT parameter), and
  1820.     other enhancements are enabled, including:
  1821.  
  1822.       o The TYPE option may (and should) be used on FILE responses from
  1823.         the filter.
  1824.  
  1825.       o Automatic processing of both incoming and outgoing HTTP headers
  1826.         is enabled (see "Automatic HTTP processing").
  1827.  
  1828.       o Tab characters have no special significance in request strings;
  1829.         the third argument passed to the filter is a 'clean' URI (see
  1830.         "Filter programs").
  1831.  
  1832.       o STRING and CONTROL command responses are returned as HTML
  1833.         documents.
  1834.  
  1835.   o The 'GOPHER' parameter
  1836.  
  1837.     This indicates that GoServe is being used as a Gopher server, using
  1838.     the Gopher Protocol.  When this is specified, the default port
  1839.     number is 70, the well-known port for Gopher (this may be overridden
  1840.     as usual by the PORT parameter).  The Gopher termination sequence (a
  1841.     line containing just a single '.') is added to TEXT files and STRING
  1842.     and CONTROL responses.
  1843.  
  1844.   o The 'PORT n' parameter
  1845.  
  1846.     The default port number for the selected protocol may be changed for
  1847.     special applications by using the PORT parameter when starting
  1848.     GoServe, for example:
  1849.  
  1850.       start goserve http port 801
  1851.  
  1852.     Servers started with different ports are independent; they use
  1853.     different filter programs, and maintain a different collection of
  1854.     options, window position information, audit file, etc.
  1855.  
  1856.     Note that the port number is used as the required or default file
  1857.     extension for some files, such as the filter, programs called from
  1858.     the filter, and the audit/log files.  This is so that the files for
  1859.     different ports don't conflict when in the same directory.
  1860.     Therefore, if you use port numbers greater than 999, you must be
  1861.     sure that the working directory for GoServe is on a disk that
  1862.     supports extensions of more than three characters (for example, an
  1863.     HPFS disk).
  1864.  
  1865.   o The 'DATADIR d' parameter
  1866.  
  1867.     This sets the data directory name (path) that will be used for this
  1868.     port from the word following the keyword DATADIR.  This name will be
  1869.     used until the name is changed using the 'DataDir' Options notebook
  1870.     page or by starting GoServe with a different DATADIR parameter.  The
  1871.     name should normally include the drive on which the data are to be
  1872.     found.
  1873.  
  1874.     The data directory name is not used directly by GoServe, but is made
  1875.     available to the filter program via the DataDir() function--hence
  1876.     allowing one filter to handle different data directories without
  1877.     "hard-coding" their names in the filter.
  1878.  
  1879.     GoServe will convert backslashes ('\') in the name to URI form
  1880.     (forward slashes, '/'), and will add a trailing '/' if one is not
  1881.     present.  For example,
  1882.  
  1883.       start goserve http datadir d:\myhome
  1884.  
  1885.     would result in the directory specification 'd:/myhome/' being passed
  1886.     to the filter via the DATADIR() function.
  1887.  
  1888.   o The 'FILTER f' parameter
  1889.  
  1890.     This sets the filter name that will be used for this port from the
  1891.     word following the keyword FILTER.  This name will be used until the
  1892.     name is changed using the 'Filter' options notebook page or by
  1893.     starting GoServe with a different FILTER parameter.  The filter must
  1894.     be in the GoServe working (current) directory, so no drive or
  1895.     directory path should be specified.  For example:
  1896.  
  1897.       start goserve http filter myfilter.80
  1898.  
  1899.     would result in the filter 'd:\goserve\myfilter.80' being used, if
  1900.     'D:\goserve' is the working directory.
  1901.  
  1902.     If no file extension is specified (that is, no period is found in
  1903.     the name), the port will be added as the extension.
  1904.  
  1905.   o The 'QUIETFAIL' parameter
  1906.  
  1907.     Certain "catastrophic" errors (such as memory allocation errors, or
  1908.     a syntax error in the Rexx filter) are considered failures by
  1909.     GoServe; that is, they cause a message dialog to be displayed on the
  1910.     screen--once the message is acknowledged, GoServe ends.
  1911.  
  1912.     The QUIETFAIL parameter can be used to prevent the failure message
  1913.     dialog being displayed:
  1914.  
  1915.       start goserve http quietfail
  1916.  
  1917.     In this case, GoServe will end immediately after a failure (after
  1918.     attempting to audit the failure, as usual).
  1919.  
  1920.   o The 'REUSE' parameter
  1921.  
  1922.     This allows reuse of the requested port, even if some other
  1923.     application (or TCP/IP) has not released it.  TCP/IP may hold on to
  1924.     a port for two or three minutes after an application (or GoServe
  1925.     itself) releases it.
  1926.  
  1927. GoServe also accepts some experimental keyword parameters:
  1928.  
  1929.   o 'TRACE' copies audit information to the PMprintf window (without
  1930.     GoServe timestamps); this does not affect auditing to the audit
  1931.     file.  This lets you watch a trace of incoming requests, actions,
  1932.     and errors as they happen without needing to look at the audit file
  1933.     itself.
  1934.  
  1935.   o 'TEST' controls experimental features (such as sending a Message-ID
  1936.     header) and also adds an extra Test page to the options notebook.
  1937.     The Test features are undefined (that is, they may be removed in
  1938.     future versions of GoServe).
  1939.  
  1940.   o 'DIAG' shows TRACE information together with additional details of
  1941.     GoServe operation (also using PMprintf).  This diagnostic
  1942.     information is intended for development use and may change over
  1943.     time.  If you are observing unexpected GoServe behaviour, the DIAG
  1944.     option may show helpful information.  'DIAG2' and 'DIAGMSG' may
  1945.     provide even more verbose diagnostic information.  'DIAG' implies
  1946.     'REUSE'.
  1947.  
  1948. Any number of GoServe parameters may be specified, in any order.  If a
  1949. parameter with a value is specified more than once, the last value is
  1950. used.
  1951.  
  1952.  
  1953. GoServe return codes
  1954. ''''''''''''''''''''
  1955. When GoServe ends, a return code is returned to the caller (for example,
  1956. when invoked from a Rexx program, this return code is placed in the Rexx
  1957. variable RC).  The value is restricted by the operating environment to
  1958. be in the range 0 through 255; GoServe uses one of three possible
  1959. values:
  1960.  
  1961.   [0] Normal completion (user action or OS/2 shutdown).
  1962.   [1] GoServe was ended by the CLOSE filter command.
  1963.   [8] Abnormal completion (failure), such as a syntax error in the filter.
  1964.  
  1965.  
  1966. Greenwich Mean Time (GMT)
  1967. """""""""""""""""""""""""
  1968. The HTTP protocol (like most international networking protocols)
  1969. requires that dates and times, where used, be quoted in GMT.  The
  1970. personal computers on which OS/2 runs, however, do not require that a
  1971. GMT clock be available--instead, the clock is usually set to local time.
  1972.  
  1973. Various mechanisms are used in OS/2 to indicate and calculate the
  1974. current offset from GMT.  The most common is to use an OS/2 environment
  1975. variable named 'TZ', and for many people running GoServe this will
  1976. already be set (for example to 'EST5EDT' for the USA East Coast).  See
  1977. the separate section on setting the value of the TZ variable.
  1978.  
  1979. If TZ is not set, GoServe will only use local time (and HTTP protocols
  1980. and header fields that require GMT will not be used or generated).
  1981.  
  1982. If the TZ variable is set, GoServe will convert from local time to GMT
  1983. as appropriate.  It will also detect a clock dislocation (that is, when
  1984. the time-of-day clock is changed by more than 10 seconds) automatically,
  1985. and record and re-calculate the GMT offset when this occurs--such as
  1986. when you change your clock for daylight-savings time.
  1987.  
  1988. Notes:
  1989.  
  1990.   1. You can see the offset that GoServe has computed by using the
  1991.      CONTROL STATISTICS command or the GMTOFFSET() function.
  1992.  
  1993.   2. Inevitably, for a few seconds between when you change the time and
  1994.      when GoServe detects that it has been changed, incoming
  1995.      transactions may be processed with anomalous time data; to avoid
  1996.      this, stop GoServe before making large time adjustments and restart
  1997.      it afterwards.
  1998.  
  1999.   3. Files in the PC-DOS and OS/2 FAT and HPFS file systems are
  2000.      timestamped with the local time of creation or last modification.
  2001.      The time-zone and daylight savings regime of that zone (and hence
  2002.      the GMT offset) are not available.  GoServe therefore calculates
  2003.      the GMT timestamp of a file by using the current GMT offset.
  2004.  
  2005.   4. If you are running a machine as a dedicated Web server, you may
  2006.      wish to set its clock to GMT and leave it set that way all year; in
  2007.      this case, set TZ to 'GMT0'.
  2008.  
  2009.  
  2010. Response time recording
  2011. """""""""""""""""""""""
  2012. GoServe records the response times of the most recent one hundred
  2013. completed requests.
  2014.  
  2015. 'Response time', here, means the time from when the client connection is
  2016. accepted to when the first data bytes are sent for the first request in
  2017. a transaction, or (for subsequent requests during a connection) the time
  2018. from when the previous request was completed to when the first data
  2019. bytes are sent for the current request.
  2020.  
  2021. The response time may include the time to receive some or all of the
  2022. request data from the client, but excludes any time taken waiting for
  2023. data to become available at the server.  It never includes the time
  2024. taken to send the response (which may be very large, and dependent on
  2025. network delays).  Response times of transactions ended due to a timeout
  2026. or other limit being exceeded are not recorded.
  2027.  
  2028. The average response time of those recorded, to the nearest 0.01 second,
  2029. is shown on the main GoServe window, next to the transactions count
  2030. (unless an error has occurred).  A more precise figure, along with the
  2031. number of transactions over which it was recorded, is included in the
  2032. CONTROL STATISTICS response (this figure will not reflect the response
  2033. time of the transaction that initiates the CONTROL STATISTICS command).
  2034. The same, more precise, figure is also shown on the 'Response' page of
  2035. the Options notebook.
  2036.  
  2037. The average read wait time (the time taken waiting for data to become
  2038. available at the server during response time measurement) is also shown
  2039. on the CONTROL STATISTICS result.  The sum of this and the average
  2040. response time gives the average total elapsed response time, as observed
  2041. by the server.
  2042.  
  2043. The GoServe response time directly affects the response time seen by the
  2044. person using the client browser, so it is desirable to keep this as low
  2045. as possible; the 'Response goal' setting in the Options notebook is
  2046. provided to make it easier to judge the performance of your server
  2047. setup.  The read wait times are not included in response times so that
  2048. the graph and averages only reflect delays that are under the control of
  2049. the server.
  2050.  
  2051. The response times record may be reset using CONTROL RESET RESPONSE (or
  2052. the Actions menu item 'Reset response times').
  2053.  
  2054.  
  2055. Automatic HTTP processing
  2056. """""""""""""""""""""""""
  2057. GoServe automates several aspects of the HTTP/1.0 protocol. (For full
  2058. details of the protocol, please see the HTTP specification.)  When an
  2059. HTTP/1.0 request is received, the HTTP header lines are read
  2060. automatically (if needed).  The Content-Length and If-Modified-Since
  2061. values are extracted as appropriate.
  2062.  
  2063. When a completion command is processed, GoServe will (if the incoming
  2064. request was HTTP/1.0) generate an appropriate response line and
  2065. HTTP header.  For example, for a FILE command with a given file TYPE,
  2066. this will include the following header lines:
  2067.  
  2068.   1. 'Server:'  The name and version of the server (e.g., 'GoServe/1.88').
  2069.  
  2070.   2. 'Date:'  The message origination date and time (only if GMT can be
  2071.       determined).
  2072.  
  2073.   3. 'Message-ID:'  A unique identifier for the message.  For example,
  2074.      '<19950101121030.80.123@12.34.56.78>', which is the local date and
  2075.      time that the server was started, the port which it is serving, and
  2076.      the transaction number, followed by the primary host address.  This
  2077.      header is not required by the HTTP protocol, and so is only sent if
  2078.      the GoServe TEST parameter is in effect.
  2079.  
  2080.   4. 'Content-Type:'  The value set by the TYPE parameter.
  2081.  
  2082.   5. 'Content-Length:'  The length of the file (less 1, if TEXT was
  2083.      specified and the file ends in an EOF character).
  2084.  
  2085.   6. 'Content-Transfer-Encoding:'  Currently always 'binary'.
  2086.  
  2087.   7. 'Expires:'  Set to the current time (only if GMT is available and
  2088.      ERASE was specified on the FILE command).
  2089.  
  2090.   8. 'Last-Modified:'  Set to the timestamp of the file, converted to
  2091.      GMT (only if GMT is available and ERASE was not specified).
  2092.  
  2093. Finally, GoServe will not actually send the body of the file if the
  2094. request verb was HEAD or (if the verb was not HEAD) if the
  2095. 'Last-Modified' date is older or the same as the first
  2096. 'If-Modified-Since' date found in the request header (if any).  In this
  2097. latter case, the response line will be 'HTTP/1.0 304 Not Modified'.
  2098.  
  2099. Notes:
  2100.  
  2101.   1. If the response line has been set explicitly by the RESPONSE
  2102.      command, this overrides any possible "Not Modified" response, and
  2103.      so the 'If-Modified-Since' check does not take place (that is, the
  2104.      body of the response will be sent).
  2105.  
  2106.   2. If the client does not send the header within a short time after
  2107.      the request string, the 'If-Modified-Since' check may be bypassed.
  2108.      This bypass is to allow for some older clients that are not fully
  2109.      HTTP/1.0 compliant, and may be removed later.
  2110.  
  2111.   3. GoServe supports and automatically generates, where appropriate,
  2112.      the experimental 'Connection: keep-alive' headers used for handling
  2113.      multiple requests over one connection.  See "Persistent
  2114.      connections" for more details.
  2115.  
  2116.   4. GoServe does not automatically send a "MIME-Version" header field,
  2117.      as it can make no guarantee that the message as a whole is
  2118.      MIME-compliant (and in most cases it will not be).
  2119.  
  2120.   5. The 'HEADER NOTIME' command may be used to inhibit the sending of
  2121.      the 'Expires:' or 'Last-Modified:' header lines.
  2122.  
  2123.  
  2124. File command cache
  2125. """"""""""""""""""
  2126. GoServe includes an optional performance optimization that may be useful
  2127. for heavily loaded servers or for applications where response time is
  2128. critical.  You should only use this option if (a) you are already
  2129. allowing access to all files in your GoServe data directory, as when
  2130. using the sample filter, or (b) you have read and understood the
  2131. remainder of this section.
  2132.  
  2133. If the file command cache is made active (by selecting the 'Active'
  2134. checkbox in the 'File command cache' box on the 'General' page of the
  2135. options notebook), then eligible FILE commands will be associated with
  2136. the current HTTP or Gopher request.  If the identical request line is
  2137. received later, the FILE command will be executed immediately, without
  2138. invoking the filter.
  2139.  
  2140. This caching avoids the overhead of calling the filter.  For the sample
  2141. filter, this is small (less than 15ms on a 486/50MHz PC), but with more
  2142. complex filters this can be significant.
  2143.  
  2144. Eligible file commands are those which do not specify ERASE or NOCACHE
  2145. (see below), do not follow a SEND command, and which are issued in
  2146. response to an HTTP GET request or any Gopher request.
  2147.  
  2148. Note, however, that if the file command cache is used, there is no
  2149. filtering of the request, and so the file will be sent unconditionally
  2150. (that is, no security checking will take place, for example).
  2151. Therefore, if file caching is to be used, FILE commands referring to
  2152. sensitive files should be protected by specifying the NOCACHE option on
  2153. the command.  This prevents them being cached, and so requests for those
  2154. files will always be processed by the filter.
  2155.  
  2156. The intent of the file command cache is to minimize the response time to
  2157. the client and the load on the server by avoiding the call to the
  2158. filter.  You may, however, request that the filter still be called
  2159. (after the cached FILE command has been executed) by selecting the 'Call
  2160. filter anyway' radio button on the 'General' page or by executing 'SET
  2161. FASTFILTER ON.  This may be useful when specialized logging is being
  2162. carried out, for example.  The filter can detect whether a cached FILE
  2163. command has already been successfully executed by using the COMPLETED()
  2164. function call.
  2165.  
  2166.  
  2167. The audit mechanism
  2168. """""""""""""""""""
  2169. GoServe includes a built-in audit mechanism that records events in an
  2170. audit file while GoServe is running.  This maintains a record of usage,
  2171. and also records any errors or failures of the server.
  2172.  
  2173. By default, all audit information (see details below) except selectors
  2174. is recorded.  Choose the 'Audit' page of the Options notebook for
  2175. detailed control over which audit information will be written to the
  2176. audit file.  You should only select auditing of 'Selectors' if the
  2177. recording of selectors (request strings) would not compromise
  2178. confidentiality or privacy.
  2179.  
  2180. The audit file has a fixed filename (GOAUDIT), with an extension that is
  2181. the TCP/IP port number used (for example, 'GOAUDIT.80').  It is written
  2182. in the working directory for GoServe.  The audit file may be read but
  2183. not altered while GoServe is running.
  2184.  
  2185. For reliability, the audit file is written directly to disk and not
  2186. cached by the file system (though GoServe caches some informational
  2187. lines briefly to improve response time).  You can select the 'Lazy
  2188. audit' option for caching of up to five seconds, which will improve
  2189. server throughput under load.
  2190.  
  2191. Each line in the audit file starts with three words, separated by one or
  2192. more blanks: the time (hhmmss), the audit type (one character), and the
  2193. transaction number (a number, incremented for each connection accepted,
  2194. that begins at 0 when GoServe is started).  Additional information
  2195. follows, depending on the audit type:
  2196.  
  2197.   A (Accept)      - addresses of the client and (if non-prime) server (n.n.n.n)
  2198.   C (Complete)    - response time (seconds), and description of action
  2199.   D (Day/Time)    - current day (yyyymmdd), and description of adjustment
  2200.   E (Error)       - description of an error in processing (e.g., timeout)
  2201.   F (Failure)     - description of the failure (terminating error)
  2202.   I (Information) - description of information (statistics, etc.)
  2203.   L (Limit)       - description of limit that has been exceeded
  2204.   N (Network)     - description of how network or client ended transaction
  2205.   P (Primary)     - primary server address and port (n.n.n.n nn)
  2206.   S (Selector)    - selector received from client for each new request
  2207.   U (User)        - description of event from User (filter) command
  2208.  
  2209. The 'A' audit line includes the address of the server only if this is
  2210. different from the primary server address shown on the 'P' line.  This
  2211. may occur if more than one network is active (perhaps a real network and
  2212. a loopback configuration, or more than one active network adapter
  2213. cards).
  2214.  
  2215. The times (and dates) recorded in the audit file may be in GMT (the
  2216. default) or in local time (the default for GoServe 1.41 and earlier).
  2217. The default may be altered using the 'Audit Selection' dialog, but note
  2218. that use of GMT is only possible if GMT times are available (that is,
  2219. the TZ environment variable was set when GoServe was started or when a
  2220. time dislocation was detected).  If GMT is in use, the word 'GMT' is
  2221. added after the current day on 'D' audit lines.
  2222.  
  2223. Additional audit types may be added later.  The format of any
  2224. "description" in the above is not strictly defined, except that all
  2225. Carriage Return, Line Feed, and End of File characters (ASCII '0d'x,
  2226. '0a'x, and '1a'x) are translated to '[', ']' and '#' respectively to
  2227. ensure audit file lines are well defined.
  2228.  
  2229. For example:
  2230.  
  2231.   103701 D 0 19950620 GMT ----- GoServe 2.40 -----
  2232.   103701 P 0 9.20.1.20 80
  2233.   103726 A 1 9.20.5.59
  2234.   103726 S 1 GET / HTTP/1.0
  2235.   103727 C 1 0.9 Sent file "d:/gohttp/index.htm" [979 bytes in 0.02s]
  2236.   103727 A 2 9.20.5.59
  2237.   103727 S 2 GET /pmglobe.gif HTTP/1.0
  2238.   103728 C 2 0.95 Sent file "d:/gohttp/pmglobe.gif" [2154 bytes in 0.043s]
  2239.   103737 A 3 9.20.5.59
  2240.   103737 S 3 GET /globe?22,40 HTTP/1.0
  2241.   103738 C 3 0.9 Sent string "You clicked on the globe" [423 bytes in 0.07s]
  2242.   103745 A 4 9.20.5.59
  2243.   103745 S 4 GET /samptest.htm HTTP/1.0
  2244.   103746 C 4 1 Sent file "d:/gohttp/samptest.htm" [664 bytes in 0.012s]
  2245.   103750 A 5 9.20.5.59
  2246.   103750 S 5 GET /!statistics HTTP/1.0
  2247.   103750 C 5 0.8 Sent response "CONTROL STATISTICS" [708 bytes in 0.017s]
  2248.   103808 I 5 Bytes sent 4928 received 3045
  2249.   103808 I 5 Close
  2250.  
  2251. Most requests will end normally, with a 'C' line in the audit file.  If
  2252. an error occurs, there may be one or more 'E' lines in the audit file
  2253. instead.  If a transaction is ended by the client or network, than an
  2254. 'N' line is used, which is not recorded as an error.  Similarly, when a
  2255. chosen limit is exceeded (such as a timeout) an 'L' line is used, which
  2256. also is not recorded as an error.  A persistent-connection timeout is
  2257. considered an uninteresting event and is not audited.
  2258.  
  2259. The response time recorded on 'C' lines is rounded down to the nearest
  2260. millisecond below, and measures the total elapsed time from receiving
  2261. the request to the first send of data to the client.  This excludes any
  2262. time spent waiting for the network, but includes any time taken to
  2263. receive data from the network and so depends on the network as well as
  2264. the speed of the processor and the work done by the filter.  (See also
  2265. "Response time recording" for more details.)
  2266.  
  2267. The 'bytes' count on 'C' lines is the total number of bytes sent to the
  2268. client (including any overhead demanded by the protocol in use), and the
  2269. time shown after the bytes count is the total elapsed time for sending
  2270. the response (rounded down to the nearest millisecond below).  This
  2271. latter depends on the speed and activity of the server, client, and the
  2272. network between the two.  It is likely to be rather variable.
  2273.  
  2274.  
  2275. --- Viewing or archiving the audit file ---
  2276.  
  2277. To look at an 'active' audit file, use a program or command that allows
  2278. shared reading of files.  TYPE is one such command; its output may be
  2279. redirected to a file to take a snapshot copy of the audit file.  For
  2280. example:
  2281.  
  2282.   type goaudit.80 > snapshot.log
  2283.  
  2284. In addition, the Actions pull down menu has an item 'Move audit to
  2285. archive'.  This closes the audit file, appends it to the GoServe archive
  2286. file in the current working directory, then erases and re-opens the
  2287. audit file.  The GoServe filter can also initiate this action, by
  2288. returning "control moveaudit"--see "CONTROL command" for details.
  2289.  
  2290. The GoServe archive file has a fixed filename (GOARCH), with an
  2291. extension that is the TCP/IP port number used (for example,
  2292. 'GOARCH.80').  It is only touched by GoServe during a "Move audit to
  2293. archive", so is readily copied, edited, or renamed.
  2294.  
  2295.  
  2296. Remote control of GoServe
  2297. """""""""""""""""""""""""
  2298. GoServe filters (see "Filter programs") can request that GoServe perform
  2299. certain actions, instead of just returning files or other data.  These
  2300. requests may be used to control GoServe remotely (from another machine
  2301. or from another process on the same machine).  Control requests can
  2302. return a document containing one or more response lines, either showing
  2303. successful completion of the request or indicating an error.
  2304.  
  2305. Specifically, if the CONTROL command is used without the VAR option
  2306. (either from within the filter program or by being returned by the
  2307. filter) then the command action is performed and the result string is
  2308. returned to the client as a document.
  2309.  
  2310. More sophisticated control is possible by using the EXTRACT and SET
  2311. commands to inspect and alter a wide variety of GoServe's internal
  2312. settings.
  2313.  
  2314. The sample pages (GOR*.HTM) and the remote control filter (GOREMOTE.80)
  2315. filters included in the package use these commands to duplicate the
  2316. functions available locally via the Options settings notebook.  All the
  2317. information and settings available in the Options notebook (except the
  2318. response time graph) are available remotely.
  2319.  
  2320. Please note that for the Apply button to work on the remote control
  2321. settings pages, you must first provide and enable a password in the
  2322. "authorize:" subroutine in the main GOFILTER.80.  See that subroutine
  2323. for instructions.
  2324.  
  2325. The sample main filter also includes examples of using control commands
  2326. initiated from standard menus or documents; these actions can be
  2327. triggered remotely using a Gopher or Web client, as appropriate.  Rexx
  2328. programs can also use the OS/2 TCP/IP RxSock library (included in the
  2329. UN64092 CSD, August 1994, and also available from most OS/2 software
  2330. sources) to send a specific request to a GoServe server.  A sample
  2331. command, MOVEAUD.CMD, is included in the GoServe package as an
  2332. indication of how this is used.
  2333.  
  2334. The filter mechanism provides flexibility in how control requests are
  2335. accepted and passed to GoServe, including the possibility of
  2336. modification so that only clients with certain addresses would be able
  2337. to use these options.  The sample Web filter includes an example of how
  2338. this might be done, and the sample GOREMOTE.80 shows a mostly-generic
  2339. example of forms processing.
  2340.  
  2341.  
  2342. Persistent connections
  2343. """"""""""""""""""""""
  2344. GoServe 2.41 (and later versions) supports an experimental
  2345. implementation of persistent connections (discussed in detail in the
  2346. HTTP working group mailing list in July-August 1995, and also in IETF
  2347. draft form).  In brief, a client may request (by including the HTTP
  2348. header 'Connection:' with value 'keep-alive' or 'maintain') that a
  2349. server not close the connection after sending a response.
  2350.  
  2351. The server may choose to ignore this, or it may hold the connection open
  2352. for a period of time (typically 15 to 30 seconds), to allow the client
  2353. to send further HTTP requests over the same connection.  In the latter
  2354. case, the client is informed by the inclusion of a matching
  2355. 'Connection:' header in the response.  At any time, the transaction can
  2356. be concluded by either the client or server closing the connection or no
  2357. longer using the 'Connection:' header in the request or response header.
  2358.  
  2359. This persistent connection protocol is handled automatically by GoServe,
  2360. under the control of the LIMITTIMEWAIT (connection maintain) setting.
  2361. This setting limits the time that GoServe will wait for a new request
  2362. after being asked to do so; it may be set to zero to force GoServe to
  2363. accept only one request per connection; for the time being, this is the
  2364. default setting.
  2365.  
  2366. Notes:
  2367.  
  2368.   1. 'Transactions' in GoServe is a count of connections, not HTTP
  2369.      requests.  The latter count is available in the CONTROL STATISTICS
  2370.      response (if different from the transactions count) or by using
  2371.      QUERY REQUESTS or EXTRACT REQUESTS.  The number of requests
  2372.      corresponds to the number of 'hits' in a World-Wide Web context.
  2373.  
  2374.   2. Clients connecting to a proxy instead of directly to a server must
  2375.      use the 'Proxy-Connection: keep-alive' header instead, if a
  2376.      persistent connection is being requested.
  2377.  
  2378.   3. Suggested values for LIMITTIMEWAIT might be 15-30 seconds (which
  2379.      would handle most cases of embedded images in HTML pages, for
  2380.      example) or 60-120 seconds (to handle most cases of multiple pages,
  2381.      with their embedded images, being requested by the same client).
  2382.  
  2383.   4. [Nov95] Current browsers use the value 'keep-alive' rather than
  2384.      'maintain' in the connection header (the latter, from the HTTP
  2385.      working group, is therefore probably obsolete).  For the time
  2386.      being, GoServe supports both values and will respond with the value
  2387.      as received.
  2388.  
  2389.   5. Once a connection is being maintained, GoServe will automatically
  2390.      SET NETBUFFER OFF, so that all parts of a data stream will be sent
  2391.      to the client immediately.
  2392.  
  2393.  
  2394. Why not CGI?
  2395. """"""""""""
  2396. Many Web servers support a protocol known as the Common Gateway
  2397. Interface (CGI) for attaching and supporting scripts.  GoServe does not
  2398. yet support this interface directly due to a number of difficulties with
  2399. the design, of which the most significant (in no particular order) are:
  2400.  
  2401.   o The primary means of communicating information to scripts is by the
  2402.     use of environment variables.  These all have to be set before the
  2403.     script is called, and as the number of these grow the overhead
  2404.     approaches or exceeds the cost of interpreting the script (GoServe
  2405.     has dozens of state variables available to scripts).
  2406.  
  2407.     For GoServe, Rexx variables could be set on startup -- but a clearer
  2408.     and more efficient way of retrieving information is to use
  2409.     specialized function calls (such as GoServe's REQFIELD) or general
  2410.     commands (such as GoServe's EXTRACT, READ, and CONTROL).  With these
  2411.     mechanisms, data are moved only when required.
  2412.  
  2413.   o Environment variables are a per-process resource in OS/2; GoServe's
  2414.     scripts run on a per-thread basis (the script runs on the same
  2415.     thread that handles the incoming connection, with no process
  2416.     overhead or resource cleanup required).
  2417.  
  2418.   o The piping of the incoming data to the script would often mean that
  2419.     data are read even when unused, hence increasing the load on the
  2420.     server (and, in some cases, on the network and client browser).
  2421.  
  2422.   o For some servers, the output sent to the client is dependent on the
  2423.     name of the script (for example, scripts whose name begins with
  2424.     "nph-" may have their output treated differently from other
  2425.     scripts).  This means that arbitrary script names cannot be
  2426.     supported.
  2427.  
  2428.   o Server directives (commands sent to the server) are sent using the
  2429.     same namespace (header lines) as the header information being sent
  2430.     to the client.  Separating this information, as in GoServe, leads to
  2431.     a more reliable and extensible protocol.
  2432.  
  2433.   o CGI binary executables are loaded from .EXEs rather than as
  2434.     functions in a DLL (which would be at least twenty times faster).
  2435.  
  2436.   o CGI does not define a channel between the script and the server
  2437.     while the script is running.  Hence, dynamic information (such as
  2438.     connections and load) known to the server cannot be made available
  2439.     to the script during processing.
  2440.  
  2441.   o Standard output is used as a data channel to the server; this means
  2442.     that the only data channel to the user (Webspinner) is standard
  2443.     error, which is inappropriate for informative or status information,
  2444.     often used while developing scripts.  It also means that data are
  2445.     processed more often than needed.
  2446.  
  2447. For these reasons, it seemed unlikely that CGI scripts could be
  2448. supported with acceptable efficiency by GoServe.  GoServe's filters
  2449. provide equivalent function, and the processing logic will be
  2450. essentially unchanged, so ports of the algorithms required are easy.
  2451.  
  2452. If necessary (for example, to use an existing CGI script), the CGI
  2453. interface can be simulated by a GoServe filter.  Porting the script
  2454. will, however, give much better response times in many cases.
  2455.  
  2456.  
  2457. Setting the TZ environment variable
  2458. """""""""""""""""""""""""""""""""""
  2459. GoServe currently computes GMT from the local time-of-day clock (set by
  2460. the TIME and DATE commands) and the setting of the TZ environment
  2461. variable.  The simple form of the value of TZ (which is suitable for use
  2462. in the USA or other countries that change to and from daylight savings
  2463. time at the same time as the USA) is as shown in:
  2464.  
  2465.   SET TZ=EST5EDT
  2466.  
  2467. where EST is the standard time zone name (this must be exactly three
  2468. characters), EDT is the daylight savings time zone name (also exactly
  2469. three characters), and 5 is the difference between the standard time
  2470. zone and GMT, measured in hours West of GMT.  The second time zone name
  2471. can be omitted if no daylight savings adjustment is used.
  2472.  
  2473. The format of the GMT offset is
  2474.  
  2475.   [+|-]hh[:mm[:ss]]
  2476.  
  2477. that is, the sign (and minutes and seconds) are optional.
  2478.  
  2479. Note that the sign of the GMT offset used in the TZ variable is opposite
  2480. to that used for calculating the local time, given GMT, as returned by
  2481. the GoServe GMTOFFSET() function.
  2482.  
  2483. The simple form of TZ setting assumes the USA default of 1 hour daylight
  2484. savings change which starts at 01:00 on the first Sunday in April, and
  2485. ends at 02:00 on the last Sunday of October.
  2486.  
  2487. For other countries, the full form of the TZ value has to be used.  More
  2488. formally, this is:
  2489.  
  2490.   SET TZ=SSS[+|-]hh[:mm[:ss]]DDD,sm,sw,sd,st,em,ew,ed,et,shift
  2491.  
  2492. Where 'SSS', 'hh', 'mm', 'ss', and 'DDD' are the values as in the simple
  2493. form.  In the long form, all the other values must be specified, as
  2494. follows.
  2495.  
  2496. 'sm', 'sw', 'sd', and 'st' define the start time for daylight savings
  2497. adjustment, where:
  2498.  
  2499.   o 'sm' is the starting month (1 to 12)
  2500.  
  2501.   o 'sw' is the starting week (1 to 4 counting from the beginning, or -1
  2502.     to -4 counting from the end).  0 indicates that a particular day of
  2503.     the month is to be specified
  2504.  
  2505.   o 'sd' is the starting day (0 to 6 [where 0 is Sunday] if 'sw' is
  2506.     non-zero, or 1 to 31 if 'sw' is 0)
  2507.  
  2508.   o 'st' is the starting time in seconds from midnight (e.g., 3600 for
  2509.     01:00).
  2510.  
  2511. 'em', 'ew', 'ed', and 'et' define the end time for daylight savings, and
  2512. take the same values.
  2513.  
  2514. 'shift' is the shift in daylight time change, in seconds (e.g., 3600 if
  2515. one hour is to be added during daylight savings time).
  2516.  
  2517. For example, for the UK in 1997, the setting is expected to be:
  2518.  
  2519.   SET TZ=GMT0BST,3,0,30,3600,10,0,26,7200,3600
  2520.  
  2521. Note that there appears to be no provision for time zone names of more
  2522. than three characters (blanks are allowed, so fewer than three
  2523. characters are OK).
  2524.  
  2525. []
  2526.