# Overview of the RefDB command-line clients

There are several client applications, each one performing a self-contained subset of tasks. This chapter provides a short overview over common features of the clients. Please refer to the reference chapters about refdba, refdbc, and refdbib for the nitty gritty details.

This manual covers only the clients shipped with RefDB. Please visit the RefDB website for other options. Currently there are tools for both Emacs and Vim which turn these editors into integrated authoring tools with bibliography support.

The clients serve the following purposes:

refdba

  The system administrator's tool to create or delete databases, set access rights, and view all kinds of statistics.

refdbc

  The client for adding, editing, deleting, and searching reference entries.

refdbib

  The tool to create bibliographies.

refdbc and refdba can be run in an interactive mode where they provide their own command line, similar to a command-line FTP client for example. They use the GNU readline library with its powerful and convenient editing and history capabilities. In a nutshell, you can edit commands on this built-in command line as you can do in your bash or in the Emacs minibuffer. You can scroll through the history of your previous commands with the arrow keys, you can use the tab key to complete command names and filenames, and you can use Ctrl r to search the history with a regular expression. For further information you should consult the readline manual.

refdba and refdbc can also be run in batch mode. You can specify one of the built-in commands as an argument to the `-C` option and pipe or redirect data into stdin. This is very useful if you want to automatize tasks using shell scripts.

refdbib does not have an interactive mode and can be run only in batch mode. The result will be written to stdout. However, you'll hardly ever run refdbib directly, as RefDB ships with convenient scripts and Makefiles for this purpose.

## Quickstart guide

These are the essential steps to get up and running as a RefDB user:

- Ask your RefDB administrator to grant access to an existing reference database or have him create one for you.

- If the application server refdbd is not installed to run as a daemon, start it now: `refdbd -s &` (see Starting refdbd for more options).

- Start the refdbc command line client to manage and retrieve references.

- Add references to the database.

- Retrieve references according to your search criteria.

- Create bibliographies with the references in your database.

There is a tutorial for first-time users available at the RefDB documentation page.

## The interactive mode of refdba and refdbc

For informations how to start these clients from the command line, please see the sections about refdba and refdbc.

If you did not specify a password in the corresponding configuration file or with the `-w` command line switch (see later in this chapter), the clients will at first prompt you for a password. This is the password to access the database which may be different from your login password. To protect your password from prying eyes, it will not be echoed on the screen while you type it, so no one can even see the length of your password. If your database account was set up without password protection, just press enter now.

If you run a client in batch mode and send data to stdin, the interactive password prompt will not work. Please use the configuration file or the `-w` option to specify the password in this case.

Then you will be faced with a command prompt similar to the one in your shell. The client waits for you to enter commands. If it just escapes you which commands are available, use the `help` command (or `?` for the lazy among us) to see a list.

The general format of a command is:

`command` -x option-argument argument

Commands may thus have options and arguments. The options have the general style `-x [option-argument]`. They consist of a dash followed by one character. Options are case-sensitive. The option may be followed by an option-argument. This has to be enclosed in quotation marks if it contains spaces. The order of the options and arguments on the command line is arbitrary. Options without arguments can be combined, e.g. you may write `-xy` instead of `-x -y`.

The command line of the RefDB interactive clients uses the GNU readline library. This offers you a functionality similar to the bash command line or the Emacs minibuffer. By default the Emacs keybindings are active, allowing you to conveniently edit your command. You can scroll through a history of previous commands. You can use the Tab key to try a completion of a partially entered token. If it is the first token on the command line, the clients try to complete a command. If it is any other token, the clients try to complete a filename.

When a command is sent to the application server, the client waits for the result of the command. This may take some time, depending on the load of the application server and of the database server. Network problems or a server crash may result in a timeout. The client will in this case return to the command prompt after a configurable time.

If everything runs smooth, you will see the results of your command. Short results of only a few lines will simply be sent to stdout. Results that may cause the terminal to scroll parts of the result off the screen will be piped through a pager of your choice. Depending on the pager, you can jump back and forth in the results and perhaps save the result or part of the result in a file or pipe it to another program. It may be necessary to press some button (like q in less) to get back to the command prompt when you're done. Instead of a pager you can specify any other program that accepts data on stdin, so you can e.g. preprocess the output with `grep` before you display it with a pager ("plumbing", i.e. piping through several applications, is of course possible). Some commands have a switch to redirect the output into a file without displaying it on the screen.

If you output large amounts of data through a pager, the pager may refuse to read on before you scroll through. In this case, a timeout would result and the data would be incomplete. The best way to deal with large amounts of data is to send them to a file and inspect them afterwards. You can use the command `tail -f outfile` to view the data in another console window while they arrive.

## The non-interactive mode of refdba and refdbc

These are the main features of the non-interactive (or batch) mode:

