home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / xco212p.zip / ISODEF / iochan.def < prev    next >
Text File  |  1994-12-22  |  7KB  |  155 lines
  1. DEFINITION MODULE IOChan;
  2.  
  3.   (* Types and procedures forming the interface to channels for
  4. device-independent data
  5.      transfer modules
  6.   *)
  7.  
  8. IMPORT IOConsts, ChanConsts, SYSTEM;
  9.  
  10. TYPE
  11.   ChanId; (* Values of this type are used to identify channels *)
  12.  
  13.   (* There is one pre-defined value identifying an invalid channel on which no data transfer
  14.      operations are available.  It may be used to initialize variables of type ChanId.
  15.   *)
  16.  
  17. PROCEDURE InvalidChan (): ChanId;
  18.   (* Returns the value identifying the invalid channel. *)
  19.  
  20.   (* For each of the following operations, if the device supports the operation on the
  21.      channel, the behaviour of the procedure conforms with the description below.  The full
  22.      behaviour is defined for each device module.  If the device does not support the
  23.      operation on the channel, the behaviour of the procedure is to raise the exception
  24.      notAvailable.
  25.   *)
  26.  
  27.   (* Text operations - these perform any required translation between the internal and
  28.      external representation of text.
  29.   *)
  30.  
  31. PROCEDURE Look (cid: ChanId; VAR ch: CHAR; VAR res: IOConsts.ReadResults);
  32.   (* If there is a character as the next item in the input stream cid, assigns its value to
  33.      ch without removing it from the stream; otherwise the value of ch is not defined.  res
  34.      (and the stored read result) are set to the value allRight, endOfLine, or endOfInput.
  35.   *)
  36.  
  37. PROCEDURE Skip (cid: ChanId);
  38.   (* If the input stream cid has ended, the exception skipAtEnd is raised; otherwise the
  39.      next character or line mark in cid is removed, and the stored read result is set to the
  40.      value allRight.
  41.   *)
  42.  
  43. PROCEDURE SkipLook (cid: ChanId; VAR ch: CHAR; VAR res: IOConsts.ReadResults);
  44.   (* If the input stream cid has ended, the exception skipAtEnd is raised; otherwise the
  45.      next character or line mark in cid is removed.  If there is a character as the next
  46.      item in cid stream, assigns its value to ch without removing it from the stream.
  47.      Otherwise, the value of ch is not defined.  res (and the stored read result) are set to
  48.      the value allRight, endOfLine, or endOfInput.
  49.   *)
  50.  
  51. PROCEDURE WriteLn (cid: ChanId);
  52.   (* Writes a line mark over the channel cid. *)
  53.  
  54. PROCEDURE TextRead (cid: ChanId; to: SYSTEM.ADDRESS; maxChars: CARDINAL;
  55.                     VAR charsRead: CARDINAL);
  56.   (* Reads at most maxChars characters from the current line in cid, and assigns
  57.      corresponding values to successive components of an ARRAY OF CHAR variable for which
  58.      the address of the first component is to. The number of characters read is assigned
  59.      to charsRead. The stored read result is set to allRight, endOfLine, or endOfInput.
  60.   *)
  61.  
  62. PROCEDURE TextWrite (cid: ChanId; from: SYSTEM.ADDRESS; charsToWrite: CARDINAL);
  63.   (* Writes a number of characters given by the value of charsToWrite, from successive
  64.      components of an ARRAY OF CHAR variable for which the address of the first component
  65.      is from, to the channel cid.
  66.   *)
  67.  
  68.   (* Direct raw operations  - these do not effect translation between the internal and
  69.      external representation of data
  70.   *)
  71.  
  72. PROCEDURE RawRead (cid: ChanId; to: SYSTEM.ADDRESS; maxLocs: CARDINAL;
  73.                    VAR locsRead: CARDINAL);
  74.   (* Reads at most maxLocs items from cid, and assigns corresponding values to successive
  75.      components of an ARRAY OF LOC variable for which the address of the first component
  76.      is to. The number of characters read is assigned to charsRead. The stored read result
  77.      is set to the value allRight, or endOfInput.
  78.   *)
  79.  
  80. PROCEDURE RawWrite (cid: ChanId; from: SYSTEM.ADDRESS; locsToWrite: CARDINAL);
  81.   (* Writes a number of items given by the value of charsToWrite, from successive
  82.      components of an ARRAY OF LOC variable for which the address of the first component
  83.      is from, to the channel cid.
  84.   *)
  85.  
  86.   (* Common operations *)
  87.  
  88. PROCEDURE GetName (cid: ChanId; VAR s: ARRAY OF CHAR);
  89.   (* Copies to s a name associated with the channel cid, possibly truncated
  90.      (depending on the capacity of s).
  91.   *)
  92.  
  93. PROCEDURE Reset (cid: ChanId);
  94.   (* Resets the channel cid to a state defined by the device module. *)
  95.  
  96. PROCEDURE Flush (cid: ChanId);
  97.   (* Flushes any data buffered by the device module out to the channel cid. *)
  98.  
  99.   (* Access to read results *)
  100.  
  101. PROCEDURE SetReadResult (cid: ChanId; res: IOConsts.ReadResults);
  102.   (* Sets the read result value for the channel cid to the value res. *)
  103.  
  104. PROCEDURE ReadResult (cid: ChanId): IOConsts.ReadResults;
  105.   (* Returns the stored read result value for the channel cid. (This is initially the value
  106.      notKnown).
  107.   *)
  108.  
  109.   (* Users can discover which flags actually apply to a channel *)
  110.  
  111. PROCEDURE CurrentFlags (cid: ChanId): ChanConsts.FlagSet;
  112.   (* Returns the set of flags that currently apply to the channel cid. *)
  113.  
  114.   (* The following exceptions are defined for this module and its clients *)
  115.  
  116. TYPE
  117.   ChanExceptions =
  118.     (wrongDevice,      (* device specific operation on wrong device *)
  119.      notAvailable,     (* operation attempted that is not available on that channel *)
  120.      skipAtEnd,        (* attempt to skip data from a stream that has ended *)
  121.      softDeviceError,  (* device specific recoverable error *)
  122.      hardDeviceError,  (* device specific non-recoverable error *)
  123.      textParseError,   (* input data does not correspond to a character or line mark -
  124.                           optional detection *)
  125.      notAChannel       (* given value does not identify a channel - optional detection *)
  126.     );
  127.  
  128. PROCEDURE IsChanException (): BOOLEAN;
  129.   (* Returns TRUE if the current coroutine is in the exceptional execution state
  130.      because of the raising of an exception from ChanExceptions;
  131.      otherwise returns FALSE.
  132.   *)
  133.  
  134. PROCEDURE ChanException (): ChanExceptions;
  135.   (* If the current coroutine is in the exceptional execution state because of the
  136.      raising of an exception from ChanExceptions, returns the corresponding
  137.      enumeration value, and otherwise raises an exception.
  138.   *)
  139.  
  140.   (* When a device procedure detects a device error, it raises the exception softDeviceError
  141.      or hardDeviceError.  If these exceptions are handled, the following facilities may be
  142.      used to discover an implementation-defined error number for the channel.
  143.   *)
  144.  
  145. TYPE
  146.   DeviceErrNum = INTEGER;
  147.  
  148. PROCEDURE DeviceError (cid: ChanId): DeviceErrNum;
  149.   (* If a device error exception has been raised for the channel cid, returns the error
  150.      number stored by the device module.
  151.   *)
  152.  
  153. END IOChan.
  154.  
  155.