. navigate
 Navigate
14. Low-Level Facilities left arrow
x
right arrow B. Pragmats
Red Reference Manual
A.

HIGH-LEVEL I/O

File Variables, Open & Close     File Processing     Text Files



A.   HIGH-LEVEL I/O

This appendix discusses a recommended set of definitions for user-level input-output programming. The definitions in this set include file types and the procedures and functions which operate on files. Files may be defined and associated with external physical files or devices. Physical files may be created, deleted, and renamed. The files may be organized for either sequential or random access and may be defined as either input, output, or update files. Files may be read or written and positioned to any component. Files may be interrogated to determine current size or position or to ascertain if the current position is at the end of the file. Additional file processing facilities are provided for files whose components are characters (i.e., have an ENUM type). These facilities allow strings of multiple characters to be read or written by a single invocation.


RED RATIONALE

Two major concepts in the RED I/0 design are the file variable, and the physical file (or device). A physical file is a repository for data. It consists of a linear sequence of data items, all of the same subtype. A physical file generally is a fairly static object and may exist for a long period of time. A file variable, however, is a connection to a particular physical file or device. Such a connection has both a position within the physical file and a directionality (input or output, or both). It is entirely possible for two different file variables to serve as input connections to the same physical file; however, depending on the implementation, two output or update connections to the same physical file might not work as expected.



A.1  FILE VARIABLES, OPEN, AND CLOSE

A file is a variable having a FILE type. A file is associated with an ordered collection of components, all having the same type. The type property list specifies the type of the components and the constraint property list specifies the access method (sequential or random) and the file use (input, output, or update). For example,

    VAR int_file : FILE [INT(min..max)] ('SEQ, 'INPUT);

defines int_file as a sequential file whose components are integers in the range min through max. The file is usable for input processing only. Note that the type of int_file is FILE [INT].

Before any file processing can occur, the file must be associated with a physical file. A physical file can be a file on a storage medium, a physical device, or a file on a storage medium representing a physical device (for example, a spooled card reader file). The association is made by the OPEN procedure, which also serves to specify the initial state of the file (old or new). If the initial state of the file was new, a file is created and its name placed in the file directory. If processing is attempted before a file is opened, an exception is raised. Assignment is not defined for file variables.

After all file processing has been completed, a file may be closed by the CLOSE procedure, which severs the association with the physical file and specifies subsequent file disposition (save or delete).


RED RATIONALE

The type of the file's components is associated with the file type in order to permit type checking. Only data objects of type T can be read from or written to a file of type FILE[T]. Thus, unless a connection is established (via OPEN) to the wrong type of file, no type errors can occur.


Although old, new, save, and delete do not apply to all physical devices, they are required for files associated with such devices. If the initial state or final disposition do not make sense, they are ignored. Requiring this information makes the program more portable, since physical devices are commonly represented by files on a storage medium. A file associated with a card reader, for example, can later be associated with a spooled card reader. Typical examples of file use are shown below:

  1. File associated with file on storage medium

    file associated with storage medium example


  2. File associated with physical device

    physical device example



Sequential and Random Files

A sequential file is a file which is processed by accessing each component in succession. A random file is a file which permits direct access to any component regardless of its position with respect to other components. Not all processing procedures and functions are valid on sequential files (i.e., a card reader cannot be backed up to the start of the file after some reading has occurred).



Text and Standard Files

Any file whose components have an enumeration type (i.e., ASCII or some other character type) is called a text file. All other files are called standard files. There are two predefined text files, SYS_IN and SYS_0UT, which are files of ASCII. A set of procedures and functions is available for reading and writing text files in a line-oriented manner. Formatting is achieved by combining text tiles with string-conversion functions.

text example



File Use

An input file is a file which is read-only. An output file is a file which is write-only. An update file is a file which may be read or written.




A.2  FILE PROCESSING

File processing is accomplished by the READ, WRITE, SET_POSITION, and FILE_RENAME procedures, and the SIZE, POSITON, and EOF functions.




READ and WRITE

READ moves data from an input or update file to a variable defined to be of the component subtype. After the READ, the file position is increased by one. WRITE moves data from a variable of the component subtype to an output or update file. After the WRITE, the file position is increased by one. If the data was written at the end of the file, the size of the file is increased by one.


RED RATIONALE

The operations for reading and writing data from files are procedures rather than statements. This means that they can be overloaded to transfer user-defined data values to and from text files.



read and write example




POSITION

POSITION returns the current file position. If the file is positioned at the start of the file (before the first component), POSITION will return 1. When a file is opened, the position will be 1. When a file is closed, the position is after the last record. If the file is positioned at the end of the file (after the last component), POSITION will return the number of components in the file plus one.




SET_POSITION

SET_POSITION moves a file to a specified position. lf an attempt is made to position the file before 1 or past the end of the file, an exception is raised.

The procedure invocation

    SET_POSITION (any_file, 1);

is equivalent to a rewind command.

The procedure invocation

    SET_POSITION (any_file, POSITION(any_file) -1);

is equivalent to a backspace command.




SIZE

SIZE returns the number of components in a file. If the file is empty, SIZE returns zero. The following example positions a file to its end and writes a new component.

    SET_POSITION (any_file, SIZE(any_file) +1);
    WRITE (any_file, temp);




EOF

EOF returns a boolean value signifying whether the position is at the end of a file. If the file is positioned at its end, EOF returns TRUE. For example,

    EOF (any_file)




FILE_RENAME

FILE_RENAME, in the presence of a file system, changes the name of an existing physical file. Any associations made between files and that physical file continue to exist. The old file name, however, can no longer be used.

