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>