Lady Ada

Ada '83 Language Reference Manual

Copyright 1980, 1982, 1983 owned by the United States Government. Direct reproduction and usage requests to the Ada Information Clearinghouse.


14.2. Sequential and Direct Files

[PREVIOUS][UP][NEXT]

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:

14.2.1. File Management

[UP][NEXT]

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

14.2.2. Sequential Input-Output

[PREVIOUS][UP][NEXT]

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

14.2.3. Specification of the Package Sequential_IO

[PREVIOUS][UP][NEXT]
    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.

14.2.4. Direct Input-Output

[PREVIOUS][UP][NEXT]

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

14.2.5. Specification of the Package Direct_IO

[PREVIOUS][UP]
    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][CONTENTS]


[Ada Information Clearinghouse]

Address any questions or comments to adainfo@sw-eng.falls-church.va.us.