# The RefDB client/server communication protocol

This chapter describes the communication protocol that the RefDB clients and server use to talk to each other. Knowledge of this protocol is useful for programmers who want to write custom RefDB clients. The protocol is versioned in order to allow clients and servers to negotiate whether they can fulfil each other's expectations. The protocol described in this document is version 5.

The RefDB project provides a Perl client module in addition to the C clients shipped with the RefDB package proper. Due to the simplicity of the Perl language, this module is a good resource for programmers who want to implement clients in other programming languages.

## Prerequisites

Custom clients or client libraries can be implemented in any programming language that can create a Unix socket connection to the server and send/receive byte sequences through the socket. As the transferred data are essentially plain text, the endianness of the computer as well as the internal representation of data types in the particular programming language are irrelevant.

## Basic principles

refdbd is implemented as a forking server. The parent process waits to accept connections from the clients. If a valid connection request is detected, the server forks. The parent closes the connection and is ready to respond to further requests. The child processes the client request and terminates when done.

The communication between the client and the server is at least a two-stage process. In the first stage, the validity of the client request is checked, the protocol version is checked and the password encryption is initiated. In the second stage, the command proper is executed and the results are sent back to the client. The second stage may use several iterations of client/server messages in order to transfer larger amounts of data.

### Message format

All data, that is client commands as well as the server-generated results, are sent as plain text. We have to distinguish between three types of messages:

Status messages

  Status messages are unterminated three-byte sequences which encode the client or server status. They may precede terminated messages, but they can also appear alone. The three bytes are a text representation of the client or server status. E.g. the sequence "000" (that is, three times the ASCII character 48 representing the digit 'zero') denotes an OK status. A listing of the status messages used by RefDB is shown in the section Status Messages.

Terminated messages

  Most of the data transfer between client and server uses terminated messages. Due to the support of multibyte character sets the string termination character is not a single '\0' character as in a C string, but a sequence of four consecutive '\0' bytes (sequences of up to three '\0' bytes may occur as part of multibyte Unicode characters). It is best to think of the messages as binary strings. A custom client has to terminate its messages to the server appropriately, and it has to scan the data sent back by the server for the terminating sequence.

Messages of a specified length

  In a few cases, the client asks the server to provide a buffer of a certain size, and will subsequently transfer exactly the requested number of bytes. These messages are unterminated.

### First stage

The purpose of the first stage is to check whether the client request makes sense at all, and if so, to initiate the exchange of the password encryption information.

#### Sanity and permission check

Unless told otherwise, refdbd accepts only local connections. If the client request stems from a computer with a different IP address than the computer that runs refdbd, the connection request is refused without any further attempt to talk to the client. From the client side the connection will simply time out. This "unfriendly" behaviour minimizes the risk of remote exploits.

If the client is allowed to connect, refdbd tries to read a terminated string from the client. If this string is too short or too long to represent the protocol number which the client is supposed to send, the connection request is refused by sending back an appropriate status message. The same occurs if the protocol version of the client is not supported by the server.

#### Password encryption

The RefDB clients may have to transmit the database username and password in order to authenticate the user with the database server. In order to avoid sending the password across the network as plain text, the clients send encrypted versions, which the refdbd server decrypts again. Database engine client libraries usually employ their own means to encrypt the passwords when they are sent from refdbd to the database engine.

RefDB uses a fairly simple password encryption. It is still too cumbersome to decrypt for bored script kiddies so it should serve it's purpose. The encryption is somewhat modeled after the (in)famous ENIGMA boxes used by the bad guys in WWII. The basic idea is that refdbd sends a string to the client which encodes the (randomly generated) rotor sequence and positions for this particular connection. The client uses this information to encode the password. The server can decrypt the password using the sequence and position information that it previously generated.

The rotor wirings are hardcoded. Any client or library has to use the same wirings as in `src/filename.c`. The encoding string has the format "ABC-DE-FG-HI", which stands for:

