doc/yaz-asncomp-man.xml

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