![[PREVIOUS]](lrm-prev.gif)
![[UP]](lrm-up.gif)
![[NEXT]](lrm-next.gif)
Two kinds of access to external files are defined: sequential access and direct access. The corresponding file types and the associated operations are provided by the generic packages SEQUENTIAL_IO and DIRECT_IO. A file object to be used for sequential access is called a sequential file, and one to be used for direct access is called a direct file.
For sequential access, the file is viewed as a sequence of values that are transferred in the order of their appearance (as produced by the program or by the environment). When the file is opened, transfer starts from the beginning of the file.
For direct access, the file is viewed as a set of elements occupying consecutive positions in linear order; a value can be transferred to or from an element of the file at any selected position. The position of an element is specified by its index, which is a number, greater than zero, of the implementation-defined integer type COUNT. The first element, if any, has index one; the index of the last element, if any, is called the current size; the current size is zero if there are no elements. The current size is a property of the external file.
An open direct file has a current index, which is the index that will be used by the next read or write operation. When a direct file is opened, the current index is set to one. The current index of a direct file is a property of a file object, not of an external file.
All three file modes are allowed for direct files. The only allowed modes for sequential files are the modes IN_FILE and OUT_FILE.
References: count type, file mode, in_file, out_file.
Sub-topics:
The procedures and functions described in this section provide for the control of external files; their declarations are repeated in each of the three packages for sequential, direct, and text input-output. For text input-output, the procedures CREATE, OPEN, and RESET have additional effects described in section 14.3.1.
procedure CREATE(FILE : in out FILE_TYPE;
MODE : in FILE_MODE := default_mode;
NAME : in STRING := "";
FORM : in STRING := "");
Establishes a new external file, with the given name and form,
and associates this external file with the given file. The given
file is left open. The current mode of the given file is set to
the given access mode. The default access mode is the mode
OUT_FILE for sequential and text input-output; it is the mode
INOUT_FILE for direct input-output. For direct access, the size
of the created file is implementation-dependent. A null string
for NAME specifies an external file that is not accessible after
the completion of the main program (a temporary file). A null
string for FORM specifies the use of the default options of the
implementation for the external file.
The exception STATUS_ERROR is raised if the given file is already
open. The exception NAME_ERROR is raised if the string given as
NAME does not allow the identification of an external file. The
exception USE_ERROR is raised if, for the specified mode, the
environment does not support creation of an external file with
the given name (in the absence of NAME_ERROR) and form.
procedure OPEN(FILE : in out FILE_TYPE;
MODE : in FILE_MODE;
NAME : in STRING;
FORM : in STRING := "");
Associates the given file with an existing external file having
the given name and form, and sets the current mode of the given
file to the given mode. The given file is left open.
The exception STATUS_ERROR is raised if the given file is already
open. The exception NAME_ERROR is raised if the string given as
NAME does not allow the identification of an external file; in
particular, this exception is raised if no external file with the
given name exists. The exception USE_ERROR is raised if, for the
specified mode, the environment does not support opening for an
external file with the given name (in the absence of NAME_ERROR)
and form.
procedure CLOSE(FILE : in out FILE_TYPE);
Severs the association between the given file and its associated
external file. The given file is left closed.
The exception STATUS_ERROR is raised if the given file is not
open.
procedure DELETE(FILE : in out FILE_TYPE);
Deletes the external file associated with the given file. The
given file is closed, and the external file ceases to exist.
The exception STATUS_ERROR is raised if the given file is not
open. The exception USE_ERROR is raised if (as fully defined in
Appendix F) deletion of the external file is not supported by the
environment.
procedure RESET(FILE : in out FILE_TYPE; MODE : in FILE_MODE);
procedure RESET(FILE : in out FILE_TYPE);
Resets the given file so that reading from or writing to its
elements can be restarted from the beginning of the file; in
particular, for direct access this means that the current index
is set to one. If a MODE parameter is supplied, the current mode
of the given file is set to the given mode.
The exception STATUS_ERROR is raised if the file is not open.
The exception USE_ERROR is raised if the environment does not
support resetting for the external file and, also, if the
environment does not support resetting to the specified mode for
the external file.
function MODE(FILE : in FILE_TYPE) return FILE_MODE;
Returns the current mode of the given file.
The exception STATUS_ERROR is raised if the file is not open.
function NAME(FILE : in FILE_TYPE) return STRING;
Returns a string which uniquely identifies the external file
currently associated with the given file (and may thus be used in
an OPEN operation). If an environment allows alternative
specifications of the name (for example, abbreviations), the
string returned by the function should correspond to a full
specification of the name.
The exception STATUS_ERROR is raised if the given file is not
open.
function FORM(FILE : in FILE_TYPE) return STRING;
Returns the form string for the external file currently
associated with the given file. If an environment allows
alternative specifications of the form (for example,
abbreviations using default options), the string returned by the
function should correspond to a full specification (that is, it
should indicate explicitly all options selected, including
default options).
The exception STATUS_ERROR is raised if the given file is not
open.
function IS_OPEN(FILE : in FILE_TYPE) return BOOLEAN;
Returns TRUE if the file is open (that is, if it is associated
with an external file), otherwise returns FALSE.
References: current mode, current size, closed file, direct access, external file, file, file_mode type, file_type type, form string, inout_file, mode, name string, name_error exception, open file, out_file, status_error exception, use_error exception.
Style Guide references: 7.7.1 Name and Form Parameters, 7.7.2 File Closing
The operations available for sequential input and output are described in this section. The exception STATUS_ERROR is raised if any of these operations is attempted for a file that is not open.
procedure READ(FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE);
Operates on a file of mode IN_FILE. Reads an element from the
given file, and returns the value of this element in the ITEM
parameter.
The exception MODE_ERROR is raised if the mode is not IN_FILE.
The exception END_ERROR is raised if no more elements can be read
from the given file. The exception DATA_ERROR is raised if the
element read cannot be interpreted as a value of the type
ELEMENT_TYPE; however, an implementation is allowed to omit this
check if performing the check is too complex.
procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE);
Operates on a file of mode OUT_FILE. Writes the value of ITEM to
the given file.
The exception MODE_ERROR is raised if the mode is not OUT_FILE.
The exception USE_ERROR is raised if the capacity of the external
file is exceeded.
function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
Operates on a file of mode IN_FILE. Returns TRUE if no more
elements can be read from the given file; otherwise returns
FALSE.
The exception MODE_ERROR is raised if the mode is not IN_FILE.
References: data_error exception, element, element_type, end_error exception, external file, file, file mode, file_type, in_file, mode_error exception, out_file, status_error exception, use_error exception.
5.9.7 Direct_IO and Sequential_IO, 7.7.3 I/O on Access Types
with IO_EXCEPTIONS;
generic
type ELEMENT_TYPE is private;
package SEQUENTIAL_IO is
type FILE_TYPE is limited private;
type FILE_MODE is (IN_FILE, OUT_FILE);
-- File management
procedure CREATE(FILE : in out FILE_TYPE;
MODE : in FILE_MODE := OUT_FILE;
NAME : in STRING := "";
FORM : in STRING := "");
procedure OPEN (FILE : in out FILE_TYPE;
MODE : in FILE_MODE;
NAME : in STRING;
FORM : in STRING := "");
procedure CLOSE (FILE : in out FILE_TYPE);
procedure DELETE(FILE : in out FILE_TYPE);
procedure RESET (FILE : in out FILE_TYPE; MODE : in FILE_MODE);
procedure RESET (FILE : in out FILE_TYPE);
function MODE (FILE : in FILE_TYPE) return FILE_MODE;
function NAME (FILE : in FILE_TYPE) return STRING;
function FORM (FILE : in FILE_TYPE) return STRING;
function IS_OPEN(FILE : in FILE_TYPE) return BOOLEAN;
-- Input and output operations
procedure READ (FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE);
procedure WRITE (FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE);
function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
-- Exceptions
STATUS_ERROR : exception renames IO_EXCEPTIONS.STATUS_ERROR;
MODE_ERROR : exception renames IO_EXCEPTIONS.MODE_ERROR;
NAME_ERROR : exception renames IO_EXCEPTIONS.NAME_ERROR;
USE_ERROR : exception renames IO_EXCEPTIONS.USE_ERROR;
DEVICE_ERROR : exception renames IO_EXCEPTIONS.DEVICE_ERROR;
END_ERROR : exception renames IO_EXCEPTIONS.END_ERROR;
DATA_ERROR : exception renames IO_EXCEPTIONS.DATA_ERROR;
private
-- implementation-dependent
end SEQUENTIAL_IO;
References: close procedure, create procedure, data_error exception, delete procedure, device_error exception, end_error exception, end_of_file function, file_mode, file_type, form function, in_file, io_exceptions, is_open function, mode function, mode_error exception, name function, name_error exception, open procedure, out_file, read procedure, reset procedure, sequential_io package, and 14.2.2, status_error exception, use_error exception, write procedure.
The operations available for direct input and output are described in this section. The exception STATUS_ERROR is raised if any of these operations is attempted for a file that is not open.
procedure READ(FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE;
FROM : in POSITIVE_COUNT);
procedure READ(FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE);
Operates on a file of mode IN_FILE or INOUT_FILE. In the case of
the first form, sets the current index of the given file to the
index value given by the parameter FROM. Then (for both forms)
returns, in the parameter ITEM, the value of the element whose
position in the given file is specified by the current index of
the file; finally, increases the current index by one.
The exception MODE_ERROR is raised if the mode of the given file
is OUT_FILE. The exception END_ERROR is raised if the index to
be used exceeds the size of the external file. The exception
DATA_ERROR is raised if the element read cannot be interpreted as
a value of the type ELEMENT_TYPE; however, an implementation is
allowed to omit this check if performing the check is too
complex.
procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE;
TO : in POSITIVE_COUNT);
procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE);
Operates on a file of mode INOUT_FILE or OUT_FILE. In the case
of the first form, sets the index of the given file to the index
value given by the parameter TO. Then (for both forms) gives the
value of the parameter ITEM to the element whose position in the
given file is specified by the current index of the file;
finally, increases the current index by one.
The exception MODE_ERROR is raised if the mode of the given file
is IN_FILE. The exception USE_ERROR is raised if the capacity of
the external file is exceeded.
procedure SET_INDEX(FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
Operates on a file of any mode. Sets the current index of the
given file to the given index value (which may exceed the current
size of the file).
function INDEX(FILE : in FILE_TYPE) return POSITIVE_COUNT;
Operates on a file of any mode. Returns the current index of the
given file.
function SIZE(FILE : in FILE_TYPE) return COUNT;
Operates on a file of any mode. Returns the current size of the
external file that is associated with the given file.
function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
Operates on a file of mode IN_FILE or INOUT_FILE. Returns TRUE
if the current index exceeds the size of the external file;
otherwise returns FALSE.
The exception MODE_ERROR is raised if the mode of the given file
is OUT_FILE.
References: count type, current index, current size, data_error exception, element, element_type, end_error exception, external file, file, file mode, file_type, in_file, index, inout_file, mode_error exception, open file, positive_count, status_error exception, use_error exception.
Style Guide references: 5.9.7 Direct_IO and Sequential_IO, 7.7.1 Name and Form Parameters, 7.7.3 I/O on Access Types
with IO_EXCEPTIONS;
generic
type ELEMENT_TYPE is private;
package DIRECT_IO is
type FILE_TYPE is limited private;
type FILE_MODE is (IN_FILE, INOUT_FILE, OUT_FILE);
type COUNT is range 0 .. implementation defined;
subtype POSITIVE_COUNT is COUNT range 1 .. COUNT'LAST;
-- File management
procedure CREATE(FILE : in out FILE_TYPE;
MODE : in FILE_MODE := INOUT_FILE;
NAME : in STRING := "";
FORM : in STRING := "");
procedure OPEN (FILE : in out FILE_TYPE;
MODE : in FILE_MODE;
NAME : in STRING;
FORM : in STRING := "");
procedure CLOSE (FILE : in out FILE_TYPE);
procedure DELETE(FILE : in out FILE_TYPE);
procedure RESET (FILE : in out FILE_TYPE; MODE : in FILE_MODE);
procedure RESET (FILE : in out FILE_TYPE);
function MODE (FILE : in FILE_TYPE) return FILE_MODE;
function NAME (FILE : in FILE_TYPE) return STRING;
function FORM (FILE : in FILE_TYPE) return STRING;
function IS_OPEN(FILE : in FILE_TYPE) return BOOLEAN;
-- Input and output operations
procedure READ (FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE; FROM :
POSITIVE_COUNT);
procedure READ (FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE);
procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE; TO :
POSITIVE_COUNT);
procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE);
procedure SET_INDEX(FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
function INDEX(FILE : in FILE_TYPE) return POSITIVE_COUNT;
function SIZE (FILE : in FILE_TYPE) return COUNT;
function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
-- Exceptions
STATUS_ERROR : exception renames IO_EXCEPTIONS.STATUS_ERROR;
MODE_ERROR : exception renames IO_EXCEPTIONS.MODE_ERROR;
NAME_ERROR : exception renames IO_EXCEPTIONS.NAME_ERROR;
USE_ERROR : exception renames IO_EXCEPTIONS.USE_ERROR;
DEVICE_ERROR : exception renames IO_EXCEPTIONS.DEVICE_ERROR;
END_ERROR : exception renames IO_EXCEPTIONS.END_ERROR;
DATA_ERROR : exception renames IO_EXCEPTIONS.DATA_ERROR;
private
-- implementation-dependent
end DIRECT_IO;
References: close procedure 14.2.1, count type 14.2, create procedure 14.2.1, data_error exception 14.4, default_mode 14.2.5, delete procedure 14.2.1, device_error exception 14.4, element_type 14.2.4, end_error exception 14.4, end_of_file function 14.2.4, file_mode 14.2.5, file_type 14.2.4, form function 14.2.1, in_file 14.2.4, index function 14.2.4, inout_file 14.2.4 14.2.1, io_exceptions package 14.4, is_open function 14.2.1, mode function 14.2.1, mode_error exception 14.4, name function 14.2.1, name_error exception 14.4, open procedure 14.2.1, out_file 14.2.1, read procedure 14.2.4, set_index procedure 14.2.4, size function 14.2.4, status_error exception 14.4, use_error exception 14.4, write procedure 14.2.4 14.2.1
![[INDEX]](lrm-idx.gif)
![[CONTENTS]](lrm-toc.gif)
![[Ada Information Clearinghouse]](small_adaic_logo.gif){kind=logo}
Address any questions or comments to adainfo@sw-eng.falls-church.va.us.