ABC

  This three-digit string denotes the sequence of the wheels. ABC denote the wheels in slots 0, 1, and 2, respectively. The wheels are also numbered 0 through 2, and each wheel can be used only once. That is, all valid combinations are "012", "021", "102", "120", "210", "201". For example, the string "120" means that wheel 1 is inserted in slot 0, wheel 2 in slot 1, and wheel 0 in slot 2.

DE

  The position of the wheel in slot 0. A two-digit integer equal to or larger than 0 and smaller than 94. For example, the string "05" means the wheel in slot 0 has to advance 5 positions.

FG

  Same as DE, but for slot 1.

HI

  Same as DE, but for slot 2.

The encryption and decryption itself is described in sufficient detail in the source file `src/enigma.c` or in the `Client.pm` file of the RefDBClient Perl module. If you cannot implement this mechanism in your favourite programming language, there is also an external program eenc as part of the RefDB distribution which performs the encryption/decryption and sends the result to `stdout`. Use it like this:

    	  ~$
    	  eenc -p ABC-DE-FG-HI password

Most programming languages allow to read the results from `stdout` into a variable and use it as the encrypted or decrypted string.

There is no switch for encryption or decryption as the ENIGMA mechanism is symmetrical.

### Second stage

As the first step of the second stage the client sends the command string proper. These strings are commands as you know them from your shell. They are roughly equivalent to the command strings that you type into the C clients. refdbd parses the command string internally with the getopt library, just as your shell does. After the command string is parsed, refdbd executes the command. The result is returned in at least two steps. With one exception, refdbd first sends back the command result, followed by a command summary. For example, the listdb command first sends back a newline-separated list of database names (the command result proper), followed by the number of available databases (the command summary). These steps are explained in more detail in the following sections. First we'll have a look at the internal command syntax.

#### Command syntax

Each command consists of the command word proper, optionally followed by switches, options, and arguments. As the string is parsed by the getopt library, the sequence of options, commands, and arguments does not matter. The following synopsis shows all possible switches and options.

`command` -a -A in_format -b listname -d database -E encoding -G URL -H host -k -n -N limit[:offset] -o number -p -P -r -R pdfroot -s format_string -S sort_string -t ref_format -u username -U name -w password -W newuser_password

-a

  The commands getjo, getjf, getj1, and getj2 use this switch to request all journal names (short, full, user abbrev1, and user abbrev2) instead of only the one used to match the query.

-A in_format

  The input data format for addref, updateref, and checkref. Currently supported values are "ris" and "risx".

-b listname

  Specifies the name of a personal reference list.

-d database

  This option sets the name of the database to be used with the current command.

-E encoding

  This option sets the character encoding for the current command.

-G URL

  The getref command uses this option to pass the URL of a CSS stylesheet to the server.

-H host

  The adduser command uses this option to set the hostname or IP address of the user to be added.

-k

  This switch tells the addref command to preserve the numerical ID of the datasets in the U5 field.

-n namespace

  This option passes a namespace prefix to the getref and getnote commands (applies only to XML output)

-N limit[:offset]

  The getref command and all other get* commands use this option to limit the range of datasets to return. limit denotes the number of references to return, and offset is an optional number of references to skip at the beginning.

-o number

  This option is used to set a custom starting number for numeric bibliographies.

-p

  This option is used with the addref and updateref commands. If set, refdbd will update personal info only.

-P

  If used with the getref command, only references in the personal interest list will be returned.

-r

  This switch is used with several commands to turn an "add" operation into a "remove" operation.

-R pdfroot

  This option tells the getref command the variant part of the link to an electronic offprint.

-s format_string

  getbib uses this option to pass the bibliography style. Checkref uses this option to request additional fields in the xhtml output.

-S sort_string

  The name of the bibliography style to be used with the getbib command.

-t ref_format

  The output format of the references retrieved with the getref and getbib commands.

-u username

  The username to be used to authenticate with the database engine.

-U name

  The name of the user to be associated with a query.

-w password

  The password to be used to authenticate with the database engine.

-W newuser_password

  The adduser command uses this option to set the password of the new user.

## Commented abstract representation of the client/server protocol

This chapter tries to explain the client/server protocol of all currently supported RefDB commands using an abstract representation which should be fairly easy to port to any real programming language.

