SYNOPSIS
Interactive mode:
- refdbc [-c pager-command] [-d database] [-e log-destination] [-f stdin] [-F fields] [-g deffile] [-G CSS-file] [-h] [-i IP-address] [-l log-level] [-L log-file] [-p port] [-q] [-R pdfroot] [-T time] [-u name] [-v] [-V] [-w password] [-x] [-y confdir]
- refdbc -C command [-c pager-command] [-d database] [-e log-destination] [-f stdin] [-F fields] [-g deffile] [-G CSS-file] [-i IP-address] [-l log-level] [-L log-file] [-p port] [-q] [-R pdfroot] [-T time] [-u name] [-v] [-V] [-w password] [-x] [-y confdir]
DESCRIPTION
OPTIONS
-c pager-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.
-C command
- The command to be run in non-interactive mode. You can supply all options and parameters that the command accepts on the refdba command line.
-d database
- The name of the default database. You can change the database anytime during an interactive session.
-e log-destination
- log-destination 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.
-f stdin
- Read data from stdin. refdbc usually knows when it should read from stdin. However, a few commands use data supplied in the command line but also allow to read from a file. Use this option to force refdbc to read from stdin in addition to values supplied on the command line.
-F fields
- Specify the default fields that are to be displayed in a getref query.
-g deffile
- This option can be used to add some default fields to all RIS references that are added or updated. The argument deffile is the filename of a RIS file containing these additional fields. refdbc first tries the filename as is, so it should be a valid relative or absolute path. If the file is not found, refdb looks for the file in $HOME. The command aborts if the file cannot be found.
-G CSS-file
- Specify the URL of a Cascading Style Sheets (CSS) file. This file will be used to customize the HTML output of the getref command. The URL can be either a local path (e.g. refdb.css, /home/myname/custom.css) or the web address of a file on a web server (e.g. m[blue]http://www.mycomp.com/refdb.cssm[]).
-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(1). Instead of the IP address you can also specify the hostname as long as it can be properly resolved by your system.
-l log-level
- 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 log-file
- Specify the full path to a log file that will receive the log messages. Typically this would be /var/log/refdba.
-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. Useful for debugging configuration files.
-R pdfroot
- Specify the root path of your collection of electronic offprints.
-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. Note: 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. Note: This password need not be identical to the login password of the user. This is the password required to access the database server.
-x
- Send passwords unencrypted.
-y confdir
- Specify the directory where the global configuration files are Note: 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.
DIAGNOSTICS
The exit code is 0 if all went fine. It will be 1 if the command (when run in batch mode) or the last command (when run in interactive mode) returned an error, or if there was a general error condition during startup like a lack of available memory.
CONFIGURATION
refdbc evaluates the refdbcrc configuration file at startup to initialize itself.
Table 1. refdbcrc
| Variable | Default |
Comment
|
| cssurl | (none) |
The URL of a Cascading Style Sheet (CSS) file. This file, if specified, is used to customize the visual appearance of the HTML output of the getref command.
|
| defaultdb | (none) |
The default database. refdbc will try to use this database unless you select a different one with the selectdb command.
|
| defaultris | (none) |
The path of a RIS file with entries that should be added to all new or updated references. This is typically used to set some default value for the RP field or to specify additional keywords.
|
| fields | (none) |
A list of additional fields which should be displayed by default in the reference output. The list is a simple concatenation of the field names. Possible fields are N1, N2, NX, AB, AD, RP, SN, PB, CY, UR, U1 through U5, M1 through M3. Use the string "ALL" to request all available fields.
|
| fromencoding | ISO-8859-1 |
The default encoding of RIS input data. You can use any encoding that your local libiconv implementation supports.
|
| logdest | file |
Where the log output should be written to. Use either stderr, syslog, or file. For the latter to work, the logfile variable must be set appropriately
|
| logfile | /var/log/refdbc.log |
The full path of a custom log file.
|
| loglevel | info |
Set the level of log information that you would receive. Possible values, in order of increasing verbosity, are: emerg, alert, crit, err, warning, notice, info, debug
|
| pager | stdout |
The command line of a pager that accepts the output of refdb on stdin to allow scrolling and other nifty things. "stdout" sends the data to stdout.
|
| passwd | * |
The password which is used for authentication with the database server. It is potentially evil to store unencrypted passwords in disk files. At least make sure that the configuration file is not readable for anyone else. The default setting causes refdbc to ask for your password interactively.
|
| pdfroot | (none) |
This value will be used as the root of the paths to PDF or Postscript offprints that can be specified with the AV field in a RIS dataset. The path should not rely on shell expansion, e.g. use /home/me/literature/ instead of ~/literature/. The pdfroot allows you to shorten the paths that you enter for each dataset and to maintain a certain portability if you have to move the offprints to a different directory or want to access them remotely. The html output routine will concatenate the relative path of each dataset with the pdfroot to construct the link to the offprint. Instead of a local path name you can specify an URL starting with http:// or ftp:// if your offprints are accessible through a web server or ftp server.
|
| port | 9734 |
The port on which refdbd listens. Change this for all clients and the server if this value interferes with another program using this port.
|
| serverip | 127.0.0.1 |
The IP address or hostname of the machine where refdbd runs. Use the default (localhost) address if the clients and refdbs run on the same machine.
|
| timeout | 180 |
The timeout in seconds. After this time has elapsed, a stalled connection is taken down. Increase this value if you encounter frequent timeout errors due to high network traffic or refdbd overload.
|
| toencoding | (none) |
The default encoding of output data. You can use any encoding that your local libiconv implementation supports. If this value is not set, the encoding of the database will be used without conversion.
|
| username | login name |
The username which is used for authentication with the database server. This may be different from the login name of the user.
|
| verbose | f |
Set this to t if you prefer verbose error messages.
|
| no_encrypt | f |
If set to 't', passwords are transmitted unencrypted. The default is to encrypt passwords.
|
COMMANDS
All commands consist of a single word which specifies the command. This may be followed by arguments and/or switches. The general syntax rules of the getopts library apply.
addlink
You have to specify exactly one note on the command line, either by using the :NID: field selector to specify the note ID, or by using the :NCK: field selector to specify the note key. Then you need at least one link target. This can be one of :ID: (reference by ID), :CK: (reference by citation key), :AU: (author by name), :KW: (keyword by name), or one of :JF:, :JO:, :J1:, :J2: (periodical by full name, abbreviated name, or user abbreviations 1 and 2).
-c command
-d database
-h
-o filename
-O filename
note-specifier
link-target
Synopsis
refdbc:
addlink :NID:=12 :CK:=Miller1999 :KW:=biochemistry
This command will link the note carrying the ID 12 with a reference specified by its citation key "Miller1999" and with the keyword "biochemistry".
addnote
-c command
-d database
-E encoding
-h
-o filename
-O filename
Synopsis
refdbc:
addnote foo.xml
This command will add the extended notes in foo.ris to the currently selected database. If the notes do not specify a date, refdbd will insert a timestamp automatically.
addref
-c command
-d database
-E encoding
-h
-o filename
-O filename
-t type
-U username
file
Synopsis
refdbc:
addref -U doe -g .refdbdefault.ris -E ISO-8859-1 foo.ris
-
$ refdbc -C addref -U doe -g .refdbdefault.ris -d db1 < foo.ris
These commands will add the references in foo.ris. The references will be associated with the user "doe". Every reference will use the specified values in .refdbdefault.ris in the appropriate fields. In the first (interactive) command, the active database will be used, and the encoding is set to ISO-8859-1, aka Latin-1. In the second (non-interactive) command, the database has to be specified explicitly with the -d option, and the default encoding (UTF-8) is assumed.
checkref
-A outtype
-c command
-d database
-E encoding
-G cssfile
-h
-o filename
-O filename
-r fieldlist
-s fieldlist
-t input-type
-U username
file
Synopsis
refdbc:
checkref -A xhtml -G /usr/local/share/refdb/css/refdb-frequency.css -E ISO-8859-1 -s KW foo.ris
This command adds the data in foo.ris to temporary tables in the current database, using the ISO-8859-1 encoding. The result of the duplicate checks is requested in xhtml format using a stylesheet that displays frequency information graphically. In addition to the default fields the keywords will be listed as well.
deletelink
You have to specify exactly one note on the command line, either by using the :NID: field selector to specify the note ID, or by using the :NCK: field selector to specify the note key. Then you need at least one link target. This can be one of :ID: (reference by ID), :CK: (reference by citation key), :AU: (author by name), :KW: (keyword by name), or one of :JF:, :JO:, :J1:, :J2: (periodical by full name, abbreviated name, or user abbreviations 1 and 2).
-c command
-d database
-h
-o filename
-O filename
note-specifier
link-target
Synopsis
refdbc:
deletelink :NID:=12 :CK:=Miller1999 :KW:=biochemistry
This command will delete the links from the note carrying the ID 12 to a reference specified by its citation key "Miller1999" and to the keyword "biochemistry".
deletenote
It is not possible to delete a note if it belongs to a different user.
-c command
-d database
-f infile
-h
-o filename
-O filename
NID
Synopsis
Caution
refdbc:
deletenote 3 5-10 26
This command will delete the extended notes with the ID values 3, 5 through 10, and 26.
deleteref
It is not possible to delete a reference if it belongs to the personal reference list of more than one user.
If you're the only user of this reference and go ahead and delete it, all data saved in the specified references will be gone, so be careful with this command. Make sure you understand the difference between the
deleteref
command and the
dumpref
command. The former deletes the data, the latter deletes only your personal data associated with the specified references (the notes, availability, and reprint data) and removes your association with this reference. In other words,
deleteref
removes the reference from the database, whereas
dumpref
removes the reference from your personal reference list, leaving the remaining data for the other users of the database.
-c command
-d database
-f infile
-h
-o filename
-O filename
ID
Synopsis
Caution
refdbc:
deleteref 3 5-10 26
This command will delete the references with the ID values 3, 5 through 10, and 26.
dumpref
-b listname
-c command
-d database
-f infile
-h
-o filename
-O filename
ID
Synopsis
refdbc:
dumpref -f foo.ris 3 5-10 26
This command will remove the references 3, 5 through 10, and 26 as well as those listed in the file foo.ris from your personal reference list.
getau, geted, getas, getax
-c command
-d database
-h
-N limit[:offset]
-o filename
-O filename
-s format
regexp
Synopsis
Note
Some database engines, like SQLite, do not support Unix-style regular expressions. Use SQL regular expressions instead.
refdbc:
getau -o authors.txt '^Simpson'
This command will write a list of all authors starting with "Simpson" to the file authors.txt.
-
refdbc: getau -N 5:10
This command prints the author names 11 through 15.
getjo, getjf, getj1, getj2
-a
-c command
-d database
-h
-N limit[:offset]
-o filename
-O filename
-s format
regexp
Synopsis
Note
Some database engines, like SQLite, do not support Unix-style regular expressions. Use SQL regular expressions instead.
refdbc:
getjo -a -o journals.txt '^J'
This command will list all synonyms of the journals whose abbreviations start with a capital J. The output will be redirected into the file journals.txt.
getkw
-c command
-d database
-h
-N limit[:offset]
-o filename
-O filename
-s format
regexp
Synopsis
Note
Some database engines, like SQLite, do not support Unix-style regular expressions. Use SQL regular expressions instead.
refdbc:
getkw -o keywords.txt '^An.*l$'
This command will request a list of all keywords that start with "An" and end with the letter "l", like "Animal", and write the result to the file keywords.txt.
-
~# refdbc -C getkw -s freq -c "sort -r|cut -d ':' -f 2"|less
Here we run the getkw command from the shell. The result list contains the frequency of each returned keyword. The data are sorted in descending order according to the frequency, and the frequency information itself is stripped off. Of course there is more than one way to arrive here. E.g. you could use the -c option to send the data to stdout and pipe them through the argument of the -c option in the example shown above.
getnote
-c command
-d database
-E encoding
-f infile
-h
-N limit[:offset]
-o filename
-O filename
-P
-S sort-string
-t output-type
search-string
Synopsis
refdbc:
getnote -t xnote :CK:=Miller1999
This command retrieves notes which are attached to the reference with the citation key "Miller1999" and displays them in the xnote format.
getref
-b listname
-c command
-d database
-E encoding
-f infile
-h
-N limit[:offset]
-o filename
-O filename
-s format-string
-S sort-string
-t output-type
search-string
Synopsis
refdbc:
getref -t ris -o temp.sgml -E ISO-8859-15 ":AU:='& ^Doe ^Jones' AND :KW:=circular\ dichroism"
This command retrieves articles with both an author starting with "Doe" and an author starting with "Jones" that have the keyword "circular dichroism". The output will be saved in RIS format to the file temp.sgml using the character encoding ISO-8859-15.
help, ?
This command is not available in the batch mode (use the
-h
option instead to review the command line usage).
Synopsis
Note
refdbc:
help
This will list the available commands.
listdb
-h
database-regexp
Synopsis
refdbc:
listdb db%
This command will list all available databases that start with "db".
liststyle
-h
style-regexp
Synopsis
Note
Some database engines, like SQLite, do not support
Unix-style regular expressions. Use
SQL regular expressions
instead.
refdbc:
liststyle ^J.*
This will list all bibliography styles that start with a capital "J".
pickref
-b listname
-c command
-d database
-f infile
-h
-o filename
-O filename
ID
Synopsis
refdbc:
pickref -f foo.ris 3 5-10 26
This command will add the references 3, 5 through 10, and 26 as well as those listed in the file foo.ris to your personal reference list.
countnote
-b listname
-c command
-d database
-f infile
-h
-N limit[:offset]
search-string
Synopsis
refdbc:
countnote :KW:~[rR]eview
This command looks for extended notes that are linked to references which contain keywords like "review" or "Review". The command will return the number of matching notes in the result summary.
countref
-b listname
-c command
-d database
-f infile
-h
-N limit[:offset]
search-string
Synopsis
refdbc:
countref ":AU:='& ^Doe ^Jones' AND :KW:=circular\ dichroism"
This command looks for articles with both an author starting with "Doe" and an author starting with "Jones" that have the keyword "circular dichroism". The command will return the number of matching references in the result summary.
selectdb
This command is not available in the batch mode. Use the
-d
command line option instead.
-h
database
Synopsis
Note
refdbc:
selectdb db1
This command will make the database db1 the active database. All further queries and operations will affect this database.
set
If you call
set
without any arguments, it will display a list of all configuration variables with their current values.
If you call
set
with one argument, it will display the value of this particular variable.
If you call
set
with two arguments, it will set the variable (first argument) to the new value (second argument). To specify an empty value, use two quotation marks like this:"".
For obvious reasons,
set
will never display the current password although you can certainly change the password with this command. To make sure no one else sees the new password that you enter, run the command
set passwd *. You will then be asked to enter a password which will not be echoed on the screen.
This command is not available in batch mode, use the command line switches instead. In the interactive mode, the changes to the configuration variables are limited to the current session. If you want to change the values permanently, you should rather edit one of the configuration files.
-h
varname
varvalue
Synopsis
Note
refdbc:
set timeout 90
This command will set the timeout to 90 seconds for the current session.
updatejo
Each periodical can have up to four synonymous names. The full name and an official abbreviation (e.g. according to the Index Medicus for biomedical publications) should always be supplied if available. In addition, refdb can store up to two user-defined abbreviations which may serve as shorthands when adding datasets.
-c command
-d database
-h
-o filename
-O filename
:XY:=name
Synopsis
refdbc:
updatejo :JO:="J.Biol.Chem." :JF:="The Journal of Biological Chemistry"
Adds (or changes) the full name of the periodical known by its official abbreviation as "J.Biol.Chem." to read "The Journal of Biological Chemistry".
updatenote
This command is essentially the same as
addnote, but it uses the
citekey
or
id
attributes (in this order) to update an existing note in the database. If the specified note does not exist in the database, a new one will be created.
-c command
-d database
-E encoding
-h
-o filename
-O filename
Synopsis
refdbc:
updatenote foo.xml
This command will update the extended notes in foo.ris in the currently selected database. If the notes do not specify a date, refdbd will insert a timestamp automatically.
updateref
This command is essentially the same as
addref, but it uses the
ID
fields in the input data to update existing references with the same ID. If the ID of a reference is not existent in the database, a new entry is created, ignoring the ID specified in the RIS or risx file. Currently refdb does not check whether the new dataset has any similarity with the old one having the same ID. If you tell refdb to update a reference, it uses whatever you send to this end.
-c command
-d database
-E encoding
-h
-o filename
-O filename
-t type
-P
-U username
file
Synopsis
refdbc:
updateref -P foo.ris
This command will update the references in foo.ris in the previously selected active database. Only the personal information (AV, N1, RP) will be added or modified for the current user.
verbose
-h
Synopsis
refdbc:
verbose
Depending on the previous value, this command will either turn the verbose mode on or off.
whichdb
-h
Synopsis
refdbc:
whichdb
This will print the information about the active database. Refer to the selectdb command for information how to change the active database. The whichdb output looks like this:
-
Current database: alltypes Number of references: 45 Highest reference ID: 45 Number of notes: 2 Highest note ID: 2 Encoding: ISO-8859-1 Database type: risx Server type: pgsql Created: 2003-12-24 22:27:43 UTC Using refdb version: 0.9.4-pre2 Last modified: 2003-12-24 22:29:05 UTC
FILES
PREFIX/etc/refdb/refdbcrc
- The global configuration file of refdbc.
$HOME/.refdbcrc
- The user configuration file of refdbc.