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