doc/yaz-asncomp-man.xml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
   2  "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
   3 [
   4 ]>
   5 <refentry id="yaz-asncomp">
   6
   7  <refmeta>
   8   <refentrytitle>yaz-asncomp</refentrytitle>
   9   <manvolnum>1</manvolnum>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>yaz-asncomp</refname>
  14   <refpurpose>YAZ ASN.1 compiler</refpurpose>
  15  </refnamediv>
  16
  17  <refsynopsisdiv>
  18   <cmdsynopsis>
  19    <command>yaz-asncomp</command>
  20    <arg choice="opt"><option>-v</option></arg>
  21    <arg choice="opt"><option>-c <replaceable>cfile</replaceable></option></arg>
  22    <arg choice="opt"><option>-h <replaceable>hfile</replaceable></option></arg>
  23    <arg choice="opt"><option>-p <replaceable>pfile</replaceable></option></arg>
  24    <arg choice="opt"><option>-d <replaceable>config</replaceable></option></arg>
  25    <arg choice="opt"><option>-I <replaceable>includeout</replaceable></option></arg>
  26    <arg choice="opt"><option>-i <replaceable>includedir</replaceable></option></arg>
  27    <arg choice="opt"><option>-m <replaceable>module</replaceable></option></arg>
  28    <arg choice="opt">filename</arg>
  29   </cmdsynopsis>
  30
  31  </refsynopsisdiv>
  32   <refsect1><title>DESCRIPTION</title>
  33   <para>
  34    <command>yaz-asncomp</command> is an ASN.1 compiler that
  35    reads an ASN.1 specification in <replaceable>filename</replaceable>
  36    and produces C/C++ definitions and BER encoders/decoders for it.
  37   </para>
  38   <para>
  39    The produced C/C++ code and header files uses the ODR module of YAZ
  40    which is a library that encodes/decodes/prints BER packages.
  41    <command>yaz-asncomp</command> allows you to specify name of
  42    resulting source via options. Alternatively, you can specify
  43    a DEFINISIONS file, which provides customized output to
  44    many output files - if the ASN.1 specification file consists
  45    of many modules.
  46   </para>
  47   <para>
  48    This utility is written in Tcl. Any version of Tcl should work.
  49   </para>
  50   </refsect1>
  51     <refsect1>
  52   <title>OPTIONS</title>
  53   <variablelist>
  54    <varlistentry><term><literal>-v </literal>
  55  </term>
  56     <listitem>
  57      <para>
  58       Makes the ASN.1 compiler print more verbose about the
  59       various stages of operations.
  60      </para>
  61     </listitem>
  62    </varlistentry>
  63
  64    <varlistentry><term><literal>-c </literal>
  65      <replaceable>cfile</replaceable></term>
  66     <listitem><para>
  67       Specifies the name of the C/C++ file with encoders/decoders.
  68      </para></listitem>
  69    </varlistentry>
  70
  71    <varlistentry><term><literal>-h </literal>
  72      <replaceable>hfile</replaceable></term>
  73     <listitem><para>
  74       Specifies the name of header file with definitions.
  75      </para></listitem>
  76    </varlistentry>
  77
  78    <varlistentry><term><literal>-p </literal>
  79      <replaceable>pfile</replaceable></term>
  80     <listitem><para>
  81       Specifies the name of the a private header file with
  82       definitions. By default all definitions are put
  83       in header file (option -h).
  84      </para></listitem>
  85    </varlistentry>
  86
  87    <varlistentry><term><literal>-d </literal>
  88      <replaceable>dfile</replaceable></term>
  89     <listitem><para>
  90       Specifies the name of a definitions file.
  91      </para></listitem>
  92    </varlistentry>
  93
  94    <varlistentry><term><literal>-I </literal>
  95      <replaceable>iout</replaceable></term>
  96     <listitem><para>
  97       Specifies first part of directory in which header files
  98       are written.
  99      </para></listitem>
 100    </varlistentry>
 101
 102    <varlistentry><term><literal>-i </literal>
 103      <replaceable>idir</replaceable></term>
 104     <listitem><para>
 105       Specifies second part of directory in which header files
 106       are written.
 107      </para></listitem>
 108    </varlistentry>
 109
 110    <varlistentry><term><literal>-m </literal>
 111      <replaceable>module</replaceable></term>
 112     <listitem><para>
 113       Specifies that ASN.1 compiler should only process the
 114       module given. If this option is not specified,
 115       all modules in the ASN.1 file are processed.
 116      </para></listitem>
 117    </varlistentry>
 118
 119   </variablelist>
 120  </refsect1>
 121  <refsect1><title>DEFINITIONS FILE</title>
 122   <para>
 123    The definitions file is really a Tcl script but follows
 124    traditional rules for Shell like configuration files.
 125    That is # denotes the beginning of a comment. Definitions
 126    are line oriented. The definitions files usually consists of
 127    a series of variable assignments of the form:
 128   </para>
 129   <para>
 130    <literal>set</literal> <replaceable>name</replaceable> <replaceable>value</replaceable>
 131   </para>
 132   <para>
 133    Available variables are:
 134    <variablelist>
 135
 136     <varlistentry><term><literal>default-prefix</literal></term>
 137      <listitem><para>
 138        Sets prefix for names in the produced output.
 139        The value consists of three tokens: C function prefix,
 140        C typedef prefix and preprocessor prefix respectively.
 141       </para></listitem>
 142     </varlistentry>
 143
 144     <varlistentry><term><literal>prefix(</literal><replaceable>module</replaceable><literal>)</literal></term>
 145      <listitem><para>
 146        This value sets prefix values for module
 147        <replaceable>module</replaceable>.
 148        The value has same form as <literal>default-prefix</literal>.
 149       </para></listitem>
 150     </varlistentry>
 151
 152     <varlistentry><term><literal>filename(</literal><replaceable>module</replaceable><literal>)</literal></term>
 153      <listitem><para>
 154        Specifies filename for C/header file for module
 155        <replaceable>module</replaceable>.
 156       </para></listitem>
 157     </varlistentry>
 158
 159     <varlistentry><term><literal>init(</literal><replaceable>module</replaceable><literal>,h)</literal></term>
 160      <listitem><para>
 161        Code fragment to be put in first part of public header for module
 162     <replaceable>module</replaceable>.
 163       </para></listitem>
 164     </varlistentry>
 165
 166     <varlistentry><term><literal>body(</literal><replaceable>module</replaceable><literal>,h)</literal></term>
 167      <listitem><para>
 168        Code fragment to be put in last part of public header for module
 169     <replaceable>module</replaceable> (trailer).
 170       </para></listitem>
 171     </varlistentry>
 172
 173     <varlistentry><term><literal>init(</literal><replaceable>module</replaceable><literal>,c)</literal></term>
 174      <listitem><para>
 175        Code fragment to be put in first part of C based encoder/decoder for
 176        module <replaceable>module</replaceable>.
 177       </para></listitem>
 178     </varlistentry>
 179
 180     <varlistentry><term><literal>body(</literal><replaceable>module</replaceable><literal>,c)</literal></term>
 181      <listitem><para>
 182        Code fragment to be put in last part of C based encoder/decoder for
 183        module <replaceable>module</replaceable> (trailer).
 184       </para></listitem>
 185     </varlistentry>
 186
 187     <varlistentry><term><literal>map(</literal><replaceable>module</replaceable><literal>,</literal><replaceable>name</replaceable><literal>)</literal></term>
 188      <listitem><para>
 189        Maps ASN.1 type in module <replaceable>module</replaceable>
 190        of <replaceable>name</replaceable> to value.
 191       </para></listitem>
 192     </varlistentry>
 193
 194     <varlistentry><term><literal>membermap(</literal><replaceable>module</replaceable><literal>,</literal><replaceable>name</replaceable><literal>,</literal><replaceable>member</replaceable><literal>)</literal></term>
 195      <listitem><para>
 196        Maps member <replaceable>member</replaceable> in SEQUENCE/CHOICE of
 197        <replaceable>name</replaceable> in module
 198        <replaceable>module</replaceable> to value.
 199        The value consists of one or two tokens.
 200        First token is name of C preprocessor part. Second token
 201        is resulting C member name. If second token is omitted
 202        the value (one token) is both preprocessor part and
 203        C <literal>struct</literal>,<literal>union</literal>.
 204       </para></listitem>
 205     </varlistentry>
 206
 207     <varlistentry><term><literal>unionmap(</literal><replaceable>module</replaceable><literal>,</literal><replaceable>name</replaceable><literal>,</literal><replaceable>member</replaceable><literal>)</literal></term>
 208      <listitem><para>
 209        Maps member <replaceable>member</replaceable> in CHOICE of
 210        <replaceable>name</replaceable> in module
 211        <replaceable>module</replaceable> to value.
 212        Value consists of to or three tokens. The first token
 213        is name of the integer in the <literal>union</literal> that
 214        is used as selector for the <literal>union</literal> itself.
 215        The second token is name of the <literal>union</literal>.
 216        The third token overrides the name of the CHOICE member;
 217        if omitted the member name is used.
 218       </para></listitem>
 219     </varlistentry>
 220    </variablelist>
 221   </para>
 222  </refsect1>
 223  <refsect1><title>FILES</title>
 224   <para>
 225    <filename>/usr/share/yaz/z39.50/z.tcl</filename>
 226   </para>
 227   <para>
 228    <filename>/usr/share/yaz/z39.50/*.asn</filename>
 229   </para>
 230  </refsect1>
 231  <refsect1><title>SEE ALSO</title>
 232   <para>
 233    <citerefentry>
 234     <refentrytitle>yaz</refentrytitle>
 235     <manvolnum>7</manvolnum></citerefentry>
 236   </para>
 237   <para>
 238    Section "The ODR Module" in the YAZ manual.
 239   </para>
 240  </refsect1>
 241 </refentry>
 242
 243 <!-- Keep this comment at the end of the file
 244 Local variables:
 245 mode: sgml
 246 sgml-omittag:t
 247 sgml-shorttag:t
 248 sgml-minimize-attributes:nil
 249 sgml-always-quote-attributes:t
 250 sgml-indent-step:1
 251 sgml-indent-data:t
 252 sgml-parent-document:nil
 253 sgml-local-catalogs: nil
 254 sgml-namecase-general:t
 255 End:
 256 -->