Classes and their functions

Like most Perl modules, the RefDBClient::Client module is object-oriented. This section introduces the two classes that you need to know in order to work with the module. To see a working example, please check the test.pl script shipped with the module.

The main class that is used to access all RefDB client functions is called RefDBClient::Client. To get started, create a new instance and set the communication parameters:

use RefDBClient::Client;

my $client = new RefDBClient::Client;

$client->set_conninfo("127.0.0.1", "9734", "markus", "pass", "refdbtest",
                      "/home/markus/literature", "/usr/local/share/refdb/css/refdb.css", "360");
    

Then you can go ahead and send commands to the server like this:

$summary = $client->refdb_listdb("");
$data = $client->get_data();
    

Note

As you can easily guess the functions implementing the client commands are analogous to the commands found in the refdba and refdbc clients. See the reference pages about these apps for further information about the commands.

There are three helper classes:

RefDBClient::Risdata

new

new RefDBClient::Risdata(void); 

Creates a new Risdata object

read_ris

$data->read_ris(  $file);

loads RIS data from a file

$file

path of file

get_ris

$data->get_ris(void); 

returns previously loaded RIS data

RefDBClient::Simplelist

new

new RefDBClient::Simplelist(void); 

creates a new Simplelist element

RefDBClient::Enigma

new

new RefDBClient::Enigma(void); 

creates a new Enigma element

RefDBClient::Client

new

new RefDBClient::Client(void); 

creates a new Client element

set_conninfo

$client->set_conninfo(  $server_ip,
   $port_address,
   $username,
   $password,
   $database,
   $pdf_root,
   $css_url,
   $timeout);

sets the initial connection parameters of a Client object

$server_ip

IP address or hostname of the server that runs refdbd

$port_address

Port address at which refdbd listens

$username

Username for database password authentication

$password

Password for database password authentication

$database

Name of the reference database

$pdf_root

Path of the root directory of all electronic offprints

$css_url

URL of a Cascading Stylesheets file for (X)HTML output

$timeout

Timeout in seconds after which a stale connection is taken down

get_status

$client->get_status(void); 

returns the numerical server status

get_status_msg

$client->get_status_msg(void); 

returns the server status message

get_data

$client->get_data(void); 

returns the data of the most recent command

get_summary

$client->get_summary(void); 

returns the summary of the most recent command

refdb_addstyle

$client->refdb_addstyle(  $styledata);

adds a citation/bibliography style to the database

$styledata

XML data representing the bibliography style

refdb_adduser

$client->refdb_adduser(  $host,
   $database,
   $newuserpassword,
   $username);

adds new users to the database

$host

host specification from which the user is allowed to connect

$database

name of the reference database

$newuserpassword

password (required only for new users)

$username

name of the user, as used to authenticate at the database engine

refdb_deleteuser

$client->refdb_deleteuser(  $host,
   $database,
   $username);

deletes users from the database

$host

host specification from which the user is allowed to connect

$database

name of the reference database

$username

name of the user, as used to authenticate at the database engine

refdb_addword

$client->refdb_addword(  $words);

adds reserved words to the main database

$words

space-separated list of words

refdb_deleteword

$summary = $client->refdb_deleteword(  $words);

removes reserved words from the main database

$words

space-separated list of words

refdb_confserv

$client->refdb_confserv(  $command);

sends a configuration command to the server

$command

the command proper, optionally followed by an argument

refdb_createdb

$client->refdb_createdb(  $dbname,
   $encoding);

creates a new database

$dbname

name of the reference database

$encoding

character encoding

refdb_deletedb

$client->refdb_deletedb(  $databasename);

deletes a reference database

$dbname

name of the database

refdb_deletestyle

$client->refdb_deletestyle(  $stylename_regexp);

deletes citation/bibliography styles

$stylename_regexp

regular expression describing the names of the styles to be deleted

refdb_getstyle

