corrected DOCTYPE header and called emacs nxml-mode instead of sgml-mode in bottom...
[yaz-moved-to-github.git] / 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 -->