X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fasn.xml;h=7f6208ec74d3fec2a1b022465952338d74ca1a00;hb=c7cff6778b8d69f6e3c41dbfd939f44436911b90;hp=453e856af5bbc63be04bea23407266cf7fe05101;hpb=fe4182bf1ca7bebcb3172cde916d4467c2154e7b;p=yaz-moved-to-github.git

diff --git a/doc/asn.xml b/doc/asn.xml
index 453e856..7f6208e 100644
--- a/doc/asn.xml
+++ b/doc/asn.xml
@@ -1,9 +1,9 @@
-<!-- $Id: asn.xml,v 1.6 2001-08-08 19:33:21 adam Exp $ -->
- <chapter><title>The ASN Module</title>
-  <sect1><title>Introduction</title>
+<!-- $Id: asn.xml,v 1.19 2007-05-04 12:24:15 adam Exp $ -->
+ <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
@@ -11,8 +11,15 @@
     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><title>Preparing PDUs</title>
+  <sect1 id="asn.preparing"><title>Preparing PDUs</title>
    
    <para>
     A structure representing a complex ASN.1 type doesn't in itself contain the
@@ -47,8 +54,8 @@
     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
@@ -110,7 +117,7 @@
    <para>
    As well as the individual PDU functions, a function
     <function>zget_APDU()</function> is provided, which allocates
-    a toplevel Z-APDU of the type requested:
+    a top-level Z-APDU of the type requested:
    </para>
    
    <synopsis>
@@ -125,7 +132,16 @@
     
    </para>
   </sect1>
-  <sect1><title id="oid">Object Identifiers</title>
+  <sect1 id="asn.oid"><title>Object Identifiers (YAZ 2)</title>
+
+  <note>
+   <para>
+    This material only applies to version 2 series of YAZ. You need not
+    read this material if you are working with YAZ 3. 
+    See <xref linkend="tools.oid"/> for more information on OIDs.
+   </para>
+  </note>
+
   <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
@@ -187,7 +203,7 @@ struct oident *oid_getentbyoid(int *o);
    </note>
   
   </sect1>
-  <sect1><title>EXTERNAL Data</title>
+  <sect1 id="asn.external"><title>EXTERNAL Data</title>
    
    <para>
     In order to achieve extensibility and adaptability to different
@@ -264,7 +280,7 @@ typedef struct Z_External
    </para>
    
    <screen>
-   Z_ext_typeent *z_ext_gettypebyref(oid_value ref);
+   Z_ext_typeent *z_ext_gettypebyref(const oid *oid);
    </screen>
 
    <para>
@@ -278,7 +294,7 @@ typedef struct Z_External
    <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;
@@ -301,8 +317,8 @@ typedef struct 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>
@@ -333,18 +349,19 @@ typedef struct Z_ext_typeent
    </note>
   
   </sect1>
-  <sect1><title>PDU Contents Table</title>
+  <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"><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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-    <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
     <thead>
      <row>
       <entry>Field</entry>
@@ -372,10 +389,10 @@ typedef struct Z_ext_typeent
        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
@@ -390,12 +407,13 @@ typedef struct Z_ext_typeent
    </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 colname="field"></colspec>
-    <colspec colname="type"></colspec>
-    <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
     <thead>
       <row>
        <entry>Field</entry>
@@ -423,10 +441,10 @@ typedef struct Z_ext_typeent
 	result</entry><entry>bool_t</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
@@ -441,11 +459,12 @@ typedef struct Z_ext_typeent
     </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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-     <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
      <thead>
       <row>
        <entry>Field</entry>
@@ -503,11 +522,12 @@ typedef struct Z_ext_typeent
     </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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-     <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
      <thead>
       <row>
        <entry>Field</entry>
@@ -552,11 +572,12 @@ typedef struct Z_ext_typeent
     </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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-     <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
      <thead>
       <row>
        <entry>Field</entry>
@@ -605,11 +626,12 @@ typedef struct Z_ext_typeent
     </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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-     <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
      <thead>
       <row>
        <entry>Field</entry>
@@ -628,7 +650,7 @@ typedef struct Z_ext_typeent
 	nextResultSetPosition</entry><entry>int</entry><entry>0
        </entry></row>
       <row><entry>
-	presentStatus</entry><entry>int</entry><entry>Z_PRES_SUCCESS
+	presentStatus</entry><entry>int</entry><entry>Z_PresentStatus_success
        </entry></row>
       <row><entry>
 	records</entry><entry>Z_Records</entry><entry>NULL
@@ -640,12 +662,13 @@ typedef struct Z_ext_typeent
     </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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-     <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
      <thead>
       <row>
        <entry>Field</entry>
@@ -658,7 +681,7 @@ typedef struct Z_ext_typeent
        </entry><entry>Z_ReferenceId</entry><entry>NULL
        </entry></row>
       <row><entry>
-	deleteFunction</entry><entry>int</entry><entry>Z_DeleteRequest_list
+	deleteFunction</entry><entry>int</entry><entry>Z_DeleteResultSetRequest_list
        </entry></row>
       <row><entry>
 	num_ids</entry><entry>int</entry><entry>0
@@ -673,12 +696,13 @@ typedef struct Z_ext_typeent
     </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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-     <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
      <thead>
       <row>
        <entry>Field</entry>
@@ -718,12 +742,13 @@ typedef struct Z_ext_typeent
     </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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-     <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
      <thead>
       <row>
        <entry>Field</entry>
@@ -763,12 +788,13 @@ typedef struct Z_ext_typeent
     </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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-     <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
      <thead>
       <row>
        <entry>Field</entry>
@@ -806,12 +832,12 @@ typedef struct Z_ext_typeent
     </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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-     <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
      <thead>
       <row>
        <entry>Field</entry>
@@ -842,12 +868,12 @@ typedef struct Z_ext_typeent
     </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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-     <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
      <thead>
       <row>
        <entry>Field</entry>
@@ -882,12 +908,12 @@ typedef struct Z_ext_typeent
     </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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-     <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
      <thead>
       <row>
        <entry>Field</entry>
@@ -913,12 +939,12 @@ typedef struct Z_ext_typeent
     </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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-     <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
      <thead>
       <row>
        <entry>Field</entry>
@@ -944,12 +970,12 @@ typedef struct Z_ext_typeent
     </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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-     <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
      <thead>
       <row>
        <entry>Field</entry>
@@ -978,11 +1004,12 @@ typedef struct Z_ext_typeent
     </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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-     <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
      <thead>
       <row>
        <entry>Field</entry>
@@ -1010,11 +1037,12 @@ typedef struct Z_ext_typeent
     </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 colname="field"></colspec>
-     <colspec colname="type"></colspec>
-     <colspec colname="value"></colspec>
+     <colspec colwidth="7*" colname="field"></colspec>
+     <colspec colwidth="5*" colname="type"></colspec>
+     <colspec colwidth="7*" colname="value"></colspec>
      <thead>
       <row>
        <entry>Field</entry>
@@ -1060,7 +1088,7 @@ typedef struct Z_ext_typeent
  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:
  -->