### First stage

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 6\0\0\0\0 |  |  | the current protocol version, a terminated string of up to 16 characters. The whole string will be converted to an integer internally. The current protocol version of RefDB is a compile-time constant which is defined in `src/connect.h`.
2 |  | 000ABC-DE-FG-HI\0\0\0\0 | ok | the ok status message, followed by the randomly generated encryption string
|  |  | error | there is no server response in case of a refused remote connection
|  | 102, 103, 104, or 801 | error | an error status message, ending the dialog
3 | 000command\0\0\0\0 |  | ok | the ok status message, followed by the command proper. See below for details.
| 112 |  | error | the error status code signalling a client error

### Second stage

The second stage is the more interesting part of the protocol, as it is here where the commands differ. The following section briefly explain the inner workings of the commands and show an abstract representation of the protocol.

#### addlink

The internal API command `addlink` corresponds to refdbc: addlink.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000addlink [options] link-spec [link-spec...]\0\0\0\0 |  | ok | the ok message status, followed by the terminated addlink command sting
2 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
|  | 803 | partial success, aborted after unrecoverable error | the error message status, followed by a terminated string containing the command result
|  | 204, 417, 233, or 801 | error | the error message status which terminates the session
3 | 000 |  | ok | the ok message status
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
5 | 000 |  | ok | the ok message status, ending the dialog

#### addnote

The internal API command `addnote` corresponds to refdbc: addnote.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000addnote [options] filename\0\0\0\0 |  | ok | the ok message status, followed by the terminated addnote command sting
2 |  | 000 | ok | the ok message status
|  | 701 | warning | the warning message status
|  | 202, 204, or 801 | error | the error message status which terminates the session
3 | 000<bytes>\0\0\0\0 |  | ok | the ok message status, followed by a terminated string denoting the number of bytes that the client wants to transmit
| 402 |  | ok | the message status saying that all data have been sent, ending the loop over all datasets
| 404 |  | ok | the message status saying that the current dataset has been sent completely
| 401 |  | error | the message status saying that there was a problem reading the input data, ending the session
4 |  | 000 | ok | the ok message status
|  | 801 | error | the error message status, ending the session
5 | <data> |  | ok | the previously announced number of data bytes
6 |  | 403 | ok | the ok status for a successfully transmitted chunk of data
|  | 400<message>\0\0\0\0 | error | the error status, followed by a terminated, server-generated error message specifying the error
|  | 408 or 413 | ok | the message status denoting success of the previous add or update action
|  | 702, 801 | error | the error status, followed by a terminated, server-generated error message specifying the error
7 | see step 3 |  | ok | repeat loop until end of data
| 402 |  | ok | the message status saying that all data have been sent, ending the loop over all datasets
| 404 |  | ok | the message status saying that the current dataset has been sent completely
8 |  | 403<result message>\0\0\0\0 | ok | the ok status signalling that a chunk has been added successfully, followed by the terminated server result message, finishing the dialog
9 | 000 |  | ok | the ok message status, ending the dialog

#### addref, updateref, checkref

The addref and updateref commands send bibliographic data in various formats to the database in order to add or update them, respectively. The related checkref command also sends bibliographic data to the server in order to check for duplicates. The client/server protocols differ slightly based on the type of data transferred. RIS data are transmitted one dataset at a time, whereas XML data are streamed in chunks of a defined size.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000XXref -s ris [options]\0\0\0\0 |  | ok | the ok message status, followed by the terminated addref command sting
2 |  | 000 | ok | the ok message status
|  | 701 | warning | the warning message status
|  | 202, 401, or 801 | error | the error message status which terminates the session
3 | 000<bytes>\0\0\0\0 |  | ok | the ok message status, followed by a terminated string denoting the number of bytes that the client wants to transmit
| 402 |  | ok | the message status saying that all data have been sent, ending the loop over all datasets
| 401 |  | error | the message status saying that there was a problem reading the input data, ending the session
4 |  | 000 | ok | the ok message status
|  | 801 | error | the error message status, ending the session
5 | <data> |  | ok | the previously announced number of data bytes
6 |  | 403 | ok | the ok status for a successfully transmitted chunk of data
|  | 400<message>\0\0\0\0 | error | the error status, followed by a terminated, server-generated error message specifying the error
|  | 408<message>\0\0\0\0 or 413<message>\0\0\0\0 | ok | the message status denoting success of the previous add or update action, followed by the current value of the dataset counter
|  | 702, 801 | error | the error status, followed by a terminated, server-generated error message specifying the error
7 | see step 3 |  | ok | repeat loop until end of data
| 402 |  | ok | the message status saying that all data have been sent, ending the loop over all datasets
8 |  | 403<data>\0\0\0\0 | ok | the ok status signalling that a chunk has been added successfully, followed by an optional terminated string containing a result message
9 | 000 |  | ok | the ok message status
10 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
11 | 000 |  | ok | the ok message status, ending the dialog

