# Poliqarp Manual

&p;

1 &version;

&p;

the Poliqarp server

    		&p;

    			-h
    			--help
    			-v
    			--version

    		&p;

    				-g
    				--gui

    				-d
    				--detach

    				-c
    				--config-file

    			file

## Options

`-h`

`--help`

- Display help and exit.

`-v`

`--version`

- Output version information and exit.

`-g`

`--gui`

- GUI mode: cause the server to terminate when the session counter drops down to zero for the first time.

`-d`

`--detach`

- After &p; is ready to accept connections, detach from the controlling terminal and run in the background.

`-c`

`--config-file=``file```

- Use the given `file` as a configuration file. The default is:

  - `$HOME/.poliqarp/poliqarpd.conf` (under Unix) or

  - `poliqarpd.conf` in the current directory (under Windows).

## Configuration file

Empty lines and lines starting with `#` are comments. Otherwise a line is of the format `keyword` `=` `setting`.

The possible keywords and their meanings are as follows:

`hostname`

- Specifies the local address that &p; listens on. The default address is `127.0.0.1`.

  New in &p; 1.3.1.

`port`

- Specifies the TCP port number that &p; listens on. 0 means any port. Ports 1-1023 are normally reserved to superuser. Ports 1024-65536 should be available to anyone. The default port is 4567.

`logging`

- `on`

- Enables server activity logging.

`off`

- Disables server activity logging.

The default value is `off`.

`log-file`

- Specifies the log file name. The default is `poliqarpd.log` in the current directory.

`match-buffer-size`

- Specifies the initial size of match buffer (i.e., maximum number of stored results). The default value is 1000. The maximum value is 50000.

`max-match-length`

- Restricts the match length to the specified number of segments. The maximum and the default values are 1000.

  New in &p; 1.3.2.

`max-session-idle`

- Restricts life-time of an idle session to the specified number of seconds. The default value is 1200 (i.e. 20 minutes). The maximum value is 86400 (i.e. 24 hours).

`corpus`

- New in &p; 1.3.2.

  `any`

- Allows one to open any corpus in the file system.

  This is the default if no other `corpus` settings are present.

`corpus-id``:``base-name`

- Allows one to open the `base-name` corpus using the `corpus-id`.

  Under the hood, the corpus will be opened at &p; startup and never closed.

## Locale

On Unix systems, &p; requires a UTF-8 locale (`LC_CTYPE` category) to be set.

## Binary format version

As of &p; 1.3.1, the only supported binary format version is 2. Please use

bpupgrade

1 to convert your corpora.

## Protocol

### Diagnostics

`PING`

- Server replies:

      R PONG

`GET-VERSION`

- Server replies:

      R server-version (sakura sakura-version)

  For this version, ``server-version`` = ``sakura-version`` = `&version;`.

  This command was renamed from `VERSION` in &p; 1.3.7.

`GET-LAST-ERROR`

- If no error was recorded, server replies:

      R NOERROR

  Otherwise, it replies:

      R ERROR error-message

  New in &p; 1.2.

### Session management

`MAKE-SESSION `session-name``

- Create a new session. Server replies:

      R OK session-id

`RESUME-SESSION `session-id` `session-name``

- Resume the previously suspended session, identified by ``session-id``.

  This command was renamed from `RECONNECT` in &p; 1.3.7.

`CLOSE-SESSION`

- Close the current session.

`SUSPEND-SESSION`

- Explicitly suspend the current session.

  Every open session is implicitly suspended if the TCP connection is terminated. However, suspending the session explicitly, gives the client a chance to receive pending asynchronous messages, which would otherwise be lost.

  New in &p; 1.3.1.

### Opening/closing corpora

`OPEN-CORPUS `base-name``

- This command was renamed from `OPEN` in &p; 1.3.7.

`OPEN-CORPUS `corpus-id``

- Possibility to open pre-defined corpora was added in &p; 1.3.2.

  This command was renamed from `OPEN` in &p; 1.3.7.

`CLOSE-CORPUS`

- This command was renamed from `CLOSE` in &p; 1.3.7.

### Corpus information

`GET-CORPUS-STATS`

- This command was renamed from `CORPUS-STATS` in &p; 1.3.7.

`GET-METADATA-TYPES`

- This command was renamed from `METADATA-TYPES` in &p; 1.3.7.

`GET-TAGSET`

- Server replies:

      R OK number-of-categories number-of-grammatical-classes
      R description-of-category-1
      …
      R description-of-category-N
      R description-of-class-1
      R description-of-class-2
      …
      R description-of-class-M

  where ``description-of-category`` is of the form ``category-name` `attr-1` `attr-2` `…`` and ``description-of-class`` is of the form ``class-name` `category-1` `category-2` `…`` where ``category-X`` are names of the appropriate categories, in square brackets if the category is optional.

  New in &p; 1.2.

### Job management

`GET-JOB-STATUS`

- This command was renamed from `STATUS` in &p; 1.3.7.

`CANCEL-JOB`

- This command was renamed from `CANCEL` in &p; 1.3.7.

### Querying

`MAKE-QUERY `query``

`RUN-QUERY`

`SORT-RESULTS `criteria``

- This command was renamed from `SORT` in &p; 1.3.7.

### Retrieving results

`GET-COLUMN-TYPES`

- New in &p; 1.2.

`GET-BUFFER-STATE`

- Server replies `R OK `capacity` `num-stored-results``.

  This command was renamed from `BUFFER-STATE` in &p; 1.3.7.

`GET-NUM-RESULTS`

- Server replies `R OK `num-spotted-results``.

  New in &p; 1.3.7.

`BUFFER-SHIFT`

- Not implemented.

`GET-RESULTS `n` `m``

- Changed in Poliqarp 1.2.

`GET-CONTEXT `n``

`GET-METADATA `n``

- This command was renamed from `GET-METADATA` in &p; 1.3.7.

### Settings

`SET-OPTION `option-name` `option-setting``

- The following options are available:

  `left-context-width`

  `right-context-width`

  `wide-context-width`

- `option-setting` is width of the left/right/wide context: in segments or characters if followed by a letter `c`.

`retrieve-lemmata`

`retrieve-tags`

`retrieve-id`

- `option-setting` is a 4-character binary string ``l``L``R``r``, indicating whether lemmata/tags/identifiers should be retrieved for left context (`l`), left match (`L`), right match (`R`) and right context (`r`).

  `retrieve-id` is new in &p; 1.3.8.

`notification-interval`

`query-flags`

- `option-setting` is a 4-character binary string ``i``x``I``X`` indicating whether:

  - regular expressions in main (`i`) and metadata (`I`) parts shoule be case-insensitive by default;

  - regular expressions in main (`x`) and metadata (`X`) parts don't have to match the whole segments or metadata items by default.

  The default is as if `SET query-flags 0011` were run, i.e.:

  - regular expressions in the main part are case-sensitive;

  - regular expressions in the main part have to match the whole segments;

  - regular expressions in the metadata part are case-insensitive;

  - regular expressions in the metadata part don't have to match the whole metadata items.

`disamb`

`rewrite`

- New in &p; 1.3.3.

`random-sample`

- New in &p; 1.3.7.

This command was renamed from `SET` in &p; 1.3.7.

`CREATE-ALIAS `alias-name` `alias-value``

`DELETE-ALIAS `alias-name``

`GET-ALIASES`

`RESIZE-BUFFER `n``

- This command was renamed from `BUFFER-RESIZE` in &p; 1.3.7.

### Variétés

`HALT`

### Deprecated aliases

Some commands were renamed in &p; 1.3.7. Old aliases are still available but deprecated.