Classes and their functions
Prev | Chapter 20. The Perl client module | Next

## 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 provides a simple interface to RIS data

- ReFDBClient::Simplelist is used internally

- RefDBClient::Enigma handles the password encryption

### 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

Prev | Up | Next
Chapter 20. The Perl client module | Home | Chapter 21. Using the backend API to implement new output formats