And now the slightly different protocol for risx data:

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000addref -s risx [options]\0\0\0\0 |  | ok | the ok message status, followed by the terminated addref command sting
2 |  | 000 | ok | the ok message status
|  | 701 | warning | the warning message status
|  | 202, 204, or 801 | error | the error message status which terminates the session
3 | 000<bytes>\0\0\0\0 |  | ok | the ok message status, followed by a terminated string denoting the number of bytes that the client wants to transmit
| 402 |  | ok | the message status saying that all data have been sent, ending the loop over all datasets
| 404 |  | ok | the message status saying that the current dataset has been sent completely
| 401 |  | error | the message status saying that there was a problem reading the input data, ending the session
4 |  | 000 | ok | the ok message status
|  | 801 | error | the error message status, ending the session
5 | <data> |  | ok | the previously announced number of data bytes
6 |  | 403 | ok | the ok status for a successfully transmitted chunk of data
|  | 400<message>\0\0\0\0 | error | the error status, followed by a terminated, server-generated error message specifying the error
|  | 408<message>\0\0\0\0 or 413<message>\0\0\0\0 | ok | the message status denoting success of the previous add or update action, followed by the current value of the dataset counter
|  | 702, 801 | error | the error status, followed by a terminated, server-generated error message specifying the error
7 | see step 3 |  | ok | repeat loop until end of data
| 402 |  | ok | the message status saying that all data have been sent, ending the loop over all datasets
8 |  | 403<data>\0\0\0\0 | ok | the ok status signalling that a chunk has been added successfully, followed by an optional terminated string containing the result message
9 | 000 |  | ok | the ok message status
10 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
11 | 000 |  | ok | the ok message status, ending the dialog

#### addstyle

The internal API command `addstyle` corresponds to refdba: addstyle.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000addstyle [options] filename\0\0\0\0 |  | ok | the ok message status, followed by the terminated addstyle command sting
2 |  | 000 | ok | the ok message status
|  | 104, 105, 106, 107, 108, 202, 203, 204, 206, or 801 | error | the error message status which terminates the session
3 | 000<bytes>\0\0\0\0 |  | ok | the ok message status, followed by a terminated string denoting the number of bytes that the client wants to transmit
| 402 |  | ok | the message status saying that all data have been sent, ending the loop over all datasets
| 404 |  | ok | the message status saying that the current dataset has been sent completely
| 401 |  | error | the message status saying that there was a problem reading the input data, ending the session
4 |  | 000 | ok | the ok message status
|  | 801 | error | the error message status, ending the session
5 | <data> |  | ok | the previously announced number of data bytes
6 |  | 403 | ok | the ok status for a successfully transmitted chunk of data
|  | 400<message>\0\0\0\0 | error | the error status, followed by a terminated, server-generated error message specifying the error
7 | see step 3 |  | ok | repeat loop until end of data
| 402 |  | ok | the message status saying that all data have been sent, ending the loop over all datasets
| 404 |  | ok | the message status saying that the current dataset has been sent completely
8 |  | 403<result message>\0\0\0\0 | ok | the ok status signalling that a chunk has been added successfully, followed by the terminated server result message, finishing the dialog
9 | 000 |  | ok | the ok message status, ending the dialog

#### adduser

