Object: SPFile

Method: accessTime

Returns the last access time of the file.

Method: appendLine

Appends a block of ASCII text data to the file and appends a line terminator.

Returns:

Returns true if the write succeeds.

Remarks:

This is the same as writeLine except that if the file already exists and has not been opened explicitly, this method appends the text to the existing file rather than replacing it.

Method: appendText

Appends a block of ASCII text data to the file.

Returns:

Returns true if the write succeeds.

Remarks:

This function behaves like writeText except that if the target file already exists and has not been explicitly opened, this method appends to the end of the existing file rather than replacing it.

Method: archive

Returns the setting of the file's "archive" flag.

Method: close

Closes the file.

Remarks:

It is not normally necessary to call this method explicitly. All files are closed automatically when the SPFile object is destroyed. However, since the exact timing of this event relative to the execution of the script cannot be guaranteed, you should close the file using this method if you need to access it again later in the script, or if you are passing it as data to another application that may be invoked by the same script.

Method: copyTo

Copies the file or folder to the specified destination. If this object is a folder, this attempts to create the folder at the destination and copy all its contents, keeping file dates as in the source as much as possible.

Returns:

Returns true if successful, false if any error

Remarks:

The usage of the destination name is as follows: If this object is a file: If the destination path specifies an existing folder, then the file is copied to that folder with its existing name If the destination path specifies an existing file, then the file is deleted and replaced by the contents of this file If the destination path does not specify an existing object, then this file is copied to a destination file with the given name. If this object is a folder: If the destination path specifies an existing folder, then the contents of this folder are copied to the specified destination. If the destination path specifies an existing file, the file is deleted and a folder is created with the destination name. If the destination path does not specify an existing object, then a folder is created using the destination name and the contents of this folder are copied to it.

Method: create

Creates, or re-creates, the file without opening it. If it is already open, this does nothing. If the file already exists, it is deleted and replaced with a new, empty one.

Returns:

Returns false if any error, true if OK.

Errors:

If the function returns false, you can use lastError or lastErrorString to get more information. If no return value is requested, an exception is generated on error.

Remarks:

WARNING: This deletes any existing file with the same name! To create a file only if it does not already exist, use openReadWrite.

Method: createTime

Returns the create time of the file.

Method: dirDialog

Displays a standard directory selection dialog box and sets the path name in the file object using the result.

Returns:

Returns false if the user clicks the Cancel button, true otherwise

Method: directory

Returns true if the specified name refers to a directory.

Method: duplicate

Makes an exact copy of the file at the specified location.

Property: exists

Returns true if the file exists, false otherwise.

Property: extension

Gets or sets the file name extension.

Remarks:

This method looks for the last dot in the file name and gets or changes only characters after the dot. If you set an extension and the existing name did not contain a dot, one is appended before the new extension.

Property: filePos

Gets or sets the file's current byte offset relative to the start.

Method: fprintf

Generates formatted text output to the file.

Returns:

void

Errors:

Does not generate any error exceptions. If the actual arguments don't match the data required by the format string, default values will be substituted in the output.

Remarks:

This method is used to generate formatted text in the console window using format arguments patterned after the standard C/C++ printf function. Since the formatting arguments are quite extensive, they are described on a separate page printf Formatting. Users familiar with the original C function should note that JavaScript conversions are considerably more general than C. For example, essentially any JavaScript data item can be converted to a string, so "%s" conversion can be used with any data argument to get a default output. IMPORTANT: See the notes regarding how files are opened for writing under the writeBinary method.

Example:

files = getFileList("c:/temp");
writeln("These are the temporary files:");
for (i = 0; i < files.length; i++)
{
    printf("File #%08d is %s", i, files[i].fullName);
}

Method: fullName

Sets or gets the full name, including directory path, of the file.

Returns the full path

Sets the file name and path given a complete path name.

Sets the file name and path given a complete path name

Get the full path

Remarks:

If used as a method with no arguments or a "get" property, this returns the full name, including path, of the file. If used as a method with a string argument or a "set" property, this sets the name associated with this file object. Note that this does not change the name of any file on disk, it only changes the name string of this object. Use rename to rename a file on disk.

If the file is open at the time the name is set, it will be closed.

Method: hidden

Returns the setting of the file's "hidden" flag.

Method: isSameFile

Returns true if the given string represents the same file as this object, taking into account possible variations in letter case and use of forward or backward slashes in the name

Method: lastError

Returns error code generated by the last operation.

Method: lastError

Returns error code generated by the last operation.

Method: length

