# The Perl client module

While the C clients shipped with RefDB are quite versatile and scriptable, you may have a desire to bypass these clients and write scripts that directly talk to the RefDB server. The separately available RefDBClient::Client Perl module implements the client/server communication necessary to run all commands offered by the C clients from a Perl script.

## Installation

Like with most Perl modules, the following command sequence will install the Perl module on your system

          ~$
          perl Makefile.PL

          ~$
          make

          ~$
          make install

You need root permissions to run the last command on most systems.

## 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();

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

### RefDBClient::Risdata

#### new

new RefDBClient::Risdata

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

returns previously loaded RIS data

### RefDBClient::Simplelist

#### new

new RefDBClient::Simplelist

creates a new Simplelist element

### RefDBClient::Enigma

#### new

new RefDBClient::Enigma

creates a new Enigma element

### RefDBClient::Client

#### new

new RefDBClient::Client

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

returns the numerical server status

#### get_status_msg

$client->get_status_msg

returns the server status message

#### get_data

$client->get_data

returns the data of the most recent command

#### get_summary

$client->get_summary

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

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

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