$client->refdb_getstyle(  $stylename);

retrieves a citation/bibliography style as a citestylex doc

$stylename

name of the style

refdb_listdb

$client->refdb_listdb(  $dbname_regexp);

lists matching databases

$dbname_regexp

regular expression describing the database names

refdb_listuser

$client->refdb_listuser(  $dbname,
   $username_regexp);

lists matching user names

$username_regexp

regular expression describing the user names

refdb_listword

$client->refdb_listword(  $word_regexp);

lists matching journal name words

$wordname_regexp

regular expression describing the word names

refdb_liststyle

$client->refdb_liststyle(  $stylename_regexp);

lists matching citation/bibliography styles

$stylename_regexp

regular expression describing the style names

refdb_viewstat

$client->refdb_viewstat(void); 

requests version/connection info from the server

refdb_scankw

$client->refdb_scankw(  $dbname);

runs a thorough keyword scan in the given database

$dbname

name of the reference database

refdb_addref

$client->refdb_addref(  $owner,
   $refdata,
   $type,
   $encoding);

adds references to the database

$owner

name of the dataset owner, if different from current user

$refdata

string containing the reference data

$type

data type, must be one of 'ris' or 'risx'

$encoding

character encoding of the input data (only for RIS data)

refdb_checkref

$client->refdb_checkref(  $risdata,
   $type,
   $encoding,
   $outtype);

Checks new references against the references in the database without adding them permanently

$risdata

string containing the reference data

$type

data type, must be one of 'ris' or 'risx'

$encoding

character encoding of the input data (only for RIS data)

$outtype

output data type, must be one of 'scrn' or 'xhtml'

refdb_updateref

$client->refdb_updateref(  $owner,
   $is_personal,
   $risdata,
   $type,
   $encoding);

updates references in the database

$owner

name of the dataset owner, if different from current user

$is_personal

set to 't' if only the personal information shall be updated

$refdata

string containing the reference data

$type

data type, must be one of 'ris' or 'risx'

$encoding

character encoding of the input data (only for RIS data)

refdb_deleteref

$client->refdb_deleteref(  $idlist);

deletes references from the database

$idlist

string specifying the IDs of the references to be deleted

refdb_addnote

$client->refdb_addnote(  $owner,
   $xnotedata);

adds notes to the database

$owner

owner of the note, if different from the current user

$xnotedata

XML data specifying the note

refdb_updatenote

$client->refdb_updatenote(  $owner,
   $is_personal,
   $xnotedata);

updates references in the database

$owner

owner of the note, if different from the current user

$is_personal

set to 't' if only the personal information shall be updated

$xnotedata

XML data specifying the note

refdb_deletenote

$client->refdb_deletenote(  $idlist);

deletes notes from the database

$idlist

string specifying the ID values of the notes to be deleted

refdb_addlink

$client->refdb_addlink(  $linkspec);

links notes to database objects

$linkspec

string specifying the link(s) to be created

refdb_deletelink

$client->refdb_deletelink(  $linkspec);

unlinks notes from database objects

$linkspec

string specifying the link(s) to be deleted

refdb_getas

$client->refdb_getas(  $limit_string,
   $name_regexp);

retrieves matching series authors

$limit_string

Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.

$name_regexp

regular expression describing the names to be retrieved

refdb_getau

$client->refdb_getau(  $limit_string,
   $name_regexp);

retrieves matching authors

$limit_string

Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.

$name_regexp

regular expression describing the names to be retrieved

refdb_geted

$client->refdb_geted(  $limit_string,
   $name_regexp);

retrieves matching editors

$limit_string

Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.

$name_regexp

regular expression describing the names to be retrieved

refdb_getkw

$client->refdb_getkw(  $limit_string,
   $keyword_regexp);

retrieves matching keywords

$limit_string

Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.

$keyword_regexp

regular expression describing the keywords to be retrieved

refdb_getjf

