B.3 gnatsd command protocol

Commands are issued to gnatsd as one or more words followed by a carriage-return/linefeed pair. For example, the CHDB (change database) command is sent as ‘CHDB database<CR><LF>’ (the CRLF will not be explicitly written for future examples.)

Replies from gnatsd are returned as one or more response lines containing a 3-digit numeric code followed by a human-readable string; the line is terminated with a <CR><LF> pair. For example, one possible response to the CHDB command above would be:

210 Now accessing GNATS database 'database'.

The three-digit code is normally followed by a single ASCII space (character 0x20). However, if additional response lines are to be returned from the server, there will be a single dash ‘-’ instead of the space character after the three-digit code.

Response code values are divided into ranges. The first digit reflects the general type of response (such as ”successful” or ”error”), and the subsequent digits identify the specific type of response.

Codes 200-299

Positive response indicating that the command was successful. No subsequent data will be transmitted with the response. In particular, code 210 (CODE_OK) is used as the positive result code for most simple commands.

Commands that expect additional data from the client (such as SUBM or VFLD) use a two-step mechanism for sending the data. The server will respond to the initial command with either a 211 (CODE_SEND_PR) or 212 (CODE_SEND_TEXT) response line, or an error code if an error occurred with the initial command. The client is then expected to send the remaining data using the same quoting mechanism as described for server responses in the 300-349 range. The server will then send a final response line to the command.

Codes 300-399

Positive response indicating that the query request was successful, and that a PR or other data will follow. Codes 300-349 are used when transmitting PRs, and 350-399 are used for other responses.

Codes in the 300-349 range are followed by a series of CRLF-terminated lines containing the command response, usually a PR. The final line of the result is a single period ‘.’. Result lines that begin with a period have an extra period prepended to them.

Codes in the 350-399 range use a different scheme for sending their responses. The three-digit numeric code will be followed by either a dash ‘-’ or a single space. If the code is followed by a dash, that indicates that another response line will follow. The final line of the response has a single space after the three-digit code.

In previous versions of the protocol the first line of a CODE_INFORMATION (310) response was to be ignored. This is no longer the case. Instead, any lines marked with code CODE_INFORMATION_FILLER (351) are to be ignored. This allows the server to transmit additional headers or other human-readable text that can be safely ignored by the clients.

Codes 400-599

An error occurred, usually because of invalid command parameters or invalid input from the client, missing arguments to the command, or a command was issued out of sequence. The human-readable message associated with the response line describes the general problem encountered with the command.

Multiple error messages may be returned from a command; in this case the ‘-’ continuation character is used on all but the last response line.

Codes 600-799

An internal error occurred on the server, a timeout occurred reading data from the client, or a network failure occurred. These errors are of the ”this should not occur” nature, and retrying the operation may resolve the problem. Fortunately, most GNATS transactions are idempotent; unfortunately, locking the database or a PR are not repeatable actions (we cannot determine if an existing lock is the one we originally requested, or someone else’s).

This document was generated by Chad Walstrom on March 3, 2015 using texi2html 1.82.