String AppendMode

 String DOSTermination

 Error E_AlreadyOpen

 Error E_CannotCopyDirs

 Error E_DestAlreadyExists

 Error E_Eof

 Error E_FailedCreatingDest

 Error E_FailedOpeningDest

 Error E_FailedOpeningSource

 Error E_FileSystemError

 Error E_Filename

 Error E_InsufficientMemory

 Error E_Mode

 Error E_ModeError

 Error E_NotADirectory

 Error E_NotEnoughFreeSpace

 Error E_NotOpen

 Error E_NotOpenForBinaryAccess

 Error E_NotOpenForRead

 Error E_NotOpenForWrite

 Error E_NotSameDirectory

 Error E_Open

 Error E_SourceNotFound

 Error E_TargetDirNotFound

 Error E_Write

 Integer FileCopyType

 Integer FileType

 String ReadBinMode

 String ReadMode

 String st_mode

 String st_ino

 String st_dev

 String st_rdev

 String st_nlink

 String st_uid

 String st_gid

 String st_size

 String st_atime

 String st_mtime

 String st_ctime

 String UNIXTermination

 String WriteBinMode

 String WriteMode

 Date pCreateDate

 String pLineTermination

 Date pModifyDate

 Boolean pReadOnly

 Long pSize

 String pType

 String Access(
            String filePath  )

Searches for the specified file.

Parameters:

filePath

-

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.

Returns:

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:

Windows	Application Directory (where the Livelink resides) Working Directory (the “Start-in” directory) %PATH% Windows Directory Windows System Directory
UNIX	Application Directory Working Directory $PATH

 

 Boolean Close(
            File openFile  )

Closes an open file. To avoid resource leaks, close all open files when they are no longer needed. See File.Open().

Parameters:

openFile

-

A File opened by File.Open().

Returns:

A Boolean value where TRUE indicates that the file was successfully closed; Error otherwise.

 Boolean CopyEnd(
             FileCopy operation  )

Ends the file copy operation and closes the File being copied. See File.CopyStart() and File.CopyNext().

Parameters:

operation

-

A FileCopy, as returned by the File.CopyStart function, indicating the file copy operation to end.

Returns:

A Boolean value where TRUE indicates that the operation successfully ended and closed the file.

 Boolean CopyNext(
              FileCopy operation  )

Copies the next block in the specified file copy operation. See File.CopyStart() and File.CopyEnd().

Parameters:

operation

-

A FileCopy value, as returned by File.CopyStart(), indicating the file copy operation to continue.

Returns:

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.

 FileCopy CopyStart(
               Dynamic source,
               Dynamic destination,
              [Integer blockSize] )

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().

Parameters:

source	-	Either a File, as returned by File.StringToFile(), or a String indicating the file to be copied.
destination	-	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.
blockSize	-	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.

Returns:

A FileCopy identifying the file copy operation, if successful; Error otherwise.

 Boolean Create(
             Dynamic newFile  )

Creates an empty text file or directory. The newly created file must be opened by File.Open() before it can be used.

Parameters:

newFile

-

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\).

Returns:

A Boolean value where TRUE indicates that the file or directory was created.

 Boolean Delete(
             Dynamic delFile  )

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.

Parameters:

delFile

-

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.

Returns:

A Boolean value where TRUE indicates that the file or directory was successfully deleted.

 String Dir(
         [String directory] )

Returns the name of the current directory and changes it if a new directory is specified.

Parameters:

directory

-

An optional String indicating the new current directory. If not specified, the current directory will not be changed.

Returns:

A String indicating the current directory. If a new directory was specified, the original directory is returned.

 Boolean Eof(
           File openFile )

Determines whether the current file position is at the end of file.

Parameters:

openFile

-

A File opened by File.Open().

Returns:

A Boolean value where TRUE indicates that the current file position is at the end of file.

 Boolean Exists(
             Dynamic theFile )

Determines if the specified file or directory exists.

Parameters:

theFile

-

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.

Returns:

A Boolean value where TRUE indicates that the specified file or directory exists.

 List FileList(
          [String directory] )

Returns a List of all of the files in the specified directory.

Parameters:

directory

-

An optional String indicating the directory whose files are to be listed. Defaults to the current directory if not specified.

Returns:

A List containing String elements, each of which is the name of a file in the specified directory.

 String FileToString(
               File theFile )

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.

Parameters:

theFile

-

A File, as returned by File.StringToFile or File.Open(), referencing the File to be converted to a String.

Returns:

A String specifying the name of the file, including any supplied path information.

 Dynamic Flush(
            File theFile )

Flushes the file buffer.

Parameters:

theFile

-

A File, as returned by File.StringToFile() or File.Open().

Returns:

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.

 Long FreeSpace(
         [String target] )

Returns the number of free bytes in the target directory, or the current directory.

Parameters:

target

-

An optional String indicating the target directory. If not specified, the current directory will be the target.

Returns:

A Long indicating the number of free bytes in the directory.

 String GetName(
            Dynamic theFile )

Returns the file name of a File, not including the path.

Parameters:

theFile

-

Either a File, as returned by File.StringToFile() or File.Open(), referencing the desired file or a String indicating the name of the file.

Returns:

A String containing the file name (file and extension), not including the path.

 String GetPath(
            Dynamic myFile )

Returns the directory specification for a file.

Parameters:

myFile

-

Either a File, as returned by File.StringToFile() or File.Open(), referencing the desired file or a String indicating the name of the file.

Returns:

A String containing only the path name, including a directory separator. Returns an empty String if the myFile parameter does not specify a path.

 Boolean IsDir(
            String directory )

Determines whether the supplied String represents an existing directory.

Parameters:

directory

-

A String indicating the directory name.

Returns:

A Boolean value where TRUE indicates that the directory parameter specifies an existing directory.

 Boolean IsDirSpec(
              String directory )

Determines whether the last character of the supplied String is a directory separator.

Parameters:

directory

-

A String to test.

Returns:

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.

 Boolean IsText(
             Dynamic theFile )

Determines if the specified file is a text file.

Parameters:

theFile

-

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.

Returns:

A Boolean value where TRUE indicates that the specified file has a txt extension.

 Integer LineTermination(
                 File theFile,
                 String terminator )

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.

Parameters:

theFile	-	A File, as returned by File.StringToFile() or File.Open(), referencing the File on which to operate.
terminator	-	A String constant indicating the type of line termination to use.

Returns:

A String specifying the line termination character string, identical to the String provided in the terminator parameter.

 Integer NextBlock(
              FileCopy operation )

Returns the ordinal number of the next file block to be copied.

Parameters:

operation

-

A FileCopy, as returned by File.CopyStart(), indicating the desired file copy operation.

Returns:

An Integer specifying the number of the next block to be copied.

 Integer NumBlocks(
              FileCopy operation )

Returns the number of file blocks to be copied.

Parameters:

operation

-

A FileCopy value, as returned by File.CopyStart(), indicating the desired file copy operation.

Returns:

An Integer specifying the total number of blocks to be copied.

 File Open(
         Dynamic theFile,
         String mode )

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.

Parameters:

theFile	-	Either a File, as returned by File.StringToFile(), or a String indicating a file name and an optional path to the desired file.
mode	-	A mode constant indicating the operation to be performed on the open file.

Returns:

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().

 File OpenStream(
            Dynamic theFile,
            String mode )

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().

Parameters:

theFile	-	The stream File to open, which should be either a String specifying the file, or a File as from File.FileToString().
mode	-	A mode constant (File.ReadMode, etc.) indicating the operation to be performed on the file.

Returns:

The newly opened file if successful; Error otherwise.

For an example, see File.ReadValue().

 String Read(
           File theFile,
          [Integer numChars] )

Reads one line from a text file.

Parameters:

theFile	-	A File, as returned by File.Open(), referencing a file that was opened for a normal, and not binary, read operation.
arg2	-	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.

Returns:

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.

 Bytes ReadBytes(
            File theFile,
            Integer numBytes )

Reads and returns a block of Bytes data from the specified File.

Parameters:

theFile	-	A File, opened with File.Open() in File.ReadBinMode, from which to read.
numBytes	-	Specifies an Integer indicating the number of bytes to read, up to a maximum of 32K.

