addstyle [-c command] [-h] [[-o filename] | [-O filename]] {style-file...}

Adds one or more bibliography style specifications from the input file(s).

-c command

Specifies a command that will receive the output instead of the default pager. This may be a different pager, any command that takes input on stdin, or the string “stdout” to send the data to stdout without using a pager.

-h

Displays the online help about the addstyle command.

-o filename

Write the output to filename instead of to stdout.

-O filename

Append the output to filename instead of writing it to stdout.

style-file

All other arguments are interpreted as the names of files containing style specifications.

	  refdba: 
	  addstyle j.biol.chem.xml pharmacol.rev.xml
	

This will add the style specifications contained in the files j.biol.chem.xml and pharmacol.rev.xml to the bibliography style database.

adduser {-d database} [-h] {-H host-IP} [-R] [-W password] {[-f file] | [username...]}

Grants access rights to a refdb database to the given users. Specify the database with the -d option.

Note

If a user is not yet known to the database server, refdb will create an account with the default access rights (=none). If you do not specify a password for the new user with the -W option (see below), the user will have access to the database server with the default password "refdb". In most cases this is not a good thing.

A new user will automatically get access to the internal refdb database refdb.

Some database engines like SQLite do not support access control. The adduser command is not supported with these engines and will just return an explanatory message.

-d database

Specifies the reference database for which the access rights should apply.

-f file

Reads a whitespace-separated list of usernames from file.

-h

Displays the online help about the adduser command.

-H hostname

hostname specifies the host the refdb application server runs on. If it runs on the same machine as the database server, you may specify “localhost” as hostname. Use “%” as hostname to allow access from all addresses except localhost. Otherwise, the hostname argument can be either a hostname, an IP address, or a subnet that specifies one or more computers to allow access from. You can add the same user several times with different hostnames.

Note
This option is only supported by MySQL. It is ignored if you use PostgreSQL as your database server. Please see the PostgreSQL documentation for help on how to manipulate host-based access control with the pg_hba.conf file.

-R

Use this option to grant read-only access for the user. By default, users are granted read/write access. Users with read-only access can basically only retrieve references and notes.

-W password

Set the password for a new user. The password is encrypted before transferring it to the application server. If the user already exists, his password will be changed accordingly.

username

All other arguments are interpreted as usernames. If neither a username argument nor an input file is specified, refdba attempts to read a whitespace-separated list of names from stdin. To force refdba to read from stdin in addition to explicitly named users, use the -f stdin option.

	  refdba: 
	  adduser -d db1 -N newpassjim 
	

This will grant access to the database db1 for the new user jim. refdbd runs on the same computer as the database server (if you leave out the -H option, localhost is assumed). "jim" will have to provide "newpass" as a password when starting one of the refdb clients.

	  refdba: 
	  adduser -d db1 -H mono.mycomp.com jim jane
	

This will grant access to the database db1 for the users jim and jane. refdbd runs on the computer with the name "mono.mycomp.com". If "jim" and "jane" are already known to the database server, they will keep their existing passwords. If not, they will have to use the default password "refdb".

If you as the refdb administrator do not have GRANT permission on your database server, the adduser command is bound to fail. As a security-minded person your database administrator might refuse to run refdba regardless of how often you ensure him it doesn't contain malicious code. He'll want to do it the hard way, and this is what he needs to do:

•

If you use MySQL as your database server, each new user needs at least entries in the mysql.user and mysql.db tables. Your database administrator might have set up his own rules, but in general the mysql.user table should grant no privileges to the user, whereas the mysql.db table should grant INSERT, SELECT, UPDATE, DELETE permissions to each user for the refdb database and SELECT, INSERT, UPDATE, DELETE, CREATE, DROP privileges for each reference database the user should have access to. Make sure to mention that the Host field in mysql.user must contain the name or address of the box that runs refdbd, which is not necessarily identical with the workstation of the user.

•

If you prefer PostgreSQL instead, things are a little simpler. When you create a refdb database, a new group will be created to manage access to this database. All your database administrator needs to do is to add the new user to the groups refdbuser (granting access to the common refdb database) and <dbname>user, where <dbname> is the name of the reference database the user should be allowed to access.

