Preparing PDUs

A structure representing a complex ASN.1 type doesn't in itself contain the members of that type. Instead, the structure contains pointers 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.

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.

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.

You can individually create the structure and its members using the malloc(2) 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.

You can use the odr_malloc() function (see section Using ODR for details). When you use odr_malloc(), you can release all of the allocated data in a single operation, independent of any pointers and relations between the data. odr_malloc() is based on a "nibble-memory" scheme, in which large portions of memory are allocated, and then gradually handed out with each call to odr_malloc(). The next time you call odr_reset(), all of the memory allocated since the last call is recycled for future use (actually, it is placed on a free-list).

You can combine all of the methods described here. This will often be the most practical approach. For instance, you might use odr_malloc() to allocate an entire structure and some of its elements, while you leave other elements pointing to global or per-session default variables.

The Z39.50 ASN.1 module provides an important aid in creating new PDUs. For each of the PDU types (say, Z_InitRequest), 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 zget_InitRequest(), 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 odr_malloc() to allocate the PDUs and its members, so you can free everything again with a single call to odr_reset(). We strongly recommend that you use the zget_* functions whenever you are preparing a PDU (in a C++ API, the zget_ functions would probably be promoted to constructors for the individual types).

The prototype for the individual PDU types generally look like this:

    Z_<type> *zget_<type>(ODR o);
   

eg.:

    Z_InitRequest *zget_InitRequest(ODR o);
   

The ODR handle should generally be your encoding stream, but it needn't be.

As well as the individual PDU functions, a function zget_APDU() is provided, which allocates a top-level Z-APDU of the type requested:

    Z_APDU *zget_APDU(ODR o, int which);
   

The which parameter is (of course) the discriminator belonging to the Z_APDU CHOICE type. All of the interface described here is provided by the Z39.50 ASN.1 module, and you access it through the proto.h header file.