GoServe: Filter programs

Filter programs

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

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

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

For examples of filters and forms processing, please see the sample filters in the GoHTTP or GoGopher collections. The following is specific technical information on how the filters work.

Three argument strings are passed to the filter:

The source of the request. This has five words [more words could be added at the end in the future], separated by one or more blanks:
- the Internet address of the server for this request (in numeric form). This is normally constant, unless you have more than one network defined; for example, a 'real' network and a loopback configuration, or more than one network adapter card.
- the server's port number used for the connection.
- the transaction number (a number, incremented for each new request, that starts at 0 when GoServe is started).
- the Internet address of the client (in numeric form). Note that this may not be the address of the end-user's machine, if the connection is made through a proxy or firewall.
- the client's port number used for the connection.
Example: "9.15.11.189 80 101 9.20.25.65 1987"
The request string.
- For a Web server, this string is the HTTP request string, exactly as received from the client. This comprises three words: the request verb (e.g., 'GET'), the URI (Universal Resource Identifier) or partial URI, and the HTTP protocol identifier (e.g., 'HTTP/1.0'). The third word may be absent when older (HTTP/0.9) clients connect. A URI of just '/' indicates the initial contact from a client, and the filter would normally respond with a default document ("home page").
  Partial URIs are (or should be) the request string from a Web 'href' attribute previously sent to the client, unchanged [except that extra data, such as incoming data from forms, may be suffixed, and a leading slash, '/', may be added]. For more information on URIs, see the technical details available on the Web. A good place to start is the Web information based at 'http://info.cern.ch/'.
- For a Gopher server, the request string is any data received from the client up to (but not including) a Tab, Carriage Return, or Line Feed. An empty request string indicates the initial contact from a client, and the filter would normally respond with a default Gopher menu. Otherwise, it will (or should) be the request string from a Gopher menu line previously sent to the client, unchanged.
You have complete freedom in setting request strings in Web documents and Gopher menus, and in deciding how the filter should respond depending on the string received. Very often, the name of a file is used, and that file is sent to the client. [Note: it is recommended that fully qualified filenames NOT be used for request strings.]
The extended request string.
- For an HTTP server, this string is the "packed" URI or partial URI. This is the second word of the request string, with escape sequences (e.g., '%7e') converted to a single byte, and with any leading slash ('/'), if present, removed.
- For a Gopher server, this is the 'Gopher+' data. Some Gopher clients can add additional information to a request, attached to the request string after a Tab character. GoServe discards the Tab character and presents the remainder as the third argument to the filter. See Gopher protocol documents for more information on how the extended selector string is used.

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

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

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

Any failure of the filter (such as a syntax error) is considered catastrophic and will cause GoServe to end.

Notes:

Remember that GoServe will run multiple copies of the filter at once, on different threads, if more than one client connects at the same time. If building temporary files, use the transaction number and port as part of the file name.
The results of SAY instructions (or tracing) in the filter program may be seen using the PMprintf package. However, Rexx interactive tracing is not supported. PMprintf should be available from the same source as GoServe, or from the GoServe Web page at http://www2.hursley.ibm.com/goserve/
You may change the name of the filter when starting GoServe or by using the 'Filter selection' options page. The filter must always be in the working directory for GoServe. If you make changes to the default filter, it's a good idea to change its name, too, so if you install a new version of GoServe your filter will not be overwritten by the new default filter.
External subroutines, written in Rexx, are easily called from the filter simply by using their name in a CALL instruction or function call. The names should not match that of a Rexx built-in function, and the routine should normally be in a file with the same extension (e.g, '.80') as the filter and in the same directory.
You can execute OS/2 commands from the filter using the Address CMD instruction, for example:
```
  address cmd
  'start e foo.bar'
  'call d:\foobar\test.cmd argstring'
```
Use caution when calling external programs before the response is complete: any slowness directly affects the response time to the client and its user. Note also that separate processes (including external commands) are not terminated automatically by GoServe if a connection times out.
Finally, when executing commands, do not build any part of the command string from data received from the client; this could allow execution of arbitrary commands on your server (for example, if an '&' command separator character were included in the data).
By default, each copy of a filter may have up to five files open at once. This limit may be increased using the Limits selection dialog (see elsewhere).
A new version of the filter is only cached (loaded) when GoServe is idle, and has been idle for 5-10 seconds. Therefore, if you change the filter while GoServe is running, the changes will not be used until the first client connects after a time when there have been no clients connected for ten seconds.
For more information on Rexx, try connecting to the Rexx Language page at: http://rexx.hursley.ibm.com/rexx/
For more information on OS/2, try connecting to the IBM Almaden Research Center server, at index.almaden.ibm.com. Both Web and Gopher clients are supported (the server runs GoServe). The IBM home page (http://www.ibm.com) is another good starting point for OS/2 information (use the Search option).

[ previous section | GoServe | next section ]