WriteBinaryFile

Release:	4.6 • 5.0 • 5.1 • 5.2 • 5.3 • 5.4 • 6.0 • 6.1 • 6.2 • 6.3 • 6.4 • 6.5

Requires Analytica 5.0 Enterprise edition or better.

ReadBinaryFile() and WriteBinaryFile() read and write binary files, in contrast to ReadTextFile and WriteTextFile, which read and write text files (surprise!). Binary files store data in a format similar to how the data are represented in computer memory used by Analytica (or any application). So they are usually more compact and much faster to read or write than text files. Text files, such as CSV files or Analytica Model file formats, represent each number as a sequence of digit characters, which have to be parsed and converted to the internal binary form, which takes time.

Of course, binary files, unlike text files, are not readable by humans. The layout and metadata, such as the size of each cell and row, and the number of rows, is not part of a binary file. This is unlike CSV files, for example, with separators for each cell and row (usually comma and new line), and column headers in the first row. For binary files, you must need to specify this information as parameters to ReadBinaryFile() and WriteBinaryFile(), including array indexes, and the data type or number of bytes per cell. It's usually worth using binary formats only when you have really large amounts of data so that the file size and read/write speed are significant issues. Occasionally, you may want to read binary files from other sources or generate binary files for use by other applications.

WriteBinaryFile(filename, data, I..., bytesPer, typeFlags, append, warn, showDialog, title, download)

Writes data to a binary file. If you wish to write data to a human-readable file, you should probably be using WriteTextFile. Use WriteBinaryFile when providing data for or integrated with another application that has a specific binary data format. Or when you have large amounts of data -- e.g. large arrays -- to save and read into Analytica, you can save substantial computation time, reduce file size, and retain full precision by using WriteBinaryFile and ReadBinaryFile relative to using text files or a database.

Parameters

filename

Name of file to create, replace or append to.

File name paths can be either relative or absolute. An absolute path specifies the full path of the file from a root drive, such as

"C:\Users\Drice\Documents\Projects\FatigueAnalysis\Results.bin"

A relative filename incompletely specifies a file path, and is interpreted relative to the CurrentDataDirectory.

If you set the «filename» to "<>", WriteBinaryFile writes to an in-memory binary data term rather than to a file.

data

The data to write, usually an array. If «data» is an array of integers from 0 to 255, by default each integer is written into one byte of the file. If the number is a real (floating point) number, it will round it to an integer, and ignore digits above 255 (the maximum integer that fits into one byte). To write larger integers or to preserve floating point numbers or text values, you can specify more bytes and other types with the optional «bytesPer» and «typeFlags» described below.

I...

The indexes of the array passed to «data». When «data» has more than one dimension, the order in which you list the indexes controls the order in which cells are written to the file. The first index you list is varied the slowest, and the last index you list varies fastest. For example, suppose index I := 1..3 and index J := 1..2, then

WriteBinaryFile(filename, data, I, J)

writes the cells in the order:

data[I = 1, J = 1]

data[I = 1, J = 2]

data[I = 2, J = 1]

data[I = 2, J = 2]

data[I = 3, J = 1]

data[I = 3, J = 2]

whereas

WriteBinaryFile(filename, data, J, I)

writes the cells in the order

data[I = 1, J = 1]

data[I = 2, J = 1]

data[I = 3, J = 1]

data[I = 1, J = 2]

data[I = 2, J = 2]

data[I = 3, J = 2]

bytesPer

The number of bytes in the file per cell of «data».

When writing integer values (the default when «typeFlags» is omitted), this specifies the number of bytes per integer word, and can be 1 (for single bytes, integers 0 to 2^8-1=255), 2 (for integers up to 2^16-1 = 65,535), 4 (for 32-bit integers up to 2^32-1 = 4,294,967,295) or 8 (for 64-bit integers up to 2^64-1).

For floating point real numbers, you can specify 4 (for 32-bit IEEE 754 reals, often called floats), or 8 (for 64-bit IEEE 754 reals, often called doubles). When «typeFlags» = 2 (floating point), the «bytesPer» defaults to 8 if not specified.

For the «typeFlags» option of 3, it uses 9 bytes per item, so you can either omit «bytesPer» or set it to 9. Any other value gives an error.

For the «typeFlags» option of 4, the number of bytes per item may vary (depending on the length of text values), and you must omit «bytesPer» to avoid an error.

typeFlags

The data type format written:

1 = Integer (default)

2 = IEEE 754 Floating point real

3 = Value (numbers, dates and null). 9 bytes per item.

4 = Value (including textand binary). Variable bytes per text item.{{{3}}}

32 = Big endian flag.

64 = Flag to issue error when cell cannot be coerced to type. By default, it will not give error messages when it cannot coerce a cell to fit in the specified data type.

A standard Intel convention writes numbers (integers or floating point values) with the least significant bytes written first, least significant bytes last, which is termed "little-endian format". WriteBinaryFile uses this default unless the typeFlags = 32 flag is specified. "Big endian" means that the most significant byte is written first.

You can add 32, 64 or 32 + 64 options to the data type selection. So, for example, a value of 2 + 32 + 64 would specify a floating point format (2) with the byte order reversed (32), and with an error issued when a non-numeric cell is encountered (64).

Integer formats write the «bytesPer» least-significant bits to the file. For example, when «bytesPer» is 2, the integers written will be between 0 and 65535 (or between -32768 and 32767). If «data» contains a number outside this range, such as 66,000, then Mod(66K, 2^16, true), which equals 464 would actually be written. It isn't necessary to differentiate between whether the integers are positive or negative at the time they are being written, but you do need to make this distinction when reading (see ReadBinaryFile).

The Value type is a variant data type, in which a byte is written to encode the internal data type of the value, and followed by an 8-byte value. The «typeFlags» option of 3 only writes Analytica data types that can be fully encoded in with 8 bytes, which includes integers, fixed-point reals, floating point reals, date and date-time numbers, and the special value Null. When using this type, Null values ARE written to the file. The «typeFlags» option of 3 cannot be used to write text values, since these vary in length. The cells will each use 9 bytes, and will be spaced every 9 bytes in the file.

The «typeFlags» option of 4 extends option 3 by allowing text values and binary data ("blobs"). When a text value occurs, the first byte indicates that the value is text, the next four bytes encode the length, n, and the next n bytes encodes the characters in UTF-8. When a binary "blob" occurs, the first byte indicates that it is binary data, the next 8 bytes encode the number of bytes, and the next nbytes are the binary data. When this format is used, the «bytesPer» parameter must be omitted. The location of items in the file are not spaced at any predictable interval, since text items vary in length.

When «typeFlags» is 7, then «data» must be in memory binary data or Null (if Null, the data is ignored). This writes the binary data directly with no extra surrounding information to indicate its type or size. Thus, if this option is applied to an array of binary data, the binary data gets directly appended.

append

When you pass True to the «append» parameter, it appends the data to the end of the file if it already exists. When you omit «append» or set it to false, it overwrites any existing file with the new contents.

warn

Use this Boolean parameter to force or suppress a warning when the file already exists. When omitted, a warning occurs unless you are appending.

showDialog

This is a flag to force or suppress the file selector dialog. When not specified, the dialog only displays if needed, for example, if the file name is blank or to a directory that is not writable or does not exist. Setting «showDialog» to false suppresses the dialog from appearing. Setting «showDialog» to true forces the dialog to display, using «filename» as the initial default.

title

The text to use as caption of file selector dialog.

download

New to Analytica 6.0

When set to True and the model is running in ACP, the data is downloaded to the end user's computer as a file with the name given by «filename».