FileStream Values
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>
[encoding:{ <#current> | <#English> | <#German> | <#French> | <#Japanese> | <#Korean> | <#Chinese> | <#utf8> | <#utf16LE> | <#utf16BE> | <int codepage> } ] \
[writeBOM:<boolean>]
Creates a new file and returns a <filestream> value. If the specified file cannot be created, the value undefined is returned.
The encoding: keyword option can be used to enforce a specific character encoding. If not supplied, it defaults to #current encoding.
The writeBOM: keyword option can be used to control whether the Byte-Order-Mark of UTF-8 files will be written.
See the Character Encoding topic for details on Unicode and BOM usage in 3ds Max 2013 and higher.
openFile <filename_string>
[mode:<mode_string>]
[encoding:{ <#current> | <#English> | <#German> | <#French> | <#Japanese> | <#Korean> | <#Chinese> | <#utf8> | <#utf16LE> | <#utf16BE> | <int codepage> } ] \
[writeBOM:<boolean>]
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:
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
The default is "rt".
a - write-only text, append writes - in 3ds Max 2013 the file is 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 is 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 is 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 is created if it does not exist (in 3ds Max 2012 and earlier, the file must exist)
w - write-only text - deletes the file contents if it exists
wt - write-only text - deletes the file contents if it exists
wb - write-only binary - deletes the file contents if it exists
w+ - read/write text - deletes the 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 the 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 the disk if close 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.
These modes are actual string and must be always 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, 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.
The encoding: keyword option can be used to enforce a specific character encoding. If not supplied, it defaults to #current encoding.
See the Character Encoding topic for details.
See File Access Function Search Behavior for a list of directories the filename_string is searched for if the full path is not specified.
openEncryptedFile <filename> <key>
[encoding:{ <#current> | <#English> | <#German> | <#French> | <#Japanese> | <#Korean> | <#Chinese> | <#utf8> | <#utf16LE> | <#utf16BE> | <int codepage> } ] \
[writeBOM:<boolean>]
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.
The encoding: keyword option can be used to enforce a specific character encoding. If not supplied, it defaults to #current encoding.
The writeBOM: keyword option can be used to control whether the Byte-Order-Mark of UTF-8 files will be written.
See the Character Encoding topic for details on Unicode and BOM usage in 3ds Max 2013 and higher.
See File Access Function Search Behavior for a list of directories the filename is searched for if the full path is not specified.
Methods
readLine <filestream>Read next line, return as string.
readChar <filestream>Read next char, return as string.
readChars <filestream> <char_count> errorAtEOF:<boolean>Reads the specified number of characters and returns them in a string.
When the errorAtEOF parameter is false, this method does not throw an exception when it attempts to read past the end of the filestream. As well, setting this parameter to false and <char_count> to -1 causes this method to read to the end of the file. The default is true.
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>Retrieves the current offset into the file.
seek <filestream> <integer>Positions the file at the given offset so that the subsequent I/O starts there.
seek methods accept #eof as an argument. Specifying this places you at the end of the file/string stream. A filePos at this point tells 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 contains the contents up to the end of the file.So, you can use:
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 the 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> ]
safeReadValue <filestream> [ ignoreStringEscapes:<boolean> ] [ignoreSSSEState:<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.
The safeReadValue() version always blocks unsafe MAXScript, .NET and Python commands.
NEW in 3ds Max 2024.1 Update
The optional ignoreSSSEState keyword argument, if true, specifies that the function is executed using restricted security settings regardless of whether Safe Scene Script Execution is enabled. The default is false.
Available in in 3ds Max 2022.1 Update and later.
readExpr <filestream>
safeReadExpr <filestream> [ignoreSSSEState:<boolean>]Read and evaluate the next MAXScript <expr> from the file.
Note that the scope of the evaluation is the global scope, and not the current scope.
The safeReadExpr() version always blocks unsafe MAXScript, .NET and Python commands.
NEW in 3ds Max 2024.1 Update
The optional ignoreSSSEState keyword argument, if true, specifies that the function is executed using restricted security settings regardless of whether Safe Scene Script Execution is enabled. The default is false.
Available in in 3ds Max 2022.1 Update and later.
execute <filestream>Read and evaluate all the expressions left in the file. Note that the scope of the evaluation is the global scope, and 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 description of these methods.