The internal API command `adduser` corresponds to refdba: adduser.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000adduser [options]\0\0\0\0 |  | ok | the ok message status, followed by the terminated adduser command sting
2 |  | 000 | ok | the ok message status
|  | 202 224 or 801 | error | the error message status which terminates the session
3 | 000<names>\0\0\0\0 |  | ok | the ok message status, followed by a terminated string containing a list of names
4 |  | 000<summary>\0\0\0\0 | ok | the ok message status
| 205 801 |  | error | the message status saying that there was a problem, ending the session
5 | 000 |  | ok | the ok message status, ending the dialog

#### addword

The internal API command `addword` handles both the refdba: addword and the refdba: deleteword client commands.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000addword [options]\0\0\0\0 |  | ok | the ok message status, followed by the terminated addword command sting
2 |  | 000 | ok | the ok message status
|  | 202, or 801 | error | the error message status which terminates the session
3 | 000<data>\0\0\0\0 |  | ok | the ok message status, followed by a terminated string containing the word list
| 112 |  | error | the error message status which terminates the session
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
5 | 000 |  | ok | the ok message status
6 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
7 | 000 |  | ok | the ok message status, ending the dialog

#### confserv

The internal API command `confserv` corresponds to refdba: confserv.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000confserv command [argument]\0\0\0\0 |  | ok | the ok message status, followed by the terminated confserv command sting
2 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
|  | 202, 301, 801, 839, 840 | error | the error message status which terminates the session
3 | 000 |  | ok | the ok message status
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
5 | 000 |  | ok | the ok message status, ending the dialog

#### createdb

The internal API command `createdb` corresponds to refdba: createdb.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000createdb [options]dbname\0\0\0\0 |  | ok | the ok message status, followed by the terminated createdb command sting
2 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
|  | 111, or 801 | error | the error message status which terminates the session
3 | 000 |  | ok | the ok message status
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
5 | 000 |  | ok | the ok message status, ending the dialog

#### deletedb

The internal API command `deletedb` corresponds to refdba: deletedb.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000deletedb [options]\0\0\0\0 |  | ok | the ok message status, followed by the terminated deletedb command sting
2 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
|  | 202, or 801 | error | the error message status which terminates the session
3 | 000 |  | ok | the ok message status
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
5 | 000 |  | ok | the ok message status, ending the dialog

#### deletenote

The internal API command `deletenote` corresponds to refdbc: deletenote.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000deletenote [options] <bytes>\0\0\0\0 |  | ok | the ok message status, followed by the terminated adduser command sting containing the number of bytes required to store the ID list.
2 |  | 000 | ok | the ok message status
|  | 111 801 | error | the error message status which terminates the session
3 | 000<ID-list>\0\0\0\0 |  | ok | the ok message status, followed by a terminated string containing a list of note IDs
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a report about the delete actions
|  | 204, 412, 801 | error | the message status saying that there was a problem, ending the session
5 | 000 |  | ok | the ok message status
6 |  | 000<summary>\0\0\0\0 | ok | the ok message status, followed by a command summary
7 | 000 |  | ok | the ok message status, ending the dialog

#### deleteref

The internal API command `deleteref` corresponds to refdbc: deleteref.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000deleteref [options] <bytes>\0\0\0\0 |  | ok | the ok message status, followed by the terminated adduser command sting containing the number of bytes required to store the ID list.
2 |  | 000 | ok | the ok message status
|  | 801 | error | the error message status which terminates the session
3 | 000<ID-list>\0\0\0\0 |  | ok | the ok message status, followed by a terminated string containing a list of reference IDs
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a report about the delete actions
|  | 204, 412, 801 | error | the message status saying that there was a problem, ending the session
5 | 000 |  | ok | the ok message status
6 |  | 000<summary>\0\0\0\0 | ok | the ok message status, followed by a command summary
7 | 000 |  | ok | the ok message status, ending the dialog

#### deletestyle

The internal API command `deletestyle` corresponds to refdba: deletestyle.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000deletestyle {regexp}\0\0\0\0 |  | ok | the ok message status, followed by the terminated deletestyle command sting
2 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
|  | 202, 234, or 801 | error | the error message status which terminates the session
3 | 000 |  | ok | the ok message status
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
5 | 000 |  | ok | the ok message status, ending the dialog