Returns length of the file.

Method: modifiedTime

Returns the last modified time of the file.

Method: name

Gets or sets the base file name (i.e. without changing the path). This can be used either as a method or property.

Remarks:

If used as a method with an argument or as a set property, this changes the name associated with this file object without setting or changing the directory path. Note that this only changes the name stored with this object, it does not affect any files on disk. Use rename to actually rename the file on disk. If the file was open, this closes it, since it will no longer be associated with the same file.

Method: newerThan

Returns true if this file is newer (more recent modified date) than the given file.

Remarks:

If this file doesn't exist, the function returns false. If the other file doesn't exist, it returns true.

Method: normal

Returns true if no other attributes are true. Since Windows by default sets the "archive" flag in all files, this will rarely be true.

Method: openAppend

Opens the file for read or write access and creates it if it doesn't exist, and sets the initial file position to the end of the file.

Remarks:

This is the same as openReadWrite except that the initial file position is set to the end of the file.

Method: openCreate

Deletes any existing file with the same name and then creates a new, empty file with read/write access.

Method: openDialog

Displays a standard open file dialog box and sets the file name using the result.

Returns:

Returns false if the user clicks the Cancel button, true otherwise

Method: openRead

Opens the file for read-only access.

Method: openReadWrite

Opens the file for read or write access and creates it if it doesn't exist.

Remarks:

If the file does exist, it will be opened for reading and writing. The initial file position will be set to the start of the file, so write methods will overwrite existing data unless you do a seek. To open for appending data use openAppend.

Method: path

Gets or sets the directory path, i.e. the full name of the directory containing the file without the file name itself. This can be used either as a method or property.

Method: readBinary

Reads the contents of the file and returns a byte array containing exactly the contents of the file.

Returns:

Returns an array of bytes containing the data, or null if any error.

Errors:

If any error occurs, the return value will be null and method lastError or lastErrorString can be used to check the error.

Remarks:

If the file was not already open before this call, it will be opened (and left open) in read-only mode. Subsequent reads will continue where this one left off.

Method: readLine

Reads a line of text from the file and returns a string in which ASCII characters in the file have been converted to internal (Unicode) format.

Errors:

If any error occurs, the return value will be null and method lastError or lastErrorString can be used to check the error.

Remarks:

This call accepts any combination of carriage return and line feed as a line terminator.

Method: readOnly

Returns the file's "read only" flag.

Method: readText

Reads the contents of the file and returns a string in which ASCII characters in the file have been converted to internal (Unicode) format.

Errors:

If any error occurs, the return value will be null and method lastError or lastErrorString can be used to check the error.

Method: readTypedData

Reads a single data object from the file and returns the same data type that was used write the object.

// Reads the type and then the data from the file

// Assumes you know the type and reads only the data from the file

Errors:

If any error occurs, the return value will be null and method lastError or lastErrorString can be used to check the error.

Remarks:

If the first form is used, the data must have been written using writeTypedData in order to have the correct type information in the file. In the second form, you are specifying the data type and it reads only the raw data from the file.

Method: relativeName

Gets the name and path of the file relative to the given directory. If the file is not inside the given directory at any level, the full, absolute path is returned. Read Only

Method: remove

Removes the file.

Method: rename

Renames an existing file or a directory (including all its children).

Remarks:

Renames (moves) either a file or a directory (including all its children) either in the same directory or across directories. The only limitation is that the function will fail on directory moves when the destination is on a different volume.

Method: saveDialog

Displays a standard save file dialog box and sets the file name using the result.

Remarks:

All parameters are identical to openDialog.

Method: setAppPath

Sets the path for this file to be in the same folder as the application. If an argument is given, it is used as the file name (optionally with sub-folders). If no argument is given, only the path part of the current file name is changed.

Example:

f = SPFile();
f.name = "test.txt";  // File name is now "test.txt" with no path given
f.setAppPath();         // File name is now "c:\Program Files\Script Pilot\test.txt"
                        // (or wherever the app is located)

g = SPFile();
g.setAppPath("docs/test.doc");  // File name is now c:\Program Files\Script Pilot\docs\test.doc"

h = SPFile();
h.name = "test.txt";  // File name is now "test.txt" with no path given
h.setAppPath("docs/");  // File name is now c:\Program Files\Script Pilot\docs\test.txt"

Method: setDesktopPath

Sets the path for this file to be the Desktop folder for the current user. If an argument is given, it is used as the file name (optionally with sub-folders). If no argument is given, only the path part of the current file name is changed. See setAppPath for more information.

