FileStream Values

Value > Stream Values > FileStream Values

Values and Collections - Quick Navigation

A FileStream class implements text file input and output in MAXScript. A FileStream value represents an open text file in MAXScript. Text file I/O is performed by calling functions on the FileStream value.

Constructors

createFile <filename_string>

Creates a new file and returns a <filestream> value. If the specified file cannot be created, the value undefined is returned.

openFile <filename_string> [mode:<mode_string>]

Opens a file and returns a <filestream> value. If the specified file cannot be opened, the value undefined is returned. The optional <mode_string> can be (default is "rt"):

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, the 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, the 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, the 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, the 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 flush 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.

WARNING!

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 flush() or seek() operation. The current position can be specified for the seek() operation, if desired.

openEncryptedFile <filename> <key>

Opens the encrypted file using the given integer key and returns a FileStream value that you can then do read calls on, exactly as you can on FileStreams returned from the openFile() function. See Encrypted Files for details on encrypted files.

Methods

readLine <filestream>

Read next char, return as string

readChars <filestream> <char_count>

Reads the specified number of characters and returns them in a string.

readDelimitedString <filestream> <string>

Takes a delimiter character (as a string) and reads in characters until the delimiter is found (or end-of-file is reached) and returns the characters in a string.

skipToString <filestream> <string>

Takes a character string and scans forward in the file until it finds an occurrence of the string and positions the file just after that string.

If the string is not found, the function returns the value undefined .

skipToNextLine <filestream>

Positions the input file at the beginning of the next line

filePos <filestream>

Retrieve the current offset into the file

seek <filestream> <integer>

Position the file at the given offset so that subsequent I/O will start there.

NOTE:The seek methods accept #eof as an argument. Specifying this will place you at the end of the file/string stream. A filePos at this point will tell you the length of the file. The readChars method now also accepts a Boolean keyword parameter called errorAtEOF . The default value for this keyword parameter is True , to match current behavior. If False , and an attempt is made to read across the end of the file, no error message is generated and the return string will contain the contents up to the end of the file.

SO YOU CAN SAY:

seek fin #eof
maxlen=filepos fin
seek fin 0
res = readChars fin maxlen errorAtEOF:false

eof <filestream>

Returns true if there is no more data in the file, false otherwise.

flush <filestream>

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

close <filestream>

Flushes the memory buffers and closes the file

free <filestream>

Frees the memory used by the filestream value without waiting for garbage collection.

Available in 3ds Max 9 and higher.

For the following methods, see the description of the execute() method in String Values for information on the scope of variables used in the evaluated expressions.

readValue <filestream> [ ignoreStringEscapes:<boolean> ]

Read and evaluate the next MAXScript <operand> from the file

If the optional ignoreStringEscapes: keyword argument is not supplied or supplied as false and the value read is a string, '\' characters in the string are handled as escape characters. If true, '\' characters in the string are not handled as escape characters. Available in 3ds Max 8 and higher.

readExpr <filestream>

Read and evaluate the next MAXScript <expr> from the file.

Note that the scope of the evaluation is the global scope, not the current scope!

execute <filestream>

Read and evaluate all the expressions left in the file. Note that the scope of the evaluation is the global scope, not the current scope!

The differences between the above methods can be seen in the following example. In this example, a stringstream value is created that contains a string containing two expressions - random 0. 1. and random red blue . The readValue , readExpr , and execute methods are then used with the stringstream as the argument.

SCRIPT

s=stringstream "random 0. 1.;random red blue"
readvalue s -- read and evaluate the first value
readvalue s -- read and evaluate the second value
seek s 0 -- position at beginning of stringstream
readexpr s -- read and evaluate the first expression
readexpr s -- read and evaluate the second expression
seek s 0 -- position at beginning of stringstream
execute s -- evaluate all expressions

OUTPUT

StringStream: "random 0. 1.;random red blue" -- result line 1
random() -- result line 2 (evaluated "random")
0.0 -- result line 3 (evaluated "0.")
OK -- result line 4
0.448042 -- result line 5 (evaluated "random 0. 1. ")
(color 86.476 0 163.24) -- result line 6 (evaluated "random red blue")
OK -- result line 7
(color 30.2417 0 143.636) -- result line 7 (evaluated all expressions,
-- returns result of last expression)

Associated Methods

print <value> to:<filestream>

Prints the value to the specified file stream.

format <fmt_string> { <value> } to:<filestream>

Formats the value to the specified file stream.

See Value Common Properties, Operators, and Methods for detailed descriptions of these methods.

FileStream Values

See Also