The following sections explain all commands available in refdbc.
addlink [-d database] [-h] [-c command | -o outfile | -O outfile] [-r] {note-specifier} {link-target...}
The addlink command links an extended note to one or more link targets. If you use the -r option, the specified links will be removed.
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] [-h] [-c command | -o outfile | -O outfile] {file | -f infile...}
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.
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 -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.
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] [-g deffile] [-h] [-c command | -o outfile | -O outfile] [-t type] [-U username] {file | -f infile...}
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.
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.
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.
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.
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.
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.
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 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. |
refdbc: deleteref 3 5-10 26 |
This command will delete the references with the ID values 3, 5 through 10, and 26.
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] [-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 -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.
The syntax of the queries is described in the section query language.
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.
getref [-d database] [-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 -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.
The syntax of the queries is described in the section query language.
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.
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).
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.
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] [-r] {ID | -f file...}
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 and -s ID options of getref.
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 -d command 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] [-h] [-c command | -o outfile | -O outfile] {file | -f infile...}
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] [-g deffile] [-h] [-c command | -o outfile | -O outfile] [-t type] [-P] [-U username] {file | -f infile...}
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, -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 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 |