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