The following sections explain all commands available in refdbc.
addlink [-d database] [-h] [-c command | -o outfile | -O outfile] {note-specifier} {link-target...}
The addlink command links an extended note to one or more link targets.
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).
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 [-d database] [-E encoding] [-h] [-c command | -o outfile | -O outfile] [file...]
Adds the extended notes in file to the current database. You can specify several files in one run. Any ID fields in the notes are ignored.
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 if it is different from the currently selected database.
Select an input character encoding with the -E option if it is different from the default UTF-8.
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.
All other command-line arguments will be interpreted as filenames to read references from. If no filenames are specified, the data will be read from stdin.
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 [-d database] [-E encoding] [-g deffile] [-h] [-c command | -o outfile | -O outfile] [-t type] [-U username] [file...]
Adds the references 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.
Select an input character encoding with the -E option if it is different from the default UTF-8. RIS datasets can use any encoding that your local libiconv supports (see man iconv_open for a list of available encodings), except UTF-16 and UTF-32. RISX datasets carry the encoding in the processing instructions, therefore this option is ignored.
You can use two different input file formats with this command. The default format is the tagged RIS format. Use -t risx to use XML files according to the RISX DTD as input data.
The -g option can be used in conjunction with RIS data 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.
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.
All other command-line arguments will be interpreted as filenames to read references from. If no filenames are specified, the data will be read from stdin.
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.
deletelink [-d database] [-h] [-c command | -o outfile | -O outfile] {note-specifier} {link-target...}
The deletelink command removes links from an extended note to one or more link targets.
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).
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 [-d database] [-h] [-c command | -o outfile | -O outfile] {ID | -f infile}...
Deletes the extended note with the identifier ID from the current database. Several extended notes may be specified in a single call of this command. Notes with consecutive ID values may be specified as ranges.
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 and -s ID options of getnote. The -f switch can also be combined with IDs specified as arguments. If no IDs are specified, the ID list is read from stdin. If you want to read from stdin in addition to other IDs, you must use the -f stdin option.
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 |
It is not possible to delete a note if it belongs to a different user. |
refdbc: deletenote 3 5-10 26 |
This command will delete the extended notes with the ID values 3, 5 through 10, and 26.
deleteref [-d database] [-h] [-c command | -o outfile | -O outfile] {ID | -f infile}...
Deletes the reference with the identifier ID from the current database. Several references may be specified in a single call of this command. References with consecutive ID values may be specified as ranges.
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 and -s ID options of getref. The -f switch can also be combined with IDs specified as arguments. If no IDs are specified, the ID list is read from stdin. If you want to read an ID list from stdin in addition to IDs passed as arguments, you have to use the -f stdin option.
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 |
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. |
refdbc: deleteref 3 5-10 26 |
This command will delete the references with the ID values 3, 5 through 10, and 26.
dumpref [-d database] [-h] [-c command | -o outfile | -O outfile] {ID | -f file}...
Removes references from your personal reference list 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. 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 and -s ID options of getref. If no IDs are specified as arguments, the ID list is read from stdin. If you want to read from stdin in addition to IDs specified as arguments, you have to use the -f stdin option.
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 [-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}
Retrieve all author names that match the regular expression unix-regexp in the current database. If no regexp argument is given, all author names will be listed, which may or may not be what you want. 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.
Note: Some database engines, like SQLite, do not support Unix-style regular expressions. Use SQL regular expressions instead.
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.
refdbc: getau -o authors.txt '^Simpson' |
This command will print a list of all authors starting with "Simpson".
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}
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 no regexp argument is given, all available journal names will be listed.
Note: Some database engines, like SQLite, do not support Unix-style regular expressions. Use SQL regular expressions instead.
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.
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 [-d database] [-h] [-c command | -o outfile | -O outfile] {unix-regexp}
Retrieve all keywords that match the regular expression unix-regexp in the current database. If no regexp argument is specified, all keywords in the database will be listed.
Note: Some database engines, like SQLite, do not support Unix-style regular expressions. Use SQL regular expressions instead.
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.
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.
getnote [-d database] [-E encoding] [-h] [-c command | -o outfile | -O outfile] [-P] [-s format-string] [-S sort-string] [-t output-format] {search-string | -f file}
Displays all extended notes 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 content for certain strings. Searching all abstracts of a database with a normal query is slow. It is usually faster to narrow down the search using other fields as far as possible without including the content 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 retrieved data will use the character encoding of the database unless you request a different encoding with the -E option. All encodings supported by your local libiconv installation may be specified here.
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 getnote 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 notes (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. |
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 notes which were added by the current user. 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 xnote (XML according to the xnote DTD), html (HTML), and xhtml.
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. If no search string is specified, the string will be read from stdin.
The syntax of the queries is described in the section query language.
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 [-d database] [-E encoding] [-h] [-c command | -o outfile | -O outfile] [-P] [-s format-string] [-S sort-string] [-t output-format] {search-string | -f file}
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 using other fields as far 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 retrieved data will use the character encoding of the database unless you request a different encoding with the -E option. All encodings supported by your local libiconv installation may be specified here. See man iconv_open for a list of available encodings.
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. |
Except for RIS and risx output which always display the full dataset, the -s switch allows to specify additional fields (N1, N2/AB, NX, RP, SN, AD, CY, PB, UR, U1 through U5, M1 through M3) that are not displayed by default. Use "ALL" as an argument to display all available fields. 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 a convenient way to generate ID lists for later operations 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 SGML V. 3.1), db31x (DocBook XML), ris (RIS as of Reference Manager 8.01), risx (XML according to the risx DTD), html (HTML), xhtml (XHTML), 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. If no search string is specified, the string is read from stdin.
The syntax of the queries is described in the section query language.
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.
Displays a brief summary of the available commands.
Note: This command is not available in the batch mode (use the
-hoption instead to review the command line usage).
listdb [-h] [SQL-regexp]
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.
refdbc: listdb db% |
This command will list all available databases that start with "db".
liststyle {unix-regexp}
Lists all available bibliography styles that match unix-regexp. unix-regexp has to be a valid Unix regular expression. If no argument is specified, all available styles will be listed.
Note: Some database engines, like SQLite, do not support Unix-style regular expressions. Use SQL regular expressions instead.
refdba: liststyle ^J.* |
This will list all bibliography styles that start with a capital "J".
pickref [-d database] [-h] [-c command | -o outfile | -O outfile] {ID | -f file}...
Adds references to your personal reference list 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. 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 and -s ID options of getref. If no IDs are specified, the ID list in RIS format is read from stdin.
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.
selectdb [-h] {database}
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
-dcommand line option instead.
The -h option displays a short command syntax and description, then returns to the command prompt.
refdbc: selectdb db1 |
This command will make the database db1 the active database. All further queries and operations will affect this database.
set [-h] [varname] [varvalue]
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.
refdbc: set timeout 90 |
This command will set the timeout to 90 seconds for the current session.
updatenote [-d database] [-E encoding] [-h] [-c command | -o outfile | -O outfile] [file...]
Updates the extended notes in file in the current database.
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.
The command line options are the same as described for the addnote command.
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 [-d database] [-E encoding] [-g deffile] [-h] [-c command | -o outfile | -O outfile] [-t type] [-P] [-U username] [file]
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 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.
For the -c, -E, -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 will be ignored. 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".
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]
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.
refdbc: verbose |
Depending on the previous value, this command will either turn the verbose mode on or off.
whichdb [-h]
Displays a plethora of information about the currently selected database.
The -h option displays a short command syntax and description, then returns to the command prompt.
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 |