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