-<!-- $Id: odr.xml,v 1.9 2003-05-20 19:55:29 adam Exp $ -->
+<!-- $Id: odr.xml,v 1.12 2004-03-19 21:12:13 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>
data you wish to decode (eg, <function>odr_integer()</function> odr
<function>z_APDU()</function>).
</para>
-
- <para>
- Examples of encoding/decoding functions:
- </para>
-
- <synopsis>
- int odr_integer(ODR o, int **p, int optional, const char *name);
-
- int z_APDU(ODR o, Z_APDU **p, int optional, const char *name);
- </synopsis>
+
+ <example><title>Encoding and decoding functions</title>
+ <synopsis>
+ int odr_integer(ODR o, int **p, int optional, const char *name);
+
+ int z_APDU(ODR o, Z_APDU **p, int optional, const char *name);
+ </synopsis>
+ </example>
<para>
If the data is absent (or doesn't match the tag corresponding to
last call to <function>odr_reset()</function> will be released.
</para>
- <para>
- The use of the double indirection can be a little confusing at first
- (its purpose will become clear later on, hopefully),
- so an example is in order. We'll encode an integer value, and
- immediately decode it again using a different stream. A useless, but
- informative operation.
- </para>
-
- <programlisting>
-
+ <example><title>Encoding and decoding of an integer</title>
+ <para>
+ The use of the double indirection can be a little confusing at first
+ (its purpose will become clear later on, hopefully),
+ so an example is in order. We'll encode an integer value, and
+ immediately decode it again using a different stream. A useless, but
+ informative operation.
+ </para>
+ <programlisting><![CDATA[
void do_nothing_useful(int value)
{
ODR encode, decode;
odr_destroy(encode);
odr_destroy(decode);
}
- </programlisting>
-
- <para>
- This looks like a lot of work, offhand. In practice, the &odr; streams
- will typically be allocated once, in the beginning of your program
- (or at the beginning of a new network session), and the encoding
- and decoding will only take place in a few, isolated places in your
- program, so the overhead is quite manageable.
- </para>
-
+]]>
+ </programlisting>
+ <para>
+ This looks like a lot of work, offhand. In practice, the &odr; streams
+ will typically be allocated once, in the beginning of your program
+ (or at the beginning of a new network session), and the encoding
+ and decoding will only take place in a few, isolated places in your
+ program, so the overhead is quite manageable.
+ </para>
+ </example>
+
</sect2>
<sect2><title>Diagnostics</title>
</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
other external forms.
</para>
+ <tip>
+ <para>
+ There is an ASN.1 tutorial available at
+ <ulink url="http://asn1.elibel.tm.fr/en/introduction/">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>.
+ </para>
+ </tip>
+
<para>
- The interface is based loosely on that of the Sun Microsystems XDR
- routines.
+ The ODR interface is based loosely on that of the Sun Microsystems
+ XDR routines.
Specifically, each function which corresponds to an ASN.1 primitive
type has a dual function. Depending on the settings of the ODR
stream which is supplied as a parameter, the function may be used
The resulting C source code is quite compact, and is a pretty
straightforward representation of the source ASN.1 specification.
</para>
-
+
<para>
In many cases, the model of the XDR functions works quite well in this
role.
</para>
<synopsis>
-int odr_integer(ODR o, int **p, int optional, const char *name);
+ int odr_integer(ODR o, int **p, int optional, const char *name);
</synopsis>
<para>
(we don't allow values that can't be contained in a C integer.)
</para>
-
+
<para>
This form is typical of the primitive &odr; functions. They are named
after the type of data that they encode or decode. They take an &odr;
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>