Ignore zoomst10

[yaz-moved-to-github.git] / doc / odr.xml

diff --git a/doc/odr.xml b/doc/odr.xml
index 3ae89c5..6a135e9 100644 (file)
--- a/doc/odr.xml
+++ b/doc/odr.xml
@@ -1,4 +1,4 @@
-<!-- $Id: odr.xml,v 1.11 2003-11-19 21:17:26 adam Exp $ -->
+<!-- $Id: odr.xml,v 1.18 2006-04-25 11:25:08 marc Exp $ -->
  <chapter id="odr"><title>The ODR Module</title>
   
   <sect1 id="odr.introduction"><title>Introduction</title>
@@ -17,15 +17,15 @@
     (<xref linkend="odr.use"/>). Only if you need to
     implement ASN.1 beyond that which has been provided, should you
     worry about the second half of the documentation
-    (section <link linkend="odr-prog">Programming with ODR</link>).
+    (<xref linkend="odr.programming"/>).
     If you use one of the higher-level interfaces, you can skip this
     section entirely.
    </para>
 
    <para>
     This is important, so we'll repeat it for emphasis: <emphasis>You do
-    not need to read section <link linkend="odr-prog">Programming with
-    ODR</link> to implement Z39.50 with &yaz;.</emphasis>
+     not need to read <xref linkend="odr.programming"/>
+     to implement Z39.50 with &yaz;.</emphasis>
    </para>
 
    <para>
@@ -355,6 +355,57 @@ void do_nothing_useful(int value)
     
    </sect2>
 
+   <sect2><title>Printing</title>
+    <para>
+     When an ODR stream is created of type <literal>ODR_PRINT</literal>
+     the ODR module will print the contents of a PDU in a readable format.
+     By default output is written to the <literal>stderr</literal> stream.
+     This behavior can be changed, however, by calling the function
+     <synopsis>
+      odr_setprint(ODR o, FILE *file);
+     </synopsis>
+     before encoders or decoders are being invoked.
+     It is also possible to direct the output to a buffer (of indeed
+     another file), by using the more generic mechanism:
+     <synopsis>
+      void odr_set_stream(ODR o, void *handle,
+                         void (*stream_write)(ODR o, void *handle, int type,
+                                              const char *buf, int len),
+                         void (*stream_close)(void *handle));
+     </synopsis>
+     Here the user provides an opaque handle and two handlers,
+     <replaceable>stream_write</replaceable> for writing,
+     and <replaceable>stream_close</replaceable> which is supposed
+     to close/free resources associated with handle. 
+     The <replaceable>stream_close</replaceable> handler is optional and
+     if NULL for the function is provided, it will not be invoked.
+     The <replaceable>stream_write</replaceable> takes the ODR handle
+     as parameter, the user defined handle, a type 
+     <literal>ODR_OCTETSTRING</literal>, <literal>ODR_VISIBLESTRING</literal>
+     which indicates the type of contents is being written.
+    </para>
+    <para>
+     Another utility useful for diagnostics (error handling) or as
+     part of the printing facilities is:
+     <synopsis>
+      const char **odr_get_element_path(ODR o);
+     </synopsis>
+     which returns a list of current elements that ODR deals with at the 
+     moment. For the returned array, say <literal>ar</literal>, 
+     <literal>ar[0]</literal> is the top level element,
+     <literal>ar[n]</literal> is the last. The last element has the
+     property that <literal>ar[n+1] == NULL</literal>.
+    </para>
+    <example>
+     <title>Element Path for record</title>
+     <para>
+      For a database record part of a PresentResponse the
+      array returned by <function>odr_get_element</function>
+      is <literal>presentResponse</literal>, <literal>databaseOrSurDiagnostics</literal>, <literal>?</literal>, <literal>record</literal>, <literal>?</literal>, <literal>databaseRecord</literal> . The question mark appears due to 
+      unnamed constructions.
+     </para>
+     </example>
+   </sect2>
    <sect2><title>Diagnostics</title>
 
     <para>
@@ -478,7 +529,7 @@ void do_nothing_useful(int value)
    </sect2>
   </sect1>
 
-  <sect1 id="odr.programming"><title id="odr-prog">Programming with ODR</title>
+  <sect1 id="odr.programming"><title>Programming with ODR</title>
 
    <para>
     The API of &odr; is designed to reflect the structure of ASN.1, rather
@@ -489,9 +540,9 @@ void do_nothing_useful(int value)
    <tip>
     <para>
      There is an ASN.1 tutorial available at
-     <ulink url="http://asn1.elibel.tm.fr/en/introduction/">this site</ulink>.
+     <ulink url="&url.asn.1.tutorial;">this site</ulink>.
      This site also has standards for ASN.1 (X.680) and BER (X.690) 
-     <ulink url="http://asn1.elibel.tm.fr/en/standards/">online</ulink>.
+     <ulink url="&url.asn.1.standards;">online</ulink>.
     </para>
    </tip>
    
@@ -704,14 +755,14 @@ int odr_oid(ODR o, Odr_oid **p, int optional, const char *name);
       The C OID representation is simply an array of integers, terminated by
       the value -1 (the <literal>Odr_oid</literal> type is synonymous with
       the <literal>int</literal> type).
-      We suggest that you use the OID database module (see section
-      <link linkend="oid">Object Identifiers</link>) to handle object identifiers
+      We suggest that you use the OID database module (see
+      <xref linkend="asn.oid"/>) to handle object identifiers
       in your application.
      </para>
 
     </sect3>
    </sect2>
-   <sect2><title id="tag-prim">Tagging Primitive Types</title>
+   <sect2 id="tag.prim"><title>Tagging Primitive Types</title>
 
     <para>
      The simplest way of tagging a type is to use the
@@ -853,9 +904,8 @@ int mySequence(ODR o, MySequence **p, int optional, const char *name)
 
     <note>
      <para>
-      See section <link linkend="tag-prim">Tagging Primitive types</link>
-      for information on how to tag the primitive types, as well as types
-      that are already defined.
+      See <xref linkend="tag.prim"/> for information on how to tag
+      the primitive types, as well as types that are already defined.
      </para>
     </note>