home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / modu1096.zip / ISOsym / iolink.def < prev    next >
Text File  |  1996-08-29  |  7KB  |  153 lines
  1. DEFINITION MODULE IOLink;
  2.  
  3.   (* Types and procedures giving the standard implementation of channels *)
  4.  
  5. FROM IOChan     IMPORT ChanId, DeviceErrNum, ChanExceptions;
  6. FROM IOConsts   IMPORT ReadResults;
  7. FROM ChanConsts IMPORT FlagSet;
  8. FROM SYSTEM     IMPORT ADDRESS;
  9.  
  10.  
  11. (* Devices need to identify themselves in order to allow a check to be made
  12.    that device-dependent operations are applied only for channels opened to
  13.    that device: *)
  14.  
  15. TYPE
  16.   DeviceId;  (* values of this type are used to identify new device modules
  17.         and are normally obtained by them during their intialization *)
  18.  
  19.  
  20. PROCEDURE AllocateDeviceId (VAR did : DeviceId);
  21. (* Allocates a unique value of type DeviceId and assigns this value to
  22.    the parameter did *)
  23.  
  24.  
  25. (* a new device module open procedure obtains a channel by calling MakeChan *)
  26.  
  27. PROCEDURE MakeChan (    did : DeviceId;
  28.                     VAR cid : ChanId);
  29. (* Attempts to make a new channel for the device module identified by did.
  30.    If no more channels can be made, the identity of the bad channel is
  31.    assigned to cid. Otherwise, the identity ofa new channel is assigned to
  32.    cid. *)
  33.  
  34.  
  35. (* If a channel is allocated but the call of the device module open
  36.    procedure is not successful, and on a successful call of a device module
  37.    close procedure, the device module unmakes the channel and returns the
  38.    value identifying the bad channel to its client: *)
  39.  
  40. PROCEDURE UnMakeChan (    did : DeviceId;
  41.                       VAR cid : ChanId);
  42. (* If the device module identified by the parameter did is not the module that
  43.    made the channel identified by the parameter cid, the exception wrongDevice
  44.    is raised.
  45.    Otherwise, the channel is deallocated and the value identifying the bad
  46.    channel is assigned to cid. *)
  47.  
  48.  
  49.  
  50. (* If the call of the device module open procedure is successful, the
  51.    device module obtains a pointer to a device table for the channel, which
  52.    will have been initialized by MakeChan. It then changes the fields of the
  53.    device table to install its own values for the device data, supported
  54.    operations, and flags, and returns to its client the identity of the
  55.    channel. *)
  56.  
  57. TYPE
  58.   DeviceTablePtr = POINTER TO DeviceTable;
  59.     (* Values of this type are used to refer to device tables *)
  60.  
  61. (* Device modules supply procedures of the following types: *)
  62.  
  63. TYPE
  64.   LookProc =      PROCEDURE (DeviceTablePtr, VAR CHAR, VAR ReadResults);
  65.   SkipProc =      PROCEDURE (DeviceTablePtr);
  66.   SkipLookProc =  PROCEDURE (DeviceTablePtr, VAR CHAR, VAR ReadResults);
  67.   TextReadProc =  PROCEDURE (DeviceTablePtr, ADDRESS, CARDINAL, VAR CARDINAL);
  68.   TextWriteProc = PROCEDURE (DeviceTablePtr, ADDRESS, CARDINAL);
  69.   WriteLnProc =   PROCEDURE (DeviceTablePtr);
  70.   RawReadProc =   PROCEDURE (DeviceTablePtr, ADDRESS, CARDINAL, VAR CARDINAL);
  71.   RawWriteProc =  PROCEDURE (DeviceTablePtr, ADDRESS, CARDINAL);
  72.   GetNameProc =   PROCEDURE (DeviceTablePtr, VAR ARRAY OF CHAR);
  73.   ResetProc =      PROCEDURE (DeviceTablePtr);
  74.   FlushProc =      PROCEDURE (DeviceTablePtr);
  75.   FreeProc =      PROCEDURE (DeviceTablePtr);
  76.    (* Carry out the operations involved in closing the corresponding
  77.       channel, including flushing buffers, but do not unmake the channel.
  78.       This procedure is called for each open channel at program termination. *)
  79.  
  80.  
  81. TYPE
  82.   DeviceData = ADDRESS;
  83.  
  84.   DeviceTable = RECORD        (* Initialized by MakeChan to: *)
  85.                   cd : DeviceData;         (* the value NIL *)
  86.                   did : DeviceId;          (* the value given to MakeChan *)
  87.                   cid : ChanId;            (* the identity of the channel *)
  88.                   result : ReadResults;    (* the value notKnown *)
  89.                   errNum : DeviceErrNum;   (* undefined *)
  90.                   flags : FlagSet;         (* FlagSet{} *)
  91.                   doLook : LookProc;       (* raise exception notAvailable *)
  92.                   doSkip : SkipProc;       (* raise exception notAvailable *)
  93.                   doSkipLook : SkipLookProc;   (* raise exception notAvailable *)
  94.                   doTextRead : TextReadProc;   (* raise exception notAvailable *)
  95.                   doTextWrite : TextWriteProc; (* raise exception notAvailable *)
  96.                   doLnWrite : WriteLnProc;     (* raise exception notAvailable *)
  97.                   doRawRead : RawReadProc;     (* raise exception notAvailable *)
  98.                   doRawWrite : RawWriteProc;   (* raise exception notAvailable *)
  99.                   doGetName : GetNameProc; (* return the empty string *)
  100.                   doReset : ResetProc;     (* do nothing *)
  101.                   doFlush : FlushProc;     (* do nothing *)
  102.                   doFree : FreeProc;       (* do nothing *)
  103.                 END;
  104.  
  105.  
  106. (* The pointer to the device table for a channel is obtained using the
  107.    following procedure: *)
  108.  
  109. PROCEDURE DeviceTablePtrValue (cid : ChanId;
  110.                    did : DeviceId): DeviceTablePtr;
  111. (* If the device module identified by the parameter did is not the module
  112.    that made the channel identified by the parameter cid, the exception
  113.    wrongDevice is raised.
  114.    Otherwise, a pointer to the device table for the channel is returned. *)
  115.  
  116.  
  117. (* A device module can ask if it opened a given channel. It does this
  118.    to implement a corresponding enquiry function that is exported from the
  119.    device module: *)
  120.  
  121. PROCEDURE IsDevice (cid : ChanId;
  122.                     did : DeviceId): BOOLEAN;
  123. (* Tests if the device module identified by the parameter did is the
  124.    module that made the channel identified by the parameter cid. *)
  125.  
  126.  
  127.  
  128. TYPE
  129.   DevExceptionRange = ChanExceptions;  (* [notAvailable .. textParseError] *)
  130.  
  131. PROCEDURE RAISEdevException (cid : ChanId;
  132.                              did : DeviceId;
  133.                              x   : DevExceptionRange;
  134.                              s   : ARRAY OF CHAR);
  135. (* If the device module identified by the parameter did is not the module
  136.    that made the channel identified by the parameter cid, the exception
  137.    wrongDevice is raised. Otherwise the given exception is raised and the
  138.    string value of the parameter s is included in the exception message. *)
  139.  
  140.  
  141. PROCEDURE IsIOException (): BOOLEAN;
  142. (* Returns TRUE if the current coroutine is in the exceptional execution state
  143.    because of the raising of an exception from ChanExceptions
  144.    Otherwise returns FALSE *)
  145.  
  146.  
  147. PROCEDURE IOException (): ChanExceptions;
  148. (* If the current coroutine is in the exceptional execution state because of
  149.    the raising of an exception from ChanExceptions, returns the corresponding
  150.    enumeration value, and otherwise raises an exception. *)
  151.  
  152. END IOLink.
  153.