The File object lets you read and write binary data from and
to a file on disk (or in a Zip file, FTP site, etc). While the Microsoft
Scripting.FileSystemObject object lets you read and write files
already, it only supports text, not binary data. You can also use the
File object to modify a file's attributes and
timestamps.
You can obtain a File object using the
FSUtil.OpenFile and
Item.Open methods. You
can open a file in one of three modes:
Property Name |
Return Type |
Description |
---|---|---|
<default value> |
string |
Returns the full pathname of the file. |
error |
int |
Returns a Win32 error code that indicates the success or failure of the
last operation. If the previous operation succeeded this will generally be
0. |
path |
object:Path |
Returns the full pathname of the file as a Path object. |
size |
object:FileSize |
Returns a FileSize object representing the size of this file, in bytes. |
tell |
object:FileSize |
Returns a FileSize object representing the current position of the read or write cursor within this file, in bytes. |
Method Name |
Arguments |
Return Type |
Description |
---|---|---|---|
Close |
none |
none |
Closes the underlying file handle. After this call the
File object is still valid but it can no longer read or
write data. |
Read |
<blob:target> |
int or |
Reads data from the file. If you provide a target Blob as the first parameter, the data will be stored in that Blob. Otherwise, a Blob will be created automatically. The optional size parameter specifies the number of bytes to read - the default behavior is to read the remaining contents of the file. A maximum of 1 GB (1073741824 bytes) can be read per call, whether a size is specified or implicit. To read a larger file, you must call Read multiple times. If you provide a Blob then the return value indicates the number of bytes read successfully from the file. If a Blob isn't provided then the return value is the automatically created Blob - you can use its size property to discover the number of bytes that were read. If Read returns zero (or an empty Blob), you can use the error property to test if anything went wrong, or if the file simply had no more data. |
Seek |
<int:delta> |
object:FileSize |
Moves the read or write cursor within this file. The delta
parameter specifies how many bytes to move - how this is interpreted
depends on the optional method parameter: |
SetAttr |
object:FileAttr or <string:attributes> |
bool |
Modifies the attributes of this file. You can either pass a string
indicating the attributes to set, or a FileAttr
object. When using a string, valid attributes
are:
When you pass a string you can also use + and
- to turn some attributes on or off without affecting
others. For example, SetAttr("-r") would turn off the
read-only attribute. |
SetTime |
<date:modify> |
bool |
Modifies one or more of the file's timestamps. The create and
access parameters are optional. If you wish to specify no change
for a timestamp, specify 0. |
SetTimeUTC |
<date:modify> |
bool |
Modifies one or more of the file's timestamps. The create and
access parameters are optional. If you wish to specify no change
for a timestamp, specify 0. |
Truncate |
none |
bool |
Truncates the file at the current position of the write cursor. You can
use this in conjunction with the Seek method to
pre-allocate a file's space on disk, for greater performance (i.e. seek to
the final size of the file, truncate at that point, and then seek
back to the start and write the data). |
Write |
<blob:source> or
<string:source> |
int |
Writes data from the specified Blob (or array) or string to the file. By default the entire contents of the Blob will be written, but you can use the optional from parameter to specify the source byte offset, and the size parameter to specify the number of bytes to write. A maximum of 1 GB (1073741824 bytes) can be written per call, whether a size is specified or implicit. To write a larger amount of data, you must call Write multiple times. If you provide a string rather than a Blob, the string will be automatically encoded as UTF-8. The return value indicates the number of bytes successfully written to the file. If Write returns zero, you can use the error property to test if anything went wrong or if there was simply no data to write (e.g. the specified Blob was empty). |