The previous section illustrated the high-level message passing protocol between client and server. This section addresses the detailed syntax and format of the individual messages. As previously mentioned, each and every client request, with the exception of the ``logoff'' and ``shutdown'' request, will receive a response. The server will only handle single line URL encoded messages terminated with a newline (``
rn'' or ``n''). If a request is received, which is not properly URL encoded, it will be rejected.
The first character of a Server Response indicates the type of response sent by Status Server. There are five different responses which the Status Server can send to the Client. Each of these responses is summarized in the following list:
The first character encoding scheme is defined in such a way that it is not specific to any particular command request sent across the interface from the client.
This section contains the full set of commands, the required syntax of each command, and the response a client should expect to see. Optional arguments are included in square brackets ``[]''. The command syntax is based on a ``mixed positional/keyword'' system. In the case of mandatory arguments, they can be provided either as space delimited fields or as a fully qualified argument. As an example, the ``REGISTER'' command can either be specified as REGISTER 124 ``foo'' or as REGISTER PID=124 NAME=''foo''. Optional arguments must always be specified in a fully qualified format. Command and argument specifiers are case insensitive. For example, the ``REGISTER'' command could be sent in either upper or lower case. For clarity purposes, command and argument specifiers are shown in upper case with the arguments in lower case within this document.
If a string argument contains embedded spaces, it must be enclosed within either single or double quotes indicating that the spaces are part of the argument string. Without the enclosing quotes, the parser will interpret the string as separate arguments. Numeric parameters should not be enclosed within quotes. If the Status Server receives a numeric parameter enclosed within quotes, it will strip off the quotes before converting the string to a number.
The Client API will always send commands with fully qualified arguments and place quotes around each string parameter sent to the Status Server.
It is important to note here that the value of an object stored in the Status Server will always be enclosed within double quotes if it is valid. If the value of the object is not valid, it will not be enclosed within double quotes. For example, the following values would be considered valid: ``data'', ``0.0'', or ``sample data''. If a value is not enclosed within double quotes, it must always be one of the following values: NONEXISTENT, UNDEFINED, or EXPIRED. As a result of this encoding scheme, it is possible for the Status Server to send back a response to the client which seems to indicate that the command passed, but the Status Server value is actually invalid. It will be the responsibility of the Client API to handle these as conditions and supply the appropriate error information available to the client.
All responses that return a data object name or directory name will always return this value in its fully-qualified absolute path format. The exception is directory listings where the absolute path of the directory will be included as part of the header line and each data object name within the directory will be expressed in relative path format.
In some cases, the response from the Status Server contains the command and in other cases it does not. Since a client can only send one command request at a time, it is not necessary to encode the command request within the response. Instead, the command responses have been set up in such a way that it could be ossible to set up a cacheing proxy server to relay Status Server information. In order to enable this, wherever possible a command/value response is returned with the object name and object value. A proxy server could store a local copy of the values sent to and from the Status Server in order to reduce the load on the Status Server. There are no plans currently in place to deploy such a server, but the message protocol has been implemented in such a way that this could be a possibility in the future.
It is possible for the Status Server to supply additional information following some of the documented command responses. While the additional information may be ignored by the Client API, it could be useful for interactive use. For example, the Status Server may include the number of items returned for a directory listing request following the end-of-transaction (EOT) message.
Once a socket connection is established between the Client and Status Server, additional details describing the client can be sent to the Status Server. This registration message is optional, but will always be sent as part of the Client API initialization. Typically, a user interacting with the Status Server via a telnet session will not use this command. The message flow for this command can be found in figure 4.
REGISTER [PID=]pid [NAME=]client_name
Input parameters for the registration command are as follows:
Response the client would expect to see:
The connection between client and Status Server will remain persistent until the client chooses to disconnect, or the network connection between client and server is broken. When using a telnet connection, it is sometimes easier to type a short command than the CTRL-']' quit sequence. The Status Server will have a command available to enable a client to terminate the connection. This command will cause the client to receive an EOF across the interface indicating that the Status Server has closed the connection. The message flow for this command can be found in figure 5.
QUIT
This command does not have any input parameters and will not generate a message response.
Prior to either updating or removing an object within the Status Server, the client must perform a ``touch'' on the object. The touch enables a client to specify the intent to update or modify a value in the Status Server. The message flow for this command can be found in figure 6.
TOUCH [NAME=]obj_name [COMMENT=obj_comment] [LIFETIME=obj_lifetime]
Input parameters for the registration command are as follows:
Response the client would expect to see:
Once a successful touch has been performed on an object, it is possible for the client to initiate an update request. The update request causes the value associated with the object to be modified. The message flow for this command can be found in figure 6.
PUT [NAME=]obj_name [VALUE=]obj_value
Input parameters for the update command are as follows:
The client will receive one of the following responses:
Since the Status Server is an open repository without permissions, any client has the ability to retrieve an object from the Status Server. This command will return the value of an object in the Status Server if it is valid. If not, the reason it is not valid will be returned. Valid values will always be encapsulated within double quotes. The message flow for this command can be found in figure 6.
GET [NAME=]obj_name
Input parameters for the retrieval command are as follows:
The client will receive one of the following responses:
Clients can initiate monitors on Status Server directory or data objects in order to be informed whenever the value of an object changes. To reduce the load on both the Status Server and client, a client also has the opportunity to specify a ``deadband'' range for both floating point and integer objects. The message flow for this command can be found in figure 6.
It is not necessary for the directory or data object to exist in the Status Server in order to place a monitor on it. In this case, the monitor will be applied by the Status Server once the object is created. The client does not need to perform a touch on the object before placing a monitor on the object. The ability to place a monitor on an object, which does not yet exist, is available to prevent potential race conditions during client start up.
A monitor placed on a directory object will cause the client to be notified when the contents of a directory change. If the Status Server contained a directory with individual data objects for each filter currently installed in the CFH12K instrument, it could be possible for a client to place a monitor on this directory. As a result, a dynamic drop-down list could be generated with the current filter options. It is important to note that when a client is notified that a directory object has changed, the client must retrieve the contents of the directory via an ``ls'' command.
MONITOR [NAME=]obj_name [DB=deadband_val]
Input parameters for the registration command are as follows:
The client will receive one of the following responses:
In the case of the Client C-API, receiving a syntax error should never occur and would be considered an internal error.
Any time a monitor is added to an object in the Status Server, it can be removed by initiating a removal request. Monitors are not automatically removed when an object is removed from the Status Server. The message flow for this command can be found in figure 6.
UNMONITOR [NAME=]obj_name
Input parameters for the retrieval command are as follows:
The client will receive one of the following responses:
The Status Server will send an ``out-of-band'' notification any time it has monitored information to send to the client. As mentioned earlier, this notification will be indicated by an asterisk ('*') in the first column. The full message will be ``* MAIL''. At this point, the client will most likely respond with a request to retrieve monitor information. The Status Server will then send all monitored information to the Client followed by an end-of-transmission (EOT) message indicating that all monitored information has been sent. The full EOT message will be ``. EOT''. It is possible for the Status Server to place additional information following the mailbox and EOT messages perhaps for a comment. While this will be unused initially by the client API, it may be useful to have. For example, when a directory listing is performed interactively it may be useful to have a comment indicating the number of objects returned. The message flow for this command can be found in figure 11.
POLL
This command does not have any input parameters.
The POLL command will generate individual responses for each monitored value which has been modified beyond the deadband threshold. Once all the individual monitor updates have been sent by the Status Server, the client will receive an end-of-transmission (EOT) message. It is also possible for the client to send a POLL command and not receive any response outside of the EOT. This could occur if a monitored value changed enough to warrant a monitor notification (mailbox message), but when the Status Server received a POLL from the client, the value was within the deadband threshold for the last value sent to the client. The possible responses the client should expect to see are as follows:
The first character of the response indicates what the response means. If the first character is a '+', this indicates that the value of a monitored object has changed. If the obj_value is enclosed within double quotes, it is a valid value. If not, the state of the Status Server data object is now invalid. The `'+' character is also used to indicate that at least one more response will be sent by the Status Server for the POLL request. Once the client receives the ``. EOT'' message, it will know that the Status Server is done sending monitor updates. In addition, it is possible for the client to receive a single-line error response indicating that the client requested a POLL, but the Status Server does not have any record of monitored objects for the client.
If the Status Server should detect that the client sent a POLL command without having received a mailbox message, this will be considered a protocol error and the client will receive a protocol error response. At this point, any subsequent message received from the client will result in the Status Server terminating the client connection. The Client API will make sure that a POLL command is never sent to the Status Server without itself having received a mailbox message, so this should not be an issue with the Client API. This is added as a safeguard to prevent clients who are directly using the socket protocol from incorrectly implementing the protocol for monitor retrieval and possibly generating an excessive number of POLL requests.
Once a successful touch has been performed on an object, it is possible for the client to initiate a removal request of the object within the Status Server. The message flow for this command can be found in figure 6.
RM [NAME=]obj_name
Input parameters for the object removal command are as follows:
The client will receive one of the following responses:
Objects within the Status Server can be referenced whether via a fully qualified directory path/object name combination, or a relative path/name combination. In order to manage relative path references, the current path will be maintained by the Status Server for each client connection. This request enables the client to retrieve its current path. The message flow for this command can be found in figure 6.
PWD
This command does not have any input parameters.
There is really only one response which the client should expect to see as a result of this command.
The initial path for each client is '/'. This path will remain the default path until it is changed by the client via the CD command.
This request will cause the Status Server to modify what it uses as the current directory for relative path references made by a client. The client can specify the new current directory with either a relative path or absolute path. The message flow for this command can be found in figure 6.
CD [PATH=]dir_path
Input parameters for the change directory path command are as follows:
The client will receive one of the following responses:
While required directories are automatically created as part of the touch command when objects are created, it is also possible to explicitly create a directory. This option will create a directory if it doesn't already exist.
This command must be used prior to removing a directory and all of its contents. When a touch is performed on a directory, it is possible to remove the directory and all the objects within it without performing an explicit touch on each object. The message flow for this command can be found in figure 6.
TOUCHDIR [DIR=]dir_path [COMMENT=dir_comment]
Input parameters for the directory touch command are as follows:
The client will receive one of the following responses:
It is possible to remove a directory and all its objects. In order to help prevent an inadvertent removal of a directory, a touchdir must be performed on the directory before it can be removed. In addition, the directory must not contain any subdirectories.
RM -R [NAME=]dir_path
Input parameters for the directory removal command are as follows:
The client will receive one of the following responses:
Much like the ``ls'' command on the UNIX file system, it will be possible to retrieve the contents of a directory. This command may return more than one line as a response. The client will receive a first line indicating whether the command was successful followed by a sequence of responses with the contents of the directory. The last line sent by the server will indicate the end of the transaction. Objects and directories will be returned in an ascending ASCII sort order by name. In addition, this command will allow for the same regular expression matching rules used by the UNIX ``ls'' command. The message flow for this command can be found in figure 10.
LS [DIR=]dir_path [-l]
Input parameters for the directory retrieval command are as follows:
The LS commend will generates a sequence of replies. Upon response to the initial LS request, the Status Server will send one of the following responses:
If the client received a positive response to the listing request, the Status Server will generate individual responses for each object or subdirectory which matches the query request. Subdirectories can be differentiated from objects by the trailing '/'. Once all the contents of the directory have been sent by the Status Server, the client will receive an end-of-transmission (EOT) message. The possible responses the client should expect following a successful LS request are:
For diagnostic purposes, it may be important to have a more detailed view of what is happening within the Status Server. This may help solve an issue with the way the Status Server is working or help diagnose a misbehaving client.
Trace information will be stored as debug information within the CFHT log. As a result, it will be possible to associate activity within the Status Server with external events to help identify and narrow down problems. The message flow for this command can be found in figure 6.
TRACE ON
This command does not have any input parameters
The client should receive the following response:
Once a trace is initiated, a client request must be performed to stop it. The message flow for this command can be found in figure 6.
TRACE OFF
This command does not have any input parameters
The client should receive the following response:
The Status Server will serialize a copy of itself to disk any time it receives a message from a client, or if the 10 minute interval has expired. The only information which will be saved is the data associated with the structure used to hold the Status Server objects. It is important to note that information associated with client connections will not be saved as part of the serialization process. This is because all client connections will be lost as part of a Status Server restart and restore operation. The message flow for this command can be found in figure 6.
AUTOSAVE
This command does not have any input parameters
The client should receive the following response:
The Status Server will send a response prior to the initiation of the forked process to perform the serialization. This is done in order to limit the complexity required to send a true return value as a result of the serialization operation in the forked process. If the serialization should fail, details regarding the failure should be available in the CFHT log. As a result, if a client actively chooses to initiate a serialization request, he/she should check to make sure the serialization file was successfully written.
For maintenance reasons, it may be necessary to shutdown the Status Server. In order to preserve the current state of information within the server, a copy of the Status Server information will be serialized to disk before an exit is performed. The message flow for this command can be found in figure 7
SHUTDOWN
This command does not have any input parameters and will not generate a response outside of the EOF sent across the interface indicating that the socket connection was closed by the server.
At some point, the client may believe that the Status Server has committed a protocol error violation. If this is detected by the Client API, it will send a ``PROTOCOL ERROR'' message to the Status Server. Once the Status Server receives this message, it will log error information to the CFHT log and terminate the client connection. Figure 9 contains a sample of a client detected protocol error.
PROTOCOL ERROR
This command does not have any input parameters and will not generate a response outside of the EOF sent across the interface to the client indicating that its connection was closed by the server.