Returns:

The number of Bytes read; Error otherwise.

The specified File must be opened by File.Open() with the mode parameter set to File.ReadBinMode.

 String ReadUntil(
             File theFile,
             String delimiter )

Reads a stream File until the specified delimiter is found.

Parameters:

theFile	-	The stream File from which to read, as opened by File.OpenStream().
delimiter	-	A character delimiter which stops reading when encountered.

Returns:

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.

 Dynamic ReadValue(
              File theFile )

Reads an OScript Value from a stream File.

Parameters:

theFile

-

A stream file, as opened with File.OpenStream(), from which one OScript value, as written by File.WriteValue(), is read.

Returns:

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.

 Boolean Rename(
             Dynamic theFile,
             Dynamic name )

Renames the specified file.

Parameters:

theFile	-	Either a File, as returned by File.StringToFile(), or a String specifying the name of the file to rename.
name	-	Either a File, as returned by the File.StringToFile function, or a String specifying the new file name.

Returns:

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.

 Boolean Rewind(
             File theFile )

Sets the file read/write pointer back to the start of the file.

Parameters:

theFile

-

Specifies a File, as returned by File.Open(), indicating the File to rewind.

Returns:

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.

 Integer Seek(
            File theFile,
            Integer newPosition )

Set the file position pointer to a new position.

Parameters:

theFile	-	A File, as returned by File.Open() with mode File.ReadBinMode.
newPosition	-	The new position that the read/write position pointer should be set to.

Returns:

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.

 String Separator()

Returns the operating system-dependent character used to separate directories in a path specification.

Returns:

The system-dependent directory separator character.

 File SetName(
          File theFile,
          String newName )

Sets the name of a file (but not the extension).

Parameters:

theFile	-	A File, as returned by File.StringToFile(), of the file to be named.
newName	-	A String indicating the new name of the file.

Returns:

A File reference to the modified file if successful; Error otherwise.

 String StartupDir()

Returns the full path of the Livelink start-up directory.

Returns:

A String indicating the directory from which the currently executing process was started.

 Assoc Stat(
             Dynamic statFile  )

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).

Parameters:

statFile

-

Either a File, as returned by File.StringToFile(), referencing the desired file, or a String indicating the file or directory.

Returns:

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.

 File StringToFile(
             String fileSpec )

Converts a file specification String to an OScript file reference. See File.FileToString().

Parameters:

fileSpec

-

Specifies a String file specification that can optionally contain path information.

Returns:

A File referencing the specified file.

 String SystemDir()

Returns the name of the System directory.

Returns:

The operating system-dependent system directory.

The directory returns depends upon the current platform:

Windows	Windows NT system directory
UNIX	HOME directory of the currently running process

 

 String ThreadDir(
            [String directory] )

Sets or queries the current working directory for the this thread.

Parameters:

directory

-

Specifies an optional String identifying the desired working directory. Defaults to the working directory of the currently executing thread if not specified.

Returns:

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.

 Boolean Write(
            File theFile,
            String text )

Writes the specified text to a text file.

Parameters:

theFile	-	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.
text	-	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.

Returns:

A Boolean value where TRUE indicates that the text was successfully written.

 

The file may be a stream file in either binary or text mode. The write pointer is set to the start of the line after the text is written. For an example, see File.Read().

 Integer WriteBytes(
               File theFile,
               Bytes value )

Writes the contents of Bytes to the specified file and returns the number of bytes written.

Parameters:

theFile	-	A File, opened with either File.Open() or File.OpenStream() with mode File.WriteBinMode, to which the Bytes are to be written.
value	-	A Bytes value indicating the binary data to be written to the file.

Returns:

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.

 Dynamic WriteValue(
               File theFile,
               Dynamic value )

Writes an OScript Value to the specified stream File.

Parameters:

theFile	-	A stream file, as opened with File.OpenStream() and either mode File.WriteMode or File.WriteBinMode, to which the specified value will be written.
value	-	An OScript value which will be written to the File for later reading with File.ReadValue().

Returns:

Undefined if successful; Error otherwise.

For an example, see File.ReadValue().