Binary Files

Binary file items are supported from S_TOOLS-STx version 3.7.x (r603). The following features are available:

• A binary file can have one or more sections.
• Every section can have a numeric item saved in it (e.g. a table, a value etc.).
• A section has a header with the following attributes:

• The data type (16-bit integer, 32-bit integer, 32-bit float or 64-bit float).
• The size of the value in bytes (2, 4 or 8).
• The number of lines.
• The number of columns.

• A file can have any number of sections.
• The file item implements functions to load and save data to sections and to list existing sections.
• Existing sections can be overwritten by data of the same length. If data is not the same length, the section must be deleted first.
• Individual sections or all sections can be deleted (see NEW file and SAVE).
• Sections can be appended to an existing file.

The S_TOOLS-STx binary file contains no metadata describing the section data! Metadata, if needed, must be stored elsewhere (e.g. in the DataSet).

Binary File Format

The S_TOOLS-STx binary file has the following format:

The binary file section header is 12 bytes long and contains three 32bit integer values.

header[0] = the binary file type

0x0102 - 16bit integer

0x0204 - 32bit integer

0x0304 - 32bit float

0x0408 - 64bit float

header[1] = the number of rows

This is stored in a signed integer.

header[2] = the number of columns

This is stored in a signed integer.

The binary data is stored directly after the binary header. Note that each column is stored as a vector. The column vectors are stored one after the other.

Binary File Example

The following script demonstrates the use of a binary file item.

[macro binary_file_example] // // create binary file item // deleting existing contents // #f := new file * 'binary_file_example.stb' /Binary /Delete if '$#f[?]' != 'file' em -1 ; $#mac - Failed to create #f // // save vector data to section 0 // $#f save $(eval fill(10,1,1)) 0 // // save matrix data to section 1 // #matrix := eval init(10,10,0) showitem $#matrix $#f save $#matrix 1 if '$rc' > 0 em $rc ; SAVE failed ($EMSG) // // save matrix data to section 2 // $#f save $(eval init(10,10,1)) 2 // // list sections in binary file // #st := new table * if '$#st[?]' != 'table' em -1 ; $#mac - Failed to create #st if '$($#f list $#st)' > 0 em $rc ; $#mac - LIST failed ($EMSG) showitem $#st // // delete section 1 // $#f save * 1 // // load matrix data from section 1 (was section 2) // #t := new table * 10 /P if '$#t[?]' != 'table' em -1 ; $#mac - Failed to create #t if '$($#f load $#t 1)' > 0 em $rc ; $#mac - LOAD failed ($EMSG) showitem $#t // // clean up // delete $#f $#matrix $#st $#t exit