addword [-h] {[-f file] | [word...]...}

Most bibliography styles use standardized abbreviations of the journal names. Most data sources specify these abbreviations without dots, as in "Mol Cell Biol". If the words are to be abbreviated with dots (as in "Mol. Cell Biol.") in the bibliography, refdb needs to know which tokens in the abbreviated name are indeed abbreviated (e.g. "Mol."), and which are full words (e.g. "Cell"). To this end, refdb keeps a list of reserved words which are known not to be abbreviations of something else. refdb ships with a fairly complete list of such words, but if you detect errors or omissions, the addword command comes in handy.

-f file

Read a whitespace-separated list of journal title words from file.

-h

Displays the online help about the addword command.

word

All other arguments are interpreted as reserved words. If neither a word list nor an input file is specified, refdba attempts to read a whitespace-separated list of words from stdin. To force refdba to read from stdin in addition to explicitly listed words, use the -f stdin option.

Note
refdb will convert all reserved words to uppercase internally, so it does not matter which case you provide these words in.

	  refdba: 
	  addword -f wordlist FOO BAR
	

This will add all reserved words in the file wordlist as well as the words "FOO" and "BAR" to the list of reserved words.

confserv {command} [value]

Configures the application server while it is running and does some tricks with the refdb helper databases as well. Some of the commands modify variables that can be set as command line arguments or with the init file. See Running the refdbd daemon for more information about these variables.

Note

This command will only reconfigure refdbd transiently. All changes are lost when the application server is restarted. To make permantent changes to the configuration, edit the init-file or change the command-line parameters in the script that starts refdbd. Please note also that remote administration must be enabled for this command to work.

The following commands are available:

stop

Stops the application server.

Note
This command affects only the refdbd parent process. Any children that may be currently serving clients will continue to do so until they are done.

ping

Checks whether the application server is still alive and well. If this is the case, it will report the process IDs of the child that handles your query and of the parent. If not, the connection will time out with no response.

serverip value

Sets the database server IP address to value.

timeout value

Sets the timeout in seconds to value.

logdest value

Sets the destination of log output to value. Possible values are 0 (stderr), 1 (the system syslog facility), 2 (a private log file as defined by logfile).

logfile value

Sets the filename of the log file to value.

loglevel value

Sets the maximum level of messages to be logged to value. 0 means that only critical errors will be logged, 7 means that all messages including the extremely verbose debug messages will be logged. -1 disables logging completely.

refdba: confserv loglevel 7

This will set the log level to 7. This temporary change will only be effective until refdbd is restarted.

createdb [-E encoding] [-h] {dbname...}

Creates a new database with the name dbname. Several databases may be specified in a single call of this command.

-E encoding

Select a character encoding for the new database. This is currently only supported by MySQL and PostgreSQL. If you use a different engine, this option is ignored. Please see the documentation of your database engine installation for available encodings. The value passed with the -E option should be the [1]IANA encoding name. If you do not use this option, the new database will use the default encoding of the database server unless your refdbdrc configuration file sets a default with a "db_encoding" entry.

-h

Displays the online help about the createdb command.

name

The name of the database. The name must not contain a colon (':') or a dash ('-') due to the citation formats in documents using RefDB. The allowed characters may be further restricted by the database engine you use. The database name should also be considered case-insensitive, i.e. don't try to create a database "mybase" if you already have one called "MYBASE".

Tip
Prepend a constant string like “rd” to all refdb database names. This speeds up retrieving refdb databases with the listdb command if your database engine manages additional, non-RefDB databases. Use a simple regular expression like “rd%” to restrict your search to RefDB databases.

	  refdba: 
	  createdb db1 -E UTF-8 db2
	

This will create the databases db1 and db2 with the character encoding UTF-8.

refdb contains two plain-text SQL scripts (installed in /usr/local/share/refdb/sql) to create database tables just like the createdb command does. These scripts are preferable to the command in these cases:

•

You do not have database administrator permissions and have to ask your admin to create the databases for you. Your admin might prefer to run the script as he can easily find out what it is going to do.

•

