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.

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:

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.