-<!-- $Id: asn.xml,v 1.5 2001-07-20 21:34:36 adam Exp $ -->
-<chapter><title>The ASN Module</title>
- <sect1><title>Introduction</title>
- <para>
- The &asn; module provides you with a set of C struct definitions for the
- various PDUs of the protocol, as well as for the complex types
- appearing within the PDUs. For the primitive data types, the C
- representation often takes the form of an ordinary C language type,
- such as <literal>int</literal>. For ASN.1 constructs that have no direct
- representation in C, such as general octet strings and bit strings,
- the &odr; module (see section <link linkend="odr">The ODR Module</link>)
- provides auxiliary definitions.
- </para>
- </sect1>
- <sect1><title>Preparing PDUs</title>
-
- <para>
- A structure representing a complex ASN.1 type doesn't in itself contain the
- members of that type. Instead, the structure contains
- <emphasis>pointers</emphasis> to the members of the type.
- This is necessary, in part, to allow a mechanism for specifying which
- of the optional structure (SEQUENCE) members are present, and which
- are not. It follows that you will need to somehow provide space for
- the individual members of the structure, and set the pointers to
- refer to the members.
- </para>
- <para>
- The conversion routines don't care how you allocate and maintain your
- C structures - they just follow the pointers that you provide.
- Depending on the complexity of your application, and your personal
- taste, there are at least three different approaches that you may take
- when you allocate the structures.
- </para>
-
- <para>
- You can use static or automatic local variables in the function that
- prepares the PDU. This is a simple approach, and it provides the most
- efficient form of memory management. While it works well for flat
- PDUs like the InitReqest, it will generally not be sufficient for say,
- the generation of an arbitrarily complex RPN query structure.
- </para>
- <para>
- You can individually create the structure and its members using the
- <function>malloc(2)</function> function. If you want to ensure that
- the data is freed when it is no longer needed, you will have to
- define a function that individually releases each member of a
- structure before freeing the structure itself.
- </para>
- <para>
- You can use the <function>odr_malloc()</function> function (see section
- <link linkend="odr-use">Using ODR</link> for details). When you use
- <function>odr_malloc()</function>, you can release all of the
- allocated data in a single operation, independent of any pointers and
- relations between the data. <function>odr_malloc()</function> is based on a
- "nibble-memory"
- scheme, in which large portions of memory are allocated, and then
- gradually handed out with each call to <function>odr_malloc()</function>.
- The next time you call <function>odr_reset()</function>, all of the
- memory allocated since the last call is recycled for future use (actually,
- it is placed on a free-list).
- </para>
- <para>
- You can combine all of the methods described here. This will often be
- the most practical approach. For instance, you might use
- <function>odr_malloc()</function> to allocate an entire structure and
- some of its elements, while you leave other elements pointing to global
- or per-session default variables.
- </para>
-
- <para>
- The &asn; module provides an important aid in creating new PDUs. For
- each of the PDU types (say, <function>Z_InitRequest</function>), a
- function is provided that allocates and initializes an instance of
- that PDU type for you. In the case of the InitRequest, the function is
- simply named <function>zget_InitRequest()</function>, and it sets up
- reasonable default value for all of the mandatory members. The optional
- members are generally initialized to null pointers. This last aspect
- is very important: it ensures that if the PDU definitions are
- extended after you finish your implementation (to accommodate
- new versions of the protocol, say), you won't get into trouble with
- uninitialized pointers in your structures. The functions use
- <function>odr_malloc()</function> to
- allocate the PDUs and its members, so you can free everything again with a
- single call to <function>odr_reset()</function>. We strongly recommend
- that you use the <literal>zget_*</literal>
- functions whenever you are preparing a PDU (in a C++ API, the
- <literal>zget_</literal>
- functions would probably be promoted to constructors for the
- individual types).
- </para>
- <para>
+<!-- $Id: asn.xml,v 1.16 2006-04-24 12:41:00 marc Exp $ -->
+ <chapter id="asn"><title>The Z39.50 ASN.1 Module</title>
+ <sect1 id="asn.introduction"><title>Introduction</title>
+ <para>
+ The &asn; module provides you with a set of C struct definitions for the
+ various PDUs of the Z39.50 protocol, as well as for the complex types
+ appearing within the PDUs. For the primitive data types, the C
+ representation often takes the form of an ordinary C language type,
+ such as <literal>int</literal>. For ASN.1 constructs that have no direct
+ representation in C, such as general octet strings and bit strings,
+ the &odr; module (see section <link linkend="odr">The ODR Module</link>)
+ provides auxiliary definitions.
+ </para>
+ <para>
+ The &asn; module is located in sub directory <filename>z39.50</filename>.
+ There you'll find C files that implements encoders and decoders for the
+ Z39.50 types. You'll also find the protocol definitions:
+ <filename>z3950v3.asn</filename>, <filename>esupdate.asn</filename>,
+ and others.
+ </para>
+ </sect1>
+ <sect1 id="asn.preparing"><title>Preparing PDUs</title>
+
+ <para>
+ A structure representing a complex ASN.1 type doesn't in itself contain the
+ members of that type. Instead, the structure contains
+ <emphasis>pointers</emphasis> to the members of the type.
+ This is necessary, in part, to allow a mechanism for specifying which
+ of the optional structure (SEQUENCE) members are present, and which
+ are not. It follows that you will need to somehow provide space for
+ the individual members of the structure, and set the pointers to
+ refer to the members.
+ </para>
+ <para>
+ The conversion routines don't care how you allocate and maintain your
+ C structures - they just follow the pointers that you provide.
+ Depending on the complexity of your application, and your personal
+ taste, there are at least three different approaches that you may take
+ when you allocate the structures.
+ </para>
+
+ <para>
+ You can use static or automatic local variables in the function that
+ prepares the PDU. This is a simple approach, and it provides the most
+ efficient form of memory management. While it works well for flat
+ PDUs like the InitReqest, it will generally not be sufficient for say,
+ the generation of an arbitrarily complex RPN query structure.
+ </para>
+ <para>
+ You can individually create the structure and its members using the
+ <function>malloc(2)</function> function. If you want to ensure that
+ the data is freed when it is no longer needed, you will have to
+ define a function that individually releases each member of a
+ structure before freeing the structure itself.
+ </para>
+ <para>
+ You can use the <function>odr_malloc()</function> function (see
+ <xref linkend="odr.use"/> for details). When you use
+ <function>odr_malloc()</function>, you can release all of the
+ allocated data in a single operation, independent of any pointers and
+ relations between the data. <function>odr_malloc()</function> is based on a
+ "nibble-memory"
+ scheme, in which large portions of memory are allocated, and then
+ gradually handed out with each call to <function>odr_malloc()</function>.
+ The next time you call <function>odr_reset()</function>, all of the
+ memory allocated since the last call is recycled for future use (actually,
+ it is placed on a free-list).
+ </para>
+ <para>
+ You can combine all of the methods described here. This will often be
+ the most practical approach. For instance, you might use
+ <function>odr_malloc()</function> to allocate an entire structure and
+ some of its elements, while you leave other elements pointing to global
+ or per-session default variables.
+ </para>
+
+ <para>
+ The &asn; module provides an important aid in creating new PDUs. For
+ each of the PDU types (say, <function>Z_InitRequest</function>), a
+ function is provided that allocates and initializes an instance of
+ that PDU type for you. In the case of the InitRequest, the function is
+ simply named <function>zget_InitRequest()</function>, and it sets up
+ reasonable default value for all of the mandatory members. The optional
+ members are generally initialized to null pointers. This last aspect
+ is very important: it ensures that if the PDU definitions are
+ extended after you finish your implementation (to accommodate
+ new versions of the protocol, say), you won't get into trouble with
+ uninitialized pointers in your structures. The functions use
+ <function>odr_malloc()</function> to
+ allocate the PDUs and its members, so you can free everything again with a
+ single call to <function>odr_reset()</function>. We strongly recommend
+ that you use the <literal>zget_*</literal>
+ functions whenever you are preparing a PDU (in a C++ API, the
+ <literal>zget_</literal>
+ functions would probably be promoted to constructors for the
+ individual types).
+ </para>
+ <para>