[Refdb-cvs] CVS: refdb/doc refdb-manual-chapter18a.sgml,NONE,1.1.2.1

[Markus H. <mho...@us...>]

Update of /cvsroot/refdb/refdb/doc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv31746

Added Files:
      Tag: Release_0_9_5_stable
	refdb-manual-chapter18a.sgml 
Log Message:
initial version

--- NEW FILE ---
<!-- $Id: refdb-manual-chapter18a.sgml,v 1.1.2.1 2005/08/14 00:30:24 mhoenicka Exp $ -->
<chapter id="chapter-perl-client-module">
  <title>The Perl client module</title>
  <para>While the C clients shipped with &appname; are quite versatile and scriptable, you may have a desire to bypass these clients and write scripts that directly talk to the &appname; 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.</para>
  <sect1>
    <title>Installation</title>
    <para>Like with most Perl modules, the following command sequence will install the Perl module on your system</para>
    <screen format="linespecific"><prompt moreinfo="none">~$ </prompt><userinput moreinfo="none">perl Makefile.PL</userinput></screen>
    <screen format="linespecific"><prompt moreinfo="none">~$ </prompt><userinput moreinfo="none">make</userinput></screen>
    <screen format="linespecific"><prompt moreinfo="none">~$ </prompt><userinput moreinfo="none">make install</userinput></screen>
    <note>
      <para>You need root permissions to run the last command on most systems.</para>
    </note>
  </sect1>
  <sect1>
    <title>Classes and their functions</title>
    <para>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 <filename moreinfo="none">test.pl</filename> script shipped with the module.</para>

    <para>The main class that is used to access all &appname; client functions is called RefDBClient::Client. To get started, create a new instance and set the communication parameters:</para>
    <programlisting format="linespecific">
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");
    </programlisting>
    <para>Then you can go ahead and send commands to the server like this:</para>
    <programlisting format="linespecific">
$summary = $client->refdb_listdb("");
$data = $client->get_data();
    </programlisting>
    <note>
      <para>As you can easily guess the functions implementing the client commands are analogous to the commands found in the <link linkend="chapter-refdba">&appname;a</link> and <link linkend="chapter-refdbc">&appname;c</link> clients. See the reference pages about these apps for further information about the commands.</para>
    </note>
    <para>There are three helper classes:</para>
    <itemizedlist>
      <listitem>
	<para>RefDBClient::Risdata provides a simple interface to RIS data</para>
      </listitem>
      <listitem>
	<para>ReFDBClient::Simplelist is used internally</para>
      </listitem>
      <listitem>
	<para>RefDBClient::Enigma handles the password encryption</para>
      </listitem>
    </itemizedlist>
&refdbclient;
  </sect1>
</chapter>

<!--
Local Variables:
sgml-parent-document: ("refdb-manual.sgml" "BOOK PART")
End:
-->