rbh@computer-science.nottingham.ac.UK (Roger Henry) (08/20/87)
**************
Number 3 of five mailings of the proposed BSI Standard I/O Library Def Mods
Please see an earlier mailing for the complete list
**************
::::::::::::::
Channel.def
::::::::::::::
DEFINITION MODULE Channel;
(* Proposed BSI Standard Modula-2 I/O Library
* Copyright Roger Henry, University of Nottingham
* Version WG/2.0, August 17th 1987
* Permission is given to copy this Definition Module, with the
* copyright notice intact, for the purposes of evaluation and test.
* At the stage of a formal draft standard, Copyright will be transferred
* to BSI (and through BSI to other recognised standards bodies).
* Status: For review by BSI/IST/5/13
*)
(*
Identification of channels by channel numbers.
Allocation of channel numbers.
*)
(*
EXPORT QUALIFIED
noNumber, minNumber, maxReady, maxNumber, Numbers, AllNumbers,
Allocate, IsAllocated, Deallocate;
*)
CONST
noNumber = 0; (* value if none free *)
minNumber = 1; (* lowest channel number *)
maxReady = 10; (* highest pre-allocated *)
maxNumber = 64; (* highest channel number *)
(* maxReady and maxNumber are implementation-defined values *)
TYPE
Numbers = [minNumber .. maxNumber];
AllNumbers = [noNumber .. maxNumber];
(* Channel numbers minNumber to maxReady are always allocated *)
(* Channel numbers maxReady+1 to maxNumber are initially unallocated *)
(* note:
the pre-allocated numbers may be used in simple programs and other
contexts where the user can ensure that there will be no conflicts.
*)
PROCEDURE Allocate(VAR cn: AllNumbers);
(* post: cn is set to noNumber *)
(* or to a previously unallocated channel number *)
(* which is now allocated *)
(* note:
the dynamic allocation scheme is provided for use in independent modules
or other contexts where the numbers in use are not known
*)
PROCEDURE IsAllocated(cn: Numbers): BOOLEAN;
(* post: TRUE iff the given channel number is allocated *)
PROCEDURE Deallocate(cn: Numbers);
(* post : for cn > maxReady, the channel number is now not Allocated *)
(* pre-allocated channels remain allocated *)
END Channel.
::::::::::::::
Device.def
::::::::::::::
DEFINITION MODULE Device;
(* Proposed BSI Standard Modula-2 I/O Library
* Copyright Roger Henry, University of Nottingham
* Version WG/2.0, August 17th 1987
* Permission is given to copy this Definition Module, with the
* copyright notice intact, for the purposes of evaluation and test.
* At the stage of a formal draft standard, Copyright will be transferred
* to BSI (and through BSI to other recognised standards bodies).
* Status: For review by BSI/IST/5/13
*)
(*
General properties of devices linked to a channel.
Operations on the devices.
*)
IMPORT
Channel;
(*
EXPORT QUALIFIED
Modes, Mappings, NlCh,
IsOpen, IsReadable, IsWriteable, IsText, IsInteractive,
Flush, Reset, Close;
*)
(* Channels are not initially Linked to a device. *)
(* The Linking is done by procedures exported from device driver modules. *)
(* These procedures specify, or allow the choice of, one of the *)
(* following Modes and Mappings *)
TYPE
Modes = (readOnly, writeOnly, readWrite);
Mappings = (text, binary);
(* text mapping device drivers shall apply any necessary *)
(* mapping between the external representation of text files *)
(* and the internal representation. *)
(* The internal representation shall be a sequence *)
(* of storage units interpreted as CHAR values with new lines being *)
(* represented by a single implementation-defined CHAR value. *)
(* In the case of binary mapping device drivers, the internal *)
(* representation of data shall be a sequence of storage units *)
(* corresponding directly to the external sequence of storage units. *)
(* note:
Not all operating systems distinguish between text and binary files.
However, for portability of programs between operating systems, text
mapping must be selected if the external data has to be in a format
compatible with other text files in the environment.
An application may employ binary mapping when it
only needs to write text to be read by itself
(or by other applications using this library on the same system).
*)
PROCEDURE NlCh(): CHAR;
(* post : returns the character used to represent new lines internally *)
(* A channel is Open if it is Linked to a device *)
(* Closed means not Open *)
PROCEDURE IsOpen(cn: Channel.Numbers): BOOLEAN;
(* post : TRUE iff the numbered channel is Linked to a device *)
PROCEDURE IsReadable(cn: Channel.Numbers): BOOLEAN;
(* post : TRUE iff the numbered channel is Linked to a device for input *)
PROCEDURE IsWriteable(cn: Channel.Numbers): BOOLEAN;
(* post : TRUE iff the numbered channel is Linked to a device for output *)
PROCEDURE IsText(cn: Channel.Numbers): BOOLEAN;
(* pre : the numbered channel is Open *)
(* post : TRUE iff the numbered channel conforms to text mapping rules *)
(* The user may enquire if a device is interactive - *)
(* if it is then input is being generated while the program is running *)
(* rather than being stored as in a disc file *)
PROCEDURE IsInteractive(cn: Channel.Numbers): BOOLEAN;
(* pre : the numbered channel is Open *)
(* post : returns TRUE iff the device is interactive *)
PROCEDURE Flush(cn: Channel.Numbers);
(* pre : the numbered channel is Linked to a device Open for output *)
(* post : all data held in output buffers has been written *)
PROCEDURE Reset(cn: Channel.Numbers);
(* pre : the numbered channel is Open *)
(* post : the drivers and the device or device instance are reset *)
PROCEDURE Close(cn: Channel.Numbers);
(* pre : the numbered channel is Open *)
(* post : all data held in output buffers has been written *)
(* note : the channel is no longer linked to the device *)
END Device.
::::::::::::::
Term.def
::::::::::::::
DEFINITION MODULE Term;
(* Proposed BSI Standard Modula-2 I/O Library
* Copyright Roger Henry, University of Nottingham
* Version WG/2.0, August 17th 1987
* Permission is given to copy this Definition Module, with the
* copyright notice intact, for the purposes of evaluation and test.
* At the stage of a formal draft standard, Copyright will be transferred
* to BSI (and through BSI to other recognised standards bodies).
* Status: For review by BSI/IST/5/13
*)
(* Terminal device driver module *)
IMPORT
Channel;
(*
EXPORT QUALIFIED
ByChar, ByLine, IsMine;
*)
(*
Char mode:
input is available as soon as it has been typed;
characters read from the channel are not echoed by the driver;
a read request for n characters will only return 1 character;
text (line) mapping applies.
Line mode:
input is buffered and made available on typing the appropriate
end of line indication or some system-defined character
(which will not be included in the input);
characters read from the channel are echoed by the driver;
a read request for n characters will return m characters
as soon as they are available where 0 < m <= n;
a read request will return 0 characters iff the user has indicated
that there is no more input and all previously typed characters
have been read - more input may be available after a call of
Reset on the associated channel;
text (line) mapping applies.
Typed characters are distributed between channels according to the
sequence of read requests.
Channels Linked to Term are Open for reading and writing and the device
is interactive.
*)
PROCEDURE ByChar(cn: Channel.Numbers);
(* pre : cn is the number of a Closed channel *)
(* post: the channel is Linked to the terminal in Char mode *)
PROCEDURE ByLine(cn: Channel.Numbers);
(* pre : cn is the number of a Closed channel *)
(* post: the channel is Linked to the terminal in Line mode *)
PROCEDURE IsMine(cn: Channel.Numbers): BOOLEAN;
(* returns TRUE iff channel is linked to Term *)
END Term.
::::::::::::::
SFile.def
::::::::::::::
DEFINITION MODULE SFile;
(* Proposed BSI Standard Modula-2 I/O Library
* Copyright Roger Henry, University of Nottingham
* Version WG/2.0, August 17th 1987
* Permission is given to copy this Definition Module, with the
* copyright notice intact, for the purposes of evaluation and test.
* At the stage of a formal draft standard, Copyright will be transferred
* to BSI (and through BSI to other recognised standards bodies).
* Status: For review by BSI/IST/5/13
*)
(*
Sequential Files.
There is a common read/write mark associated with every channel.
The mark is at the start of the file after opening and after a Reset.
It is moved forward by the number of storage units read or written.
*)
IMPORT
Channel;
FROM Device
IMPORT text, binary, readOnly, readWrite;
(*
EXPORT QUALIFIED
Mappings, Modes, New, Old, Fresh, IsMine;
*)
TYPE
Mappings = [text .. binary];
Modes = [readOnly .. readWrite];
(* The Open routines may generate device errors *)
PROCEDURE New(
cn: Channel.Numbers;
name: ARRAY OF CHAR;
map: Mappings;
mode: Modes
);
(* pre: cn is the number of a Closed channel *)
(* name is the required name of a new file *)
(* map is text to guarantee line mapping *)
(* mode gives the required transfer operations *)
(* post: the channel is Linked to SFile *)
PROCEDURE Old(
cn: Channel.Numbers;
name: ARRAY OF CHAR;
map: Mappings;
mode: Modes
);
(* pre: cn is the number of a Closed channel *)
(* name is the required name of an existing file *)
(* map is text to guarantee line mapping *)
(* mode gives the required transfer operations *)
(* post: the channel is Linked to SFile *)
PROCEDURE Fresh(
cn: Channel.Numbers;
name: ARRAY OF CHAR;
map: Mappings;
mode: Modes
);
(* pre: cn is the number of a Closed channel *)
(* name is the required name of the file *)
(* map is text to guarantee line mapping *)
(* mode gives the required transfer operations *)
(* post: the channel is Linked to SFile *)
(* if the file already existed, it is truncated to zero length *)
PROCEDURE IsMine(cn: Channel.Numbers): BOOLEAN;
(* post: TRUE iff the numbered channel is Linked to SFile *)
END SFile.
::::::::::::::
RFile.def
::::::::::::::
DEFINITION MODULE RFile;
(* Proposed BSI Standard Modula-2 I/O Library
* Copyright Roger Henry, University of Nottingham
* Version WG/2.0, August 17th 1987
* Permission is given to copy this Definition Module, with the
* copyright notice intact, for the purposes of evaluation and test.
* At the stage of a formal draft standard, Copyright will be transferred
* to BSI (and through BSI to other recognised standards bodies).
* Status: For review by BSI/IST/5/13
*)
(*
Random access files.
(On some systems, random access may not be supported on text files.)
There is a common read/write mark associated with every channel.
The mark is at the start of the file after opening and after a Reset.
It is moved forward by the number of storage units read or written and
may be saved and restored using GetMark and SetMark.
*)
IMPORT
Channel;
FROM Device
IMPORT text, binary, readOnly, readWrite;
(*
EXPORT QUALIFIED
Mappings, Modes, New, Old, Fresh, IsMine,
FileMark, GetMark, SetMark, SetAtStart, SetAtEnd, MoveMark;
*)
TYPE
Mappings = [text .. binary];
Modes = [readOnly .. readWrite];
(* The Open routines may generate device errors *)
PROCEDURE New(
cn: Channel.Numbers;
name: ARRAY OF CHAR;
map: Mappings;
mode: Modes
);
(* pre: cn is the number of a Closed channel *)
(* name is the required name of a new file *)
(* map is text to guarantee line mapping *)
(* mode gives the required transfer operations *)
(* post: the channel is Linked to RFile *)
PROCEDURE Old(
cn: Channel.Numbers;
name: ARRAY OF CHAR;
map: Mappings;
mode: Modes
);
(* pre: cn is the number of a Closed channel *)
(* name is the required name of an existing file *)
(* map is text to guarantee line mapping *)
(* mode gives the required transfer operations *)
(* post: the channel is Linked to RFile *)
PROCEDURE Fresh(
cn: Channel.Numbers;
name: ARRAY OF CHAR;
map: Mappings;
mode: Modes
);
(* pre: cn is the number of a Closed channel *)
(* name is the required name of the file *)
(* map is text to guarantee line mapping *)
(* mode gives the required transfer operations *)
(* post: the channel is Linked to RFile *)
(* if the file already existed, it is truncated to zero length *)
PROCEDURE IsMine(cn: Channel.Numbers): BOOLEAN;
(* post: TRUE iff the numbered channel is Linked to RFile *)
(*
read/write positions are given in storage units relative to the start
of the file.
*)
TYPE
FileMark =
RECORD
high: CARDINAL;
low: CARDINAL
END;
PROCEDURE GetMark(cn: Channel.Numbers; VAR mark: FileMark);
(* pre : the numbered channel is Linked to RFile and is Open *)
(* post : mark = read/write position relative to the start of the file *)
PROCEDURE SetMark(cn: Channel.Numbers; mark: FileMark);
(* pre : the numbered channel is Linked to RFile and is Open, *)
(* mark <= number of storage units in the file *)
(* post : the read/write mark is set relative to the start of the file *)
PROCEDURE SetAtStart(cn: Channel.Numbers);
(* pre : the numbered channel is Linked to RFile and is Open, *)
(* post : the read/write mark is set to the start of the file *)
PROCEDURE SetAtEnd(cn: Channel.Numbers);
(* pre : the numbered channel is Linked to RFile and is Open, *)
(* post : the read/write mark is set to the end of the file *)
PROCEDURE MoveMark(cn: Channel.Numbers; by: INTEGER);
(* pre : the numbered channel is Linked to RFile and is Open, *)
(* the move will not attempt to move the file mark *)
(* beyond the limits of the file *)
(* post : the read/write mark is set relative to the previous mark *)
END RFile.