$client->refdb_getjf(  $is_all,
   $limit_string,
   $journal_regexp);

retrieves matching periodicals (full names)

$is_all

set to 't' if all synonymous journal names shall be returned

$limit_string

Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.

$name_regexp

regular expression describing the names to be retrieved

refdb_getjo

$client->refdb_getjo(  $is_all,
   $limit_string,
   $journal_regexp);

retrieves matching periodical names (abbrev)

$is_all

set to 't' if all synonymous journal names shall be returned

$limit_string

Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.

$name_regexp

regular expression describing the names to be retrieved

refdb_getj1

$client->refdb_getj1(  $is_all,
   $limit_string,
   $journal_regexp);

retrieves matching periodical names (custom abbrev 1)

$is_all

set to 't' if all synonymous journal names shall be returned

$limit_string

Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.

$name_regexp

regular expression describing the names to be retrieved

refdb_getj2

$client->refdb_getj2(  $is_all,
   $limit_string,
   $journal_regexp);

retrieves matching periodical names (custom abbrev 2)

$is_all

set to 't' if all synonymous journal names shall be returned

$limit_string

Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.

$name_regexp

regular expression describing the names to be retrieved

refdb_getref

$client->refdb_getref(  $type,
   $format_string,
   $sort_string,
   $listname,
   $encoding,
   $limit_string,
   $query_string);

retrieves references

$type

select output format

$format_string

specify additional fields to be retrieved

$sort_string

specify sorting key

$listname

specify a list name if the search is to be confined to a particular personal reference list

$encoding

the character encoding for the output data

$limit_string

Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.

$query_string

the query that describes the datasets to be retrieved

refdb_countref

$client->refdb_countref(  $listname,
   $limit_string,
   $query_string);

Counts matching references

$listname

specify a list name if the search is to be confined to a particular personal reference list

$limit_string

Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.

$query_string

the query that describes the datasets to be counted

refdb_pickref

$client->refdb_pickref(  $idlist$listname);

adds references to the users personal reference list

$idlist

specifies the ID values of the references to be picked

$listname

the name of the personal list that the references should be added to. If this string is empty, the default personal list is used instead,

refdb_dumpref

$client->refdb_dumpref(  $idlist$listname);

removes references from personal reference list

$idlist

specifies the ID values of the references to be dumped

$listname

the name of the personal list that the references should be added to. If this string is empty, the default personal list is used instead,

refdb_getnote

$client->refdb_getnote(  $type,
   $format_string,
   $sort_string,
   $encoding,
   $limit_string,
   $query_string);

retrieves references

$type

select output format

$format_string

specify additional fields to be retrieved

$sort_string

specify sorting key

$encoding

the character encoding for the output data

$limit_string

Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.

$query_string

the query that describes the datasets to be retrieved

refdb_countnote

$client->refdb_countnote(  $listname,
   $limit_string,
   $query_string);

Counts matching extended notes

$listname

specify a list name if the search is to be confined to a particular personal reference list

$limit_string

Limits the matching datasets. Must be in the form 'limit[:offset]', where limit is the number of returned datasets, and offset the number of datasets to skip.

$query_string

the query that describes the datasets to be counted

refdb_selectdb

$client->refdb_selectdb(  $dbname);

selects an existing database as the current database

$dbname

name of the reference database

refdb_whichdb

$client->refdb_whichdb(void); 

displays information about the current database

refdb_texbib

$client->refdb_texbib(  $style,
   $cite_data);

retrieves a bibliography in bibtex format based on citationlistx data

$style

the name of the citation/bibliography style

$cite_data

XML data describing the references

refdb_dbib

$client->refdb_dbib(  $type,
   $style,
   $encoding,
   $cite_data);

retrieves an XML/SGML bibliography based on citationlistx data

$type

type of the bibliography output

$style

name of the citation/bibliography style

$encoding

character encoding of the output data

$cite_data

XML data specifying the references