BinStream for Binary Reading and Writing

The BinStream methods can be used to read and write binary files. The methods are very similar to the ones provided by the FileStream Values

Methods:

<BinStream>fopen <String fileName> <String mode>

Opens a file for reading or writing based on the mode parameter. The function will return a BinStream value.

The fopen method parses the mode string looking for exactly one of {rwa}, at most one '+', at most one of {tb}, at most one of {SR}, at most one 'T', and at most one 'D'.

In other words, a mode string is valid if

 

r - read-only text - file must exist

rt - read-only text - file must exist

rb - read-only binary - file must exist

r+ - read/write text - file must exist

 

a - write-only text, append writes - file must exist

at - write-only text, append writes - file must exist

ab - write-only binary, append writes - file must exist

a+ - read/write text, append writes - file must exist

 

w - write-only text - deletes file contents if it exists

wt - write-only text - deletes file contents if it exists

wb - write-only binary - deletes file contents if it exists

w+ - read/write text - deletes file contents if it exists

 

S - access is primarily sequentional

R - access is primarily random

T - temporary storage file, try not to flush

D - file is deleted when last handle is closed

c - enable the commit flag for the associated filename so that the contents of the file buffer are written directly to disk if flush or fflush is called.

n - reset the commit flag for the associated filename to "no-commit" - contents of the file buffer are written to operating system buffers.

Note: These modes are actual string and should always be written in quotation marks! They are also CASE SENSITIVE!

 

When a file is opened with one of the "a" access types, all write operations occur at the end of the file. The file pointer can be repositioned using seek, but is always moved back to the end of the file before any write operation is carried out. Thus, existing data cannot be overwritten.

The "a" mode does not remove the EOF marker before appending to the file. After appending has occurred, the MS-DOS TYPE command only shows data up to the original EOF marker and not any data appended to the file.

The "a+" mode does remove the EOF marker before appending to the file. After appending, the MS-DOS TYPE command shows all data in the file. The "a+" mode is required for appending to a stream file that is terminated with the CTRL+Z EOF marker.

When the "r+", "w+", or "a+" access type is specified, both reading and writing are allowed (the file is said to be open for "update"). However, when you switch between reading and writing, there must be an intervening fflush or fseek operation. The current position can be specified for the fseek operation, if desired.

Having any character not listed above, having any repeats of characters listed above, or having both of a 'one of' pair will result in a runtime error being thrown.

If the mode string does not include 't' or 'b', 'b' is automatically appended to the mode string so that the file is opened in binary mode. Available in 3ds Max 8 and higher.

 

fflush <binStream>

Ensure all output to file is on disk, flushes the memory buffers.

<Boolean>FClose <BinStream>

Close a BinStream value. Returns True if it successfully closed the BinStream.

<Boolean>fseek <BinStream> <Integer> <#seek_set | #seek_cur | #seek_end>

Move the file pointer to the specified location based off the seek parameter.

#seek_set - base off start of file.

#seek_cur - base off current position.

#seek_end - base off end of file.

 

<Integer>ftell <BinStream>

Returns the current file pointer position.

<Boolean>WriteByte <BinStream> <Integer> [#signed | #unsigned]

Writes a Integer to the file as one byte. Returns True if write was successful.

<Boolean>WriteShort <BinStream> <Integer> [#signed | #unsigned]

Writes a Integer to the file as two bytes. Returns True if write was successful.

<Boolean>WriteLong <BinStream> <Integer> [#signed | #unsigned]

Writes a Integer to the file as four bytes. Returns True if write was successful.

<Boolean>WriteFloat <BinStream> <Float>

Writes a Float to the file as four bytes. Returns True if write was successful.

<Boolean>WriteString <BinStream> <String>

Writes a string to the file. Returns True if write was successful.

<Integer>ReadByte <BinStream> [#signed | #unsigned]

Read a one byte value and return as an Integer.

<Integer>ReadShort <BinStream> [#signed | #unsigned]

Read a two byte value and return as an Integer.

<Integer>ReadLong <BinStream> [#signed | #unsigned]

Read a four byte value and return as an Integer.

<Float>ReadFloat <BinStream>

Read a four byte value and return as an Float.

<String>ReadString <BinStream>

Read a string from the file.

 

Example:

f=fopen "c:\\test.bin" "wb"

WriteString f "String"

WriteByte f 64

WriteShort f 128

WriteLong f 256

WriteFloat f 512.0

WriteString f "gnirtS"

WriteLong f (ftell f)

fclose f

f=fopen "c:\\test.bin" "rb"

ReadString f

ReadByte f

ReadShort f

ReadLong f

ReadFloat f

ReadString f

ftell f

ReadLong f

fclose f

See also

FileStream Values