WriteBinaryFile
Requires Analytica 5.0 Enterprise edition or better.
WriteBinaryFile(filename, data, I..., bytesPer, typeFlags, append, warn, showDialog, title)
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. One other use is to same the contents of multi-dimensional arrays from your model to a file and read them back later using ReadBinaryFile, which can have some speed, precision and convenience advantages to doing the same using text files or data bases.
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.
data
The data to write. This will almost always be an array, unless your intent is to write a single item to the file. In most cases, the array will contain only numbers.
A common usage is to provide an array of integers, which become the bytes of the file. With no optional parameters, one byte is written for each cell of «data», except that nothing is written for cells containing the null value.
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, I, J)
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 (as is the default when «typeFlags» is omitted), this specifies the number of bytes per integer word, and can be 1 (for single bytes), 2 (for 16-bit words), 4 (for 32-bit integers) or 8 (for 64-bit integers).
When writing floating point real numbers, this can be 4 (for 32-bit IEEE 754 reals, often called floats), or 8 (for 64-bit IEEE 754 reals, often called doubles). When «typeFlags» has 2 (floating point), the default for «bytesPer» is 8 if not specified.
For the «typeFlags» option of 3, nine bytes per item are used, so you can either omit «bytesPer» or set it to 9. Any other value throws an error.
For the «typeFlags» option of 4, the number of bytes per item may vary (depending on the length of text values), and so «bytesPer» must be omitted or an error will be issued.
typeFlags
The data type format written.
1= Integer (default)2= IEEE 754 Floating point real3= Value (numbers, dates and null). 9 bytes per item.4= Value (including text). Variable bytes per text item.32= Big endian flag.64= Flag to issue error when cell cannot be coerced to 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". This is the default assumed by WriteBinaryFile 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. When a text value occurs, the first byte indicates that the value is text, the next two bytes encode the length, n, and the next n bytes encodes the characters in UTF-8. 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.
append
When you pass True to the «append» parameter, the data is appended to the end of the file if it already exists. When «append» is omitted or false, the file will be replaced with the contends written.
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.
Enable comment auto-refresher