An object that provides byte-level access to files and contains various file directory methods.

Syntax

[<oRef> =] new File( )

<oRef>

A variable or property in which to store a reference to the newly created File object.

Properties

The following tables list the properties and methods of the File class. (No events are associated with this class.)

Property

Default

Description

baseClassName

FILE

Identifies the object as an instance of the File class

className

(FILE)

Identifies the object as an instance of a custom class. When no custom class exists, defaults to baseClassName

handle

1

Operating system file handle

path

 

Full path and file name for open file

position

0

Current position of file pointer, relative to the start of the file

 

Method

Parameters

Description

accessDate( )

<filename expC>

Returns the last date a file was opened

close( )

 

Closes the currently open file

copy( )

<filename expC>
, <new name expC>

Makes a copy of the specified file

create( )

<filename expC>
[,<access rights>]

Creates a new file with optional access attributes

createDate( )

<filename expC>

Returns the date when the file was created

createTime( )

<filename expC>

Returns the time a file was created as a string

date( )

<filename expC>

Returns the date the file was last modified

delete( )

<filename expC>

Deletes the specified file

eof( )

 

Returns true or false indicating if the file pointer is positioned past the end of the currently open file

error( )

 

Returns a number indicating the last error encountered

exists( )

<filename expC>

Returns true or false to indicate whether the specified disk file exists

flush( )

 

Writes current data in the file buffer to disk and keeps file open

gets( )

[<chars read expN>]
[, <eol expC>]

Reads and returns a line from a file, leaving the file pointer at the beginning of the next line. Same as readln( )

open( )

<filename expC>
[,<access rights>]

Opens an existing file with optional access attributes

puts( )

<input string expC>
[, <max chars expN>
[, <eol expC>]

Writes a character string and end-of-line character(s) to a file. Same as writeln( )

read( )

<characters expN>

Reads and returns the specified number of characters from the file starting at the current file pointer position. Leaves the file pointer at the character following the last one read.

readln( )

[<chars read expN>]
[, <eol expC>]

Reads and returns a line from a file, leaving the file pointer at the beginning of the next line. Same as gets( ).

rename( )

<filename expC>
, <new name expC>

Changes the name of the specified file to a new name

seek( )

<offset expN>
[, 0 | 1 | 2 ]

Moves the file pointer the specified number of bytes within a file, optionally allowing the movement to be from the beginning (0), end (2), or current file position (1)

shortName( )

<filename expC>

Returns the short (8.3) name for a file

size( )

<filename expC>

Returns the number of bytes in the specified file

time( )

<filename expC>

Returns the time the file was last modified as a string

write( )

<expC>
[, <max chars expN>]

Writes the specified string into the file at the current file position, overwriting any existing data and leaving the file pointer at the character after the last character written

writeln( )

<input string expC>
[, <max chars expN>
[, <eol expC>]

Writes a character string and end-of-line character(s) to a file. Same as puts( ).

Description

Use a File object for direct byte-level access to files. Once you create a new File object, you can open() an existing file or create() a new one. Be sure to close() the file when you are done. A File object may access only one file at a time, but after closing a file, you may open or create another.

To communicate directly with a Web server, use the File object's open() method to access "StdIn" or "StdOut".

To open StdIn use:

fIn = new File() 

fIn.open( "StdIn", "RA") 

To open StdOut use:

fOut = new File() 

fOut.open( "StdOut", "RA") 

When reading or writing to a binary file, be sure to specify the "B" binary access specifier. Without it, the file is treated as a text file; if the current language driver is a multi-byte language, each character in the file may be one or two bytes. Binary access ensures that each byte is read and written without translation.

File objects also contain information and utility methods for file directories, such as returning the size of a file or changing a file name. If you intend to call multiple methods, you can create and reuse a File object. For example,

ff = new File( )

? ff.size( "Plus_en.hlp" )

? ff.accessDate( "Plus_en.hlp" )

Or you can create a File object for a WITH block. For example,

with new File( )

? size( "Plus_en.hlp" ) 

? accessDate( "Plus_en.hlp" ) 

endwith

For a single call, you can create and use the File object in the same statement:

? new File( ).size( "Plus_en.hlp" )

However, unless you happen to have a File object handy, its easier to use the equivalent built-in function or command to get the file information or perform the file operation:

? fsize( "Plus_en.hlp" )

? faccessdate( "Plus_en.hlp" )