Forth Programmer’s Handbook

can display its associated shadow block.

Consult your product documentation for further details regarding your system’s features.

Glossary

Return a-addr, the address of a cell containing the block number of the most recently LISTed block. “S-C-R”

3.5 FILE-BASED DISK ACCESS

Forth systems provide access to mass storage using a block-based or file-based method. This section discusses words that access mass storage using files. Section 3.4 discusses words used to access and manage disk blocks and block buffers in Forth. One or the other of these sections (occasionally both) will be relevant to a particular Forth system.

In a block-based system, mass storage is partitioned into blocks of 1024 bytes. In a file-based system, a host operating system is required; it provides and manages files of variable length, which Forth uses directly for mass storage.

Many items discussed in this section, such as the specific value and meaning of non-zero I/O result codes, allowable forms of filenames, values of line terminators, etc. are system dependent. Consult your product documentation for details.

3.5.1 Overview

The Forth words described in this section provide access to mass storage in the form of files, under the following conditions and assumptions:

96 System Functions

Forth Programmer’s Handbook

!Files are provided by a host operating system.

!File state information (e.g., current position in the file, size, etc.) is managed by the host operating system. File sizes are dynamically variable, so write operations will increase the size of a file as necessary.

!Filenames are represented as character strings. The format of the names is determined by the host operating system. Filenames may include system-specific pathnames.

!A file identifier (fileid) is a single-cell value that is passed to file operators to refer to specific files. Opening a file assigns it a file identifier, which remains valid until the file is closed. When the text interpreter is using a file as the input, its fileid will be returned by SOURCE-ID. The other possible values that SOURCE-ID can return are zero (if the user input device is the source), and -1 (if the source is a character string passed by EVALUATE).

!File contents are accessed as a sequence of characters. The file position is the character offset from the start of the file. The file position is updated by all read, write, and re-position commands.

!File read operations return an actual transfer count, which can differ from the requested transfer count.

!A file access method (fam) is a single-cell value indicating a permissible means of accessing a specific file, such as read/write or read-only.

!An I/O result (ior) is a single-cell value indicating the result of an I/O operation. A value of zero always indicates success; non-zero values are definitionand system-specific. An operation reaching the end of a file shall not consider it an error and shall return a zero ior.

3.5.2 Global File Operations

The words in this section are used to manipulate files as entire entities.

System Functions 97

Forth Programmer’s Handbook

CREATE-FILE ( c-addr u fam — fileid ior ) Core

Create a file whose name is given by the character string at c-addr and whose length is u, and open it with file access method fam. If the file already exists, recreate it as an empty file, replacing the pre-existing file of that name. If creation and opening are successful, return an ior of zero and the fileid. Otherwise, return a non-zero ior and an undefined value for fileid.

Force any buffered contents of the file referred to by fileid to be written to mass storage, and the size information for the file to be recorded by the system, if changed. Return an ior of zero if successful; otherwise, return a system-depen- dent value.

OPEN-FILE ( c-addr u fam — fileid ior ) File

Open the file whose name is given by the character string at c-addr whose length is u, with file access method fam. If opening is successful, set the file position to zero, and return an ior of zero and the fileid; otherwise, return a non-zero ior and an undefined value for fileid.

RENAME-FILE ( c-addr1 u1 c-addr2 u2 — ior )

Rename the file whose current name is given by the character string at c-addr1 and whose length is u1, to the name given by the character string at c-addr2 and whose length is u2. Return an I/O result.

RESIZE-FILE ( ud fileid — ior ) File

Set the size of the file identified by fileid to ud, and return an I/O result code. If the file size is increased, the contents of the newly allocated space is indeterminate. After this operation (if successful), FILE-SIZE will return the same value for ud, and FILE-POSITION returns an undefined value.

98 System Functions

Forth Programmer’s Handbook

3.5.3 File Reading and Writing

The words in this section are used to read or write to a specific file.

Read and interpret the given file, performing the following steps: Save the current input source specification. Store the given fileid in SOURCE-ID, set BLK to zero, and make this file the input source. Read a line from the file at the current file position, fill the input buffer with the contents of the line, set >IN to zero, and interpret the buffer contents. Continue reading lines until the end of file is reached. When the end of the file is reached, close the file and restore the previous input source specification.

INCLUDED ( c-addr u — ) File

Same as INCLUDE-FILE, except the file is specified by its name, which is stored at c-addr and is of length u. The file is opened and its fileid is stored in

SOURCE-ID.

Read and store text from the given file, without interpretation, and update FILE-POSITION. From the current position in the file identified by fileid, read u1 consecutive characters, storing them at c-addr. Return an ior and u2, the number of characters successfully read. If no exception occurs, return ior of zero and u2 = u1 or the number of characters actually read before encountering the end of the file, whichever is smaller. If FILE-POSITION was equal to FILE-SIZE before executing READ-FILE, u2 is zero. If a non-zero ior is returned, u2 is the number of characters successfully transferred before the exception occurred.

READ-LINE ( c-addr u1 fileid — u2 flag ior ) File

Read and store one line of text from the given file, without interpretation, and update FILE-POSITION: From the current position in the file identified by

System Functions 99