#### getau, geted, getas, getkw, getjo, getjf, getj1, getj2

These internal API commands correspond to the client commands refdbc: getau, refdbc: geted, refdbc: getas, refdbc: getkw, refdbc: getjo, refdbc: getjf, refdbc: getj1, refdbc: getj2.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000getXX [options]\0\0\0\0 |  | ok | the ok message status, followed by the terminated command sting
2 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
|  | 204, 208, 234, or 801 | error | the error message status which terminates the session
3 | 000 |  | ok | the ok message status
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
5 | 000 |  | ok | the ok message status, ending the dialog

#### getbib

The internal API command `getbib` is used by the refdbib tool to retrieve cooked SGML and XML bibliographies.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000getbib [options]\0\0\0\0 |  | ok | the ok message status, followed by the terminated getbib command string.
2 |  | 000 | ok | the ok message status, meaning no style spec will be transmitted (jump to 4)
|  | 402 | ok | the ok message status, meaning the style spec will be transmitted
|  | 202, 204, 241, 701, 801 | error | the error message status, terminating the dialog
3 | 000 |  | ok | the ok message status
4 |  | 000 | ok | the ok message status
|  | 242 | error | the error message status, finishing the dialog
5 | 000<bytes>\0\0\0\0 |  | ok | the ok message status, followed by a terminated string denoting the number of bytes that the client wants to transmit
| 402 |  | ok | the message status saying that all data have been sent, ending the loop over all datasets
| 404 |  | ok | the message status saying that the current dataset has been sent completely
| 401 |  | error | the message status saying that there was a problem reading the input data, ending the session
6 |  | 000 | ok | the ok message status
|  | 801 | error | the error message status, ending the session
7 | <data> |  | ok | the previously announced number of data bytes
8 |  | 403 | ok | the ok status for a successfully transmitted chunk of data
|  | 400<message>\0\0\0\0 | error | the error status, followed by a terminated, server-generated error message specifying the error
9 | 000 |  | ok | the ok message status
10 |  | 404 | ok | the ok status for a successfully transmitted chunk of data
|  | 402 | ok | the ok status for the last chunk of data
11 | 000 |  | ok | the ok message status
12 |  | 000<summary>\0\0\0\0 | ok | the ok message status, followed by the terminated command summary string.
13 | 000 |  | ok | the ok message status, finishing the dialog

#### getnote, countnote

The internal API command `getnote` corresponds to refdbc: getnote and refdbc: countnote.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000getnote [options] <bytes>\0\0\0\0 |  | ok | the ok message status, followed by the terminated getref command sting containing the number of bytes required to store the query string
2 |  | 000 | ok | the ok message status
|  | 801 | error | the error message status which terminates the session
3 | 000<query-string>\0\0\0\0 |  | ok | the ok message status, followed by a terminated string containing the query
4 |  | 404<data>\0\0\0\0 | ok | the ok message status denoting a complete dataset, followed by a terminated string containing the dataset
|  | 402<data>\0\0\0\0 | ok | the ok message status denoting the last chunk of data (usually a "footer"), followed by a terminated string containing the data
|  | 204, 234, 701, or 801 | error | the error message status which terminates the session
5 | 000 |  | ok | the ok message status
6 |  | 402<data>\0\0\0\0 | ok | the ok message status denoting the last chunk of data (usually a "footer"), see step 2
7 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
|  | 702, or 801 | error | the error message status which terminates the session
8 | 000 |  | ok | the ok message status, ending the dialog

#### getref, countref