Method: setDocRootPath

Sets the path for this file to be in the same folder that is set to be the document root, that is, where default place where user document files are stored. This is typically c:\Users\xxx\Documents\application_name If an argument is given, it is used as the file name (optionally with sub-folders). If no argument is given, only the path part of the current file name is changed. See setAppPath for more information.

Method: setDocumentsPath

Sets the path for this file to be the "My Documents" folder for the current user. If an argument is given, it is used as the file name (optionally with sub-folders). If no argument is given, only the path part of the current file name is changed. See setAppPath for more information.

Method: setProgramFilesPath

Sets the path for this file to be the Program Files folder on this computer. If an argument is given, it is used as the file name (optionally with sub-folders). If no argument is given, only the path part of the current file name is changed. See setAppPath for more information.

Method: setScriptPath

Sets the path for this file to be in the same folder that contains the current script. If an argument is given, it is used as the file name (optionally with sub-folders). If no argument is given, only the path part of the current file name is changed. Note that some program mechanisms allow a script to be run directly from text in memory, in which case this will be a null value. See setAppPath for more information.

Method: setSystemPath

Sets the path for this file to be the Windows system folder on this computer. If an argument is given, it is used as the file name (optionawlly with sub-folders). If no argument is given, only the path part of the current file name is changed. See setAppPath for more information.

Method: setTempName

Generates a unique file name and path in the system's temporary directory.

Creates a name with the default prefix "temp_" and no extension.

Creates a name with the given prefix and no extension.

Creates a name with the given prefix and extension.

Remarks:

This method generates a file name and directory path to the system's temporary directory. The file name is made unique by adding decimal digits after the given prefix. This call does not open or create the file, it only sets the name associated with this SPFile object.

Method: system

Returns the setting of the file's "system" flag.

Method: title

Gets the title (i.e. the user-visible name) of the file.

Remarks:

If the user has set "hide file extensions" then this will return the name without an extension, otherwise it is the same as name. The title can only be read, it cannot be set.

Property: url

Gets or sets the file name in URL format, e.g. file:///c:\temp\file.txt.

Method: wait

Waits for the file to become available for use.

Returns:

Returns true if the file is no open anywhere else.

Remarks:

This can be called if you have invoked an external application or process to create a file and don't know exactly when it will be available. The function returns true when the file can be opened for exclusive use.

Method: write

Writes to the file. If the given data is a string, data is written out as ASCII text, otherwise it is written as raw binary.

Remarks:

This function behaves like writeText if the argument is a string, otherwise, like writeBinary. IMPORTANT: See the notes regarding how files are opened for writing under the writeBinary method.

Method: writeBinary

Writes a block of binary data to the file.

Returns:

Returns true if successful, false otherwise. If the return value is false, getLastError or getErrorString can be used to get more information on the error.

Errors:

If no return value is requested, an exception will be generated on error.

Remarks:

This method is used to write a block of binary data to the file. Data will be written directly in its internal representation. For example, if you pass a text string as an argument, it will be written as a sequence of Unicode (16-bit) characters. To generate a normal ASCII text file in this case, you need to use writeText.

The exact behaviour of this method depends on how the file is opened. If the file is not opened explicitly or is opened using openCreate, any existing file will be replaced, so all writing will start from the beginning of the new, empty file. If the file is explicitly opened using openReadWrite, then writeBinary will append data at the end of the existing file. This behaviour can be overridden by using the seek method.

Example:

rawData = SPFile("C:/secret stuff.zip").readBinary();
SPFile("C:/secure stuff.dat").writeBinary(encrypt("no one will guess this", rawData));

Method: writeLine

Writes a block of ASCII text data to the file and appends a line terminator.

Returns:

Returns true if the write succeeds.

Remarks:

This is the same as writeText except that it appends a line terminator. IMPORTANT: See the notes regarding how files are opened for writing under the writeBinary method.

Method: writeText

Writes a block of ASCII text data to the file.

Returns:

Returns true if the write succeeds.

Remarks:

This function converts the given string to 8-bit ASCII text with CR/LF line termination and writes it to the file. IMPORTANT: See the notes regarding how files are opened for writing under the writeBinary method.

Method: writeTypedData

Writes a single data object from the file and returns the same data type that was used write the object. NOTE: Only scalar objects (e.g. int, boolean, float) are supported in this version.

Errors:

If any error occurs, the function returns false. If no return value is assigned, an exception is generated.

Remarks:

This function writes out a 4-byte type word, followed by the data itself. It is intended to be read using readTypedData.

See Also: