-<!-- $Id: asn.xml,v 1.18 2006-10-05 08:26:58 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.oid"><title>Object Identifiers</title>
- <para>
- When you refer to object identifiers in your application, you need to
- be aware that SR and Z39.50 use two different set of OIDs to refer to
- the same objects. To handle this easily, &yaz; provides a utility module
- to &asn; which provides an internal representation of the OIDs used in
- both protocols. Each oid is described by a structure:
- </para>
-
- <screen>
-typedef struct oident
-{
- enum oid_proto proto;
- enum oid_class class;
- enum oid_value value;
- int oidsuffix[OID_SIZE];
- char *desc;
-} oident;
- </screen>
-
- <para>
- The <literal>proto</literal> field can be set to either
- <literal>PROTO_SR</literal> or <literal>PROTO_Z3950</literal>.
- The <literal>class</literal> might be, say,
- <literal>CLASS_RECSYN</literal>, and the <literal>value</literal> might be
- <literal>VAL_USMARC</literal> for the USMARC record format. Functions
- </para>
-
- <screen>
-int *oid_ent_to_oid(struct oident *ent, int *dst);
-struct oident *oid_getentbyoid(int *o);
- </screen>
-
- <para>
- are provided to map between object identifiers and database entries.
- If you store a member of the <literal>oid_proto</literal> type in
- your association state information, it's a simple matter, at runtime,
- to generate the correct OID when you need it. For decoding, you can
- simply ignore the proto field, or if you're strict, you can verify
- that your peer is using the OID family from the correct protocol.
- The <literal>desc</literal> field is a short, human-readable name
- for the PDU, useful mainly for diagnostic output.
+
</para>
-
- <note>
- <para>
- The old function <function>oid_getoidbyent</function> still exists but
- is not thread safe. Use <function>oid_ent_to_oid</function> instead
- and pass an array of size <literal>OID_SIZE</literal>.
- </para>
- </note>
-
- <note>
- <para>
- Plans are underway to merge the two protocols into a single
- definition, with one set of object identifiers. When this happens, the
- oid module will no longer be required to support protocol
- independence, but it should still be useful as a simple OID database.
- </para>
- </note>
-
</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(oid_value ref);
+ Z_ext_typeent *z_ext_gettypebyref(const oid *oid);
</screen>
<para>
<literal>Z_ext_typeent</literal>
is defined as:
</para>
-
+
<screen>
typedef struct Z_ext_typeent
{
- oid_value dref; /* the direct-reference OID value. */
+ int oid[OID_SIZE]; /* the direct-reference OID. */
int what; /* discriminator value for the external CHOICE */
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