Revision of some help pages for module fileio.
[scilab.git] / scilab / modules / fileio / help / en_US / save_format.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:id="save_format" xml:lang="en">
3     <refnamediv>
4         <refname>save_format</refname>
5         <refpurpose>format of files produced by "save"</refpurpose>
6     </refnamediv>
7     <refsection>
8         <title>Description</title>
9         <para>
10             Variables are saved by Scilab with the <link linkend="save">save</link> function in the following format:
11         </para>
12         <para>
13             each variable record is appended consecutively to the file. The variable record begins with 6 <literal>long integer</literal> holding the variable name in encoded format (see the Remarks section below), after that comes the variable type (<literal>long integer</literal>), then, depending on it, for:
14         </para>
15         <variablelist>
16             <varlistentry>
17                 <term>Floating matrices (type 1)</term>
18                 <listitem>
19                     <para>
20                         <varname>row_size</varname> <varname>m</varname> (a <literal>long integer</literal>),
21                     </para>
22                     <para>
23                         <varname>column_size</varname> <varname>n</varname> (a <literal>long integer</literal>),
24                     </para>
25                     <para>
26                         real/complex flag <varname>it</varname> (a <literal>long integer</literal> in {0,1}),
27                     </para>
28                     <para>
29                         data (n*m*(it+1) <literal>double</literal>s)
30                     </para>
31                 </listitem>
32             </varlistentry>
33         </variablelist>
34         <variablelist>
35             <varlistentry>
36                 <term>Polynomials (type 2) and Size implicit indices (type 129)</term>
37                 <listitem>
38                     <para>
39                         <varname>row_size</varname> <varname>m</varname> (a <literal>long integer</literal>),
40                     </para>
41                     <para>
42                         <varname>column_size</varname> <varname>n</varname> (a <literal>long integer</literal>),
43                     </para>
44                     <para>
45                         real/complex flag <varname>it</varname> (long integer in {0,1}),
46                     </para>
47                     <para>
48                         formal variable name (16 bytes),
49                     </para>
50                     <para>
51                         <varname>index_table</varname> (m*n+1 <literal>long integer</literal>s),
52                     </para>
53                     <para>
54                         data ((N-1)*(it+1) <literal>double</literal>s), where <varname>N</varname> is the 
55                         value of the last entry of the <varname>index_table</varname>.
56                     </para>
57                 </listitem>
58             </varlistentry>
59         </variablelist>
60         <variablelist>
61             <varlistentry>
62                 <term>Booleans (type 4)</term>
63                 <listitem>
64                     <para>
65                         <varname>row_size</varname> <varname>m</varname> (a <literal>long integer</literal>),
66                     </para>
67                     <para>
68                         <varname>column_size</varname> <varname>n</varname> (a <literal>long integer</literal>),
69                     </para>
70                     <para>
71                         data (n*m <literal>long integer</literal>s).
72                     </para>
73                 </listitem>
74             </varlistentry>
75         </variablelist>
76         <variablelist>
77             <varlistentry>
78                 <term>Floating sparse matrices (type 5)</term>
79                 <listitem>
80                     <para>
81                         <varname>row_size</varname> <varname>m</varname> (a <literal>long integer</literal>),
82                     </para>
83                     <para>
84                         <varname>column_size</varname> <varname>n</varname> (a <literal>long integer</literal>),
85                     </para>
86                     <para>
87                         real/complex_flag <varname>it</varname> (a <literal>long integer</literal> in {0,1}),
88                     </para>
89                     <para>
90                         <varname>total_number_of_non_zero_elements</varname> <varname>nel</varname> (a <literal>long integer</literal>),
91                     </para>
92                     <para>
93                         <varname>number_of_non_zero_elements_per_row</varname> (m <literal>long integer</literal>s),
94                     </para>
95                     <para>
96                         <varname>column_index_non_zero_elements</varname> (nel <literal>long integer</literal>s),
97                     </para>
98                     <para>
99                         <varname>non_zero_values</varname> (nel*(it+1) <literal>double</literal>s).
100                     </para>
101                 </listitem>
102             </varlistentry>
103         </variablelist>
104         <variablelist>
105             <varlistentry>
106                 <term>Boolean sparse matrices (type 6)</term>
107                 <listitem>
108                     <para>
109                         <varname>row_size</varname> <varname>m</varname> (a <literal>long integer</literal>),
110                     </para>
111                     <para>
112                         <varname>column_size</varname> <varname>n</varname> (a <literal>long integer</literal>),
113                     </para>
114                     <para>
115                         unused <varname>it</varname> (a <literal>long integer</literal>),
116                     </para>
117                     <para>
118                         <varname>total_number_of_non_zero_elements</varname> <varname>nel</varname> (a <literal>long integer</literal>),
119                     </para>
120                     <para>
121                         <varname>number_of_non_zero_elements_per_row</varname> (m <literal>long integer</literal>s),
122                     </para>
123                     <para>
124                         <varname>column_index_non_zero_elements</varname> (nel <literal>long integer</literal>s).
125                     </para>
126                 </listitem>
127             </varlistentry>
128         </variablelist>
129         <variablelist>
130             <varlistentry>
131                 <term>Matlab sparse matrix (type 7)</term>
132                 <listitem>
133                     <para>
134                         <varname>row_size</varname> <varname>m</varname> (a <literal>long integer</literal>),
135                     </para>
136                     <para>
137                         <varname>column_size</varname> <varname>n</varname> (a <literal>long integer</literal>),
138                     </para>
139                     <para>
140                         real/complex_flag <varname>it</varname> (a <literal>long integer</literal> in {0,1}),
141                     </para>
142                     <para>
143                         <varname>total_number_of_non_zero_elements</varname> <varname>nel</varname> (a <literal>long integer</literal>),
144                     </para>
145                     <para>
146                         <varname>number_of_non_zero_elements_per_column</varname> (n <literal>long integer</literal>s),
147                     </para>
148                     <para>
149                         <varname>row_index_non_zero_elements</varname> (nel <literal>long integer</literal>s),
150                     </para>
151                     <para>
152                         <varname>non_zero_values</varname> (nel*(it+1) <literal>double</literal>s).
153                     </para>
154                 </listitem>
155             </varlistentry>
156         </variablelist>
157         <variablelist>
158             <varlistentry>
159                 <term>Integer matrices (type 8)</term>
160                 <listitem>
161                     <para>
162                         <varname>row_size</varname> <varname>m</varname> (a <literal>long integer</literal>),
163                     </para>
164                     <para>
165                         <varname>column_size</varname> <varname>n</varname> (a <literal>long integer</literal>),
166                     </para>
167                     <para>
168                         <varname>integer_type</varname> (a <literal>long integer</literal>): 1,2,4, or 11,12,14 for signed and unsigned 1,2,4 bytes integers,
169                     </para>
170                     <para>
171                         data (n*m bytes for <varname>integer_type</varname> 1 or 11, n*m <literal>short integer</literal>s for <varname>integer_type</varname> 2 or 12, n*m <literal>long integer</literal>s for <varname>integer_type</varname> 4 or
172                         14).
173                     </para>
174                 </listitem>
175             </varlistentry>
176         </variablelist>
177         <variablelist>
178             <varlistentry>
179                 <term>handles (type 9)</term>
180                 <listitem>
181                     <para>version (4 bytes)</para>
182                     <para>
183                         <varname>row_size</varname> <varname>m</varname> (a byte),
184                     </para>
185                     <para>
186                         <varname>column_size</varname> <varname>n</varname> (a byte),
187                     </para>
188                     <para>
189                         data (m*n <varname>serialization_record</varname>s)
190                     </para>
191                     <para>
192                         A <varname>serialization_record</varname> is a flat 
193                         representation of the C data structure associated with the 
194                         corresponding graphic object. Each graphic object is defined by 
195                         a (recursive) set of properties (see the <link linkend="get">get</link> function).
196                     </para>
197                     <para>
198                         The saved <varname>serialization_record</varname> of a graphic object is structured as follow.
199                     </para>
200                     <variablelist>
201                         <varlistentry>
202                             <term>serialization_record</term>
203                             <listitem>
204                                 <para>
205                                     <varname>type_length</varname> <varname>n</varname> (a byte),
206                                 </para>
207                                 <para>
208                                     type (n bytes, the ascii codes of the type name),
209                                 </para>
210                                 <para>
211                                     <varname>property_values</varname> record (variable length).
212                                 </para>
213                             </listitem>
214                         </varlistentry>
215                     </variablelist>
216                 </listitem>
217             </varlistentry>
218         </variablelist>
219         <variablelist>
220             <varlistentry>
221                 <term>Strings (type 10)</term>
222                 <listitem>
223                     <para>
224                         <varname>row_size</varname> <varname>m</varname> (a <literal>long integer</literal>),
225                     </para>
226                     <para>
227                         <varname>column_size</varname> <varname>n</varname> (a <literal>long integer</literal>),
228                     </para>
229                     <para>
230                         <varname>index_table</varname> (n*m+1 <literal>long integer</literal>s),
231                     </para>
232                     <para>
233                         data (N <literal>long integer</literal>s, the Scilab encoding of the characters (see <link linkend="code2str">code2str</link>), where <varname>N</varname> is the value of the last entry of the <varname>index_table</varname>.
234                     </para>
235                 </listitem>
236             </varlistentry>
237         </variablelist>
238         <variablelist>
239             <varlistentry>
240                 <term>Uncompiled functions (type 11)</term>
241                 <listitem>
242                     <para>
243                         <varname>nout</varname> (a <literal>long integer</literal>),
244                     </para>
245                     <para>
246                         <varname>lhs_names</varname> (6*nout <literal>long integer</literal>s, see the Remarks section below),
247                     </para>
248                     <para>
249                         <varname>nin</varname> (a <literal>long integer</literal>),
250                     </para>
251                     <para>
252                         <varname>rhs_names</varname> (6*nin <literal>long integer</literal>s, see the Remarks section below),
253                     </para>
254                     <para>
255                         <varname>code_length</varname> <varname>N</varname> (a <literal>long integer</literal>),
256                     </para>
257                     <para>
258                         <varname>code</varname> (N <literal>long integer</literal>s).
259                     </para>
260                 </listitem>
261             </varlistentry>
262         </variablelist>
263         <variablelist>
264             <varlistentry>
265                 <term>Compiled functions (type 13)</term>
266                 <listitem>
267                     <para>
268                         <varname>nout</varname> (a <literal>long integer</literal>),
269                     </para>
270                     <para>
271                         <varname>lhs_names</varname> (6*nout <literal>long integer</literal>s, see the Remarks section below),
272                     </para>
273                     <para>
274                         <varname>nin</varname> (a <literal>long integer</literal>),
275                     </para>
276                     <para>
277                         <varname>rhs_names</varname> (6*nin <literal>long integer</literal>s, see the Remarks section below),
278                     </para>
279                     <para>
280                         <varname>pseudo_code_length</varname> <varname>N</varname> (a <literal>long integer</literal>),
281                     </para>
282                     <para>
283                         <varname>pseudo_code</varname> (N <literal>long integer</literal>s).
284                     </para>
285                 </listitem>
286             </varlistentry>
287         </variablelist>
288         <variablelist>
289             <varlistentry>
290                 <term>Libraries (type 14)</term>
291                 <listitem>
292                     <para>
293                         <varname>path_length</varname> np (a <literal>long integer</literal>),
294                     </para>
295                     <para>
296                         <varname>path_name</varname> (np <literal>long integer</literal>s: the path character codes sequence, (see <link linkend="code2str">code2str</link>)),
297                     </para>
298                     <para>
299                         number of names nn (a <literal>long integer</literal>),
300                     </para>
301                     <para>
302                         names (6*nn <literal>long integer</literal>s, see the Remarks section
303                         below).
304                     </para>
305                 </listitem>
306             </varlistentry>
307         </variablelist>
308         <variablelist>
309             <varlistentry>
310                 <term>Lists (type 15), tlists (type 16), mlists (type 17)</term>
311                 <listitem>
312                     <para>
313                         number of fields <varname>n</varname> (a <literal>long integer</literal>),
314                     </para>
315                     <para>
316                         index (n+1 <literal>long integer</literal>s),
317                     </para>
318                     <para>
319                         <varname>variables_sequence</varname> (n variables, each one written according to its format).
320                     </para>
321                 </listitem>
322             </varlistentry>
323         </variablelist>
324         <variablelist>
325             <varlistentry>
326                 <term>Pointers (type 128)</term>
327                 <listitem>
328                     <para>Not handled</para>
329                 </listitem>
330             </varlistentry>
331         </variablelist>
332         <variablelist>
333             <varlistentry>
334                 <term>Function pointers (type 130)</term>
335                 <listitem>
336                     <para>
337                         <varname>function_ptr</varname> (a <literal>long integer</literal>, (see <link linkend="funptr">funptr</link>)),
338                     </para>
339                     <para>
340                         <varname>function_name_code</varname> (6 <literal>long integer</literal>s, see the 
341                         Remarks section below).
342                     </para>
343                 </listitem>
344             </varlistentry>
345         </variablelist>
346     </refsection>
347     <refsection>
348         <title>Remarks</title>
349         <para>
350             Numbers (a <literal>long interger</literal>, <literal>short integer</literal>s,  <literal>double</literal>) are stored using the 
351             little endian convention.
352         </para>
353         <para>
354             The variable names are stored as a sequence of 6 <literal>long integer</literal>s, with 
355             a specific encoding. See the <literal>cvname.f</literal> file for
356             details.
357         </para>
358     </refsection>
359     <refsection role="see also">
360         <title>See Also</title>
361         <simplelist type="inline">
362             <member>
363                 <link linkend="save">save</link>
364             </member>
365             <member>
366                 <link linkend="load">load</link>
367             </member>
368             <member>
369                 <link linkend="listvarinfile">listvarinfile</link>
370             </member>
371             <member>
372                 <link linkend="type">type</link>
373             </member>
374             <member>
375                 <link linkend="typeof">typeof</link>
376             </member>
377         </simplelist>
378     </refsection>
379 </refentry>