Commands

addref

Synopsis

addref [-d database] [-h] [-k] [-c command | -o outfile | -O outfile] [-U username] {file | -f infile...}

Description

Adds the references in RIS format in file to the current database. You can specify several files in one run. Any ID fields in the references are ignored unless you specify the -k option.

The -c switch allows to specify a command. refdbc will open a pipe to the first program in the command and send the output to this program's stdin. The command may be any valid command that you can run in your shell, so further plumbing is perfectly legal. This feature may e.g. be used to filter the output with grep for the error messages, dropping all success messages. This is of course not intended to make your world look grey and dull, but to make it easier to spot the (hopefully zero or few) error messages inbetween all those success messages.

Use the -d option to specify the database that you want to work with.

The -g option can be used to add some default fields to all references that are added with this command. 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.

Keep in mind that this default file, just like any other RIS file, has to start with a newline and needs at least the TY and ER fields.

The following example RIS file would switch the reprint status of all added references to "ON REQUEST" as of Jan 1, 2001 and let them have the type "journal" (please note the mandatory empty first line created by a LF):

          
          TY  - JOUR
          RP  - ON REQUEST(01/01/01)
          ER  - 
       

The -h option displays a short command syntax and description, then returns to the command prompt.

Use the -k switch if you want to keep existing reference ID values. The database assigns a unique ID to each added reference, so it is not possible to enforce a certain ID. The -k switch simply puts a copy of the old ID into the field U5 (any other value that you specify for U5 may interfere, so better not use this field). This switch is useful if you want to transfer an existing database (e.g. your 5000 reference database in Reference Manager) to refdb without losing the correlation between the ID and your numbered paper copies.

The -o and -O switches allow to redirect the output to outfile instead of the default screen display. The two options differ in the way they handle an existing outfile. -o will replace the existing file, while -O will append to the existing file. If outfile cannot be opened with the proper permissions, the output is sent to stdout instead.

The -U switch allows to provide a different username than the current user, so e.g. some technician or administrative staff can add references in behalf of a researcher.

The -f switch allows to specify a file which contains a whitespace-separated list of filenames instead of explicitly naming these files on the command line.

All other command-line arguments will be interpreted as filenames to read references from. If data are available on stdin, all files will be ignored and the data will be read from stdin.

Example

refdbc: addref -U doe -g .refdbdefault.ris 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. In the second (non-interactive) command, the database has to be specified explicitly with the -d option.

deleteref

Synopsis

deleteref [-d database] [-h] [-c command | -o outfile | -O outfile] {ID | -f infile...}

Description

Deletes the reference with the identifier ID from the current database. Several references may be specified in a single call of this command.

Alternatively you can specify a file with the -f switch which contains a list of IDs in the RIS format. This can e.g. be a previously saved search with the -o option of getref. The -f switch can also be combined with IDs specified as arguments.

The -c switch allows to specify a shell command. refdbc will open a pipe to the first program in the command and send the output to this program's stdin. The command may be any valid command that you can run in your shell, so further plumbing is perfectly legal. This feature may e.g. be used to filter the output with grep.

Use the -d option to specify the database that you want to work with.

The -h option displays a short command syntax and description, then returns to the command prompt.

The -o and -O switches allow to redirect the output to outfile instead of the default screen display. The two options differ in the way they handle an existing outfile. -o will replace the existing file, while -O will append to the existing file. If outfile cannot be opened with the proper permissions, the output is sent to stdout instead.

Caution

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 pickref -r 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 pickref -r removes the reference from your personal reference list, leaving the remaining data for the other users of the database.

Example

refdbc: deleteref 3 5 26

This command will delete the references with the ID values 3, 5, and 26.

getau, geted, getas

Synopsis

getau [-d database] [-h] [-c command | -o outfile | -O outfile] {unix-regexp}

geted [-d database] [-h] [-c command | -o outfile | -O outfile] {unix-regexp}

getas [-d database] [-h] [-c command | -o outfile | -O outfile] {unix-regexp}

Description

Retrieve all author names that match the regular expression unix-regexp in the current database. getau retrieves the primary authors which is the most common case if you want to locate a publication. geted and getas retrieve book or periodical editors and series authors, respectively.

The -c switch allows to specify a command. refdbc will open a pipe to the first program in the command and send the output to this program's stdin. The command may be any valid command that you can run in your shell, so further plumbing is perfectly legal.

The -h option displays a short command syntax and description, then returns to the command prompt.

The -o and -O switches allow to redirect the output to outfile instead of the default screen display. The two options differ in the way they handle an existing outfile. -o will replace the existing file, while -O will append to the existing file. If outfile cannot be opened with the proper permissions, the output is sent to stdout instead.

