Chapter 5
© 2000, The TRAC Foundation
File Primitives
This chapter describes the file and file position primitives.
5.1 Introduction to the File Primitives
The two groups of primitives that create and use files and position the file pointer in a file are the file group and the file position group. The file group primitive mnemonics have the initial letter f, and the file position group primitive mnemonics have the initial letters fp.
Caution: TRAC does not buffer files, so you cannot undo an operation. If you delete a file or overwrite characters in a file, the action is permanent.
5.1.1 File Group
The file primitives create and manipulate sequential files in external memory. The primitives do not manipulate nonsequential files, such as hypertext files.
For the primitives that take a filename argument, you can designate as the <filename> string any filename that the host operating system accepts. For example, MS-DOS filenames are not case-sensitive, so the filenames file4.abc and FILE4.ABC specify the same file. For MS-DOS filenames, you may use upper case, lower case or a mix of the cases when specifying a file or directory name. The MS-DOS operating system displays filenames and directory names in upper case.
UNIX operating systems do distinguish between upper and lower case in file and directory names, so the filenames file4.abc and FILE4.ABC specify two different files. UNIX accepts filename constructs like .../DeF/Jones.
The TRAC processor provides six file channels, numbered 1 to 6. You can open one file per channel. You specify the channel number by appending the number to the mnemonic of the primitive statement. Specifying a channel number is optional. If you do not specify a channel number, the processor uses channel 1 by default.
Channels remain open while in use. The processor has interlocks that prevent the opening of more than one file per channel, or opening the same file on two different channels. You can use the file status primitive fs to learn the status of the open channels.
When you create a new file with the fg primitive, the TRAC processor sets the channel to Write state and opens the file. If you open an existing file with the fo primitive, the processor sets the channel to Initial state. An fg or fo primitive statement produces the <z-return> value if the processor could not generate or open the file.
If the channel is in Initial state, you can call the fw primitive to set the channel to Write state and write to the file, or you can call the fr primitive to set the channel to Read state and read from the file. Once you set the state to read or write, you cannot change the state without first closing the file with the fc primitive. Reads and writes begin at the head of the file. Each successive read continues reading from the previous read position. Each successive write appends to the end of the previous write. See Section 5.1.2, "File Position Group," for information on resetting the channel state without closing the file, and for nonsequential read and write operations.
Note: To edit a file with a text editor after you have opened a file with an fg or fo statement, you must close the file with an fc statement, or exit the Dialer application. Stopping the interactive TRAC script by a g statement or by clicking on the Dialer application Stop script button does not release the file, even though an fs statement reports No File is Open. If you attempt to open the file with Notepad, for example, Notepad displays a message saying the file is already in use.
When moving files by diskette or by ftp from an MS-DOS system to either a UNIX or a XENIX system, be aware that the UNIX or XENIX operating system removes (or inserts) carriage return characters in the file as it copies the file unless you specifically direct the operating system not to do so.
The file primitives are:
fc Close an open file.
fe Erase (delete) a file.
fg Generate (create) a file.
fo Open an existing file.
fr Read from a file sequentially.
fs Report the status of channels.
fw Write to a file sequentially.
5.1.2 File Position Group
The four primitives in the file position group reposition, or report the position of, the file pointer in the file open on the specified channel. The file position primitives also put the channel into the Initial state. You can then either read to the file with an fr statement or write to the file with an fw statement. The first read or write operation changes the channel state to the state of the calling operation.
File positioning depends upon using a signed number offset from a base position. Depending on the primitive, the base position may be the beginning or end of the file, or the current location of the pointer. After positioning the file pointer, the next read or write operation begins at the new position. Subsequent reads or writes begin from the point at which the previous read or write left off.
The file position primitives are:
fpb Positions the file pointer as an offset from the beginning of the file.
fpc Positions the file pointer as an offset from the current location.
fpe Positions the file pointer as an offset from the end of the file.
fpr Reports the current position of the file pointer.
5.2 File Primitive Reference
This section provides the syntax, input arguments, value string, and description of each file and file position primitive in alphabetical order.
fc - File Close
Syntax
:(fc<j>)
Input Arguments
<j> Suffix specifying the channel to close.
Description
The null-valued file close primitive fc writes out any content in the output buffer of channel <j>, and then closes the channel. You may then reuse the channel <j> with another file.
Example
The first command of the following example closes the file open on channel 1. The second command closes the file open on channel 6.
:(fc)'
:(fc6)'
fe - File Erase
Syntax
:(fe,<filename>)
Input Arguments
<filename> The name of the file to erase (delete).
Description
The null-valued file erase primitive fe erases (deletes) the file specified by <filename>.
Caution: This primitive deletes the specified file immediately. It does not ask you to confirm your decision to delete a file.
Example
The following command deletes the file c:\TRAC\test.txt.
:(fe,C:\TRAC\test.txt)'
fg - Generate New File
Syntax
:(fg<j>,<filename>,<z-ret>)
Input Arguments
<j> Suffix specifying the output channel.
<filename> Name of the file to create.
Description
The null-valued generate file primitive fg causes the TRAC processor to create a new file on channel <j>.
Caution: If a file with the same name already exists, the processor deletes that file.
The processor opens the channel in Write state. You can then use the fw primitive to write to the file.
Example
In the following example, the first fg command creates the file \TRAC\test.txt and opens it on channel 5. The second command creates a different file and opens it on channel 6 if channel 5 is in use or if the file specified in the first statement is already open.
:(fg5,\TRAC\test.txt,((Cannot create file.)))'
:(fg5,\TRAC\test.txt,(
:(fg6,\TRAC\test2.txt,((Cannot create file.)))
))'
fo - File Open
Syntax
:(fo<j>,<fi1ename>,<z-ret>)
Input Arguments
<j> Suffix specifying the input or output channel.
<filename> Name of the file to open.
Description
The null-valued file open primitive fo opens channel <j> to an existing file. The primitive opens the channel in the Initial state. You can then call the fw primitive to set the channel to Write state and write to the file, or you can call the fr primitive to set the channel to Read state and read from the file. Once you set the state to read or write, you cannot change the state without either closing the file with the fc primitive or resetting to the Initial state with one of the file position primitives.
Example
The following command opens the file test.txt in the directory TRAC on the current drive. If the processor cannot open the file, the processor displays the text string Cannot open file as the <z-ret> argument specifies.
:(fo,\TRAC\test.txt,(
:(o,(Cannot open file.))
))'
fpb - Position from Beginning
Syntax
:(fpb<j>,<offset>,<z-ret>)
Input Arguments
<j> Suffix specifying the channel to the file.
<offset> Number of characters to offset the file pointer.
Description
The null-valued file position to beginning primitive fpb positions the file pointer in the open file at channel <j> to <offset> characters from the beginning of the file. The fpb primitive leaves the channel in the Initial state so you can either read from or write to the file. If there is an error, such as no file is open, the primitive statement produces the <z-ret> argument.
Note: Writing to the file overwrites characters already in the file starting at the file pointer position.
The <offset> argument should not be a negative value. If it is, the file pointer does not move. Also, you should not specify an offset that is beyond the end of the file. If you do, you may get garbage characters in the file.
Example
The following command moves the file pointer 50 characters in from the beginning of the file open on channel 1:
:(fpb,50,error)'
fpc - Position from Current
Syntax
:(fpc <j>,<offset>,<z-ret>)
Input Arguments
<j> Suffix specifying the channel to the file.
<offset> Number of characters to offset the file pointer.
Description
The null-valued file position from current location primitive fpc positions the file pointer in the open file at channel <j> to <offset> characters from the current location in the file. The fpc primitive leaves the channel in the Initial state so you can either read from or write to the file. If there is an error, such as no file is open, the primitive statement produces the <z-ret> argument.
Note: Writing to the file overwrites characters already in the file starting at the file pointer position.
The <offset> argument can be a positive or negative integer. You should not, however, specify an offset that is beyond the beginning or the end of the file. If you do, you may get garbage characters in the file.
Example
The following command moves the file pointer 20 characters back, toward the beginning of the file open on channel 1, from the position of the file pointer before the call to fpc:
:(fpc,-20,error)'
fpe - Position from End
Syntax
:(fpe<j>,<offset>,<z-ret>)
Input Arguments
<j> Suffix specifying the channel to the file.
<offset> Number of characters to offset the file pointer.
Description
The null-valued file position to end primitive fpe positions the file pointer in the open file at channel <j> to <offset> characters from the end of the file. The fpe primitive leaves the channel in the Initial state so you can either read from or write to the file. If there is an error, such as no file is open, the primitive statement produces the <z-ret> argument.
Note: Writing to the file overwrites characters already in the file starting at the file pointer position.
The <offset> argument should be a negative integer. A negative number offsets the file pointer back toward the beginning of the file. A positive number offsets the pointer beyond the end of the file. You should not, however, specify an offset that is beyond the beginning or the end of the file. If you do, you may get garbage characters in the file.
Example
The following command moves the file pointer 120 characters back, toward the beginning of the file, from the end of the file open on channel 1:
:(fpe,-120,error)'
fpr - Position Read
Syntax
:(fpr<j>,<z-ret>)
Input Arguments
<j> Suffix specifying the channel to the file.
Description
The file position read primitive fpr produces as a value string an integer decimal that is the current position of the file pointer, that is, the location of the next character to be read, or the next character to be written. The fpr primitive leaves the channel in the Initial state so you can either read from or write to the file.
If there is an error, such as no file is open, the primitive statement produces the string you supply as the <z-ret> argument.
Example
The following command reports the position of the file pointer in the file open on channel 1:
:(fpr,error)'
fr - File Read
Syntax
:(fr<j>,<term>,<N>,<z-ret>)
Input Arguments
<j> Suffix specifying the input channel.
<term> Terminator character or string to end the read operation.
<N> Integer value specifying the number of characters to read from the file.
Description
The value-producing file read primitive fr reads a string of characters from the file open on channel <j>. The value string this primitive produces is the string of characters it reads from the file.
You may use the read primitive repeatedly to incrementally read from the file. Each subsequent read begins from the end of the previous read.
You can enter a single character or a string of characters as the <term> terminator argument. The processor stops the read when it encounters the terminator, but deletes the terminator from the read.
The terminator may be, or contain, any character, even a control character providing you enclose the control character in parentheses to protect it from the TRAC processor. The processor deletes unprotected control characters.
Note: Because of limitations imposed by some operating systems, the use of certain characters such as carriage return or Control+Z (MS-DOS end of file mark) in the <term> argument may not produce the effects you intend. For each kind of system, you must verify the utility of such characters.
When argument <N> is non-null, and is an integer, the fr primitive reads N characters (or as many as are available in the file) from the file to provide the value string of the primitive. This argument does not override the <term> argument.
If both <N> and <term> are null strings, the read primitive reads the default number of 256 characters.
At the beginning of its execution, if the fr primitive finds that the file pointer is at the end of the file, so there are no characters left to read, the primitive produces the <z-ret> argument.
Example
In the following examples, the top-level directory file test.txt contains the following lines
This is the file \test.txt. +
Each line ends with a plus sign and a carriage return/line feed. +
The file has 190 characters, including the carriage return +
and line feed characters. +
The following command opens channel 4 to the file test.txt:
:(fo4, test.txt, cannot_open)'
The next four commands call the fr primitive with different arguments each time. The results of each call appear after the primitive. The first call specifies the plus sign as the terminator. Note that the plus sign does not appear in the value string because the TRAC processor deletes the terminator character or string from the value string:
:(fr4, +,, end)'This is the file \test.txt.
The following example specifies the number of characters to read. The read continues from the position of the previous read, so the read begins with the carriage return/line feed combination at the end of the first line of the test.txt file:
:(fr4,, 50, end)'
Each line ends with a plus sign and a carriage r
The next example specifies null strings as the <term> and <N> arguments, so the fr primitive reads the default number of characters from the file:
:(fr4,,, end)'eturn/line feed. +
The file has 190 characters, including the carriage return +
and line feed characters. +
In the following example the TRAC processor produces the z-return value, since the file pointer is at the end of the file:
:(fr4,,, end)'end
fs - File Status
Syntax
(fs<n><j>)
Input Arguments
<n> The suffix n or N.
<j> Suffix specifying the input or output channel.
Description
The file status primitive fs is null-valued if you do not specify a suffix. With no suffix, the fs primitive displays a table that reports the status of all the active file channels.
The fs primitive is value-producing if you specify a channel number with the <j> suffix, or request the name of the open file with the n suffix.
If you do specify a channel number with the <j> suffix, the fs primitive produces an integer as the value string. The integer indicates the status of the channel. The possible integers and the status they indicate are:
0 No file is open on this channel.
1 File open for read.
2 File open for write.
3 File in Initial state.
You can store the integer value string or otherwise use the value. For example, you could use the integer value string as an argument to the ag greater than (equality) arithmetic primitive, and then supply other primitives for the processor to execute based on the result of the ag comparison.
If you specify the letter n or N (for name) before the <j> suffix, the fs primitive provides as a value string the filename for the file open at channel <j>. If you specify the n suffix without a <j> suffix, the primitive produces the name of the file open on the default channel 1.
Example
The following command shows the status of all channels currently open to files:
:(fs)'
Channel No. 1 State: Initial File name: testl.txt
Channel No. 2 State: Open for Read File name: test2.txt
Channel No. 3 State: Open for Write File name: test3.txt
The next example reports the file status for channels one through four. A file is open in Initial state on channel 1 (state 3), a file is open for a read on channel 2 (state 1), a file is open for a write on channel 3 (state 2), and no file is open on channel 4 (state 0)
:(fs1)'3
:(fs2)'1
:(fs3)'2
:(fs4)'0
The following command demonstrates the <n> suffix to report the name of the file open on channel 2:
:(fsn2)'test2.txt
fw - File Write
syntax
:(fw<j>,<text>)
Input Arguments
<j> Suffix specifying the output channel.
<text> Text to write into the file.
Description
The null-valued file write primitive fw writes the string <text> to the file open on channel <j>. You can use this primitive repeatedly to incrementally write to a file. To preserve spaces in the text, put the text inside protective parentheses.
Caution: The first time you call the fw primitive, it begins writing at the head of the file, overwriting any previous content. Subsequent writes continue in the file where the last write left off. To append text to a file, first call the fpe primitive before calling the initial fw.
Example
The following example writes a text string of 37 characters to the file open on channel 2. If the file contained any text, the call overwrites the first 37 characters in the file:
:(fw2, (Here is some text to put is the file.)'