refdb handbook: covers version 0.9.6
Prev	Chapter 20. The Perl client module	Next

20.2. 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");

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 provides a simple interface to RIS data
ReFDBClient::Simplelist is used internally
RefDBClient::Enigma handles the password encryption

20.2.1. RefDBClient::Risdata

20.2.1.1. new

new RefDBClient::Risdata(void);

Creates a new Risdata object

20.2.1.2. read_ris

$data->read_ris($file);

loads RIS data from a file

$file: path of file

20.2.1.3. get_ris

$data->get_ris(void);

returns previously loaded RIS data

20.2.2. RefDBClient::Simplelist

20.2.2.1. new

new RefDBClient::Simplelist;(void);

creates a new Simplelist element

20.2.3. RefDBClient::Enigma

20.2.3.1. new

new RefDBClient::Enigma;(void);

creates a new Enigma element

20.2.4. RefDBClient::Client

20.2.4.1. new

new RefDBClient::Client;(void);

creates a new Client element

20.2.4.2. set_conninfo

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

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

$styledata: XML data representing the bibliography style

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

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

20.2.4.10. refdb_addword

$client->refdb_addword($words);

adds reserved words to the main database

$words: space-separated list of words

20.2.4.11. refdb_deleteword

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

removes reserved words from the main database

$words: space-separated list of words

20.2.4.12. refdb_confserv

$client->refdb_confserv($command);

sends a configuration command to the server

$command: the command proper, optionally followed by an argument

20.2.4.13. refdb_createdb

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

creates a new database

$dbname: name of the reference database
$encoding: character encoding

20.2.4.14. refdb_deletedb

$client->refdb_deletedb($databasename);

deletes a reference database

$dbname: name of the database

20.2.4.15. refdb_deletestyle

$client->refdb_deletestyle($stylename_regexp);

deletes citation/bibliography styles

$stylename_regexp: regular expression describing the names of the styles to be deleted

20.2.4.16. refdb_getstyle

$client->refdb_getstyle($stylename);

retrieves a citation/bibliography style as a citestylex doc

$stylename: name of the style

20.2.4.17. refdb_listdb

$client->refdb_listdb($dbname_regexp);

lists matching databases

$dbname_regexp: regular expression describing the database names

20.2.4.18. refdb_listuser

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

lists matching user names

$username_regexp: regular expression describing the user names

20.2.4.19. refdb_listword

$client->refdb_listword($word_regexp);

lists matching journal name words

$wordname_regexp: regular expression describing the word names

20.2.4.20. refdb_liststyle

$client->refdb_liststyle($stylename_regexp);

lists matching citation/bibliography styles

$stylename_regexp: regular expression describing the style names

20.2.4.21. refdb_viewstat

$client->refdb_viewstat(void);

requests version/connection info from the server

20.2.4.22. refdb_scankw

$client->refdb_scankw($dbname);

runs a thorough keyword scan in the given database

$dbname: name of the reference database

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

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

20.2.4.25. refdb_deleteref

$client->refdb_deleteref($idlist);

deletes references from the database

$idlist: string specifying the IDs of the references to be deleted

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

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

20.2.4.28. refdb_deletenote

$client->refdb_deletenote($idlist);

deletes notes from the database

$idlist: string specifying the ID values of the notes to be deleted

20.2.4.29. refdb_addlink

$client->refdb_addlink($linkspec);

links notes to database objects

$linkspec: string specifying the link(s) to be created

20.2.4.30. refdb_deletelink

$client->refdb_deletelink($linkspec);

unlinks notes from database objects

$linkspec: string specifying the link(s) to be deleted

20.2.4.31. refdb_getas

$client->refdb_getas($name_regexp);

retrieves matching series authors

$name_regexp: regular expression describing the names to be retrieved

20.2.4.32. refdb_getau

$client->refdb_getau($name_regexp);

retrieves matching authors

$name_regexp: regular expression describing the names to be retrieved

20.2.4.33. refdb_geted

$client->refdb_geted($name_regexp);

retrieves matching editors

$name_regexp: regular expression describing the names to be retrieved

20.2.4.34. refdb_getkw

$client->refdb_getkw($keyword_regexp);

retrieves matching keywords

$keyword_regexp: regular expression describing the keywords to be retrieved

20.2.4.35. refdb_getjf

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

retrieves matching periodicals (full names)

$is_all: set to 't' if all synonymous journal names shall be returned
$name_regexp: regular expression describing the names to be retrieved

20.2.4.36. refdb_getjo

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

retrieves matching periodical names (abbrev)

$is_all: set to 't' if all synonymous journal names shall be returned
$name_regexp: regular expression describing the names to be retrieved

20.2.4.37. refdb_getj1

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

retrieves matching periodical names (custom abbrev 1)

$is_all: set to 't' if all synonymous journal names shall be returned
$name_regexp: regular expression describing the names to be retrieved

20.2.4.38. refdb_getj2

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

retrieves matching periodical names (custom abbrev 2)

$is_all: set to 't' if all synonymous journal names shall be returned
$name_regexp: regular expression describing the names to be retrieved

20.2.4.39. refdb_getref

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

retrieves references

$type: select output format
$format_string: specify additional fields to be retrieved
$sort_string: specify sorting key
$is_personal: set to 't' to retrieve only references in the current users personal interest list
$encoding: the character encoding for the output data
$query_string: the query that describes the datasets to be retrieved