Node:gnatsd command protocol, Next:gnatsd commands, Previous:gnatsd options, Up:gnatsd
gnatsd
command protocolCommands 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.
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 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.
Multiple error messages may be returned from a command; in this case the
-
continuation character is used on all but the last response
line.