Fix do_nothing_useful example

[yaz-moved-to-github.git] / doc / odr.xml

diff --git a/doc/odr.xml b/doc/odr.xml
index 38d300e..230dcd1 100644 (file)
--- a/doc/odr.xml
+++ b/doc/odr.xml
@@ -1,4 +1,3 @@
-<!-- $Id: odr.xml,v 1.19 2006-10-05 08:26:58 adam Exp $ -->
  <chapter id="odr"><title>The ODR Module</title>
   
   <sect1 id="odr.introduction"><title>Introduction</title>
@@ -105,7 +104,7 @@
     </para>
 
     <synopsis>
-     void odr_reset(ODR o, int size);
+     void odr_reset(ODR o);
     </synopsis>
 
     <para>
@@ -263,7 +262,7 @@
     <example id="example.odr.encoding.and.decoding.functions">
      <title>Encoding and decoding functions</title>
      <synopsis>
-      int odr_integer(ODR o, int **p, int optional, const char *name);
+      int odr_integer(ODR o, Odr_int **p, int optional, const char *name);
       
       int z_APDU(ODR o, Z_APDU **p, int optional, const char *name);
      </synopsis>
@@ -309,10 +308,10 @@
       informative operation.
      </para>
      <programlisting><![CDATA[
-void do_nothing_useful(int value)
+void do_nothing_useful(Odr_int value)
 {
     ODR encode, decode;
-    int *valp, *resvalp;
+    Odr_int *valp, *resvalp;
     char *bufferp;
     int len;
      
@@ -322,23 +321,24 @@ void do_nothing_useful(int value)
     if (!(decode = odr_createmem(ODR_DECODE)))
         return;
 
-    valp = &amp;value;
-    if (odr_integer(encode, &amp;valp, 0, 0) == 0)
+    valp = &value;
+    if (odr_integer(encode, &valp, 0, 0) == 0)
     {
         printf("encoding went bad\n");
         return;
     }
-    bufferp = odr_getbuf(encode, &amp;len);
-    printf("length of encoded data is &percnt;d\n", len);
+    bufferp = odr_getbuf(encode, &len, 0);
+    printf("length of encoded data is %d\n", len);
 
     /* now let's decode the thing again */
-    odr_setbuf(decode, bufferp, len);
-    if (odr_integer(decode, &amp;resvalp, 0, 0) == 0)
+    odr_setbuf(decode, bufferp, len, 0);
+    if (odr_integer(decode, &resvalp, 0, 0) == 0)
     {
         printf("decoding went bad\n");
         return;
     }
-    printf("the value is &percnt;d\n", *resvalp);
+    /* ODR_INT_PRINTF format for printf (such as %d) */
+    printf("the value is " ODR_INT_PRINTF "\n", *resvalp);
 
     /* clean up */
     odr_destroy(encode);
@@ -492,7 +492,7 @@ void do_nothing_useful(int value)
     </para>
 
     <synopsis>
-     char *odr_errlist&lsqb;&rsqb;
+     char *odr_errlist[]
     </synopsis>
 
     <para>
@@ -505,7 +505,7 @@ void do_nothing_useful(int value)
     <title>Summary and Synopsis</title>
 
     <synopsis>
-     #include &lt;odr.h>
+     #include &lt;yaz/odr.h>
 
      ODR odr_createmem(int direction);
 
@@ -513,19 +513,17 @@ void do_nothing_useful(int value)
 
      void odr_reset(ODR o);
 
-     char *odr_getbuf(ODR o, int *len);
+     char *odr_getbuf(ODR o, int *len, int *size);
 
-     void odr_setbuf(ODR o, char *buf, int len);
+     void odr_setbuf(ODR o, char *buf, int len, int can_grow);
 
      void *odr_malloc(ODR o, int size);
 
-     ODR_MEM odr_extract_mem(ODR o);
-
-     void odr_release_mem(ODR_MEM r);
+     NMEM odr_extract_mem(ODR o);
 
      int odr_geterror(ODR o);
 
-     void odr_perror(char *message);
+     void odr_perror(ODR o, const char *message);
 
      extern char *odr_errlist[];
     </synopsis>
@@ -588,11 +586,11 @@ void do_nothing_useful(int value)
      </para>
 
      <synopsis>
-      int odr_integer(ODR o, int **p, int optional, const char *name);
+      int odr_integer(ODR o, Odr_int **p, int optional, const char *name);
      </synopsis>
 
      <para>
-      (we don't allow values that can't be contained in a C integer.)
+      The <literal>Odr_int</literal> is just a simple integer.
      </para>
      
      <para>
@@ -641,7 +639,7 @@ void do_nothing_useful(int value)
     <sect3 id="odr.boolean"><title>BOOLEAN</title>
 
      <synopsis>
-int odr_bool(ODR o, bool_t **p, int optional, const char *name);
+int odr_bool(ODR o, Odr_bool **p, int optional, const char *name);
      </synopsis>
 
     </sect3>
@@ -655,7 +653,7 @@ int odr_bool(ODR o, bool_t **p, int optional, const char *name);
     <sect3 id="odr.null"><title>NULL</title>
 
      <synopsis>
-int odr_null(ODR o, bool_t **p, int optional, const char *name);
+int odr_null(ODR o, Odr_null **p, int optional, const char *name);
      </synopsis>
 
      <para>
@@ -759,9 +757,9 @@ int odr_oid(ODR o, Odr_oid **p, int optional, const char *name);
      <para>
       The C OID representation is simply an array of integers, terminated by
       the value -1 (the <literal>Odr_oid</literal> type is synonymous with
-      the <literal>int</literal> type).
+      the <literal>short</literal> type).
       We suggest that you use the OID database module (see
-      <xref linkend="asn.oid"/>) to handle object identifiers
+      <xref linkend="tools.oid.database"/>) to handle object identifiers
       in your application.
      </para>
 
@@ -789,7 +787,7 @@ int odr_explicit_tag(ODR o, Odr_fun fun, int class, int tag,
     </para>
 
     <screen>
-     MyInt ::= &lsqb;210&rsqb; IMPLICIT INTEGER
+     MyInt ::= [210] IMPLICIT INTEGER
     </screen>
 
     <para>
@@ -797,7 +795,7 @@ int odr_explicit_tag(ODR o, Odr_fun fun, int class, int tag,
     </para>
 
     <screen>
-int myInt(ODR o, int **p, int optional, const char *name)
+int myInt(ODR o, Odr_int **p, int optional, const char *name)
 {
     return odr_implicit_tag(o, odr_integer, p,
                            ODR_CONTEXT, 210, optional, name);
@@ -869,8 +867,8 @@ MySequence ::= SEQUENCE {
     <screen>
 typedef struct MySequence
 {
-    int *intval;
-    bool_t *boolval;
+    Odr_int *intval;
+    Odr_bool *boolval;
 } MySequence;
      
 int mySequence(ODR o, MySequence **p, int optional, const char *name)
@@ -923,7 +921,7 @@ int mySequence(ODR o, MySequence **p, int optional, const char *name)
      </para>
 
      <screen>
-MySequence ::= &lsqb;10&rsqb; IMPLICIT SEQUENCE {
+MySequence ::= [10] IMPLICIT SEQUENCE {
       intval INTEGER,
       boolval BOOLEAN OPTIONAL
 }
@@ -976,7 +974,7 @@ int mySequence(ODR o, MySequence **p, int optional, const char *name)
      </para>
 
      <screen>
-MySequence ::= &lsqb;10&rsqb; IMPLICIT SEQUENCE {
+MySequence ::= [10] IMPLICIT SEQUENCE {
    intval INTEGER,
    boolval BOOLEAN OPTIONAL
 }
@@ -1073,7 +1071,7 @@ MyArray ::= SEQUENCE OF INTEGER
 typedef struct MyArray
 {
     int num_elements;
-    int **elements;
+    Odr_int **elements;
 } MyArray;
     </screen>
 
@@ -1107,7 +1105,7 @@ int myArray(ODR o, MyArray **p, int optional, const char *name)
     </para>
 
     <synopsis>
-int odr_choice(ODR o, Odr_arm arm&lsqb;&rsqb;, void *p, void *whichp,
+int odr_choice(ODR o, Odr_arm arm[], void *p, void *whichp,
                const char *name);
     </synopsis>
 
@@ -1152,7 +1150,7 @@ typedef struct odr_arm
 
      <varlistentry><term>which</term>
       <listitem><para>The value of the discriminator that corresponds to
-       this CHOICE element. Typically, it will be a &num;defined constant, or
+       this CHOICE element. Typically, it will be a #defined constant, or
        an enum member.</para></listitem>
      </varlistentry>
 
@@ -1177,7 +1175,7 @@ typedef struct odr_arm
     <screen>
 MyChoice ::= CHOICE {
     untagged INTEGER,
-    tagged   &lsqb;99&rsqb; IMPLICIT INTEGER,
+    tagged   [99] IMPLICIT INTEGER,
     other    BOOLEAN
 }
     </screen>
@@ -1197,9 +1195,9 @@ typedef struct MyChoice
     } which;
     union
     {
-        int *untagged;
-        int *tagged;
-        bool_t *other;
+        Odr_int *untagged;
+        Odr_int *tagged;
+        Odr_bool *other;
     } u;
 };
     </screen>
@@ -1211,7 +1209,7 @@ typedef struct MyChoice
     <screen>
 int myChoice(ODR o, MyChoice **p, int optional, const char *name)
 {
-    static Odr_arm arm&lsqb;&rsqb; =
+    static Odr_arm arm[] =
     {
       {-1, -1, -1, MyChoice_untagged, odr_integer, "untagged"},
       {ODR_IMPLICIT, ODR_CONTEXT, 99, MyChoice_tagged, odr_integer,