/usr/share/doc/refdb/refdb-manual/ch19s02.html is in refdb-doc 1.0.2-3ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Interfaces</title><link rel="stylesheet" type="text/css" href="manual.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="home" href="index.html" title="RefDB handbook" /><link rel="up" href="ch19.html" title="Chapter 19. Using RefDB in your programs" /><link rel="prev" href="ch19.html" title="Chapter 19. Using RefDB in your programs" /><link rel="next" href="ch19s03.html" title="Tips and tricks" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Interfaces</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch19.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Using RefDB in your programs</th><td width="20%" align="right"> <a accesskey="n" href="ch19s03.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idp66052000"></a>Interfaces</h2></div></div></div><p>There are two interfaces available which will be explained below.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idp66053152"></a>Call the C clients from your program</h3></div></div></div><p>Using system calls is fairly straightforward. Most programming languages provide constructs to run external programs and to send data to their standard input or to read data from their standard output (rarely, however, both at a time). The following commands give an example how to accomplish this in Perl:</p><pre class="programlisting">
$output = `refdbc -d $dbname -C whichdb -u $user -w $pass 2>/dev/null`;
$result = `refdbc -d $dbname -C addref -t $type -u $user -w $pass $infile 2>&1`;
</pre><p>The first call discards the standard error of the command and writes only the standard output to the variable <code class="varname">$output</code>. The second call collects both standard error and standard output in a single variable. Your program would have to parse <code class="varname">$result</code> in order to separate both. In both cases Perl variables are used to supply database names, file names, or the reference type.</p><p>This kind of access works from most programming languages. For an example written in Lisp, see the <a class="ulink" href="http://refdb.sourceforge.net/emacs.html" target="_top">Emacs frontend</a> for RefDB. Easy as it may be, running the C clients from your program does have some drawbacks:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>As shown in the examples above, the handling of standard output and standard error is less than perfect. You can retrieve either, or both in a single variable. Your program therefore needs the logic to separate output from error messages. If you need both separately, you can redirect both to separate files and then read in these files, but this is as kludgy as it sounds.</p></li><li class="listitem"><p>On most systems you can't send to standard input and read from standard output at the same time (see <a class="ulink" href="http://www.cpan.org/scripts/process-handling/STDIN.STDOUT.connection.pipe" target="_top">this Perl script</a> how you can still achieve this). This can be circumvented by either writing the input data to a file (most RefDB commands can read data from files) or by capturing the input data in a file via redirection.</p></li><li class="listitem"><p>Last but not least, you need to have the C clients installed along with your own program.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idp67452944"></a>Directly talk to refdbd</h3></div></div></div><p>This is a somewhat more ambitious approach, as you have to implement the client part of the client/server dialog described <a class="link" href="ch23.html" title="Chapter 23. The RefDB client/server communication protocol">here</a>. The client/server dialog is a plain-text protocol which is fairly easy to implement in just about any language. The only tricky part is the password encryption, but that can be handed over to a little C program called <a class="link" href="re30.html" title="eenc">eenc</a> that is part of the RefDB sources. The RefDB project currently has client libraries for two languages which provide an implementation of the client part of the client/server protocol. The <a class="link" href="ch20.html" title="Chapter 20. The Perl client module">Perl client module</a> provides an object-oriented access to refdbd which you can use in your programs without having to know anything about the client/server protocol. There is also a (rudimentary and currently unmaintained) implementation in Ruby.</p><p>To give you an impression of how you can use a client library, look at the following Perl example which does approximately the same as the examples above:</p><pre class="programlisting">
use RefDBClient::Client;
# create a Client object. You can create as many as you need
my $client = new RefDBClient::Client;
# set the initial connection parameters
$client->set_conninfo("127.0.0.1", "9734", "markus", "pass", "refdbtest",
"/home/markus/literature", "/usr/local/share/refdb/css/refdb.css");
# run the whichdb command. We're not interested in the command summary,
# but read only the data proper into $data
$client->refdb_whichdb();
$data = $client->get_data();
# in order to add references from a RIS file, we first read the file contents
# into a Risdata object
my $risdata = new RefDBClient::Risdata;
$risdata->read_ris("testdata/pubmed.ris");
# now we send the data to the server. This time we read both the command
# summary (which the C clients send to stderr) into $summary and the
# data proper into $data
$summary = $clientc->refdb_addref(undef, $risdata, "ris", "ISO-8859-1");
$data = $clientc->get_data();
</pre><p>The advantages and disadvantages of using a client library are as follows:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>You get a clean, object-oriented interface</p></li><li class="listitem"><p>No fiddling with standard error or standard output</p></li><li class="listitem"><p>However, there may be no client library for your favourite language</p></li></ul></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch19.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch19.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch19s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 19. Using RefDB in your programs </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Tips and tricks</td></tr></table></div></body></html>
|