rbh@computer-science.nottingham.ac.UK (Roger Henry) (08/20/87)
**************
Number 4 of 5 Mailings of the Proposed BSI Standard I/O Library Def Mods
Please see an earlier mailing for the complete list
**************
::::::::::::::
In.def
::::::::::::::
DEFINITION MODULE In;
(* 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
*)
(* Device independent input of storage units and characters *)
(* Note:
This is a direct interface to the device drivers and should not
normally be used on channels over which higher level buffered input
is taking place.
*)
FROM SYSTEM IMPORT
ADDRESS;
IMPORT
Channel;
(*
EXPORT QUALIFIED
Read, ReadCh, ReadChars;
*)
PROCEDURE Read(
cn: Channel.Numbers;
maxStunts: CARDINAL; (* maximum number of storage units to read *)
where: ADDRESS; (* where to read them to *)
VAR nStunts: CARDINAL); (* number read *)
(* pre : the numbered channel is open for reading *)
(* do : call Linked device read routine once *)
(* post: nStunts is the number of storage units supplied by Linked device *)
(* nStunts = 0 implies end of data *)
PROCEDURE ReadCh(cn: Channel.Numbers; VAR ch: CHAR; VAR done: BOOLEAN);
(* pre : the numbered channel is open for reading *)
(* do : read and interpret storage units from device for one character *)
(* post: iff done = TRUE, a character has been read and stored in ch *)
(* note: done is FALSE if there is not enough data from the device *)
PROCEDURE ReadChars(
cn: Channel.Numbers;
VAR chars: ARRAY OF CHAR; (* array to read chars to *)
start: CARDINAL; (* relative index to start storing *)
VAR nChars: CARDINAL (* number of characters read *)
);
(* pre : the numbered channel is open for reading *)
(* do : call Linked driver to read characters from start to end of array *)
(* post: nChars is the number of characters supplied by Linked device *)
(* nChars = 0 implies end of data *)
END In.
::::::::::::::
BuffIn.def
::::::::::::::
DEFINITION MODULE BuffIn;
(* 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
*)
IMPORT
Channel;
FROM SYSTEM IMPORT
ADDRESS;
(*
EXPORT QUALIFIED
Have, Look, Forward,
HaveCh, ThisCh, ForwardCh,
Mark, Rewind,
SetBuffer, FreeBuffer;
*)
(*
Input is taken through a buffer.
The buffer is allocated on the first operation on which it is needed
(in which case a default buffer size is used) or it may be pre-allocated.
Look and ThisCh copy data from the current read position.
The read position is only moved forward by calls of Forward and ForwardCh.
It is returned to the logical start of the buffer by Rewind.
Mark sets the logical start of the buffer to the current read position.
The buffer shall be set empty if the driver indicates that the read position
has moved since the last read (because of an intervening operation such as
a seek on a file).
*)
PROCEDURE Have(cn: Channel.Numbers; nStunts: CARDINAL): BOOLEAN;
(* pre : the numbered channel is open for reading *)
(* do : make repeated calls of the Linked driver routines as necessary *)
(* to make nStunts storage units available in the buffer or *)
(* until no further data is available from the device *)
(* post: returns TRUE iff there are at least nStunts of data *)
(* available from the current read position *)
PROCEDURE Look(cn: Channel.Numbers; nStunts: CARDINAL; where: ADDRESS);
(* pre : at least nStunts of data are available from the *)
(* current read position in the buffer or in the subsequent data *)
(* post : nStunts storage units copied from the read position *)
(* to the given address *)
PROCEDURE Forward(cn: Channel.Numbers; nStunts: CARDINAL);
(* pre : at least nStunts of data are available from the *)
(* current read position in the buffer or in the subsequent data *)
(* post : the read position is moved forward by nStunts storage units *)
(*
Character routines also provided for convenience
*)
PROCEDURE HaveCh(cn: Channel.Numbers): BOOLEAN;
(* post : returns TRUE iff there is at least one character available *)
(* from the current read position *)
PROCEDURE ThisCh(cn: Channel.Numbers): CHAR;
(* pre : at least one character is available from the current *)
(* read position *)
(* post : returns the character at the current read position *)
PROCEDURE ForwardCh(cn: Channel.Numbers);
(* pre : at least one character is available from the current *)
(* read position *)
(* post : the read position is moved forward by one character *)
(*
*)
PROCEDURE Mark(cn: Channel.Numbers);
(* pre : a buffer is allocated for the channel *)
(* post : the start of the buffer is set to the current read position *)
PROCEDURE Rewind(cn: Channel.Numbers);
(* pre : a buffer is allocated for the channel *)
(* post : the current read position is set to the buffer start *)
(*
*)
PROCEDURE SetBuffer(cn: Channel.Numbers; bufSize: CARDINAL);
(* pre : a buffer is not allocated for the channel *)
(* post : a buffer of the given size is allocated to the channel *)
PROCEDURE FreeBuffer(cn: Channel.Numbers);
(* post : any buffer previously allocated to the channel is now freed *)
(* note : data which has not been copied from the buffer will be lost *)
END BuffIn.
::::::::::::::
Out.def
::::::::::::::
DEFINITION MODULE Out;
(* 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
*)
(* device independent output of storage units and characters *)
IMPORT
Channel;
FROM SYSTEM IMPORT
ADDRESS;
(*
EXPORT QUALIFIED
Write, WriteCh, WriteChars;
*)
PROCEDURE Write(
cn: Channel.Numbers;
nStunts: CARDINAL; (* number of storage units to write *)
where: ADDRESS (* from where *)
);
(* pre : the numbered channel is open for writing *)
(* post : nStunts storage units have been copied by the device driver *)
(* for transmission to the destination *)
PROCEDURE WriteCh(cn: Channel.Numbers; ch: CHAR);
(* pre : the numbered channel is open for writing *)
(* post: the given character value has been copied by the device driver *)
(* for transmission to the destination *)
PROCEDURE WriteChars(
cn: Channel.Numbers;
VAR chars: ARRAY OF CHAR;
start, nChars: CARDINAL
);
(* pre : the numbered channel is open for writing *)
(* there are nChars initialised elements from start in the array *)
(* post: nChars character values from start have been copied by *)
(* the device driver for transmission to the destination *)
END Out.