1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2. Preparing PDUs</title><meta name="generator" content="DocBook XSL Stylesheets V1.70.1"><link rel="start" href="index.html" title="YAZ User's Guide and Reference"><link rel="up" href="asn.html" title="Chapter 6. The Z39.50 ASN.1 Module"><link rel="prev" href="asn.html" title="Chapter 6. The Z39.50 ASN.1 Module"><link rel="next" href="asn.oid.html" title="3. Object Identifiers"></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">2. Preparing PDUs</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="asn.html">Prev</a> </td><th width="60%" align="center">Chapter 6. The Z39.50 ASN.1 Module</th><td width="20%" align="right"> <a accesskey="n" href="asn.oid.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="asn.preparing"></a>2. Preparing PDUs</h2></div></div></div><p>
2 A structure representing a complex ASN.1 type doesn't in itself contain the
3 members of that type. Instead, the structure contains
4 <span class="emphasis"><em>pointers</em></span> to the members of the type.
5 This is necessary, in part, to allow a mechanism for specifying which
6 of the optional structure (SEQUENCE) members are present, and which
7 are not. It follows that you will need to somehow provide space for
8 the individual members of the structure, and set the pointers to
11 The conversion routines don't care how you allocate and maintain your
12 C structures - they just follow the pointers that you provide.
13 Depending on the complexity of your application, and your personal
14 taste, there are at least three different approaches that you may take
15 when you allocate the structures.
17 You can use static or automatic local variables in the function that
18 prepares the PDU. This is a simple approach, and it provides the most
19 efficient form of memory management. While it works well for flat
20 PDUs like the InitReqest, it will generally not be sufficient for say,
21 the generation of an arbitrarily complex RPN query structure.
23 You can individually create the structure and its members using the
24 <code class="function">malloc(2)</code> function. If you want to ensure that
25 the data is freed when it is no longer needed, you will have to
26 define a function that individually releases each member of a
27 structure before freeing the structure itself.
29 You can use the <code class="function">odr_malloc()</code> function (see
30 <a href="odr.use.html" title="2. Using ODR">Section 2, “Using ODR”</a> for details). When you use
31 <code class="function">odr_malloc()</code>, you can release all of the
32 allocated data in a single operation, independent of any pointers and
33 relations between the data. <code class="function">odr_malloc()</code> is based on a
35 scheme, in which large portions of memory are allocated, and then
36 gradually handed out with each call to <code class="function">odr_malloc()</code>.
37 The next time you call <code class="function">odr_reset()</code>, all of the
38 memory allocated since the last call is recycled for future use (actually,
39 it is placed on a free-list).
41 You can combine all of the methods described here. This will often be
42 the most practical approach. For instance, you might use
43 <code class="function">odr_malloc()</code> to allocate an entire structure and
44 some of its elements, while you leave other elements pointing to global
45 or per-session default variables.
47 The Z39.50 ASN.1 module provides an important aid in creating new PDUs. For
48 each of the PDU types (say, <code class="function">Z_InitRequest</code>), a
49 function is provided that allocates and initializes an instance of
50 that PDU type for you. In the case of the InitRequest, the function is
51 simply named <code class="function">zget_InitRequest()</code>, and it sets up
52 reasonable default value for all of the mandatory members. The optional
53 members are generally initialized to null pointers. This last aspect
54 is very important: it ensures that if the PDU definitions are
55 extended after you finish your implementation (to accommodate
56 new versions of the protocol, say), you won't get into trouble with
57 uninitialized pointers in your structures. The functions use
58 <code class="function">odr_malloc()</code> to
59 allocate the PDUs and its members, so you can free everything again with a
60 single call to <code class="function">odr_reset()</code>. We strongly recommend
61 that you use the <code class="literal">zget_*</code>
62 functions whenever you are preparing a PDU (in a C++ API, the
63 <code class="literal">zget_</code>
64 functions would probably be promoted to constructors for the
67 The prototype for the individual PDU types generally look like this:
68 </p><pre class="synopsis">
69 Z_<type> *zget_<type>(ODR o);
72 </p><pre class="synopsis">
73 Z_InitRequest *zget_InitRequest(ODR o);
75 The <acronym class="acronym">ODR</acronym> handle should generally be your encoding stream, but it
78 As well as the individual PDU functions, a function
79 <code class="function">zget_APDU()</code> is provided, which allocates
80 a top-level Z-APDU of the type requested:
81 </p><pre class="synopsis">
82 Z_APDU *zget_APDU(ODR o, int which);
84 The <code class="varname">which</code> parameter is (of course) the discriminator
85 belonging to the <code class="varname">Z_APDU</code> <code class="literal">CHOICE</code> type.
86 All of the interface described here is provided by the Z39.50 ASN.1 module, and
87 you access it through the <code class="filename">proto.h</code> header file.
89 </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="asn.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="asn.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="asn.oid.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 6. The Z39.50 ASN.1 Module </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 3. Object Identifiers</td></tr></table></div></body></html>