BinStream Value for Binary Reading and Writing

Values and Collections - Quick Navigation

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

• First mode character is 'r', 'w', or 'a'

• There can be up to six more optional mode characters:

  • One '+' character,

  • One of 't' and 'b', and

  • One of 'c' and 'n', and

  • One of 'S' and 'R', and

  • One of 'T',

  • One of 'D'.

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 - in 3ds Max 2013 the file will be created if it does not exist (in 3ds Max 2012 and earlier, file must exist)

at - write-only text, append writes - in 3ds Max 2013 the file will be created if it does not exist (in 3ds Max 2012 and earlier, file must exist)

ab - write-only binary, append writes - in 3ds Max 2013 the file will be created if it does not exist (in 3ds Max 2012 and earlier, file must exist)

a+ - read/write text, append writes - in 3ds Max 2013 the file will be created if it does not exist (in 3ds Max 2012 and earlier, 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 sequential

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.

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.

<Boolean>WriteLongLong <BinStream> <Integer64> [#signed | #unsigned]

Writes an Integer64 to the file as eight bytes. Returns True if write was successful.

Available in 3ds Max 2008 and higher. Previously available in the Avguard Extensions.

<Boolean>WriteDouble <BinStream> <Double>

Writes a Double to the file as eight bytes. Returns True if write was successful.

Available in 3ds Max 2008 and higher. Previously available in the Avguard Extensions.

<Boolean>WriteFloatAsDouble <BinStream> <float>

Writes a float value as a double precision (eight bytes) float to the BinStream. Returns True if write was successful.

Available in 3ds Max 2008 and higher. Previously available in the Avguard Extensions.

<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.

<Float>ReadDoubleAsFloat <BinStream>

Reads a double precision (eight byte) float from the BinStream and returns as a float.

Available in 3ds Max 2008 and higher. Previously available in the Avguard Extensions.

<Integer64>ReadLongLong <BinStream> [#signed | #unsigned]

Read an eight byte value and return as an Integer64. Available in 3ds Max 2008 and higher.

Previously available in the Avguard Extensions.

<Double>ReadDouble <BinStream>

Read an eight byte value and return as a Double. Available in 3ds Max 2008 and higher.

Previously available in the Avguard Extensions.

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

 Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. Please see the Autodesk Creative Commons FAQ for more information.