Commands may be executed by GoServe filters at any time, using the usual Rexx command syntax (a clause that is just an expression). In addition, any string returned by the filter will be executed as a command.
For simplicity and efficiency, most requests can be satisfied by executing a single command which sends some data (often a file) to the client and then closes the connection (unless it is persistent, see below). These commands (CLOSE, CONTROL, FILE, NODATA, STRING, and VAR) are known as 'completion commands'; that is, after executing the command, the response to the client will have been sent and will be complete.
Only one completion command may be executed for each request received; once a completion command has been executed, no further commands (except CLOSE) will be accepted for the transaction until a new request is received, which can only occur if the connection is persistent.
In some situations, it is useful to be able to build up the response from more than one data source; in this case, the SEND command is used to start the sending of the response. One or more of the completion commands are then used to send the data (in this case, the connection is not closed after the commands), and then the connection is closed by using the SEND COMPLETE command.
When completion commands are executed, GoServe (actually, TCP/IP) will normally collect the data from them in a buffer and send packets of data when enough has been collected. GoServe can be made to send the data immediately the commands are executed by using the command SET NETBUFFER OFF.
If the filter ends without error or sending any data and without executing or returning any completion command, the server will generate one (currently "String [No information available]").
Errors and failures in commands are reported by a non-zero return code (which is placed in the Rexx variable RC), and also may raise the ERROR or FAILURE condition if enabled by SIGNAL ON or CALL ON in the filter. Command errors are also audited unless Error auditing has been turned off. For details on the possible return codes, see "Command return codes".
The total length of a command is limited to 1000 characters.
The most important commands are the completion commands, though there are others which will be useful to filter writers. The commands follow in alphabetical order; note that keywords and file specifications may be in lower, upper, or mixed case.
[ previous section | contents | next section ]
From 'goserve.doc', version 2.52.
Copyright © IBM Corporation, 1993, 1998. All rights reserved.