X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fasn.xml;h=78ee8148a1c0ce6a43c4301eb7078ed064602757;hp=e0c70efa51992af796f1d8159237ac048a48e1fc;hb=053367cbe356fb3ce0def34b065dae589d700daf;hpb=03531ce2d54914dde2e679aa6382eb04d9e8f1d6

diff --git a/doc/asn.xml b/doc/asn.xml
index e0c70ef..78ee814 100644
--- a/doc/asn.xml
+++ b/doc/asn.xml
@@ -1,4 +1,3 @@
-<!-- $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>
@@ -6,7 +5,8 @@
     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.
@@ -15,12 +15,12 @@
     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
@@ -38,7 +38,7 @@
     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
@@ -73,7 +73,7 @@
     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
@@ -101,11 +101,11 @@
    <synopsis>
     Z_&lt;type> *zget_&lt;type>(ODR o);
    </synopsis>
-   
+
    <para>
     eg.:
    </para>
-   
+
    <synopsis>
     Z_InitRequest *zget_InitRequest(ODR o);
    </synopsis>
@@ -119,21 +119,21 @@
     <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
@@ -143,7 +143,7 @@
     specialized version of the EXTERNAL construct, called
     <literal>Z_External</literal>.It is defined thus:
    </para>
-   
+
    <screen>
 typedef struct Z_External
 {
@@ -184,7 +184,7 @@ 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
@@ -198,7 +198,7 @@ typedef struct Z_External
     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
@@ -207,7 +207,7 @@ typedef struct Z_External
     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>
@@ -219,7 +219,7 @@ typedef struct Z_External
     <literal>Z_ext_typeent</literal>
     is defined as:
    </para>
-  
+
    <screen>
 typedef struct Z_ext_typeent
 {
@@ -228,7 +228,7 @@ 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
@@ -239,7 +239,7 @@ typedef struct Z_ext_typeent
     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
@@ -249,7 +249,7 @@ typedef struct Z_ext_typeent
     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
@@ -266,7 +266,7 @@ typedef struct Z_ext_typeent
     is necessary to tell the different, structured types apart
     on decoding.
    </para>
-   
+
    <note>
     <para>
      Eventually, the EXTERNAL processing will most likely
@@ -276,15 +276,15 @@ typedef struct Z_ext_typeent
      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">
@@ -309,10 +309,10 @@ typedef struct Z_ext_typeent
        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
@@ -361,13 +361,13 @@ typedef struct Z_ext_typeent
 	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)"
@@ -406,22 +406,22 @@ typedef struct Z_ext_typeent
 	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
@@ -465,27 +465,27 @@ typedef struct Z_ext_typeent
       </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
@@ -522,13 +522,13 @@ typedef struct Z_ext_typeent
 	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
@@ -540,13 +540,13 @@ typedef struct Z_ext_typeent
 	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
@@ -554,7 +554,7 @@ typedef struct Z_ext_typeent
      </tbody>
     </tgroup>
    </table>
-   
+
    <table frame="top" id="asn.default.present.response">
     <title>Default settings for PDU Present Response</title>
     <tgroup cols="3">
@@ -573,13 +573,13 @@ typedef struct Z_ext_typeent
 	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
@@ -590,7 +590,7 @@ typedef struct Z_ext_typeent
      </tbody>
     </tgroup>
    </table>
-   
+
    <table frame="top" id="asn.default.delete.result.set.request">
     <title>Default settings for Delete Result Set Request
     </title>
@@ -610,10 +610,10 @@ typedef struct Z_ext_typeent
        </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
@@ -644,19 +644,19 @@ typedef struct Z_ext_typeent
 	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
@@ -690,7 +690,7 @@ typedef struct Z_ext_typeent
 	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
@@ -702,13 +702,13 @@ typedef struct Z_ext_typeent
 	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
@@ -732,21 +732,21 @@ typedef struct Z_ext_typeent
       </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
@@ -775,24 +775,24 @@ typedef struct Z_ext_typeent
       </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>
@@ -811,24 +811,24 @@ typedef struct Z_ext_typeent
       </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
@@ -851,7 +851,7 @@ typedef struct Z_ext_typeent
       </row>
      </thead>
      <tbody>
-      
+
       <row><entry>
 	referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
        </entry></row>
@@ -867,7 +867,7 @@ typedef struct Z_ext_typeent
      </tbody>
     </tgroup>
    </table>
-   
+
    <table frame="top" id="asn.default.access.control.request">
     <title>Default settings for Access Control Request</title>
     <tgroup cols="3">
@@ -882,7 +882,7 @@ typedef struct Z_ext_typeent
       </row>
      </thead>
      <tbody>
-      
+
       <row><entry>
 	referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
        </entry></row>
@@ -913,7 +913,7 @@ typedef struct Z_ext_typeent
       </row>
      </thead>
      <tbody>
-      
+
       <row><entry>
 	referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
        </entry></row>
@@ -947,15 +947,15 @@ typedef struct Z_ext_typeent
       </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
@@ -985,7 +985,7 @@ typedef struct Z_ext_typeent
 	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
@@ -999,7 +999,7 @@ typedef struct Z_ext_typeent
       <row><entry>
 	otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
        </entry></row>
-      
+
      </tbody>
     </tgroup>
    </table>