Example

refdbc: getau -o authors.txt '^Simpson'

This command will print a list of all authors starting with "Simpson".

getjo, getjf, getj1, getj2

Synopsis

getjo [-a] [-d database] [-h] [-c command | -o outfile | -O outfile] {unix-regexp}

getjf [-a] [-d database] [-h] [-c command | -o outfile | -O outfile] {unix-regexp}

getj1 [-a] [-d database] [-h] [-c command | -o outfile | -O outfile] {unix-regexp}

getj2 [-a] [-d database] [-h] [-c command | -o outfile | -O outfile] {unix-regexp}

Description

Retrieve all journal names that match the regular expression unix-regexp in the current database. The unix-regexp will be matched to the journal abbreviation, the full name, the custom abbreviation 1, and the custom abbreviation 2, respectively.

If the -a option is present, all synonymous journal names will be returned (i.e. full name, abbreviation, custom abbreviation 1, and custom abbreviation 2). If the option is absent, only the name that you search for will be returned (e.g. only the full name in the case of getjf).

The -c switch allows to specify a command. refdbc will open a pipe to the first program in the command and send the output to this program's stdin. The command may be any valid command that you can run in your shell, so further plumbing is perfectly legal.

Use the -d option to specify the database that you want to work with.

The -h option displays a short command syntax and description, then returns to the command prompt.

The -o and -O switches allow to redirect the output to outfile instead of the default screen display. The two options differ in the way they handle an existing outfile. -o will replace the existing file, while -O will append to the existing file. If outfile cannot be opened with the proper permissions, the output is sent to stdout instead.

Example

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

Synopsis

getkw [-d database] [-h] [-c command | -o outfile | -O outfile] {unix-regexp}

Description

Retrieve all keywords that match the regular expression unix-regexp in the current database.

The -c switch allows to specify a command. refdbc will open a pipe to the first program in the command and send the output to this program's stdin. The command may be any valid command that you can run in your shell, so further plumbing is perfectly legal.

The -h option displays a short command syntax and description, then returns to the command prompt.

The -o and -O switches allow to redirect the output to outfile instead of the default screen display. The two options differ in the way they handle an existing outfile. -o will replace the existing file, while -O will append to the existing file. If outfile cannot be opened with the proper permissions, the output is sent to stdout instead.

Example

refdbc: getkw -o keywords.txt '^An.*l$'

This command will print a list of all keywords that start with "An" and end with the letter "l", like "Animal".

getref

Synopsis

getref [-d database] [-h] [-c command | -o outfile | -O outfile] [-P] [-s format-string] [-S sort-string] [-t output-format] {search-string | -f file}

Description

Displays all datasets which match the search-string in the current database. Refer to the section The query language for a description of the syntax of a search string.

The -c switch allows to specify a shell command. refdbc will open a pipe to the first program in the command and send the output to this program's stdin. The command may be any valid command that you can run in your shell, so further plumbing is perfectly legal. This command is handy if you want to search potentially long fields like the abstracts for certain strings. Searching all abstracts of a database with a normal query is slow. It is usually faster to narrow down the search as much as possible without including the N2 field and then use grep to find what you want.

Use the -d option to specify the database that you want to work with.

The -h option displays a short command syntax and description, then returns to the command prompt.

The -o and -O switches allow to redirect the output to outfile instead of the default screen display. The two options differ in the way they handle an existing outfile. -o will replace the existing file, while -O will append to the existing file. If outfile cannot be opened with the proper permissions, the output is sent to stdout instead.

Caution

Depending on your query, the getref command can generate an enormous amount of output. If you view the output with a pager, the client-server communication will stall as soon as the pager accepts no new data. If the connection times out, your query results will be incomplete. It is strongly recommended to redirect all queries which return a lot of references (rule of thumb: more than 100 for screen output, more than 50 for other output) to a file or to a pipe that can handle the amount of data.

If applied to screen output, the -s switch allows to specify additional fields (N1, N2/AB, RP, SN, AD, CY, PB, UR, U1 through U5, M1 through M3) that are not displayed by default. If several fields are specified, the argument has to be enclosed by single quotation marks. If applied to RIS output, you can specify ID as format-string to get only a list of ID values in RIS format for all references that match the search. This is more economical than retrieving the full references if you plan to use the IDs of a saved query for a later operation like deleteref.

The -S switch is used to sort the output. Currently you can sort only by ID (the default) or by PY (publication year).

The -P switch limits the search to the files which are in the current user's personal reference list. If this switch is absent, the whole database will be searched.