You want to integrate refdb with an existing or a custom database system. In that case you want the refdb-specific tables in an existing database in addition to non-refdb tables.

	      #~ 
	      mysql -e "CREATE DATABASE dbname"
	    

	      #~ 
	      mysql dbname < empty.mysql.dump
	    

	      #~ 
	      sed 's/refdbtest/dbname/g' < empty.pgsql.dump.in > empty.pgsql.dump
	    

	      #~ 
	      psql template1 < empty.pgsql.dump
	    

deletedb [-h] {dbname...}

Deletes the database with the name dbname. Several databases may be specified in a single call of this command.

Caution

The database structure and the data will be gone, really gone, so be careful with this command. Think twice and, if in doubt, at least make a backup first to avoid extensive hairpulling.

-h

Displays a brief usage message and returns to the prompt.

dbname

The name of the database to be deleted.

	  refdba: 
	  deletedb db1 db2
	

This will delete the databases db1 and db2.

deletestyle [-h] {unix-regexp}

Deletes the bibliography styles whose names match the Unix regular expression unix-regexp.

Note

Some database engines, like SQLite, do not support Unix-style regular expressions. Use SQL regular expressions instead.

-h

Displays a brief usage message and returns to the prompt.

unix-regexp

The remaining arguments are interpreted as a regular expression which specifies the style or styles to be deleted.

	  refdba: 
	  deletestyle J\..*
	

This will delete all bibliography styles that start with “J.”.

deleteuser {-d database} [-h] {-H host-IP} {-R} {[-f file] | [username...]}

Revokes access rights to a refdb database from the given users.

Note

Some database engines like SQLite do not support access control. The adduser command is not supported with these engines and will just return an explanatory message.

refdb will only revoke the access rights to the specified database. It will revoke neither access rights to the internal database refdb, nor will it revoke database server access. You can revoke access to the internal database by specifying "refdb" with the -d option. To revoke access to the database server, please use the command line utilities of your database server.

-d database

Specify the name of the database.

-f filename

Read the usernames from filename

-h

Displays the online help about the deleteuser command.

-H hostname

Specify the hostname or IP address for which to modify the access rights. This must be the same name that you used for a previous call to adduser.

Note
This option is only supported by MySQL. It is ignored if you useother database engines.

-R

Revokes read-only access.

username

All other arguments are interpreted as usernames. If neither a username argument nor an input file is specified, refdba attempts to read a whitespace-separated list of names from stdin. To force refdba to read from stdin in addition to explicitly named users, use the -f stdin option.

	  refdba: 
	  deleteuser -d -H % db1jim
	

This will revoke the access to the database db1 for the user jim for all but local connections.

deleteword [-h] {[-f file] | [word...]...}

This command performs the reverse operation of addword. The specified reserved words will be removed from the list.

-f

Read a whitespace-separated list of words from file.

-h

Displays the online help about the addword command.

word

All other arguments are interpreted as reserved words. If neither a word list nor an input file is specified, refdba attempts to read a whitespace-separated list of words from stdin. To force refdba to read from stdin in addition to explicitly listed words, use the -f stdin option.

Note
refdb will convert all reserved words to uppercase internally, so it does not matter in which case you provide these words.

	  refdba: 
	  deleteword -f wordlist FOO BAR
	

This will delete all reserved words in the file wordlist as well as the words "FOO" and "BAR" from the list of reserved words.

getstyle [-c] [-h] [[-o] | [-O]] {style...}

Retrieves one or more bibliography style specifications from the database and formats them as an XML file.

-c command

Specify a command that will receive the output instead of the default pager. This may be a different pager, any command that takes input on stdin, or the string “stdout” to send the data to stdout without using a pager.

-h

Displays the online help about the getstyle command.

-o

Write the output to a file instead of to stdout.

-O

Append the output to a file instead of writing it to stdout

Warning
Be careful with the append (-O) option. refdb will output the processing instructions, the doctype line, and one CITESTYLE element for each individually requested style. If you concatenate the results of several getstyle calls, the resulting XML file will not be well-formed without further processing. In order to write several styles into a single XML file, use a single getstyle call and list all required styles as arguments. This will output the styles wrapped in a STYLESET element, resulting in a valid XML file.

