-<!-- $Id: odr.xml,v 1.10 2003-11-03 10:45:05 adam Exp $ -->
+<!-- $Id: odr.xml,v 1.14 2004-08-13 07:30:06 adam Exp $ -->
<chapter id="odr"><title>The ODR Module</title>
<sect1 id="odr.introduction"><title>Introduction</title>
<para>
If you are only interested in writing a Z39.50 implementation based on
the PDUs that are already provided with &yaz;, you only need to concern
- yourself with the section on managing ODR streams (section
- <link linkend="odr-use">Using ODR</link>). Only if you need to
+ yourself with the section on managing ODR streams
+ (<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>
</para>
</sect1>
- <sect1 id="odr.use"><title id="odr-use">Using ODR</title>
+ <sect1 id="odr.use"><title>Using ODR</title>
<sect2><title>ODR Streams</title>
</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>
</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
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
<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>