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