- You have to specify a command name with the `-C` option. Specify all options that the command would take in an interactive session as additional options on the command line. The client will execute this command and exit.

- The clients accept the input for some commands on stdin. If input is available on stdin, be it through a pipe or from a redirected file, this input will be used and any input from a file with the `-f` option will be ignored. As mentioned previously, the automatic detection of data on stdin does not work on a few platforms like Windows/Cygwin. In this case, please use the `-f stdin` option to make the client read from stdin.

- The main purpose of the batch mode is to run the clients from shell scripts (or Perl or PHP if you prefer). You can figure out scripts of arbitrary complexity to interact with your reference database.

  You will still be prompted for a password unless you specify one with the `-w` or in the configuration file. Both ways are considered less secure than typing it on the password prompt, but this is a tradeoff if you want unattended operation. Please keep also in mind that the password prompt will fail if you send data to stdin.

### Example

The following command runs refdbc and uses the `getref` command to retrieve references by the author "Miller", using the database "refs" and requesting the RIS output format as well as the abstracts.

    	~$
    	refdbc -d refs -t ris -s AB -C getref :AU:=Miller

## The non-interactive mode of refdbib

refdbib is a somewhat simpler "filter"-style application. It accepts data either at stdin or from a file whose name is specified on the command line. The output always goes to stdout and can be piped to other applications or redirected into a file as you need it. For an overview of the command-line options, please see the section about starting refdbib. Keep in mind that the runbib script offers a simpler and more versatile way to run refdbib.

## Common command-line options for all clients

All clients share a common set of command-line options. The command-line options override the corresponding settings in the configuration files. Please see the chapters about the individual applications in the Reference manual for all application-specific options.

All clients use the GNU getopt library to parse the command line. Switches can be combined (`-abc` is the same as `-a` `-b` `-c`) and the sequence is arbitrary (`-a` `-b` is the same as `-b` `-a`). All options are case sensitive (`-A` is not the same as `-a`).

-c command

  The command line of the pager that is to be used. Instead of a pager you can of course specify any valid command that accepts data on stdin. Use stdout to request data output to stdout. This is the default, but you may want to specify it on the command line if you need to temporarily override a default pager setting in your configuration file.

-e logdest

  logdest can have the values 0, 1, or 2, or the equivalent strings "stderr", "syslog", or "file", respectively. This value specifies where the log information goes to. "0" (zero) means the messages are sent to stderr. They are immediately available on the screen but they may interfere with command output. "1" will send the output to the syslog facility. Keep in mind that syslog must be configured to accept log messages from user programs, see the syslog(8) man page for further information. Unix-like systems usually save these messages in `/var/log/user.log`. "2" will send the messages to a custom log file which can be specified with the `-L` option.

-h

  Displays help and usage screen, then exits.

-i IP-address

  Set the IP address of the box which is running the application server (refdbd). Instead of the IP address you can also specify the hostname as long as it can be properly resolved by your system.

-l loglevel

  Specify the priority up to which events are logged. This is either a number between "0" and "7" or one of the strings "emerg", "alert", "crit", "err", "warning", "notice", "info", "debug", respectively (see also Log level definitions). "-1" disables logging completely. A low log level like "0" means that only the most critical messages are logged. A higher log level means that less critical events are logged as well. "7" will include debug messages. The latter can be verbose and abundant, so you want to avoid this log level unless you need to track down problems.

-L logfile

  Specify the full path to a log file that will receive the log messages. Typically this would be `/var/log/<appname>`.

-p port

  Set the port of the box which is running the application server

-q

  Start without reading the configuration files. The client will use the compile-time defaults for all values that you do not set with command-line switches.

-T time

  Set the timeout for client/application server dialogue in seconds. A connection with unsuccessful read or write attempts will be considered as dead and taken down after this amount of time has elapsed.

-u name

  Set the username for the database access.

  This username need not be identical to the login name of the user. This is the username required to access the database server.

-v

  Prints version and copyright information, then exits.

-V

  Switches to verbose mode.

-w password

  Set the password for the database access.

  This password need not be identical to the login password of the user. This is the password required to access the database server.

  If you pass the password as a command-line parameter, it will be visible in the process listing with the `ps` command (at least for a brief period of time, until the client overwrites the password string). To avoid sharing your password with the rest of the world, you should either keep your password in your configuration file or use "-w '*'" instead. This will cause the RefDB client to ask you for the password interactively (this is also the default if you don't use the `-w` switch at all and don't have an entry in the configuration file). You must protect the '*' with single quotation marks to prevent the shell from expanding it into a list of files in the current working directory.

-y

  Specify the directory where the global configuration files are

  By default, all RefDB applications look for their configuration files in a directory that is specified during the configure step when building the package. That is, you don't need the `-y` option unless you use precompiled binaries in unusual locations, e.g. by relocating a rpm package.