The internal API command `getref` corresponds to refdbc: getref and refdbc: countref.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000getref [options] <bytes>\0\0\0\0 |  | ok | the ok message status, followed by the terminated getref command sting containing the number of bytes required to store the query string (including the terminal NULL bytes)
2 |  | 000 | ok | the ok message status
|  | 301 | error | the error message status which terminates the session
|  | 801 | error | the error message status which terminates the session
3 | 000<query-string>\0\0\0\0 |  | ok | the ok message status, followed by a terminated string containing the query
4 |  | 404<data>\0\0\0\0 | ok | the ok message status denoting a complete dataset, followed by a terminated string containing the dataset
|  | 402<data>\0\0\0\0 | ok | the ok message status denoting the last chunk of data (usually a "footer"), followed by a terminated string containing the data
|  | 204, 234, 701, or 801 | error | the error message status which terminates the session
5 | 000 |  | ok | the ok message status
6 |  | 402<data>\0\0\0\0 | ok | the ok message status denoting the last chunk of data (usually a "footer"), see step 2
7 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
|  | 702, or 801 | error | the error message status which terminates the session
8 | 000 |  | ok | the ok message status, ending the dialog

#### getrefx

The internal API command `getrefx` is used by the refdbib tool to retrieve raw SGML and XML bibliographies.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000getrefx [options]\0\0\0\0 |  | ok | the ok message status, followed by the terminated getbib command string.
2 |  | 000 | ok | the ok message status
|  | 204, 701, 801 | error | the error message status, terminating the dialog
3 | 000<bytes>\0\0\0\0 |  | ok | the ok message status, followed by a terminated string denoting the number of bytes that the client wants to transmit
| 402 |  | ok | the message status saying that all data have been sent, ending the loop over all datasets
| 404 |  | ok | the message status saying that the current dataset has been sent completely
| 401 |  | error | the message status saying that there was a problem reading the input data, ending the session
4 |  | 000 | ok | the ok message status
|  | 801 | error | the error message status, ending the session
5 | <data> |  | ok | the previously announced number of data bytes
6 |  | 403 | ok | the ok status for a successfully transmitted chunk of data
|  | 400<message>\0\0\0\0 | error | the error status, followed by a terminated, server-generated error message specifying the error
7 | 000 |  | ok | the ok message status
8 |  | 404 | ok | the ok status for a successfully transmitted chunk of data
|  | 402 | ok | the ok status for the last chunk of data
|  | 234, 801, 702 | error | the error message status
9 | 000 |  | ok | the ok message status
10 |  | 000<summary>\0\0\0\0 | ok | the ok message status, followed by the terminated command summary string.
11 | 000 |  | ok | the ok message status, finishing the dialog

#### getstyle

The internal API command `getstyle` corresponds to refdba: getstyle.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000getstyle [options][regexp]\0\0\0\0 |  | ok | the ok message status, followed by the terminated getstyle command sting
2 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
|  | 202, or 801 | error | the error message status which terminates the session
3 | 000 |  | ok | the ok message status, ending the dialog

#### gettexbib

The internal API command `gettexbib` is used by the refdbib tool to retrieve bibtex bibliographies.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000gettexbib [options] data-size\0\0\0\0 |  | ok | the ok message status, followed by the terminated gettexbib command string. The only non-option argument is the size, in bytes, of the ID data to be sent, including the terminator.
2 |  | 000 | ok | the ok message status
|  | 801 | error | the error message status, terminating the dialog
3 | 000id-data\0\0\0\0 |  | ok | the ok message status, followed by the terminated ID list. This is a whitespace separated list of ID or CK values.
4 |  | 404<data>\0\0\0\0 | ok | the ok message status denoting a complete dataset, followed by a terminated string containing the dataset
|  | 402<data>\0\0\0\0 | ok | the ok message status denoting the last chunk of data (usually a "footer"), followed by a terminated string containing the data
|  | 204, 234, 269, 701, 801, or 842 | error | the error message status which terminates the session
5 | 000 |  | ok | the ok message status
6 |  | 402<data>\0\0\0\0 | ok | the ok message status denoting the last chunk of data (usually a "footer"), see step 4
7 | 000 |  | ok | the ok message status
8 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
|  | 702, or 801 | error | the error message status which terminates the session
9 | 000 |  | ok | the ok message status, ending the dialog

#### listdb

The internal API command `listdb` corresponds to refdbc: listdb.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000listdb [regexp]\0\0\0\0 |  | ok | the ok message status, followed by the terminated listdb/selectdb command sting
2 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
|  | 202, 225, 226, 802, or 802 | error | the error message status which terminates the session
3 | 000 |  | ok | the ok message status
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
5 | 000 |  | ok | the ok message status, ending the dialog