The -t switch determines the type of output. The default value for output-format is scrn (screen output), other possible values are db31 (DocBook V. 3.1), ris (RIS as of Reference Manager 8.01), html (HTML), and bibtex (BibTeX).

The -f switch reads the search string from file instead of from the command line, thus allowing to save searches which will be run repeatedly.

The syntax of the queries is described in the section query language.

Example

refdbc: getref -t db31 -o temp.sgml ":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 as DocBook SGML into the file temp.sgml.

help, ?

Synopsis

help

?

Description

Displays a brief summary of the available commands.

Note: This command is not available in the batch mode (use the -h option instead to review the command line usage).

Example

refdbc: help

This will list the available commands.

listdb

Synopsis

listdb [-h] [SQL-regexp]

Description

Lists all available databases if no argument is specified. If SQL-regexp is specified, only the databases matching this expression will be listed. SQL-regexp has to be a valid SQL regular expression.

The -h option displays a short command syntax and description, then returns to the command prompt.

Example

refdbc: listdb db%

This command will list all available databases that start with "db".

liststyle

Synopsis

liststyle {unix-regexp}

Description

Lists all available bibliography styles that match unix-regexp. unix-regexp has to be a valid Unix regular expression.

Example

refdba: liststyle ^J.*

This will list all bibliography styles that start with a capital "J".

pickref

Synopsis

pickref [-d database] [-h] [-c command | -o outfile | -O outfile] [-r] {ID | -f file...}

Description

Adds or removes references from your personal reference list in the current database. The default action is add, unless you provide the -r switch.

The -c switch allows to specify a command. refdbc will open a pipe to the first program in the command and send the output to this program's stdin. The command may be any valid command that you can run in your shell, so further plumbing is perfectly legal. This feature may e.g. be used to filter the output with grep.

Use the -d option to specify the database that you want to work with.

The -h option displays a short command syntax and description, then returns to the command prompt.

The -o and -O switches allow to redirect the output to outfile instead of the default screen display. The two options differ in the way they handle an existing outfile. -o will replace the existing file, while -O will append to the existing file. If outfile cannot be opened with the proper permissions, the output is sent to stdout instead.

The references can be specified on the command line or they can be read from a file which is specified with the -f option. Both methods can be combined. The file has to be in RIS format and can e.g. be a previously saved search with the -o option of getref.

Example

refdbc: pickref -f foo.ris 3 5 26

This command will add the references 3,5, and 26 as well as those listed in the file foo.ris to your personal reference list.

selectdb

Synopsis

selectdb [-h] {database}

Description

Select database as the current database. This current database will be used in all queries unless you specify a different database with the -d option of the query commands.

Note: This command is not available in the batch mode. Use the -d command line option instead.

The -h option displays a short command syntax and description, then returns to the command prompt.

Example

refdbc: selectdb db1

This command will make the database db1 the active database. All further queries and operations will affect this database.

set

Synopsis

set [-h] [varname] [varvalue]

Description

The set command displays or modifies the values of configuration variables.

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:"".

Run set -h to see a brief usage message.

Note: 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.

Example

refdbc: set timeout 90

This command will set the timeout to 90 seconds for the current session.

updateref

Synopsis

updateref [-d database] [-g deffile] [-h] [-c command | -o outfile | -O outfile] [-P] [-U username] {file | -f infile...}

Description

Updates the references in RIS format in file in the current database.

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 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.

For the -c, -g, -h, -o, -O, -U, and -f options, please refer to the description of the addref command.

Use the -P switch to update only the personal information for this reference, i.e. the N1 (notes), RP (reprint status), and AV (availability) fields. This will automatically add the reference to your personal reference list. All other fields (except TY and ER which are mandatory for any RIS dataset) will be ignored and need not be present. Combine this option with the -g option e.g. to quickly change the reprint status of existing references to "IN FILE" from "NOT IN FILE" or from "ON REQUEST".

Example

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

Synopsis

verbose [-h]

Description

Toggles the verbose mode on or off. If the verbose mode is on, the error messages and warnings may be some more comprehensible.

The -h option displays a short command syntax and description, then returns to the command prompt.

Example

refdbc: verbose

Depending on the previous value, this command will either turn the verbose mode on or off.

whichdb

Synopsis

whichdb [-h]

Description

Displays the name of the currently selected database, the number of references in this database, and the highest ID in this database.

The -h option displays a short command syntax and description, then returns to the command prompt.

Example

refdbc: whichdb

This will print the information about the active database. Refer to the selectdb command for information how to change the active database.