| |
OScript API/Built-in Package Index |
The File Package offers a set of built-in functions for handling the OScript File data type which is used to reference and access files in the file system. The File Package facilitates file and directory creation, deletion, directory traversal, and searching, as well as the usual reading and writing functions.
A file may opened for read or write in either normal text mode, or binary mode. Files also come in two types, standard (as opened with File.Open()) and stream files (as opened with File.OpenStream()) which differ in that stream files behave as streams or pipes, and thus are not traversable (as with File.Seek() or File.Rewind()), and while the content readable from them can be exhausted for a given time, there is no "end" until the stream is closed, since, as with C's STDIN, there is always the potential for more input waiting, even if it is not present. Certain read and write functions operate on only stream files, while others operate on normal files, and some operate on both. See File.OpenStream() for further details.
The major functionalities offered in the File Package are the following:
Passed to File.Write() to open the file in Append mode; sets the write pointer to the end of the file.
Passed to File.LineTermination() to specify that DOS line termination be used.
Error returned by File.Open() indicating that the specified file is currently open.
Error returned by File.CopyStart() indicating that the specified directory is a source directory.
Error returned by File.CopyStart() indicating that the specified destination file already exists.
Error returned by File.Read() and File.CopyNext() indicating that the end of the file has been reached.
Error returned by File.CopyStart() indicating that a problem occurred while creating the destination file.
Error returned by File.CopyStart() indicating that an error occurred while attempting to open the specified destination file.
Error returned by File.CopyStart() indicating that an error occurred while attempting to open the specified source file.
Error returned by functions that require a File specification indicating that a file name was not specified or that bad file name syntax was used.
Error returned by various File built-in functions indicating that an internal File system error occurred.
Error returned by File.CopyNext() or File.Read() indicating that there is not enough memory to perform the read or copy operation.
Error returned by File.Open() indicating that an illegal open option was specified.
Error returned by various File built-in functions indicating that the File being acted upon should be a stream, as opened with File.OpenStream(), but is not, or vice versa.
Error returned by various File built-in functions indicating that the specified directory is invalid.
Error returned by File.CopyStart() indicating that there is not enough disk space to place a file in the specified location.
Error returned by File.Open() indicating that the specified file is not open.
Error returned indicating that the file being operated on is not in binary mode.
Error returned by File.Read() indicating that the File.ReadMode or File.ReadBinMode constant was not passed as the mode parameter to File.Open().
Error returned by File.Write() indicating that the File.WriteMode or File.WriteBinMode constant was not passed as the mode parameter to File.Open().
Error returned by File.Rename() indicating that the specified directory is different than the original file directory.
Error returned by File.Open() indicating that the specified file could not be opened.
Error returned by File.CopyStart() indicating that the specified source file cannot be located.
Error returned by File.CopyStart() indicating that the target directory cannot be located or does not exist.
Error returned by File.Write() or File.WriteBytes() indicating that there was an error writing to the file.
Specifies a value of type FileCopy.
Specifies a value of type File.
Indicates that the amount of freespace is too big.
Passed to File.Lock(); opens for writing at the end of the file (appending).
Passed to File.Lock(); opens the file for reading and appending.
Passed to File.Lock(); opens the file for reading.
Passed to File.Lock(); opens an empty file for reading and writing.
Passed to File.Lock(); opens the file for reading and writing.
Passed to File.Lock(); opens the file for writing.
Passed to File.Open(); opens the file for reading in binary mode.
Passed to File.Open(); opens the file for reading in text mode.
Used as an index in the Assoc returned by Stat().
Used as an index in the Assoc returned by Stat().
Used as an index in the Assoc returned by Stat().
Used as an index in the Assoc returned by Stat().
Used as an index in the Assoc returned by Stat().
Used as an index in the Assoc returned by Stat().
Used as an index in the Assoc returned by Stat().
Used as an index in the Assoc returned by Stat().
Used as an index in the Assoc returned by Stat().
Passed to File.LineTermination(); sets line termination to UNIX line termination.
Passed to File.Open(); opens the file for writing in binary mode.
Passed to File.Open(); opens the file for writing in text mode.
Date and time on which the file was created.
Line terminator currently set for the file. This feature defaults to the appropriate value for the platform from which the file is obtained. The File.DOSTermination and File.UNIXTermination constants are available for use with this property.
The date and time on which the file was most recently modified.
DOS read only file attribute.
The size (in bytes) of the file.
The file type.
Searches for the specified file.
Closes an open file.
Ends the file copy operation and closes the File being copied.
Copies the next block in the specified file copy operation.
Begins a file copy operation.
Creates an empty text file or directory.
Deletes the specified file or directory.
Returns the name of the current directory, and changes it if a new directory is specified.
Determines whether the current file position is at the end of file.
Determines if the specified file or directory exists.
Returns a List of all of the files in the specified directory.
Converts a File reference to a String.
Flushes the file buffer.
Returns the number of free bytes in the given directory, or number of free bytes in the current directory if no directory is specified.
Returns the permissions of the specified file.
Returns the file name, not including path, of a file.
Returns the directory specification path of a file ending in File.Separator() and not including the file's name.
Determines whether the supplied String represents an existing directory when the object being tested is accessible.
Determines whether the last character of the supplied String is a directory separator.
Determines if the specified file is a text file.
Specifies the type of line termination to use when writing to a text file.
Locks a physical text file.
Returns the ordinal number of the next file block to be copied.
Returns the number of file blocks to be copied.
Opens a text file in preparation for an append, read, or write operation.
Opens a file as a stream file.
Reads one line from a text file.
Reads and returns a block of Bytes data from the specified File.
Read file until the delimiter is found.
Read an OScript Value from a file.
Renames the specified file.
Sets the file read/write pointer back to the start of the file.
Set the file position pointer to a new position.
Returns the operating system-dependent character used to separate directories in a path specification.
Sets the specified file permission to the specified file.
Sets the name of a file.
Returns the full path of the Livelink start-up directory.
Get an Assoc of the file status for the given file.
Converts a file specification String to an OScript file reference.
Returns the name of the System directory.
Returns or optionally sets the working directory for the currently executing thread.
Unlocks a physical text file.
Writes the specified text to a text file.
Writes the contents of Bytes to the specified file and returns the number of bytes written.
Writes an OScript Value to a file.
Passed to File.Write() to open the file in Append mode; sets the write pointer to the end of the file.
Passed to File.LineTermination() to specify that DOS line termination be used.
Error returned by File.Open() indicating that the specified file is currently open.
Error returned by File.CopyStart() indicating that the specified directory is a source directory.
Error returned by File.CopyStart() indicating that the specified destination file already exists.
Error returned by File.Read() and File.CopyNext() indicating that the end of the file has been reached.
Error returned by File.CopyStart() indicating that a problem occurred while creating the destination file.
Error returned by File.CopyStart() indicating that an error occurred while attempting to open the specified destination file.
Error returned by File.CopyStart() indicating that an error occurred while attempting to open the specified source file.
Error returned by functions that require a File specification indicating that a file name was not specified or that bad file name syntax was used.
Error returned by various File built-in functions indicating that an internal File system error occurred.
Error returned by File.CopyNext() or File.Read() indicating that there is not enough memory to perform the read or copy operation.
Error returned by File.Open() indicating that an illegal open option was specified.
Error returned by various File built-in functions indicating that the operation requires a stream File as opened with File.OpenStream() instead of a regular file as opened with File.Open(), or vice versa.
Error returned by various File built-in functions indicating that the specified directory is invalid.
Error returned by File.CopyStart() indicating that there is not enough disk space to place a file in the specified location.
Error returned by File.Open() indicating that the specified file is not open.
Error returned by File.ReadBytes(), File.WriteBytes(), or File.Seek() indicating that the File being operated upon is not in binary mode as required.
Error returned by File.Read() indicating that File.ReadMode or File.ReadBinMode was not passed as the mode parameter to File.Open().
Error returned by File.Write() indicating that File.WriteMode or File.WriteBinMode was not passed as the mode parameter to File.Open().
Error returned by File.Rename() indicating that the specified directory is different than the original file directory.
Error returned by File.Open() indicating that the specified file could not be opened.
Error returned by File.CopyStart() indicating that the specified source file cannot be located.
Error returned by File.CopyStart() indicating that the target directory cannot be located or does not exist.
Error returned by File.Write() or the File.WriteBytes function indicating that there was an error writing to the file.
The type number for a value of type FileCopy.
The type number for a value of type File.
The value that can be returned by FreeSpace() if the amount of freespace exceeds the size of the largest Integer.
Passed to File.Lock(); opens for writing at the end of the file (appending); creates the file first if it does not exist.
Passed to File.Lock(); opens the file for reading and appending; creates the file first if it does not exist.
Passed to File.Lock(); opens the file for reading. The file must exist.
Passed to File.Lock(); opens an empty file for reading and writing. If the file already exists, its contents are destroyed.
Passed to File.Lock(); opens the file for reading and writing. The file must exist.
Passed to File.Lock(); opens an empty file for writing. If the file already exists, its contents are destroyed.
Passed to File.Open(); opens the file for reading in binary mode.
Passed to File.Open(); opens the file for reading in text mode.
Constant used as an index in the Assoc returned by Stat().
Constant used as an index in the Assoc returned by Stat().
Constant used as an index in the Assoc returned by Stat().
Constant used as an index in the Assoc returned by Stat().
Constant used as an index in the Assoc returned by Stat().
Constant used as an index in the Assoc returned by Stat().
Constant used as an index in the Assoc returned by Stat().
Constant used as an index in the Assoc returned by Stat().
Constant used as an index in the Assoc returned by Stat().
Constant used as an index in the Assoc returned by Stat().
Passed to File.LineTermination(); sets line termination to UNIX line termination.
Passed to File.Open(); opens the file for writing in binary mode.
Passed to File.Open(); opens the file for writing in text mode.
Date and time on which the file was created.
Not used.
Line terminator currently set for the file. This feature defaults to the appropriate value for the platform from which the file is obtained. The File.DOSTermination and File.UNIXTermination constants are available for use with this property.
The date and time on which the file was most recently modified.
DOS read-only file attribute.
Always return 0.
The size (in bytes) of the file.
The file type.
Searches for the specified file.
A String indicating the local file path and file name. The path can be specified in full or partially. The name of the file (for example, MYFILE.TXT) must be specified.
The full file path of the specified file, if found; Undefined otherwise.
If only a partial file path is specified, the search is performed in the following order:
Closes an open file. To avoid resource leaks, close all open files when they are no longer needed. See File.Open().
A File opened by File.Open().
A Boolean value where TRUE indicates that the file was successfully closed; Error otherwise.
Ends the file copy operation and closes the File being copied. See File.CopyStart() and File.CopyNext().
A FileCopy, as returned by the File.CopyStart function, indicating the file copy operation to end.
A Boolean value where TRUE indicates that the operation successfully ended and closed the file.
Copies the next block in the specified file copy operation. See File.CopyStart() and File.CopyEnd().
A FileCopy value, as returned by File.CopyStart(), indicating the file copy operation to continue.
TRUE if there are more file blocks to copy, File.E_Eof if the last block was copied; or another Error if an error occurred in the file copy process.
Begins a file copy operation. This function fails and returns Error if the file specified by the destination parameter exists. Use File.Exists() to determine if the file exists before proceeding with File.CopyStart(). See File.CopyNext() and File.CopyEnd().
Either a File, as returned by File.StringToFile(), or a String indicating the file to be copied.
Either a File, as returned by File.StringToFile(), or a String indicating the path and file name of the file to be copied to the source file.
An optional Integer indicating the size, in bytes, of the file blocks to be copied. Defaults to a block size of 16K if not specified.
A FileCopy identifying the file copy operation, if successful; Error otherwise.
Creates an empty text file or directory. The newly created file must be opened by File.Open() before it can be used.
Either a file or directory, as returned by File.StringToFile(), or a String indicating the file or directory (including full path specification) to be created. Defaults to the current directory if no path is specified. A directory is created if the operating system-specific directory separator is included in newFile (for example, TEMP).
A Boolean value where TRUE indicates that the file or directory was created.
Deletes the specified file or directory. No confirmation dialog box is displayed before the specified file or directory is deleted. The File.Delete function fails and returns FALSE if the specified directory is not empty. The File.Delete function will fail if the file being deleted was opened by File.Open(). If the file is open, it must be closed by File.Close() before it can be deleted.
Either a File, as returned by File.StringToFile(), referencing the desired file, or a String indicating the file or directory to be deleted. Defaults to the current directory if no path is specified.
A Boolean value where TRUE indicates that the file or directory was successfully deleted.
Returns the name of the current directory and changes it if a new directory is specified.
An optional String indicating the new current directory. If not specified, the current directory will not be changed.
A String indicating the current directory. If a new directory was specified, the original directory is returned.
Determines whether the current file position is at the end of file.
A File opened by File.Open().
A Boolean value where TRUE indicates that the current file position is at the end of file.
Determines if the specified file or directory exists.
Either a File, as returned by File.FileToString(), referencing the desired file or directory, or a String indicating the name of the file or directory. Defaults to the current directory if no path is specified.
A Boolean value where TRUE indicates that the specified file or directory exists.
Returns a List of all of the files in the specified directory.
An optional String indicating the directory whose files are to be listed. Defaults to the current directory if not specified.
A List containing String elements, each of which is the name of a file in the specified directory.
Converts a File reference to a String. This function is the converse of File.StringToFile(), and not Str.FileToString(), in that it does nothing regarding the contents of a file, but rather it only returns the file name with appropriate path information as related to an open File.
A File, as returned by File.StringToFile or File.Open(), referencing the File to be converted to a String.
A String specifying the name of the file, including any supplied path information.
Flushes the file buffer.
A File, as returned by File.StringToFile() or File.Open().
Undefined if successful, or an Error if the operation failed.
If the file is open for output, Flush() writes the contents of the buffer to that file. If the file is open for input, Flush() clears the contents of the buffer.
Returns the number of free bytes in the target directory, or the current directory.
An optional String indicating the target directory. If not specified, the current directory will be the target.
A Long indicating the number of free bytes in the directory.
Returns the permissions of the specified file.
The file path.
The permission settings on the file if successful; 0 (zero) otherwise.
Returns the file name of a File, not including the path.
Either a File, as returned by File.StringToFile() or File.Open(), referencing the desired file or a String indicating the name of the file.
A String containing the file name (file and extension), not including the path.
Returns the directory specification for a file.
Either a File, as returned by File.StringToFile() or File.Open(), referencing the desired file or a String indicating the name of the file.
A String containing only the path name, including a directory separator. Returns an empty String if the myFile parameter does not specify a path.
Determines whether the supplied String represents an existing directory when the object being tested is accessible.
A String indicating the directory name.
A Boolean value where TRUE indicates that the directory parameter specifies an existing directory. Note that the function would also return FALSE when the object being tested is not accessible due to various reasons (e.g., network failure, insufficient permissions).
Determines whether the last character of the supplied String is a directory separator.
A String to test.
A Boolean value where TRUE indicates that the last character of the supplied String is the system-dependent directory separator. This function does not check for the existence of the specified directory.
Determines if the specified file is a text file.
Either a File, as returned by File.StringToFile() or File.Open(), referencing the desired file or a String indicating the name of the file. Defaults to the current directory if no path is specified.
A Boolean value where TRUE indicates that the specified file has a txt extension.
Alters the system-dependent default line termination used by File.Write() for a given File. This allows text files to be created for use on different platforms. This function alters the system-dependent default line termination used by File.Write(). This allows text files to be created for use on different platforms.
A File, as returned by File.StringToFile() or File.Open(), referencing the File on which to operate.
A String constant indicating the type of line termination to use.
A String specifying the line termination character string, identical to the String provided in the terminator parameter.
Checks if the calling process can immediately lock a physical text file (that is, the file is not already locked). If so, this function locks the file. Otherwise, this function waits until it can acquire the lock, and does so then.
A String indicating the path and file name of the desired file.
A mode constant indicating the mode in which to open the file to lock.
If the function successfully locked the file, it returns a File representing the file. Otherwise, it returns an Error.
Returns the ordinal number of the next file block to be copied.
A FileCopy, as returned by File.CopyStart(), indicating the desired file copy operation.
An Integer specifying the number of the next block to be copied.
Returns the number of file blocks to be copied.
A FileCopy value, as returned by File.CopyStart(), indicating the desired file copy operation.
An Integer specifying the total number of blocks to be copied.
Opens a text file in preparation for an append, read, or write operation. Note that the file is not opened as a stream file, as with File.OpenStream(), and certain read and write operations, such as File.ReadValue(), File.ReadUntil(), and File.WriteValue() require a stream file.
Either a File, as returned by File.StringToFile(), or a String indicating a file name and an optional path to the desired file.
A mode constant indicating the operation to be performed on the open file.
A File representing the open file if successful; Error otherwise.
If the file was opened for write (File.Open() mode = File.WriteMode), the write pointer is positioned at the beginning of the file, all text currently in the file is deleted. If the file was opened for append (File.Open() mode = File.AppendMode), the write pointer is positioned at the end of the file. If the specified file does not exist and either the File.AppendMode or File.WriteMode constant is specified, the file is automatically created and then opened.
The File.Open function may fail if the specified file cannot be found, if the required operating system-specific permissions are not set, or if there is insufficient memory to open the file. Each successful call to the File.Open function should be followed with a subsequent File.Close() once the file is no longer needed.
For an example, See File.Read().
Similar to File.Open(), except that the file is opened as a stream file. A stream file differs from a regular file in that behaves as a stream, pipe, socket, or C's STDIN. Because of this cannot be traversed (File.Seek() and File.Rewind() are not supported on stream files) and, while its input can be exhausted, File.Eof() does not apply in practice, since there is no "end" to the stream since the potential for more input exists while the stream is open. Various other operations are not supported for streams, such as File.Read() or File.ReadBytes(). Meanwhile, other operations are available only to stream files, such as File.ReadUntil(), File.ReadValue(), and File.WriteValue().
The stream File to open, which should be either a String specifying the file, or a File as from File.FileToString().
A mode constant (File.ReadMode, etc.) indicating the operation to be performed on the file.
The newly opened file if successful; Error otherwise.
For an example, see File.ReadValue().
Reads one line from a text file.
A File, as returned by File.Open(), referencing a file that was opened for a normal, and not binary, read operation.
An optional Integer indicating the number of characters to read. If not included, one line, as determined by an operating system-specific line delimiter, is read. To read a line that is longer than the default of 1024 characters, specify a value between 1024 and 65,534 inclusive. Values outside of this range will be ignored.
A String containing one line of the File (not including the line delimiter) if successful; Error otherwise.
The specified File must be opened by File.Open() with the mode parameter set to File.ReadMode. After execution, Read() sets the read pointer to the next character. Here is an example:
String fname = "c:/tmp/somefile.txt" File f = File.Open( fname, File.WriteMode ) File fr String s = "" File.Write( f, "This is some text." ) File.Write( f, "This is some more text." ) File.Close( f ) fr = File.Open( fname, File.ReadMode ) if ( !IsError( fr ) ) for ( s = File.Read( fr ); \ s != File.E_Eof; \ s = File.Read( fr ) ) Echo( s ) end File.Close( fr ) end
The output of the example is:
This is some text. This is some more text.
Reads and returns a block of Bytes data from the specified File.
A File, opened with File.Open() in File.ReadBinMode, from which to read.
Specifies an Integer indicating the number of bytes to read, up to a maximum of 32K.
The number of Bytes read; Error otherwise.
The specified File must be opened by File.Open() with the mode parameter set to File.ReadBinMode.
Reads a stream File until the specified delimiter is found.
The stream File from which to read, as opened by File.OpenStream().
A character delimiter which stops reading when encountered.
A String if no error resulted, which will be the characters read either up to and including delimiter if it is found, or until the stream is exhausted. The File must be a stream, as opened with File.OpenStream(), otherwise File.E_NotOpenForBinaryAccess is returned.
Reads an OScript Value from a stream File.
A stream file, as opened with File.OpenStream(), from which one OScript value, as written by File.WriteValue(), is read.
The value read, or Undefined if there was nothing on the stream to read, or File.E_ModeError if the File is not a stream as opened with File.OpenStream().
File.ReadValue() can only be used on a stream. ReadValue() may return unpredictable results if the value read was not written with File.WriteValue(). Here is an example:
String fname = "c:/tmp/somefile.txt" File f = File.OpenStream( fname, File.WriteMode ) File fr String s File.WriteValue( f, "This is some text." ) File.WriteValue( f, 6 ) File.WriteValue( f, { 8, Date.Now(), 4.7, "blue" } ) File.WriteValue( f, "This is some more text." ) File.Close( f ) fr = File.OpenStream( fname, File.ReadMode ) if ( !IsError( fr ) ) while IsDefined( s = File.ReadValue( fr ) ) Echo( s ) end File.Close( fr ) end
The output of the example is:
This is some text. 6 {8,D/1998/9/2:2:7:16,G4.7,'blue'} This is some more text.
Renames the specified file.
Either a File, as returned by File.StringToFile(), or a String specifying the name of the file to rename.
Either a File, as returned by the File.StringToFile function, or a String specifying the new file name.
A Boolean value where TRUE indicates that the file was successfully renamed.
A full path for the file to be renamed can be specified, but the same path must be specified in the new file name. This function cannot be used to move a file from one directory to another. This function will fail if the name parameter specifies an existing file.
Sets the file read/write pointer back to the start of the file.
Specifies a File, as returned by File.Open(), indicating the File to rewind.
A Boolean value where TRUE indicates that the pointer was successfully moved to the start of the file.
If a File that has already been written to is rewound, the next write operation is performed at the beginning of the File, thus overwriting any previously written text.
Set the file position pointer to a new position.
A File, as returned by File.Open() with mode File.ReadBinMode.
The new position that the read/write position pointer should be set to.
The new position of the file position pointer, or an error if the file was not opened, or the mode is not File.ReadBinMode, or the file is a stream file.
Returns the operating system-dependent character used to separate directories in a path specification.
The system-dependent directory separator character.
Sets the specified file permission to the specified file.
The file path.
Permission setting for the file.
true if successful, false else.
Sets the name of a file (but not the extension).
A File, as returned by File.StringToFile(), of the file to be named.
A String indicating the new name of the file.
A File reference to the modified file if successful; Error otherwise.
Returns the full path of the Livelink start-up directory.
A String indicating the directory from which the currently executing process was started.
Returns the status of the specified file or directory. This is intended to be used by those who are familiar with the ANSI stat function. It will return an Assoc of values for platform-specific status information. Constants are available to use as keys into the returned Assoc (see below).
Either a File, as returned by File.StringToFile(), referencing the desired file, or a String indicating the file or directory.
An Assoc of the status values on success; undefined otherwise.
The valid key values are StatFileMode, StatInodeNumber, StatDeviceID, StatRDevice, StatNumberLinks, StatUserID, StatGroupID, StatSize, StatLastAccessTime, StatLastModifyTime, and StatLastChangeTime.
Converts a file specification String to an OScript file reference. See File.FileToString().
Specifies a String file specification that can optionally contain path information.
A File referencing the specified file.
Returns the name of the System directory.
The operating system-dependent system directory.
The directory returns depends upon the current platform:
Sets or queries the current working directory for the this thread.
Specifies an optional String identifying the desired working directory. Defaults to the working directory of the currently executing thread if not specified.
A String indicating the current thread directory. If the directory parameter was specified, the String returned indicates the previous thread directory before execution of this function.
Note: different threads can have different working directories.
Unlocks a physical text file.
A File indicating the desired file.
A Boolean value where TRUE indicates that the file was successfully unlocked; FALSE otherwise.
Writes the specified text to a text file.
Specifies a File, as returned by either File.Open() or File.OpenStream(), referencing a file that is open for write or append in either File.WriteMode or File.WriteBinMode.
Specifies the String to be written to the file. It can contain multiple line delimiters if multiple lines are to be written. Once written, an operating system-specific line delimiter is automatically appended to the end of the specified String.
A Boolean value where TRUE indicates that the text was successfully written.
Writes the contents of Bytes to the specified file and returns the number of bytes written.
A File, opened with either File.Open() or File.OpenStream() with mode File.WriteBinMode, to which the Bytes are to be written.
A Bytes value indicating the binary data to be written to the file.
The number of bytes written; Error otherwise.
The specified File may be a stream file, but it must be opened with mode File.WriteBinMode. The function can return the error File.E_NotOpenForBinaryAccess if specified file is open but not in File.WriteBinMode, or File.E_NotOpen if specified file is not open.
Writes an OScript Value to the specified stream File.
A stream file, as opened with File.OpenStream() and either mode File.WriteMode or File.WriteBinMode, to which the specified value will be written.
An OScript value which will be written to the File for later reading with File.ReadValue().
Undefined if successful; Error otherwise.
For an example, see File.ReadValue().
| Copyright © 2023 OpenText Corporation. All rights reserved. |