-<!-- $Id: asn.xml,v 1.9 2001-10-24 09:27:59 adam Exp $ -->
- <chapter id="asn"><title>The ASN Module</title>
+ <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 protocol, as well as for the complex types
+ 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.
</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>
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
+ 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
</para>
</sect1>
- <sect1 id="asn.oid"><title id="oid">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>
</para>
<screen>
- Z_ext_typeent *z_ext_gettypebyref(oid_value ref);
+ Z_ext_typeent *z_ext_gettypebyref(const oid *oid);
</screen>
<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;
<literal>z_ext_gettypebyref</literal> to look for the provided
direct-reference.
If the return value is different from NULL, you can use the provided
- function to decode the BER string (see section <link linkend="odr-use">
- Using ODR</link>).
+ function to decode the BER string (see <xref linkend="odr.use"/>
+ ).
</para>
<para>
PDU, as well as their default settings.
</para>
- <table frame="top"><title>Default settings for PDU Initialize Request</title>
+ <table frame="top" id="asn.default.initialize.request">
+ <title>Default settings for PDU Initialize Request</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
<colspec colwidth="5*" colname="type"></colspec>
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
</entry></row>
<row><entry>
- implementationId</entry><entry>char*</entry><entry>"YAZ (id=81)"
+ implementationId</entry><entry>char*</entry><entry>"81"
</entry></row>
<row><entry>
- implementationName</entry><entry>char*</entry><entry>"Index Data/YAZ"
+ implementationName</entry><entry>char*</entry><entry>"YAZ"
</entry></row>
<row><entry>
implementationVersion</entry><entry>char*</entry><entry>YAZ_VERSION
</tgroup>
</table>
- <table frame="top"><title>Default settings for PDU Initialize
+ <table frame="top" id="asn.default.initialize.response">
+ <title>Default settings for PDU Initialize
Response</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
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>"YAZ (id=81)"
+ implementationId</entry><entry>char*</entry><entry>"id)"
</entry></row>
<row><entry>
- implementationName</entry><entry>char*</entry><entry>"Index Data/YAZ"
+ implementationName</entry><entry>char*</entry><entry>"YAZ"
</entry></row>
<row><entry>
implementationVersion</entry><entry>char*</entry><entry>YAZ_VERSION
</tgroup>
</table>
- <table frame="top"><title>Default settings for PDU Search Request</title>
+ <table frame="top" id="asn.default.search.request">
+ <title>Default settings for PDU Search Request</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
<colspec colwidth="5*" colname="type"></colspec>
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
</tgroup>
</table>
- <table frame="top"><title>Default settings for PDU Search Response</title>
+ <table frame="top" id="asn.default.search.response">
+ <title>Default settings for PDU Search Response</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
<colspec colwidth="5*" colname="type"></colspec>
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
</tgroup>
</table>
- <table frame="top"><title>Default settings for PDU Present Request</title>
+ <table frame="top" id="asn.default.present.request">
+ <title>Default settings for PDU Present Request</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
<colspec colwidth="5*" colname="type"></colspec>
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
</tgroup>
</table>
- <table frame="top"><title>Default settings for PDU Present Response</title>
+ <table frame="top" id="asn.default.present.response">
+ <title>Default settings for PDU Present Response</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
<colspec colwidth="5*" colname="type"></colspec>
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_PRES_SUCCESS
+ presentStatus</entry><entry>Odr_int</entry><entry>Z_PresentStatus_success
</entry></row>
<row><entry>
records</entry><entry>Z_Records</entry><entry>NULL
</tgroup>
</table>
- <table frame="top"><title>Default settings for Delete Result Set Request
+ <table frame="top" id="asn.default.delete.result.set.request">
+ <title>Default settings for Delete Result Set Request
</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
</entry><entry>Z_ReferenceId</entry><entry>NULL
</entry></row>
<row><entry>
- deleteFunction</entry><entry>int</entry><entry>Z_DeleteRequest_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
</tgroup>
</table>
- <table frame="top"><title>Default settings for Delete Result Set Response
+ <table frame="top" id="asn.default.delete.result.set.response">
+ <title>Default settings for Delete Result Set Response
</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
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
</tgroup>
</table>
- <table frame="top"><title>Default settings for Scan Request
+ <table frame="top" id="asn.default.scan.request">
+ <title>Default settings for Scan Request
</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
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
</tgroup>
</table>
- <table frame="top"><title>Default settings for Scan Response
+ <table frame="top" id="asn.default.scan.response">
+ <title>Default settings for Scan Response
</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
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
</tgroup>
</table>
- <table frame="top"><title>Default settings for Trigger Resource
- Control Request </title>
+ <table frame="top" id="asn.default.trigger.resource.control.request">
+ <title>Default settings for Trigger Resource Control Request </title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
<colspec colwidth="5*" colname="type"></colspec>
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
</tgroup>
</table>
- <table frame="top"><title>Default settings for Resource
- Control Request</title>
+ <table frame="top" id="asn.default.resource.control.request">
+ <title>Default settings for Resource Control Request</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
<colspec colwidth="5*" colname="type"></colspec>
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
</tgroup>
</table>
- <table frame="top"><title>Default settings for Resource
- Control Response</title>
+ <table frame="top" id="asn.default.resource.control.response">
+ <title>Default settings for Resource Control Response</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
<colspec colwidth="5*" colname="type"></colspec>
</tgroup>
</table>
- <table frame="top"><title>Default settings for Access
- Control Request</title>
+ <table frame="top" id="asn.default.access.control.request">
+ <title>Default settings for Access Control Request</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
<colspec colwidth="5*" colname="type"></colspec>
</tgroup>
</table>
- <table frame="top"><title>Default settings for Access
- Control Response</title>
+ <table frame="top" id="asn.default.access.control.response">
+ <title>Default settings for Access Control Response</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
<colspec colwidth="5*" colname="type"></colspec>
</tgroup>
</table>
- <table frame="top"><title>Default settings for Segment</title>
+ <table frame="top" id="asn.default.segment">
+ <title>Default settings for Segment</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
<colspec colwidth="5*" colname="type"></colspec>
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
</tgroup>
</table>
- <table frame="top"><title>Default settings for Close</title>
+ <table frame="top" id="asn.default.close">
+ <title>Default settings for Close</title>
<tgroup cols="3">
<colspec colwidth="7*" colname="field"></colspec>
<colspec colwidth="5*" colname="type"></colspec>
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
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document: "yaz.xml"
- sgml-local-catalogs: "../../docbook/docbook.cat"
+ sgml-local-catalogs: nil
sgml-namecase-general:t
End:
-->