rename example



EXAMPLES

  1. Copies entire file

    copy entire file example



  2. Sequential update processing

    sequential update example



  3. Copies entire file n times

    copies file n times example






Implementation-Dependent Procedures and Functions

It is anticipated that a variety of implementation and/or device-dependent procedures and functions will be available for setting and interrogating file characteristics such as protection, physical blocking, buffering, and file space.



EXAMPLES

  1. 370 VS example

    370 vs example



  2. PDP-10 TOPS 10 example

    PDP-10 TOPS 10 example






A.3  TEXT FILES

A text file is a file whose components have an enumeration type. The enumeration type will specify a character set, usually ASCII. The following example defines a text file which might be a card reader.

card reader example

Two text files are predefined, SYS_IN and SYS_OUT. These must be opened to associate them with an appropriate physical file for input and output.




File Processing

lt is possible to perform character by character processing of a text file using the file processing procedures and functions already described. lt is usually more convenient, however, to think of a text file as a sequence of lines rather than characters, where a line consists of the string of all characters up to, but not including, the carriage-return line-feed characters ('CR & 'LF). For example, if a text file contains

    "ABC" & 'CR & 'LF & "DEFGH" & 'CR & 'LF

then that text file is considered to be composed of two lines, "ABC" and "DEFGH". The type of the characters making up the line are the same as the type of the file component. As shown in the above example, lines within the same file may be of different lengths.

The READLN procedure and the WRITELN procedure are provided to read lines from and write lines to text files. Also provided are: a SIZELN function to interrogate the size of the line about to be read; definitions of READLN, SIZELN, and EOF which assume that the file name is the predefined file SYS_IN; and a definition of WRITELN which assumes that the file name is the predefined file SYS__0UT.

RED RATIONALE

END-OF-LINE
Source program end-of-lines, such as carriage-return line-feed sequences, are converted to new line boundaries in Basic 55.




READLN and WRITELN

READLN reads a line from an input or update text file into a variable. After the READLN, the file position is increased by the number of components contained in the line just read, plus the carriage return and line feed. WRITELN writes a line from a variable of the component subtype into an output or update text file. After the WRITELN, the file position is increased by the number of components in the line just written, plus the carriage return and line feed.




SIZELN

SIZELN returns the number of characters between the current position and the first end of line ('CR & 'LF).



EXAMPLES

  1. Echo input to output, one line at a time, using SYS_IN and SYS_OUT.

    echo using SYS_IN and SYS_OUT example



  2. Echo input to output, one line at a time, using user-defined text files.

    echo using user-defined text example



  3. Reverse lines from SYS_IN and output onto SYS_OUT.

    reverse lines example






Conversions Upon Input

Conversions are defined from strings to booleans, integers, floating point numbers, and enumeration values. Any leading or trailing blanks in the input strings are ignored. The form of the remaining characters must be a legal literal of the type to which the form will be converted, with an optional plus or minus sign preceding an integer or floating point literal. if the minus sign is present, the literal will be converted to a negative value.

If an integer or floating point subtype is specified as the target of the conversion, the string literal must be within the target range or an exception is raised. If the string literal has more precision than the target floating point subtype, truncation is performed.




Conversions Upon Output

Conversions are defined from booleans, integers, floating point numbers, and enumeration values to strings. Each value is converted to the literal form and, if the value is a negative integer or floating point number, a minus sign is inserted before the integer or floating point literal. The format of a string literal of a floating point number is an optional minus sign followed by

    n.nnnnE+mmm

or

    n.nnnnE-mmm

where the number of n's is the precision of the floating point number.

If the target is a string subtype (that is, if a length is specified) and the length is longer than the string literal, the string is padded on the left with blanks. If the length is shorter than the string literal, an exception is raised.



EXAMPLES

  1. Reads in a line which contains only an integer

    read in integer example



  2. Writes out a line which contains only an integer.

    write out integer example



  3. Reads in a line which contains two integers, one in the first five columns and the next in the second five columns.

    read in by column example






Output Formatting

To simplify the conversion of floating point numbers to ASCII strings for output, two format functions are provided in addition to the standard conversion function.

A floating point number can be output without an exponent by invoking the FORMAT function and passing the floating point value, the number of characters to be output to the left of the decimal polnt, and the number of characters to be output to the right of the decimal point. Zeros on the left are not suppressed. if the value is negative, a minus sign is output to the left of the string. The total number) of characters in

    FORMAT (float_number, n, m)

is n + m + z (for the sign and decimal point). If the first significant digit would be lost, the X_FORMAT exception is raised.

A floating point number can be output with an exponent by invoking the FORMAT function with one additional parameter, the number of characters to be output to the right of E. The sign of the exponent will always be printed. The first significant digit will appear as the leftmost character. If the value is negative, a minus sign is printed to the left of the string. The total number of characters in

    FORMAT (float_number, n, m, o)

is n + m + o + 4 (for the sign, decimal point, E, and the exponent sign). If the exponent will not fit in o digits, the X_FORMAT exception is raised.



EXAMPLES

formatted output example






File Variables, Open & Close     File Processing     Text Files

14. Low-Level Facilities left arrow
x
right arrow B. Pragmats


Overview

Requirements
     Strawman
     Woodenman
     Tinman
     Ironman
     Steelman

RED Reference
RED Rationale

Types in RED
Time/Life Computer Languages
Memories

Site Index

Overview             Reference ToC             Rationale ToC             Site Index



Home   Favorites   Map

IME logo Copyright © 2009, Mary S. Van Deusen