dependencies/yaz_3.0.14/doc/zoom.extendedservices.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>6. Extended Services</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="YAZ User's Guide and Reference"><link rel="up" href="zoom.html" title="Chapter 3. ZOOM"><link rel="prev" href="zoom.scan.html" title="5. Scan"><link rel="next" href="zoom.options.html" title="7. Options"></head><body><link rel="stylesheet" type="text/css" href="common/style1.css"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">6. Extended Services</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="zoom.scan.html">Prev</a> </td><th width="60%" align="center">Chapter 3. ZOOM</th><td width="20%" align="right"> <a accesskey="n" href="zoom.options.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="zoom.extendedservices"></a>6. Extended Services</h2></div></div></div><p>
   2     ZOOM offers an interface to a subset of the Z39.50 extended services
   3     as well as a few privately defined ones:
   4    </p><div class="itemizedlist"><ul type="disc"><li><p>
   5       Z39.50 Item Order (ILL).
   6       See <a class="xref" href="zoom.extendedservices.html#zoom.item.order" title="6.1. Item Order">Section 6.1, &#8220;Item Order&#8221;</a>.
   7      </p></li><li><p>
   8       Record Update. This allows a client to insert, modify or delete
   9       records.
  10       See <a class="xref" href="zoom.extendedservices.html#zoom.record.update" title="6.2. Record Update">Section 6.2, &#8220;Record Update&#8221;</a>.
  11      </p></li><li><p>
  12       Database Create. This a non-standard feature. Allows a client
  13       to create a database.
  14       See <a class="xref" href="zoom.extendedservices.html#zoom.database.create" title="6.3. Database Create">Section 6.3, &#8220;Database Create&#8221;</a>.
  15      </p></li><li><p>
  16       Database Drop. This a non-standard feature. Allows a client
  17       to delete/drop a database.
  18       See <a class="xref" href="zoom.extendedservices.html#zoom.database.drop" title="6.4. Database Drop">Section 6.4, &#8220;Database Drop&#8221;</a>.
  19      </p></li><li><p>
  20       Commit operation. This a non-standard feature. Allows a client
  21       to commit operations.
  22       See <a class="xref" href="zoom.extendedservices.html#zoom.commit" title="6.5. Commit Operation">Section 6.5, &#8220;Commit Operation&#8221;</a>.
  23      </p></li></ul></div><p>
  24     To create an extended service operation a <code class="literal">ZOOM_package</code>
  25     must be created. The operation is a five step operation. The
  26     package is created, package is configured by means of options,
  27     the package is send, result is inspected (by means of options),
  28     the package is destroyed.
  29    </p><pre class="synopsis">
  30     ZOOM_package ZOOM_connection_package(ZOOM_connection c,
  31                                          ZOOM_options options);
  32
  33     const char *ZOOM_package_option_get(ZOOM_package p,
  34                                         const char *key);
  35     void ZOOM_package_option_set(ZOOM_package p, const char *key,
  36                                  const char *val);
  37     void ZOOM_package_send(ZOOM_package p, const char *type);
  38
  39     void ZOOM_package_destroy(ZOOM_package p);
  40    </pre><p>
  41     The <code class="function">ZOOM_connection_package</code> creates a
  42     package for the connection given using the options specified.
  43    </p><p>
  44     Functions <code class="function">ZOOM_package_option_get</code> and
  45     <code class="function">ZOOM_package_option_set</code> gets and sets
  46     options.
  47    </p><p>
  48     <code class="function">ZOOM_package_send</code> sends
  49     the package the via connection specified in
  50     <code class="function">ZOOM_connection_package</code>.
  51     The <em class="parameter"><code>type</code></em> specifies the actual extended service
  52     package type to be sent.
  53    </p><div class="table"><a name="zoom.extendedservices.options"></a><p class="title"><b>Table 3.5. Extended Service Common Options</b></p><div class="table-contents"><table summary="Extended Service Common Options" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Option</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td>package-name</td><td>Extended Service Request package name. Must be specified
  54        as part of a request</td><td>none</td></tr><tr><td>user-id</td><td>User ID of Extended Service Package. Is a request option</td><td>none</td></tr><tr><td>function</td><td>
  55         Function of package - one of <code class="literal">create</code>,
  56         <code class="literal">delete</code>, <code class="literal">modify</code>. Is
  57         a request option.
  58        </td><td><code class="literal">create</code></td></tr><tr><td>waitAction</td><td>
  59         Wait action for package. Possible values:
  60         <code class="literal">wait</code>, <code class="literal">waitIfPossible</code>,
  61         <code class="literal">dontWait</code> or <code class="literal">dontReturnPackage</code>.
  62        </td><td><code class="literal">waitIfPossible</code></td></tr><tr><td>targetReference</td><td>
  63         Target Reference. This is part of the response as returned
  64         by the server. Read it after a successful operation.
  65        </td><td><code class="literal">none</code></td></tr></tbody></table></div></div><br class="table-break"><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="zoom.item.order"></a>6.1. Item Order</h3></div></div></div><p>
  66      For Item Order, type must be set to <code class="literal">itemorder</code> in
  67      <code class="function">ZOOM_package_send</code>.
  68     </p><div class="table"><a name="zoom.item.order.options"></a><p class="title"><b>Table 3.6. Item Order Options</b></p><div class="table-contents"><table summary="Item Order Options" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Option</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td>contact-name</td><td>ILL contact name</td><td>none</td></tr><tr><td>contact-phone</td><td>ILL contact phone</td><td>none</td></tr><tr><td>contact-email</td><td>ILL contact email</td><td>none</td></tr><tr><td>itemorder-item</td><td>Position for item (record) requested. An integer</td><td>1</td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="zoom.record.update"></a>6.2. Record Update</h3></div></div></div><p>
  69      For Record Update, type must be set to <code class="literal">update</code> in
  70      <code class="function">ZOOM_package_send</code>.
  71     </p><div class="table"><a name="zoom.record.update.options"></a><p class="title"><b>Table 3.7. Record Update Options</b></p><div class="table-contents"><table summary="Record Update Options" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Option</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td>action</td><td>
  72          The update action. One of
  73          <code class="literal">specialUpdate</code>,
  74          <code class="literal">recordInsert</code>,
  75          <code class="literal">recordReplace</code>,
  76          <code class="literal">recordDelete</code>,
  77          <code class="literal">elementUpdate</code>.
  78         </td><td><code class="literal">specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate)</code></td></tr><tr><td>recordIdOpaque</td><td>Opaque Record ID</td><td>none</td></tr><tr><td>recordIdNumber</td><td>Record ID number</td><td>none</td></tr><tr><td>record</td><td>The record itself</td><td>none</td></tr><tr><td>syntax</td><td>The record syntax (transfer syntax). Is a string that
  79          is a known record syntax.
  80         </td><td>no syntax</td></tr><tr><td>databaseName</td><td>Database from connection object</td><td>Default</td></tr><tr><td>correlationInfo.note</td><td>Correlation Info Note (string)</td><td>none</td></tr><tr><td>correlationInfo.id</td><td>Correlation Info ID (integer)</td><td>none</td></tr><tr><td>elementSetName</td><td>Element Set for Record</td><td>none</td></tr><tr><td>updateVersion</td><td>Record Update version which holds one of the values
  81          1, 2 or 3. Each version has a distinct OID:
  82          1.2.840.10003.9.5
  83          (<a class="ulink" href="http://www.loc.gov/z3950/agency/markup/18.html#auxiliaryStatus4" target="_top">first version</a>) ,
  84          1.2.840.10003.9.5.1
  85          (second version) and
  86          1.2.840.10003.9.5.1.1
  87          (<a class="ulink" href="http://www.loc.gov/z3950/agency/defns/update-es-rev1.html" target="_top">third and
  88           newest version</a>).
  89         </td><td>3</td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="zoom.database.create"></a>6.3. Database Create</h3></div></div></div><p>
  90      For Database Create, type must be set to <code class="literal">create</code> in
  91      <code class="function">ZOOM_package_send</code>.
  92     </p><div class="table"><a name="zoom.database.create.options"></a><p class="title"><b>Table 3.8. Database Create Options</b></p><div class="table-contents"><table summary="Database Create Options" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Option</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td>databaseName</td><td>Database from connection object</td><td>Default</td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="zoom.database.drop"></a>6.4. Database Drop</h3></div></div></div><p>
  93      For Database Drop, type must be set to <code class="literal">drop</code> in
  94      <code class="function">ZOOM_package_send</code>.
  95     </p><div class="table"><a name="zoom.database.drop.options"></a><p class="title"><b>Table 3.9. Database Drop Options</b></p><div class="table-contents"><table summary="Database Drop Options" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Option</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td>databaseName</td><td>Database from connection object</td><td>Default</td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="zoom.commit"></a>6.5. Commit Operation</h3></div></div></div><p>
  96      For Commit, type must be set to <code class="literal">commit</code> in
  97      <code class="function">ZOOM_package_send</code>.
  98     </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="zoom.extended.services.behavior"></a>6.6. Protocol behavior</h3></div></div></div><p>
  99      All the extended services are Z39.50-only.
 100     </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
 101       The database create, drop and commit services are privately defined
 102       operations.
 103       Refer to <code class="filename">esadmin.asn</code> in YAZ for the ASN.1
 104       definitions.
 105      </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="zoom.scan.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="zoom.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="zoom.options.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5. Scan </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 7. Options</td></tr></table></div></body></html>