#### liststyle

The internal API command `liststyle` corresponds to refdbc: liststyle.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000liststyle [options][regexp]\0\0\0\0 |  | ok | the ok message status, followed by the terminated liststyle command sting
2 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
|  | 202, or 801 | error | the error message status which terminates the session
3 | 000 |  | ok | the ok message status
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
5 | 000 |  | ok | the ok message status, ending the dialog

#### listuser

The internal API command `listuser` corresponds to refdba: listuser.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000listuser [options] regexp\0\0\0\0 |  | ok | the ok message status, followed by the terminated listuser command sting
2 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
|  | 204, 207, or 801 | error | the error message status which terminates the session
3 | 000 |  | ok | the ok message status
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
5 | 000 |  | ok | the ok message status, ending the dialog

#### listword

The internal API command `listword` corresponds to refdba: listword.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000listword regexp\0\0\0\0 |  | ok | the ok message status, followed by the terminated listword command sting
2 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
|  | 204, 207, or 801 | error | the error message status which terminates the session
3 | 000 |  | ok | the ok message status
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
5 | 000 |  | ok | the ok message status, ending the dialog

#### pickref

The internal API command `pickref` handles the client commands refdbc: pickref and dumpref.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000pickref [options] <bytes>\0\0\0\0 |  | ok | the ok message status, followed by the terminated pickref command sting containing the number of bytes required to store the ID list.
2 |  | 000 | ok | the ok message status
|  | 111 801 | error | the error message status which terminates the session
3 | 000<ID-list>\0\0\0\0 |  | ok | the ok message status, followed by a terminated string containing a list of note IDs
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a report about the pick or dump actions
|  | 204, 412, 801 | error | the message status saying that there was a problem, ending the session
5 | 000 |  | ok | the ok message status
6 |  | 000<summary>\0\0\0\0 | ok | the ok message status, followed by a command summary
|  | 227, 228, 234 | error | the error status, terminating the dialog
7 | 000 |  | ok | the ok message status, ending the dialog

#### scankw

The internal API command `scankw` corresponds to refdba: scankw.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000scankw -d <databasename>\0\0\0\0 |  | ok | the ok message status, followed by the terminated scankw command sting
2 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
|  | 204, 208, or 801 | error | the error message status which terminates the session
3 | 000 |  | ok | the ok message status
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
5 | 000 |  | ok | the ok message status, ending the dialog

#### selectdb

The internal API command `selectdb` corresponds to refdbc: selectdb.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000selectdb dbname\0\0\0\0 |  | ok | the ok message status, followed by the terminated listdb/selectdb command sting
2 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
|  | 202, 225, 226, 802, or 802 | error | the error message status which terminates the session
3 | 000 |  | ok | the ok message status
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
5 | 000 |  | ok | the ok message status, ending the dialog

#### viewstat

The internal API command `viewstat` corresponds to refdba: viewstat.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000viewstat [options]\0\0\0\0 |  | ok | the ok message status, followed by the terminated viewstat command sting
2 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
|  | 204, 208, or 801 | error | the error message status which terminates the session
3 | 000 |  | ok | the ok message status
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
5 | 000 |  | ok | the ok message status, ending the dialog

#### whichdb

The internal API command `whichdb` corresponds to refdbc: whichdb.

step | client | server | message type | comment
--- | --- | --- | --- | ---
1 | 000whichdb\0\0\0\0 |  | ok | the ok message status, followed by the terminated whichdb command sting
2 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result
|  | 204, 207, or 801 | error | the error message status which terminates the session
3 | 000 |  | ok | the ok message status
4 |  | 000<data>\0\0\0\0 | ok | the ok message status, followed by a terminated string containing the command result summary
5 | 000 |  | ok | the ok message status, ending the dialog

### Status messages

The status codes which are multiples of 100 are not associated with a fixed message. Instead, clients should retrieve the terminated string sent after these codes to read the dynamically generated message.

refdb-manual-statustable.xml appears to be missing

## Tools for the client-server protocol

eenc.1.xml appears to be missing