-<!-- $Id: asn.xml,v 1.20 2007-10-16 10:45:53 adam Exp $ -->
<chapter id="asn"><title>The Z39.50 ASN.1 Module</title>
<sect1 id="asn.introduction"><title>Introduction</title>
<para>
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
+ such as <literal>Odr_int</literal> which is equivalent to an integral
+ C integer. 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.
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>,
+ <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
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
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
<synopsis>
Z_<type> *zget_<type>(ODR o);
</synopsis>
-
+
<para>
eg.:
</para>
-
+
<synopsis>
Z_InitRequest *zget_InitRequest(ODR o);
</synopsis>
<function>zget_APDU()</function> is provided, which allocates
a top-level Z-APDU of the type requested:
</para>
-
+
<synopsis>
Z_APDU *zget_APDU(ODR o, int which);
</synopsis>
-
+
<para>
The <varname>which</varname> parameter is (of course) the discriminator
belonging to the <varname>Z_APDU</varname> <literal>CHOICE</literal> type.
All of the interface described here is provided by the &asn; module, and
you access it through the <filename>proto.h</filename> header file.
-
+
</para>
</sect1>
<sect1 id="asn.external"><title>EXTERNAL Data</title>
-
+
<para>
In order to achieve extensibility and adaptability to different
application domains, the new version of the protocol defines many
specialized version of the EXTERNAL construct, called
<literal>Z_External</literal>.It is defined thus:
</para>
-
+
<screen>
typedef struct Z_External
{
} u;
} Z_External;
</screen>
-
+
<para>
When decoding, the &asn; module will attempt to determine which
syntax describes the data by looking at the reference fields
For non-ASN.1 data such as MARC records, use the
<literal>octet_aligned</literal> arm of the union.
</para>
-
+
<para>
Some servers return ASN.1 structured data values (eg. database
records) as BER-encoded records placed in the
these records. To help you decode the records in the application, the
function
</para>
-
+
<screen>
Z_ext_typeent *z_ext_gettypebyref(const oid *oid);
</screen>
<literal>Z_ext_typeent</literal>
is defined as:
</para>
-
+
<screen>
typedef struct Z_ext_typeent
{
Odr_fun fun; /* decoder function */
} Z_ext_typeent;
</screen>
-
+
<para>
The <literal>what</literal> member contains the
<literal>Z_External</literal> union discriminator value for the
record syntax, the value of <literal>fun</literal> would be
<literal>z_SUTRS</literal> (a function pointer).
</para>
-
+
<para>
If you receive an EXTERNAL which contains an octet-string value that
you suspect of being an ASN.1-structured data value, you can use
function to decode the BER string (see <xref linkend="odr.use"/>
).
</para>
-
+
<para>
If you want to <emphasis>send</emphasis> EXTERNALs containing
ASN.1-structured values in the occtet-aligned branch of the CHOICE, this
is necessary to tell the different, structured types apart
on decoding.
</para>
-
+
<note>
<para>
Eventually, the EXTERNAL processing will most likely
various modules.
</para>
</note>
-
+
</sect1>
<sect1 id="asn.pdu"><title>PDU Contents Table</title>
-
+
<para>
We include, for reference, a listing of the fields of each top-level
PDU, as well as their default settings.
</para>
-
+
<table frame="top" id="asn.default.initialize.request">
<title>Default settings for PDU Initialize Request</title>
<tgroup cols="3">
options</entry><entry>Odr_bitmask</entry><entry>Empty bitmask
</entry></row>
<row><entry>
- preferredMessageSize</entry><entry>int</entry><entry>30*1024
+ preferredMessageSize</entry><entry>Odr_int</entry><entry>30*1024
</entry></row>
<row><entry>
- maximumRecordSize</entry><entry>int</entry><entry>30*1024
+ maximumRecordSize</entry><entry>Odr_int</entry><entry>30*1024
</entry></row>
<row><entry>
idAuthentication</entry><entry>Z_IdAuthentication</entry><entry>NULL
options</entry><entry>Odr_bitmask</entry><entry>Empty bitmask
</entry></row>
<row><entry>
- preferredMessageSize</entry><entry>int</entry><entry>30*1024
+ preferredMessageSize</entry><entry>Odr_int</entry><entry>30*1024
</entry></row>
<row><entry>
- maximumRecordSize</entry><entry>int</entry><entry>30*1024
+ maximumRecordSize</entry><entry>Odr_int</entry><entry>30*1024
</entry></row>
<row><entry>
- result</entry><entry>bool_t</entry><entry>TRUE
+ result</entry><entry>Odr_bool</entry><entry>TRUE
</entry></row>
<row><entry>
implementationId</entry><entry>char*</entry><entry>"id)"
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
<row><entry>
- smallSetUpperBound</entry><entry>int</entry><entry>0
+ smallSetUpperBound</entry><entry>Odr_int</entry><entry>0
</entry></row>
<row><entry>
- largeSetLowerBound</entry><entry>int</entry><entry>1
+ largeSetLowerBound</entry><entry>Odr_int</entry><entry>1
</entry></row>
<row><entry>
- mediumSetPresentNumber</entry><entry>int</entry><entry>0
+ mediumSetPresentNumber</entry><entry>Odr_int</entry><entry>0
</entry></row>
<row><entry>
- replaceIndicator</entry><entry>bool_t</entry><entry>TRUE
+ replaceIndicator</entry><entry>Odr_bool</entry><entry>TRUE
</entry></row>
<row><entry>
resultSetName</entry><entry>char *</entry><entry>"default"
</entry></row>
<row><entry>
- num_databaseNames</entry><entry>int</entry><entry>0
+ num_databaseNames</entry><entry>Odr_int</entry><entry>0
</entry></row>
<row><entry>
databaseNames</entry><entry>char **</entry><entry>NULL
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
<row><entry>
- resultCount</entry><entry>int</entry><entry>0
+ resultCount</entry><entry>Odr_int</entry><entry>0
</entry></row>
<row><entry>
- numberOfRecordsReturned</entry><entry>int</entry><entry>0
+ numberOfRecordsReturned</entry><entry>Odr_int</entry><entry>0
</entry></row>
<row><entry>
- nextResultSetPosition</entry><entry>int</entry><entry>0
+ nextResultSetPosition</entry><entry>Odr_int</entry><entry>0
</entry></row>
<row><entry>
- searchStatus</entry><entry>bool_t</entry><entry>TRUE
+ searchStatus</entry><entry>Odr_bool</entry><entry>TRUE
</entry></row>
<row><entry>
- resultSetStatus</entry><entry>int</entry><entry>NULL
+ resultSetStatus</entry><entry>Odr_int</entry><entry>NULL
</entry></row>
<row><entry>
- presentStatus</entry><entry>int</entry><entry>NULL
+ presentStatus</entry><entry>Odr_int</entry><entry>NULL
</entry></row>
<row><entry>
records</entry><entry>Z_Records</entry><entry>NULL
resultSetId</entry><entry>char*</entry><entry>"default"
</entry></row>
<row><entry>
- resultSetStartPoint</entry><entry>int</entry><entry>1
+ resultSetStartPoint</entry><entry>Odr_int</entry><entry>1
</entry></row>
<row><entry>
- numberOfRecordsRequested</entry><entry>int</entry><entry>10
+ numberOfRecordsRequested</entry><entry>Odr_int</entry><entry>10
</entry></row>
<row><entry>
- num_ranges</entry><entry>int</entry><entry>0
+ num_ranges</entry><entry>Odr_int</entry><entry>0
</entry></row>
<row><entry>
additionalRanges</entry><entry>Z_Range</entry><entry>NULL
preferredRecordSyntax</entry><entry>Odr_oid</entry><entry>NULL
</entry></row>
<row><entry>
- maxSegmentCount</entry><entry>int</entry><entry>NULL
+ maxSegmentCount</entry><entry>Odr_int</entry><entry>NULL
</entry></row>
<row><entry>
- maxRecordSize</entry><entry>int</entry><entry>NULL
+ maxRecordSize</entry><entry>Odr_int</entry><entry>NULL
</entry></row>
<row><entry>
- maxSegmentSize</entry><entry>int</entry><entry>NULL
+ maxSegmentSize</entry><entry>Odr_int</entry><entry>NULL
</entry></row>
<row><entry>
otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
</tbody>
</tgroup>
</table>
-
+
<table frame="top" id="asn.default.present.response">
<title>Default settings for PDU Present Response</title>
<tgroup cols="3">
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
<row><entry>
- numberOfRecordsReturned</entry><entry>int</entry><entry>0
+ numberOfRecordsReturned</entry><entry>Odr_int</entry><entry>0
</entry></row>
<row><entry>
- nextResultSetPosition</entry><entry>int</entry><entry>0
+ nextResultSetPosition</entry><entry>Odr_int</entry><entry>0
</entry></row>
<row><entry>
- presentStatus</entry><entry>int</entry><entry>Z_PresentStatus_success
+ presentStatus</entry><entry>Odr_int</entry><entry>Z_PresentStatus_success
</entry></row>
<row><entry>
records</entry><entry>Z_Records</entry><entry>NULL
</tbody>
</tgroup>
</table>
-
+
<table frame="top" id="asn.default.delete.result.set.request">
<title>Default settings for Delete Result Set Request
</title>
</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
<row><entry>
- deleteFunction</entry><entry>int</entry><entry>Z_DeleteResultSetRequest_list
+ deleteFunction</entry><entry>Odr_int</entry><entry>Z_DeleteResultSetRequest_list
</entry></row>
<row><entry>
- num_ids</entry><entry>int</entry><entry>0
+ num_ids</entry><entry>Odr_int</entry><entry>0
</entry></row>
<row><entry>
resultSetList</entry><entry>char**</entry><entry>NULL
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
<row><entry>
- deleteOperationStatus</entry><entry>int</entry>
+ deleteOperationStatus</entry><entry>Odr_int</entry>
<entry>Z_DeleteStatus_success</entry></row>
<row><entry>
- num_statuses</entry><entry>int</entry><entry>0
+ num_statuses</entry><entry>Odr_int</entry><entry>0
</entry></row>
<row><entry>
deleteListStatuses</entry><entry>Z_ListStatus**</entry><entry>NULL
</entry></row>
<row><entry>
- numberNotDeleted</entry><entry>int</entry><entry>NULL
+ numberNotDeleted</entry><entry>Odr_int</entry><entry>NULL
</entry></row>
<row><entry>
- num_bulkStatuses</entry><entry>int</entry><entry>0
+ num_bulkStatuses</entry><entry>Odr_int</entry><entry>0
</entry></row>
<row><entry>
bulkStatuses</entry><entry>Z_ListStatus</entry><entry>NUL
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
<row><entry>
- num_databaseNames</entry><entry>int</entry><entry>0
+ num_databaseNames</entry><entry>Odr_int</entry><entry>0
</entry></row>
<row><entry>
databaseNames</entry><entry>char**</entry><entry>NULL
termListAndStartPoint</entry><entry>Z_AttributesPlus...
</entry><entry>NULL</entry></row>
<row><entry>
- stepSize</entry><entry>int</entry><entry>NULL
+ stepSize</entry><entry>Odr_int</entry><entry>NULL
</entry></row>
<row><entry>
- numberOfTermsRequested</entry><entry>int</entry><entry>20
+ numberOfTermsRequested</entry><entry>Odr_int</entry><entry>20
</entry></row>
<row><entry>
- preferredPositionInResponse</entry><entry>int</entry><entry>NULL
+ preferredPositionInResponse</entry><entry>Odr_int</entry><entry>NULL
</entry></row>
<row><entry>
otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
<row><entry>
- stepSize</entry><entry>int</entry><entry>NULL
+ stepSize</entry><entry>Odr_int</entry><entry>NULL
</entry></row>
<row><entry>
- scanStatus</entry><entry>int</entry><entry>Z_Scan_success
+ scanStatus</entry><entry>Odr_int</entry><entry>Z_Scan_success
</entry></row>
<row><entry>
- numberOfEntriesReturned</entry><entry>int</entry><entry>0
+ numberOfEntriesReturned</entry><entry>Odr_int</entry><entry>0
</entry></row>
<row><entry>
- positionOfTerm</entry><entry>int</entry><entry>NULL
+ positionOfTerm</entry><entry>Odr_int</entry><entry>NULL
</entry></row>
<row><entry>
entries</entry><entry>Z_ListEntris</entry><entry>NULL
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
<row><entry>
- requestedAction</entry><entry>int</entry><entry>
+ requestedAction</entry><entry>Odr_int</entry><entry>
Z_TriggerResourceCtrl_resou..
</entry></row>
<row><entry>
prefResourceReportFormat</entry><entry>Odr_oid</entry><entry>NULL
</entry></row>
<row><entry>
- resultSetWanted</entry><entry>bool_t</entry><entry>NULL
+ resultSetWanted</entry><entry>Odr_bool</entry><entry>NULL
</entry></row>
<row><entry>
otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
</entry></row>
-
+
</tbody>
</tgroup>
</table>
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
<row><entry>
- suspendedFlag</entry><entry>bool_t</entry><entry>NULL
+ suspendedFlag</entry><entry>Odr_bool</entry><entry>NULL
</entry></row>
<row><entry>
resourceReport</entry><entry>Z_External</entry><entry>NULL
</entry></row>
<row><entry>
- partialResultsAvailable</entry><entry>int</entry><entry>NULL
+ partialResultsAvailable</entry><entry>Odr_int</entry><entry>NULL
</entry></row>
<row><entry>
- responseRequired</entry><entry>bool_t</entry><entry>FALSE
+ responseRequired</entry><entry>Odr_bool</entry><entry>FALSE
</entry></row>
<row><entry>
- triggeredRequestFlag</entry><entry>bool_t</entry><entry>NULL
+ triggeredRequestFlag</entry><entry>Odr_bool</entry><entry>NULL
</entry></row>
<row><entry>
otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
</tbody>
</tgroup>
</table>
-
+
<table frame="top" id="asn.default.access.control.request">
<title>Default settings for Access Control Request</title>
<tgroup cols="3">
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
</row>
</thead>
<tbody>
-
+
<row><entry>
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
<row><entry>
- numberOfRecordsReturned</entry><entry>int</entry><entry>value=0
+ numberOfRecordsReturned</entry><entry>Odr_int</entry><entry>value=0
</entry></row>
<row><entry>
- num_segmentRecords</entry><entry>int</entry><entry>0
+ num_segmentRecords</entry><entry>Odr_int</entry><entry>0
</entry></row>
<row><entry>
segmentRecords</entry><entry>Z_NamePlusRecord</entry><entry>NULL
referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
<row><entry>
- closeReason</entry><entry>int</entry><entry>Z_Close_finished
+ closeReason</entry><entry>Odr_int</entry><entry>Z_Close_finished
</entry></row>
<row><entry>
diagnosticInformation</entry><entry>char*</entry><entry>NULL
<row><entry>
otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
</entry></row>
-
+
</tbody>
</tgroup>
</table>
projects / yaz-moved-to-github.git / blobdiff