Dico

B.2 Standard Commands

The following are standard commands, defined in RFC2229.

B.2.1 The DEFINE Command

The DEFINE command searches for definitions of a word.

Command: DEFINE db word

Look up the word word in database db. If db is ‘!’, then all the databases will be searched until the word is found, and all matches in that database will be returned. Similarly, if db is ‘*’, then all the databases will be searched and all matches in all databases will be returned. In these two cases, the databases are searched in the same order as that returned by SHOW DB command (see SHOW DB).

If the word was not found, response code 552 is returned.

If the word is found, a response code 150 is sent, followed by the number of definitions found. Then, for each definition a response code 151 is returned, followed by the textual body of the definition. In a 151 response, the first three space-delimited parameters give the word looked for, the name and a short description of the database. The latter two are the same as shown in the output from SHOW DB command.

The textual body of each definition is terminated with a dot (‘.’) on a line alone. If any line in the definition begins with a dot, it is duplicated to avoid confusion with body terminator.

After all of the definitions have been sent, a status code 250 is sent. If timing is set to ‘true’ in the configuration file, this latter response also carries timing information. See Tuning, for more information about timing output.

Possible responses from DEFINE command are:

550 Invalid database, use SHOW DB for a list

552 No match

150 n definitions found: list follows

151 word database name

250 ok (optional timing information here)

Example transaction:

C: DEFINE eng-swa man
S: 150 1 definitions found: list follows
S: 151 "man" eng-swa "English-Swahili xFried/FreeDict Dictionary"
S: man  <n.>
S: 
S:    mwanamume
S:
S: .
S: 250 Command complete [d/m/c = 1/0/12 0.000r 0.000u 0.000s]

B.2.2 The MATCH Command

The MATCH command searches for word in the database index. The searching algorithm is determined by strategy. See Strategies, for a list of strategies offered by GNU Dico.

Command: MATCH database strategy word

Match word in database using strategy. As with DEFINE, the database can be ‘!’ or ‘*’ (See DEFINE, for a detailed description of these wildcards).

The strategy is either the name of a strategy to use, or a dot (‘.’), meaning to use default strategy. The default strategy is set using default-strategy configuration file statement (see default-strategy. Its default value is ‘lev’, which means ‘use Levenshtein algorithm’ (see Strategies).

If no matches are found in any of the searched databases, then response code 552 will be returned. Otherwise, response code 152 will be returned followed by a list of matched words, one per line, in the form:

database word

Thus, prepending a ‘DEFINE ’ to each such response, one obtains a valid DEFINE command.

The textual body of the match list is terminated with a line containing only a dot character.

Following the list, response code 250 is sent, which includes timing information, if timing directive is set in the configuration file (see Tuning).

Possible responses:

550 Invalid database, use SHOW DB for a list

551 Invalid strategy, use SHOW STRAT for a list

552 No match

152 n matches found: list follows

250 ok (optional timing information here)

Examples:

C: MATCH * . "weather"
S: 152 12 matches found: list follows
C: eng-afr "feather"
C: eng-afr "leather"
C: eng-afr "weather"
C: eng-deu "feather"
C: eng-deu "heather"
C: eng-deu "leather"
C: eng-deu "weather"
C: eng-deu "wether"
C: eng-deu "wheather"
C: devils "WEATHER"
S: .
S: 250 Command complete [d/m/c = 0/12/100677 0.489r 0.479u 0.007s]

B.2.3 The SHOW Command

The SHOW command outputs various information about the server and databases.

Command: SHOW DB

Command: SHOW DATABASES

Display the list of currently accessible databases, one per line, in the form:

database description

The list is terminated with is a dot (‘.’) on a line alone.

Possible responses:

110 n databases present

554 No databases present

Command: SHOW STRAT

Command: SHOW STRATEGIES

Display the list of currently supported search strategies, one per line, in the form:

strategy description

The list is terminated with is a dot (‘.’) on a line alone.

Possible responses:

111 n strategies available

555 No strategies available

Command: SHOW INFO database

Displays the information about the specified database. The information is a free-form text and is suitable for display to the user in the same manner as a definition. The textual body of the response is terminated with is a dot (‘.’) on a line alone.

Possible responses:

550 Invalid database, use SHOW DB for a list

112 database information follows

The textual body is retrieved from the info statement in the configuration file (see info), or, if it is not specified, from the database itself, using dico_db_info callback function (see dico_db_info). If neither source returns anything, the string ‘No information available.’ is returned.

Command: SHOW SERVER

Return a server-specific information.

Response:

114 server information follows

The information follows, terminated with a dot on a line alone.

The textual body returned by the SHOW SERVER command consists of two parts. It begins with a line containing host name of the server and, optionally an additional information about the daemon and the system it runs on. The exact look and amount of information in this line is controlled by show-sys-info configuration statement (see show-sys-info). This line is followed by the text supplied with server-info configuration statement (see server-info).

B.2.4 The OPTION Command

The OPTION command allows to request optional features on the remote server. Currently the only implemented subcommand is:

Command: OPTION MIME

Requests that all text responses be prefaced by a MIME header (RFC2045) followed by a single blank line.

After this command is issued, the server begins each textual response with a MIME header. This header consists of ‘Content-type’ and ‘Content-transfer-encoding’ headers, as supplied by the corresponding configuration file statements for this database (See content-type, see content-transfer-encoding). Any or both of these headers may be missing.

B.2.5 The AUTH Command

The AUTH command allows client to authenticate itself to the server. Depending on the server configuration, authenticated users may get access to more databases (see Database Visibility) or more detailed server information (see show-sys-info).

Command: AUTH username auth-string

Authenticate client to the server using a username and password. The auth-string is computed as in the APOP protocol (RFC1939. Briefly, it is the MD5 checksum of the concatenation of the msg-id (see Initial Reply) and the shared secret that is stored both on the server and client machines.

See Authentication, for information on how to configure server for authenticating clients.

This command is supported only if ‘auth’ capability is requested in the configuration (see auth).

B.2.6 The CLIENT Command

Command: CLIENT info

Identify client to server. The info argument contains a string identifying the client program (e.g. its name and version number). This information can then be used in logging (see %C).

B.2.7 The STATUS Command

Command: STATUS

Display cumulative timing information. This command returns a ‘210’ status code, followed by the timing information as described in Tuning, e.g.

C: STATUS
S: 210 [d/m/c = 28/1045/119856 21.180r 10.360u 1.040s]

B.2.8 The HELP Command

Command: HELP

The HELP command provides a short summary of commands that are understood by the server. The response begins with a ‘113’ code, followed by textual body defined in help-text configuration file statement (see help-text), which is terminated by a dot on a line by itself. A ‘250’ response code finishes the output. For example:

113 help text follows
DEFINE database word         -- look up word in database
MATCH database strategy word -- match word in database 
SHOW DB                      -- list all accessible databases
SHOW DATABASES               -- list all accessible databases
SHOW STRAT                   -- list available matching strategies
SHOW STRATEGIES              -- list available matching strategies
SHOW INFO database           -- provide database information
SHOW SERVER                  -- provide site-specific information
CLIENT info                  -- identify client to server
STATUS                       -- display timing information
HELP                         -- display this help information
QUIT                         -- terminate connection
.
250 Ok

B.2.9 The QUIT Command

Command: QUIT

Terminate connection.

This command returns a response code 221, optionally followed by timing information (see Tuning).