style

All other arguments are interpreted as the names of bibliography styles.

	  refdba: 
	  getstyle -o j.biol.chem.xml J.Biol.Chem.
	

This will write the style specification stored under the style name "J.Biol.Chem." to the file j.biol.chem.xml.

help

?

Displays a brief summary of the available commands.

listdb [-h] [database-regexp]

Lists all available databases if no argument is specified. If database-regexp is specified, only the databases matching this expression will be listed.

Note

In order to tell refdb reference databases apart from other databases maintained by your database server, refdbd has to peek into each database returned by the database server. Depending on the number of available databases this may take some time. Therefore it may be a good idea to use a common prefix for all refdb databases as explained in the section about the createdb command.

-h

Displays a help message explaining the listdb command.

database-regexp

A valid SQL regular expression which limits the output to matching database names.

	  refdba: 
	  listdb db%
	

This will list all databases with names that start with the string “db”.

liststyle [-h] [style-regexp]

Lists all available bibliography styles that match style-regexp. If no argument is given, all available styles will be listed. This may or may not be what you want.

-h

Displays a help message explaining the listdb command.

style-regexp

A valid Unix regular expression which limits the output to matching style names.

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

listuser {-d database} [-h] [name-regexp]

Lists all available users of the specified database that match name-regexp. If no argument is given, all available users will be listed. This may or may not be what you want.

-d database

Specify the database name.

-h

Displays a help message explaining the listdb command.

name-regexp

A valid Unix regular expression which limits the output to matching database user names.

Note
Some database engines, like SQLite, do not support Unix-style regular expressions. Use SQL regular expressions instead.

	  refdba: 
	  listuser -d refs ^mo.*
	

This will list all users of the database "refs" whose names start with “mo”.

listword [-h] {word-regexp}

Lists all available reserved journal words that match unix-regexp. If no argument is given, all available words will be listed. This may or may not be what you want.

Note

Keep in mind that the journal words are uppercased internally. You should write your unix-regexp using all caps accordingly.

-h

Displays a help message explaining the listdb command.

word-regexp

A valid Unix regular expression which limits the output to matching journal title words.

Note
Some database engines, like SQLite, do not support Unix-style regular expressions. Use SQL regular expressions instead.

Note
For a brief description of the purpose of reserved words, see the addword command.

	  refdba: 
	  listword ^BIO.*
	

This will list all reserved journal words that start with “BIO”.

scankw {-d database} [-h]

This command schedules a full keyword scan in the database specified with the -d option. The abstract field as well as all title fields of all references found in the database are scanned for the presence of all keywords available in the database. If a match is found and the keyword is not yet associated with that reference, the keyword is added to that reference. As the time required to perform this operation increases with both the number of references and the number of keywords, the keyword scan is performed in the background and the command returns immediately on the client side. See the server log for the results.

As this command will cause a huge number of database accesses it is best scheduled to run automatically as a cron job at a time of low use, either nightly or on weekends.

Please note the difference between the full keyword scan and the automatic keyword scan which can be requested by the refdbd command line switch -K or the corresponding configuration variable keyword_scan. The full keyword scan is "retrospective", i.e. it will add keywords that were added later to previously existing references. The automatic keyword scan will only add existing keywords to newly added references, thus causing less impact on the database performance while users are likely to access the database.

-d database

Specify the database name.

-h

Displays a help message explaining the listdb command.

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 current 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) for the current session. To specify an empty value, use two quotation marks like this:"".

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.

-h

Displays a help message explaining the listdb command.

varname

The name of the variable whose value should be displayed or set.

varvalue

The new value of the variable to be set.

	  refdba: 
	  set timeout 90
	

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

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.

-h

Displays a help message explaining the listdb command.

	  refdba: 
	  verbose
	

Depending on the previous setting, this will toggle the verbose mode on or off.

viewstat [-h]

Shows the version numbers of the libdbi driver used to connect to your database server as well as the version information of that server. It also shows the current values of the variables that can be modified with confserv.

-h

Displays a help message explaining the listdb command.

	  refdba: 
	  viewstat
	

This will print some connection statistics and informations on the screen.