Command/Reply Formatting Rules

The commands sent by a client and responses sent back by the server must adhere to the following formatting conventions.

Client Command Format

• Each client command is composed of a single line of text terminated by a newline character. A carriage return followed by a newline (\r\n) is considered to be the same as a newline character (\n) alone.
• Client commands may or may not require additional parameters. Each parameter consists of the option name and value, separated by an equal sign (=) and enclosed in quotes. Multiple parameters should be separated by a comma (,) and space. Example command1=value1, command2=value2 ... If a parameter supports multiple values, the values should be separated by a comma (,). Example: command1=value1,value2,...
• No whitespace characters should appear in the argument name. No whitespace should occur between the argument name and the equal (=) delimiter. Whitespace that occurs after the equal (=) is considered part of the argument value.
• Double-quotes are not permitted as part of the value.
• For each client command, the server responds with a response code indicating success or failure, and optionally some descriptive text indicating actions taken.
• If a client command produces a reply with more than one line of output, the server responds with a 203 response code (see below). Each set of output is terminated with a newline (\n) and the end of the array is indicated with a newline (\n) by itself.
• Command and parameter names are NOT case sensitive.
• Parameters for any command may appear in any order following the command.
• Certain parameters indicate a value of <regexp>, which indicates that the parameter may point to a non-unique value. You can use an asterisk (*) as a wildcard in such case. For example, dev* would match device1 and Device B but not my device. However, *dev* would match all three.
• Parameters which indicate <value> require a value which is already present in the database, while <new_value> indicates a new value to be inserted into the database.
• All date/time values should be specified in YYYYMMDDhhmm format and in the logged in user's timezone.
• For startTime, a blank value or zero (0) indicates 24 hours ago and for endTime, it indicates now.
• timezone_value is specified in format listed at http://www.timezoneconverter.com/cgi-bin/zonehelp.tzc?cc=US.
• A special parameter userName=<value> is available to admin users. When used, the command is executed for the matching objects as the specified user.

Server Response Format

The server always responds to client initiated commands/requests with text in the format: <status code> <response code> <optional informative text>
where <status_code> is one of the following:

• OK, which indicates the command/request was successful
• ERR, which indicates failure to execute the request
• and <response_code> is a three digit numeric code which provides additional details about the status code.