gcc/m2/gm2-libs-iso/IOChan.mod - gcc.git - Git at Google

 (* IOChan.mod implement the ISO IOChan specification.

 Copyright (C) 2002-2025 Free Software Foundation, Inc.
 Contributed by Gaius Mulley <gaius.mulley@southwales.ac.uk>.

 This file is part of GNU Modula-2.

 GNU Modula-2 is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 3, or (at your option)
 any later version.

 GNU Modula-2 is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 General Public License for more details.

 Under Section 7 of GPL version 3, you are granted additional
 permissions described in the GCC Runtime Library Exception, version
 3.1, as published by the Free Software Foundation.

 You should have received a copy of the GNU General Public License and
 a copy of the GCC Runtime Library Exception along with this program;
 see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
 <http://www.gnu.org/licenses/>.  *)

 IMPLEMENTATION MODULE IOChan ;

 IMPORT FIO, EXCEPTIONS, M2EXCEPTION, RTio,
        RTentity, errno, ErrnoCategory, IOLink, StdChans, M2RTS ;

 FROM EXCEPTIONS IMPORT ExceptionSource, RAISE, AllocateSource,
                        IsCurrentSource, IsExceptionalExecution ;
 FROM Storage IMPORT ALLOCATE ;


 TYPE
    ChanId = RTio.ChanId ;

 VAR
    iochan :  ExceptionSource ;
    invalid:  ChanId ;


 PROCEDURE InvalidChan () : ChanId ;
   (* Returns the value identifying the invalid channel. *)
 BEGIN
    RETURN( invalid )
 END InvalidChan ;


 PROCEDURE CheckValid (cid: ChanId) ;
   (* internal routine to check whether we have a valid channel *)
 BEGIN
    IF cid=InvalidChan()
    THEN
       RAISE(iochan, ORD(notAChannel), 'IOChan: ChanId specified is invalid')
    END
 END CheckValid ;


   (* For each of the following operations, if the device supports the
      operation on the channel, the behaviour of the procedure conforms
      with the description below.  The full behaviour is defined for
      each device module.  If the device does not support the operation
      on the channel, the behaviour of the procedure is to raise the
      exception notAvailable.
   *)

   (* Text operations - these perform any required translation
      between the internal and external representation of text.
   *)

 PROCEDURE Look (cid: ChanId; VAR ch: CHAR; VAR res: IOConsts.ReadResults) ;
   (* If there is a character as the next item in the input stream cid,
      assigns its value to ch without removing it from the stream;
      otherwise the value of ch is not defined.
      res (and the stored read result) are set to the value
      allRight, endOfLine, or endOfInput.
   *)
 VAR
    did: IOLink.DeviceId ;
    dtp: IOLink.DeviceTablePtr ;
 BEGIN
    CheckValid(cid) ;
    did := RTio.GetDeviceId(cid) ;
    dtp := IOLink.DeviceTablePtrValue(cid, did) ;
    IF dtp=NIL
    THEN
       RAISE(iochan, ORD(hardDeviceError),
             'IOChan.Look: device table ptr is NIL')
    ELSE
       WITH dtp^ DO
          IF cid=StdChans.NullChan()
          THEN
             result := IOConsts.endOfInput
          ELSIF (ChanConsts.readFlag IN flags) AND (ChanConsts.textFlag IN flags)
          THEN
             doLook(dtp, ch, res)
          ELSE
             res := IOConsts.wrongFormat
          END ;
          result := res
       END
    END
 END Look ;


 PROCEDURE Skip (cid: ChanId) ;
   (* If the input stream cid has ended, the exception skipAtEnd is raised;
      otherwise the next character or line mark in cid is removed,
      and the stored read result is set to the value allRight.
   *)
 VAR
    did: IOLink.DeviceId ;
    dtp: IOLink.DeviceTablePtr ;
 BEGIN
    CheckValid(cid) ;
    did := RTio.GetDeviceId(cid) ;
    dtp := IOLink.DeviceTablePtrValue(cid, did) ;
    IF dtp=NIL
    THEN
       RAISE(iochan, ORD(hardDeviceError),
             'IOChan.Skip: device table ptr is NIL')
    ELSE
       WITH dtp^ DO
          IF (cid=StdChans.NullChan()) OR (result=IOConsts.endOfInput)
          THEN
             RAISE(iochan, ORD(skipAtEnd),
                   'IOChan.Skip: attempt to skip data from a stream that has ended')
          ELSIF (ChanConsts.readFlag IN flags) AND (ChanConsts.textFlag IN flags)
          THEN
             doSkip(dtp) ;
             result := IOConsts.allRight
          ELSE
             RAISE(iochan, ORD(notAvailable),
                   'IOChan.Skip: attempt to skip data from a channel which is not configured as read and text')
          END
       END
    END
 END Skip ;


 PROCEDURE SkipLook (cid: ChanId;
                     VAR ch: CHAR;
                     VAR res: IOConsts.ReadResults) ;
   (* If the input stream cid has ended, the exception skipAtEnd is raised;
      otherwise the next character or line mark in cid is removed.
      If there is a character as the next item in cid stream,
      assigns its value to ch without removing it from the stream.
      Otherwise, the value of ch is not defined.
      res (and the stored read result) are set to the value allRight,
      endOfLine, or endOfInput.
   *)
 VAR
    did: IOLink.DeviceId ;
    dtp: IOLink.DeviceTablePtr ;
 BEGIN
    CheckValid(cid) ;
    did := RTio.GetDeviceId(cid) ;
    dtp := IOLink.DeviceTablePtrValue(cid, did) ;
    IF dtp=NIL
    THEN
       RAISE(iochan, ORD(hardDeviceError),
             'IOChan.SkipLook: device table ptr is NIL')
    ELSE
       WITH dtp^ DO
          IF (cid=StdChans.NullChan()) OR (result=IOConsts.endOfInput)
          THEN
             RAISE(iochan, ORD(skipAtEnd),
                   'IOChan.SkipLook: attempt to skip data from a stream that has ended')
          ELSIF (ChanConsts.readFlag IN flags) AND (ChanConsts.textFlag IN flags)
          THEN
             doSkipLook(dtp, ch, result)
          ELSE
             RAISE(iochan, ORD(notAvailable),
                   'IOChan.SkipLook: attempt to skip data from a channel which is not configured as read and text')
          END ;
          res := result
       END
    END
 END SkipLook ;


 PROCEDURE WriteLn (cid: ChanId) ;
   (* Writes a line mark over the channel cid. *)
 VAR
    did: IOLink.DeviceId ;
    dtp: IOLink.DeviceTablePtr ;
 BEGIN
    CheckValid(cid) ;
    did := RTio.GetDeviceId(cid) ;
    dtp := IOLink.DeviceTablePtrValue(cid, did) ;
    IF dtp=NIL
    THEN
       RAISE(iochan, ORD(hardDeviceError),
             'IOChan.WriteLn: device table ptr is NIL')
    ELSE
       WITH dtp^ DO
          IF cid=StdChans.NullChan()
          THEN
             (* do nothing *)
          ELSIF (ChanConsts.writeFlag IN flags) AND (ChanConsts.textFlag IN flags)
          THEN
             dtp^.doLnWrite(dtp)
          ELSE
             RAISE(iochan, ORD(notAvailable),
                   'IOChan.WriteLn: attempting to write to a channel which is not configured as write and text')
          END
       END
    END
 END WriteLn ;


 PROCEDURE TextRead (cid: ChanId;
                     to: SYSTEM.ADDRESS;
                     maxChars: CARDINAL;
                     VAR charsRead: CARDINAL) ;
   (* Reads at most maxChars characters from the current line in cid,
      and assigns corresponding values to successive components of an
      ARRAY OF CHAR variable for which the address of the first
      component is to. The number of characters read is assigned
      to charsRead. The stored read result is set to allRight,
      endOfLine, or endOfInput.
   *)
 VAR
    did: IOLink.DeviceId ;
    dtp: IOLink.DeviceTablePtr ;
 BEGIN
    CheckValid(cid) ;
    did := RTio.GetDeviceId(cid) ;
    dtp := IOLink.DeviceTablePtrValue(cid, did) ;
    IF dtp=NIL
    THEN
       RAISE(iochan, ORD(hardDeviceError),
             'IOChan.TextRead: device table ptr is NIL')
    ELSE
       WITH dtp^ DO
          IF (cid=StdChans.NullChan()) OR (result=IOConsts.endOfInput)
          THEN
             charsRead := 0 ;
             result := IOConsts.endOfInput
          ELSIF (ChanConsts.readFlag IN flags) AND (ChanConsts.textFlag IN flags)
          THEN
             doTextRead(dtp, to, maxChars, charsRead)
          ELSE
             RAISE(iochan, ORD(notAvailable),
                   'IOChan.TextRead: attempt to read data from a channel which is not configured as read and text')
          END
       END
    END
 END TextRead ;


 PROCEDURE TextWrite (cid: ChanId;
                      from: SYSTEM.ADDRESS;
                      charsToWrite: CARDINAL) ;
   (* Writes a number of characters given by the value of charsToWrite,
      from successive components of an ARRAY OF CHAR variable for which
      the address of the first component is from, to the channel cid.
   *)
 VAR
    did: IOLink.DeviceId ;
    dtp: IOLink.DeviceTablePtr ;
 BEGIN
    CheckValid(cid) ;
    did := RTio.GetDeviceId(cid) ;
    dtp := IOLink.DeviceTablePtrValue(cid, did) ;
    IF dtp=NIL
    THEN
       RAISE(iochan, ORD(hardDeviceError),
             'IOChan.TextWrite: device table ptr is NIL')
    ELSE
       WITH dtp^ DO
          IF cid=StdChans.NullChan()
          THEN
             (* do nothing *)
          ELSIF (ChanConsts.writeFlag IN flags) AND (ChanConsts.textFlag IN flags)
          THEN
             doTextWrite(dtp, from, charsToWrite)
          ELSE
             RAISE(iochan, ORD(notAvailable),
                   'IOChan.TextWrite: attempt to write data to a channel which is not configured as write and text')
          END
       END
    END
 END TextWrite ;


   (* Direct raw operations - these do not effect translation between
      the internal and external representation of data
   *)

 PROCEDURE RawRead (cid: ChanId;
                    to: SYSTEM.ADDRESS;
                    maxLocs: CARDINAL;
                    VAR locsRead: CARDINAL) ;
   (* Reads at most maxLocs items from cid, and assigns corresponding
      values to successive components of an ARRAY OF LOC variable for
      which the address of the first component is to. The number of
      characters read is assigned to locsRead. The stored read result
      is set to the value allRight, or endOfInput.
   *)
 VAR
    did: IOLink.DeviceId ;
    dtp: IOLink.DeviceTablePtr ;
 BEGIN
    CheckValid(cid) ;
    did := RTio.GetDeviceId(cid) ;
    dtp := IOLink.DeviceTablePtrValue(cid, did) ;
    IF dtp=NIL
    THEN
       RAISE(iochan, ORD(hardDeviceError),
             'IOChan.RawRead: device table ptr is NIL')
    ELSE
       WITH dtp^ DO
          IF (cid=StdChans.NullChan()) OR (result=IOConsts.endOfInput)
          THEN
             locsRead := 0 ;
             result := IOConsts.endOfInput
          ELSIF (ChanConsts.readFlag IN flags) AND (ChanConsts.rawFlag IN flags)
          THEN
             doRawRead(dtp, to, maxLocs, locsRead)
          ELSE
             RAISE(iochan, ORD(notAvailable),
                   'IOChan.RawRead: attempt to read data from a channel which is not configured as read and raw')
          END
       END
    END
 END RawRead ;


 PROCEDURE RawWrite (cid: ChanId; from: SYSTEM.ADDRESS; locsToWrite: CARDINAL) ;
   (* Writes a number of items given by the value of charsToWrite,
      from successive components of an ARRAY OF LOC variable for
      which the address of the first component is from, to the channel cid.
   *)
 VAR
    did: IOLink.DeviceId ;
    dtp: IOLink.DeviceTablePtr ;
 BEGIN
    CheckValid(cid) ;
    did := RTio.GetDeviceId(cid) ;
    dtp := IOLink.DeviceTablePtrValue(cid, did) ;
    IF dtp=NIL
    THEN
       RAISE(iochan, ORD(hardDeviceError),
             'IOChan.RawWrite: device table ptr is NIL')
    ELSE
       WITH dtp^ DO
          IF (cid=StdChans.NullChan()) OR (result=IOConsts.endOfInput)
          THEN
             result := IOConsts.endOfInput
          ELSIF (ChanConsts.writeFlag IN flags) AND (ChanConsts.rawFlag IN flags)
          THEN
             doRawWrite(dtp, from, locsToWrite)
          ELSE
             RAISE(iochan, ORD(notAvailable),
                   'IOChan.RawWrite: attempt to write data to a channel which is not configured as write and raw')
          END
       END
    END
 END RawWrite ;


   (* Common operations *)

 PROCEDURE GetName (cid: ChanId; VAR s: ARRAY OF CHAR) ;
   (* Copies to s a name associated with the channel cid, possibly truncated
      (depending on the capacity of s).
   *)
 VAR
    did: IOLink.DeviceId ;
    dtp: IOLink.DeviceTablePtr ;
 BEGIN
    CheckValid(cid) ;
    did := RTio.GetDeviceId(cid) ;
    dtp := IOLink.DeviceTablePtrValue(cid, did) ;
    IF dtp=NIL
    THEN
       RAISE(iochan, ORD(hardDeviceError),
             'IOChan.GetName: device table ptr is NIL')
    ELSE
       dtp^.doGetName(dtp, s)
    END
 END GetName ;


 PROCEDURE Reset (cid: ChanId) ;
   (* Resets the channel cid to a state defined by the device module. *)
 VAR
    did: IOLink.DeviceId ;
    dtp: IOLink.DeviceTablePtr ;
 BEGIN
    CheckValid(cid) ;
    did := RTio.GetDeviceId(cid) ;
    dtp := IOLink.DeviceTablePtrValue(cid, did) ;
    IF dtp=NIL
    THEN
       RAISE(iochan, ORD(hardDeviceError),
             'IOChan.Reset: device table ptr is NIL')
    ELSE
       dtp^.doReset(dtp)
    END
 END Reset ;


 PROCEDURE Flush (cid: ChanId) ;
   (* Flushes any data buffered by the device module out to the channel cid. *)
 VAR
    did: IOLink.DeviceId ;
    dtp: IOLink.DeviceTablePtr ;
 BEGIN
    CheckValid(cid) ;
    did := RTio.GetDeviceId(cid) ;
    dtp := IOLink.DeviceTablePtrValue(cid, did) ;
    IF dtp=NIL
    THEN
       RAISE(iochan, ORD(hardDeviceError),
             'IOChan.Flush: device table ptr is NIL')
    ELSE
       dtp^.doFlush(dtp)
    END
 END Flush ;


   (* Access to read results *)

 PROCEDURE SetReadResult (cid: ChanId; res: IOConsts.ReadResults) ;
   (* Sets the read result value for the channel cid to the value res. *)
 VAR
    did: IOLink.DeviceId ;
    dtp: IOLink.DeviceTablePtr ;
 BEGIN
    CheckValid(cid) ;
    did := RTio.GetDeviceId(cid) ;
    dtp := IOLink.DeviceTablePtrValue(cid, did) ;
    IF dtp=NIL
    THEN
       RAISE(iochan, ORD(hardDeviceError),
             'IOChan.SetReadResult: device table ptr is NIL')
    ELSE
       dtp^.result := res
    END
 END SetReadResult ;


 PROCEDURE ReadResult (cid: ChanId) : IOConsts.ReadResults ;
   (* Returns the stored read result value for the channel cid.
      (This is initially the value notKnown).
   *)
 VAR
    did: IOLink.DeviceId ;
    dtp: IOLink.DeviceTablePtr ;
 BEGIN
    CheckValid(cid) ;
    did := RTio.GetDeviceId(cid) ;
    dtp := IOLink.DeviceTablePtrValue(cid, did) ;
    IF dtp=NIL
    THEN
       RAISE(iochan, ORD(hardDeviceError),
             'IOChan.SetReadResult: device table ptr is NIL') ;
       RETURN IOConsts.notKnown
    ELSE
       RETURN( dtp^.result )
    END
 END ReadResult ;


   (* Users can discover which flags actually apply to a channel *)

 PROCEDURE CurrentFlags (cid: ChanId) : ChanConsts.FlagSet ;
   (* Returns the set of flags that currently apply to the channel cid. *)
 VAR
    did  : IOLink.DeviceId ;
    dtp  : IOLink.DeviceTablePtr ;
    empty: ChanConsts.FlagSet ;
 BEGIN
    CheckValid(cid) ;
    did := RTio.GetDeviceId(cid) ;
    dtp := IOLink.DeviceTablePtrValue(cid, did) ;
    IF dtp=NIL
    THEN
       RAISE(iochan, ORD(hardDeviceError),
             'IOChan.SetReadResult: device table ptr is NIL') ;
       empty := ChanConsts.FlagSet {} ;
       RETURN empty
    ELSE
       RETURN( dtp^.flags )
    END
 END CurrentFlags ;


   (* The following exceptions are defined for this module and its clients *)

 PROCEDURE IsChanException () : BOOLEAN ;
   (* Returns TRUE if the current coroutine is in the exceptional
      execution state because of the raising of an exception from
      ChanExceptions; otherwise returns FALSE.
   *)
 BEGIN
    RETURN( IsExceptionalExecution() AND IsCurrentSource(iochan) )
 END IsChanException ;


 PROCEDURE ChanException () : ChanExceptions ;
   (* If the current coroutine is in the exceptional execution state
      because of the raising of an exception from ChanExceptions,
      returns the corresponding enumeration value, and otherwise
      raises an exception.
   *)
 BEGIN
    IF IsChanException()
    THEN
       RETURN( VAL(ChanExceptions, EXCEPTIONS.CurrentNumber(iochan)) )
    ELSE
       M2RTS.NoException (SYSTEM.ADR(__FILE__), __LINE__,
                         __COLUMN__, SYSTEM.ADR(__FUNCTION__),
                         SYSTEM.ADR ("not in the exceptional execution state"))
    END
 END ChanException ;


   (* When a device procedure detects a device error, it raises the
      exception softDeviceError or hardDeviceError.  If these exceptions
      are handled, the following facilities may be used to discover
      an implementation-defined error number for the channel.
   *)

 PROCEDURE DeviceError (cid: ChanId) : DeviceErrNum ;
   (* If a device error exception has been raised for the channel cid,
      returns the error number stored by the device module.
   *)
 VAR
    did: IOLink.DeviceId ;
    dtp: IOLink.DeviceTablePtr ;
 BEGIN
    CheckValid(cid) ;
    did := RTio.GetDeviceId(cid) ;
    dtp := IOLink.DeviceTablePtrValue(cid, did) ;
    IF dtp=NIL
    THEN
       RAISE(iochan, ORD(hardDeviceError),
             'IOChan.DeviceError: device table ptr is NIL') ;
       RETURN DeviceError (invalid)
    ELSE
       RETURN( dtp^.errNum )
    END
 END DeviceError ;


 BEGIN
    AllocateSource(iochan) ;
    invalid := ChanId(RTio.InitChanId())
 END IOChan.
	(* IOChan.mod implement the ISO IOChan specification.

	Copyright (C) 2002-2025 Free Software Foundation, Inc.
	Contributed by Gaius Mulley <gaius.mulley@southwales.ac.uk>.

	This file is part of GNU Modula-2.

	GNU Modula-2 is free software; you can redistribute it and/or modify
	it under the terms of the GNU General Public License as published by
	the Free Software Foundation; either version 3, or (at your option)
	any later version.

	GNU Modula-2 is distributed in the hope that it will be useful, but
	WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	General Public License for more details.

	Under Section 7 of GPL version 3, you are granted additional
	permissions described in the GCC Runtime Library Exception, version
	3.1, as published by the Free Software Foundation.

	You should have received a copy of the GNU General Public License and
	a copy of the GCC Runtime Library Exception along with this program;
	see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
	<http://www.gnu.org/licenses/>. *)

	IMPLEMENTATION MODULE IOChan ;

	IMPORT FIO, EXCEPTIONS, M2EXCEPTION, RTio,
	RTentity, errno, ErrnoCategory, IOLink, StdChans, M2RTS ;

	FROM EXCEPTIONS IMPORT ExceptionSource, RAISE, AllocateSource,
	IsCurrentSource, IsExceptionalExecution ;
	FROM Storage IMPORT ALLOCATE ;


	TYPE
	ChanId = RTio.ChanId ;

	VAR
	iochan : ExceptionSource ;
	invalid: ChanId ;


	PROCEDURE InvalidChan () : ChanId ;
	(* Returns the value identifying the invalid channel. *)
	BEGIN
	RETURN( invalid )
	END InvalidChan ;


	PROCEDURE CheckValid (cid: ChanId) ;
	(* internal routine to check whether we have a valid channel *)
	BEGIN
	IF cid=InvalidChan()
	THEN
	RAISE(iochan, ORD(notAChannel), 'IOChan: ChanId specified is invalid')
	END
	END CheckValid ;


	(* For each of the following operations, if the device supports the
	operation on the channel, the behaviour of the procedure conforms
	with the description below. The full behaviour is defined for
	each device module. If the device does not support the operation
	on the channel, the behaviour of the procedure is to raise the
	exception notAvailable.
	*)

	(* Text operations - these perform any required translation
	between the internal and external representation of text.
	*)

	PROCEDURE Look (cid: ChanId; VAR ch: CHAR; VAR res: IOConsts.ReadResults) ;
	(* If there is a character as the next item in the input stream cid,
	assigns its value to ch without removing it from the stream;
	otherwise the value of ch is not defined.
	res (and the stored read result) are set to the value
	allRight, endOfLine, or endOfInput.
	*)
	VAR
	did: IOLink.DeviceId ;
	dtp: IOLink.DeviceTablePtr ;
	BEGIN
	CheckValid(cid) ;
	did := RTio.GetDeviceId(cid) ;
	dtp := IOLink.DeviceTablePtrValue(cid, did) ;
	IF dtp=NIL
	THEN
	RAISE(iochan, ORD(hardDeviceError),
	'IOChan.Look: device table ptr is NIL')
	ELSE
	WITH dtp^ DO
	IF cid=StdChans.NullChan()
	THEN
	result := IOConsts.endOfInput
	ELSIF (ChanConsts.readFlag IN flags) AND (ChanConsts.textFlag IN flags)
	THEN
	doLook(dtp, ch, res)
	ELSE
	res := IOConsts.wrongFormat
	END ;
	result := res
	END
	END
	END Look ;


	PROCEDURE Skip (cid: ChanId) ;
	(* If the input stream cid has ended, the exception skipAtEnd is raised;
	otherwise the next character or line mark in cid is removed,
	and the stored read result is set to the value allRight.
	*)
	VAR
	did: IOLink.DeviceId ;
	dtp: IOLink.DeviceTablePtr ;
	BEGIN
	CheckValid(cid) ;
	did := RTio.GetDeviceId(cid) ;
	dtp := IOLink.DeviceTablePtrValue(cid, did) ;
	IF dtp=NIL
	THEN
	RAISE(iochan, ORD(hardDeviceError),
	'IOChan.Skip: device table ptr is NIL')
	ELSE
	WITH dtp^ DO
	IF (cid=StdChans.NullChan()) OR (result=IOConsts.endOfInput)
	THEN
	RAISE(iochan, ORD(skipAtEnd),
	'IOChan.Skip: attempt to skip data from a stream that has ended')
	ELSIF (ChanConsts.readFlag IN flags) AND (ChanConsts.textFlag IN flags)
	THEN
	doSkip(dtp) ;
	result := IOConsts.allRight
	ELSE
	RAISE(iochan, ORD(notAvailable),
	'IOChan.Skip: attempt to skip data from a channel which is not configured as read and text')
	END
	END
	END
	END Skip ;


	PROCEDURE SkipLook (cid: ChanId;
	VAR ch: CHAR;
	VAR res: IOConsts.ReadResults) ;
	(* If the input stream cid has ended, the exception skipAtEnd is raised;
	otherwise the next character or line mark in cid is removed.
	If there is a character as the next item in cid stream,
	assigns its value to ch without removing it from the stream.
	Otherwise, the value of ch is not defined.
	res (and the stored read result) are set to the value allRight,
	endOfLine, or endOfInput.
	*)
	VAR
	did: IOLink.DeviceId ;
	dtp: IOLink.DeviceTablePtr ;
	BEGIN
	CheckValid(cid) ;
	did := RTio.GetDeviceId(cid) ;
	dtp := IOLink.DeviceTablePtrValue(cid, did) ;
	IF dtp=NIL
	THEN
	RAISE(iochan, ORD(hardDeviceError),
	'IOChan.SkipLook: device table ptr is NIL')
	ELSE
	WITH dtp^ DO
	IF (cid=StdChans.NullChan()) OR (result=IOConsts.endOfInput)
	THEN
	RAISE(iochan, ORD(skipAtEnd),
	'IOChan.SkipLook: attempt to skip data from a stream that has ended')
	ELSIF (ChanConsts.readFlag IN flags) AND (ChanConsts.textFlag IN flags)
	THEN
	doSkipLook(dtp, ch, result)
	ELSE
	RAISE(iochan, ORD(notAvailable),
	'IOChan.SkipLook: attempt to skip data from a channel which is not configured as read and text')
	END ;
	res := result
	END
	END
	END SkipLook ;


	PROCEDURE WriteLn (cid: ChanId) ;
	(* Writes a line mark over the channel cid. *)
	VAR
	did: IOLink.DeviceId ;
	dtp: IOLink.DeviceTablePtr ;
	BEGIN
	CheckValid(cid) ;
	did := RTio.GetDeviceId(cid) ;
	dtp := IOLink.DeviceTablePtrValue(cid, did) ;
	IF dtp=NIL
	THEN
	RAISE(iochan, ORD(hardDeviceError),
	'IOChan.WriteLn: device table ptr is NIL')
	ELSE
	WITH dtp^ DO
	IF cid=StdChans.NullChan()
	THEN
	(* do nothing *)
	ELSIF (ChanConsts.writeFlag IN flags) AND (ChanConsts.textFlag IN flags)
	THEN
	dtp^.doLnWrite(dtp)
	ELSE
	RAISE(iochan, ORD(notAvailable),
	'IOChan.WriteLn: attempting to write to a channel which is not configured as write and text')
	END
	END
	END
	END WriteLn ;


	PROCEDURE TextRead (cid: ChanId;
	to: SYSTEM.ADDRESS;
	maxChars: CARDINAL;
	VAR charsRead: CARDINAL) ;
	(* Reads at most maxChars characters from the current line in cid,
	and assigns corresponding values to successive components of an
	ARRAY OF CHAR variable for which the address of the first
	component is to. The number of characters read is assigned
	to charsRead. The stored read result is set to allRight,
	endOfLine, or endOfInput.
	*)
	VAR
	did: IOLink.DeviceId ;
	dtp: IOLink.DeviceTablePtr ;
	BEGIN
	CheckValid(cid) ;
	did := RTio.GetDeviceId(cid) ;
	dtp := IOLink.DeviceTablePtrValue(cid, did) ;
	IF dtp=NIL
	THEN
	RAISE(iochan, ORD(hardDeviceError),
	'IOChan.TextRead: device table ptr is NIL')
	ELSE
	WITH dtp^ DO
	IF (cid=StdChans.NullChan()) OR (result=IOConsts.endOfInput)
	THEN
	charsRead := 0 ;
	result := IOConsts.endOfInput
	ELSIF (ChanConsts.readFlag IN flags) AND (ChanConsts.textFlag IN flags)
	THEN
	doTextRead(dtp, to, maxChars, charsRead)
	ELSE
	RAISE(iochan, ORD(notAvailable),
	'IOChan.TextRead: attempt to read data from a channel which is not configured as read and text')
	END
	END
	END
	END TextRead ;


	PROCEDURE TextWrite (cid: ChanId;
	from: SYSTEM.ADDRESS;
	charsToWrite: CARDINAL) ;
	(* Writes a number of characters given by the value of charsToWrite,
	from successive components of an ARRAY OF CHAR variable for which
	the address of the first component is from, to the channel cid.
	*)
	VAR
	did: IOLink.DeviceId ;
	dtp: IOLink.DeviceTablePtr ;
	BEGIN
	CheckValid(cid) ;
	did := RTio.GetDeviceId(cid) ;
	dtp := IOLink.DeviceTablePtrValue(cid, did) ;
	IF dtp=NIL
	THEN
	RAISE(iochan, ORD(hardDeviceError),
	'IOChan.TextWrite: device table ptr is NIL')
	ELSE
	WITH dtp^ DO
	IF cid=StdChans.NullChan()
	THEN
	(* do nothing *)
	ELSIF (ChanConsts.writeFlag IN flags) AND (ChanConsts.textFlag IN flags)
	THEN
	doTextWrite(dtp, from, charsToWrite)
	ELSE
	RAISE(iochan, ORD(notAvailable),
	'IOChan.TextWrite: attempt to write data to a channel which is not configured as write and text')
	END
	END
	END
	END TextWrite ;


	(* Direct raw operations - these do not effect translation between
	the internal and external representation of data
	*)

	PROCEDURE RawRead (cid: ChanId;
	to: SYSTEM.ADDRESS;
	maxLocs: CARDINAL;
	VAR locsRead: CARDINAL) ;
	(* Reads at most maxLocs items from cid, and assigns corresponding
	values to successive components of an ARRAY OF LOC variable for
	which the address of the first component is to. The number of
	characters read is assigned to locsRead. The stored read result
	is set to the value allRight, or endOfInput.
	*)
	VAR
	did: IOLink.DeviceId ;
	dtp: IOLink.DeviceTablePtr ;
	BEGIN
	CheckValid(cid) ;
	did := RTio.GetDeviceId(cid) ;
	dtp := IOLink.DeviceTablePtrValue(cid, did) ;
	IF dtp=NIL
	THEN
	RAISE(iochan, ORD(hardDeviceError),
	'IOChan.RawRead: device table ptr is NIL')
	ELSE
	WITH dtp^ DO
	IF (cid=StdChans.NullChan()) OR (result=IOConsts.endOfInput)
	THEN
	locsRead := 0 ;
	result := IOConsts.endOfInput
	ELSIF (ChanConsts.readFlag IN flags) AND (ChanConsts.rawFlag IN flags)
	THEN
	doRawRead(dtp, to, maxLocs, locsRead)
	ELSE
	RAISE(iochan, ORD(notAvailable),
	'IOChan.RawRead: attempt to read data from a channel which is not configured as read and raw')
	END
	END
	END
	END RawRead ;


	PROCEDURE RawWrite (cid: ChanId; from: SYSTEM.ADDRESS; locsToWrite: CARDINAL) ;
	(* Writes a number of items given by the value of charsToWrite,
	from successive components of an ARRAY OF LOC variable for
	which the address of the first component is from, to the channel cid.
	*)
	VAR
	did: IOLink.DeviceId ;
	dtp: IOLink.DeviceTablePtr ;
	BEGIN
	CheckValid(cid) ;
	did := RTio.GetDeviceId(cid) ;
	dtp := IOLink.DeviceTablePtrValue(cid, did) ;
	IF dtp=NIL
	THEN
	RAISE(iochan, ORD(hardDeviceError),
	'IOChan.RawWrite: device table ptr is NIL')
	ELSE
	WITH dtp^ DO
	IF (cid=StdChans.NullChan()) OR (result=IOConsts.endOfInput)
	THEN
	result := IOConsts.endOfInput
	ELSIF (ChanConsts.writeFlag IN flags) AND (ChanConsts.rawFlag IN flags)
	THEN
	doRawWrite(dtp, from, locsToWrite)
	ELSE
	RAISE(iochan, ORD(notAvailable),
	'IOChan.RawWrite: attempt to write data to a channel which is not configured as write and raw')
	END
	END
	END
	END RawWrite ;


	(* Common operations *)

	PROCEDURE GetName (cid: ChanId; VAR s: ARRAY OF CHAR) ;
	(* Copies to s a name associated with the channel cid, possibly truncated
	(depending on the capacity of s).
	*)
	VAR
	did: IOLink.DeviceId ;
	dtp: IOLink.DeviceTablePtr ;
	BEGIN
	CheckValid(cid) ;
	did := RTio.GetDeviceId(cid) ;
	dtp := IOLink.DeviceTablePtrValue(cid, did) ;
	IF dtp=NIL
	THEN
	RAISE(iochan, ORD(hardDeviceError),
	'IOChan.GetName: device table ptr is NIL')
	ELSE
	dtp^.doGetName(dtp, s)
	END
	END GetName ;


	PROCEDURE Reset (cid: ChanId) ;
	(* Resets the channel cid to a state defined by the device module. *)
	VAR
	did: IOLink.DeviceId ;
	dtp: IOLink.DeviceTablePtr ;
	BEGIN
	CheckValid(cid) ;
	did := RTio.GetDeviceId(cid) ;
	dtp := IOLink.DeviceTablePtrValue(cid, did) ;
	IF dtp=NIL
	THEN
	RAISE(iochan, ORD(hardDeviceError),
	'IOChan.Reset: device table ptr is NIL')
	ELSE
	dtp^.doReset(dtp)
	END
	END Reset ;


	PROCEDURE Flush (cid: ChanId) ;
	(* Flushes any data buffered by the device module out to the channel cid. *)
	VAR
	did: IOLink.DeviceId ;
	dtp: IOLink.DeviceTablePtr ;
	BEGIN
	CheckValid(cid) ;
	did := RTio.GetDeviceId(cid) ;
	dtp := IOLink.DeviceTablePtrValue(cid, did) ;
	IF dtp=NIL
	THEN
	RAISE(iochan, ORD(hardDeviceError),
	'IOChan.Flush: device table ptr is NIL')
	ELSE
	dtp^.doFlush(dtp)
	END
	END Flush ;


	(* Access to read results *)

	PROCEDURE SetReadResult (cid: ChanId; res: IOConsts.ReadResults) ;
	(* Sets the read result value for the channel cid to the value res. *)
	VAR
	did: IOLink.DeviceId ;
	dtp: IOLink.DeviceTablePtr ;
	BEGIN
	CheckValid(cid) ;
	did := RTio.GetDeviceId(cid) ;
	dtp := IOLink.DeviceTablePtrValue(cid, did) ;
	IF dtp=NIL
	THEN
	RAISE(iochan, ORD(hardDeviceError),
	'IOChan.SetReadResult: device table ptr is NIL')
	ELSE
	dtp^.result := res
	END
	END SetReadResult ;


	PROCEDURE ReadResult (cid: ChanId) : IOConsts.ReadResults ;
	(* Returns the stored read result value for the channel cid.
	(This is initially the value notKnown).
	*)
	VAR
	did: IOLink.DeviceId ;
	dtp: IOLink.DeviceTablePtr ;
	BEGIN
	CheckValid(cid) ;
	did := RTio.GetDeviceId(cid) ;
	dtp := IOLink.DeviceTablePtrValue(cid, did) ;
	IF dtp=NIL
	THEN
	RAISE(iochan, ORD(hardDeviceError),
	'IOChan.SetReadResult: device table ptr is NIL') ;
	RETURN IOConsts.notKnown
	ELSE
	RETURN( dtp^.result )
	END
	END ReadResult ;


	(* Users can discover which flags actually apply to a channel *)

	PROCEDURE CurrentFlags (cid: ChanId) : ChanConsts.FlagSet ;
	(* Returns the set of flags that currently apply to the channel cid. *)
	VAR
	did : IOLink.DeviceId ;
	dtp : IOLink.DeviceTablePtr ;
	empty: ChanConsts.FlagSet ;
	BEGIN
	CheckValid(cid) ;
	did := RTio.GetDeviceId(cid) ;
	dtp := IOLink.DeviceTablePtrValue(cid, did) ;
	IF dtp=NIL
	THEN
	RAISE(iochan, ORD(hardDeviceError),
	'IOChan.SetReadResult: device table ptr is NIL') ;
	empty := ChanConsts.FlagSet {} ;
	RETURN empty
	ELSE
	RETURN( dtp^.flags )
	END
	END CurrentFlags ;


	(* The following exceptions are defined for this module and its clients *)

	PROCEDURE IsChanException () : BOOLEAN ;
	(* Returns TRUE if the current coroutine is in the exceptional
	execution state because of the raising of an exception from
	ChanExceptions; otherwise returns FALSE.
	*)
	BEGIN
	RETURN( IsExceptionalExecution() AND IsCurrentSource(iochan) )
	END IsChanException ;


	PROCEDURE ChanException () : ChanExceptions ;
	(* If the current coroutine is in the exceptional execution state
	because of the raising of an exception from ChanExceptions,
	returns the corresponding enumeration value, and otherwise
	raises an exception.
	*)
	BEGIN
	IF IsChanException()
	THEN
	RETURN( VAL(ChanExceptions, EXCEPTIONS.CurrentNumber(iochan)) )
	ELSE
	M2RTS.NoException (SYSTEM.ADR(__FILE__), __LINE__,
	__COLUMN__, SYSTEM.ADR(__FUNCTION__),
	SYSTEM.ADR ("not in the exceptional execution state"))
	END
	END ChanException ;


	(* When a device procedure detects a device error, it raises the
	exception softDeviceError or hardDeviceError. If these exceptions
	are handled, the following facilities may be used to discover
	an implementation-defined error number for the channel.
	*)

	PROCEDURE DeviceError (cid: ChanId) : DeviceErrNum ;
	(* If a device error exception has been raised for the channel cid,
	returns the error number stored by the device module.
	*)
	VAR
	did: IOLink.DeviceId ;
	dtp: IOLink.DeviceTablePtr ;
	BEGIN
	CheckValid(cid) ;
	did := RTio.GetDeviceId(cid) ;
	dtp := IOLink.DeviceTablePtrValue(cid, did) ;
	IF dtp=NIL
	THEN
	RAISE(iochan, ORD(hardDeviceError),
	'IOChan.DeviceError: device table ptr is NIL') ;
	RETURN DeviceError (invalid)
	ELSE
	RETURN( dtp^.errNum )
	END
	END DeviceError ;


	BEGIN
	AllocateSource(iochan) ;
	invalid := ChanId(RTio.InitChanId())
	END IOChan.