Commented abstract representation of the client/server protocol
Prev | Chapter 23. The RefDB client/server communication protocol | Next

## 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

### Note

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.

000

  ok

001

  error

100

  void

101

  incorrect scramble string

102

  client and server protocols do not match

103

  invalid client request

104

  incomplete client command

105

  missing client command

106

  missing client command option

107

  unknown client command option

108

  could not descramble password

109

  timeout while reading

110

  timeout while writing

111

  missing client command argument

112

  client aborted command

200

  void

201

  main database is missing

202

  could not open main database

203

  main database is too old or corrupt

204

  could not open reference database

205

  could not connect to database server

206

  main database version is not supported

207

  could not create result from database query

208

  could not retrieve reference database metadata

209

  could not create reference database

210

  could not create reference database metadata

211

  create t_meta failed

212

  create t_refdb failed

213

  create t_author failed

214

  create t_keyword failed

215

  create t_periodical failed

216

  create t_note failed

217

  create t_user failed

218

  create t_xauthor failed

219

  create t_xkeyword failed

220

  create t_xuser failed

221

  create t_xnote failed

222

  could not create user group

223

  could not grant user permissions

224

  access control not supported

225

  not a RefDB database

226

  database does not exist

227

  begin transaction failed

228

  cannot lock tables

229

  failed to remove keyword

230

  failed to remove author

231

  failed to remove periodical

232

  failed to update main reference data

233

  inserting reference data failed

234

  select failed

235

  database successfully created

236

  assume localhost as host

237

  grant user permissions successful

238

  revoke user permissions successful

239

  could not revoke user permissions

240

  switched to database

241

  failed to access style data

242

  create temporary table failed

243

  delete temporary table failed

244

  incomplete reference data

245

  failed to remove note xlink

246

  failed to delete main note data

247

  failed to remove user

248

  failed to delete main reference data

249

  failed to delete database

250

  could not delete user group

251

  database successfully deleted

252

  personal interest list is empty

253

  failed to detach dataset from user

254

  sucessfully detached dataset from user

255

  failed to attach dataset to user

256

  sucessfully attached dataset to user

257

  create t_link failed

258

  create t_xlink failed

259

  failed to remove ulink

260

  failed to update journal names

261

  failed to create citation key

262

  failed to create personal list

263

  successfully created personal list

264

  failed to delete personal list

265

  successfully deleted personal list

266

  personal list not owned by current user

267

  personal list does not exist

268

  create t_temp_xdup failed

269

  style not found

300

  void

301

  missing argument

302

  unknown output format

400

  void

401

  no more data available

402

  finished transferring data

403

  chunk added successfully

404

  finished transferring dataset

405

  finished adding dataset

406

  citation key

407

  refused to overwrite dataset

408

  dataset added successfully

409

  numerical id ignored

410

  numerical id nonexistent

411

  citation key nonexistent

412

  ID and citation key missing

413

  dataset updated successfully

414

  failed to add dataset

415

  missing link target

416

  incorrect link type

417

  dataset not found

418

  link already exists

419

  dataset removed successfully

420

  failed to remove dataset

421

  link added successfully

422

  only owner can fiddle with dataset

423

  dataset is still in use

424

  dataset is already attached to user

425

  periodical name changed successfully

426

  reference type changed

700

  void

701

  failed to initialize character set conversion

702

  character set conversion failed

703

  remote administration disabled

704

  administration is not restricted

705

  administration not permitted

706

  administration permitted

707

  process ID

708

  application server stop submitted

709

  set server IP submitted

710

  set timeout submitted

711

  set logfile submitted

712

  set logdest submitted

713

  set loglevel submitted

800

  void

801

  out of memory

802

  failed to load cgi templates

803

  command partially processed, aborted after unrecoverable error

804

  suffix pool exhausted

805

  REFNUMBER formatting failed

806

  AUTHORLIST formatting failed

807

  EDITORLIST formatting failed

808

  SEDITORLIST formatting failed

809

  PUBDATE formatting failed

810

  PUBDATESEC formatting failed

811

  TITLE formatting failed

812

  BOOKTITLE formatting failed

813

  SERIESTITLE formatting failed

814

  JOURNALNAME formatting failed

815

  VOLUME formatting failed

816

  ISSUE formatting failed

817

  PAGES formatting failed

818

  PUBLISHER formatting failed

819

  PUBPLACE formatting failed

820

  SERIAL formatting failed

821

  ADDRESS formatting failed

822

  URL formatting failed

823

  USERDEF1 formatting failed

824

  USERDEF2 formatting failed

825

  USERDEF3 formatting failed

826

  USERDEF4 formatting failed

827

  USERDEF5 formatting failed

828

  MISC1 formatting failed

829

  MISC2 formatting failed

830

  MISC3 formatting failed

831

  LINK1 formatting failed

832

  LINK2 formatting failed

833

  LINK3 formatting failed

834

  LINK4 formatting failed

835

  ABSTRACT formatting failed

836

  NOTES formatting failed

837

  SEPARATOR formatting failed

838

  remote administration failed

839

  child->parent communication failure

840

  FIFO write error

841

  unknown command

842

  failed to load style

999

  summary

Prev | Up | Next
Basic principles | Home | Tools for the client-server protocol