home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / XLIB.ZIP / XSTREAM.DOC < prev    next >
Encoding:
Text File  |  1992-09-06  |  10.3 KB  |  340 lines
  1.  
  2.                                 XStream
  3.                                 -------
  4.  
  5. This unit give some more stream-objects than the ones you
  6. know from turbo-vision. If you need more informations
  7. about stream you should have a look on the STREAM13.ZIP stream
  8. collection from DJ Murdoch.
  9.  
  10. ▌TObject▐─┬...
  11.           │
  12.           ├─▌TStream─────┬─▌TDosStream▐────────▌TBufStream▐
  13.           .              ├─▌TEmsStream▐
  14.           .              ├──TXmsStream
  15.           .              ├──TMemStream
  16.                          ├──TObjStream
  17.                          ├──TPortStream──────┬──TLptStream
  18.                          │                   └──TComStream
  19.                          └──TNulStream──────────TCrcStream
  20.  
  21. !! Note ▌Txxxxxx▐ are object came from Turbo-Vision
  22.  
  23. TMemStream
  24. ~~~~~~~~~~
  25. This stream can be used for temporairly objects where you don't
  26. want to open an extra file. Note than this stream use the HEAP
  27. for the data, so don't use it extensive. For bigger memory-
  28. streams use TEmsStream or TXmsStream, instead of this one.
  29. I myself use this stream for copy objects, patched load-constructors,
  30. etc.
  31.  
  32.  Fields:
  33.  -------
  34.  BuffSize : WORD         The size of the buffer which were allocated
  35.  Buffer   : POINTER      A Pointer to access the buffer on the heap
  36.  Position : LONGINT      Position within the datablock
  37.  
  38.  Methods
  39.  -------
  40.  CONSTRUCTOR Init( ASize : Word );
  41.  Try to allocate the specified size on heap. If not successfull
  42.  the error-method would be called but no fail.
  43.  
  44.  DESTRUCTOR  Done; virtual;
  45.  Deallocate the memory on the heap
  46.  
  47.  FUNCTION    GetPos: LongInt; virtual;
  48.  Only return the Position field
  49.  
  50.  FUNCTION    GetSize: LongInt; virtual;
  51.  Only return the BuffSize field
  52.  
  53.  PROCEDURE   Read(var Buf; Count: word); virtual;
  54.  Transfer some data from the heap to the buffer
  55.  
  56.  PROCEDURE   Seek(Pos: LongInt); virtual;
  57.  Move the Position to a new value
  58.  
  59.  PROCEDURE   Write(var Buf; Count: word); virtual;
  60.  Transder some data from the buffer to the heap
  61.  
  62. TObjStream
  63. ~~~~~~~~~~
  64. This stream is a descendant from TMemStream, with the difference that
  65. it not allocate the data from heap, but set it to some existing data
  66. in the EXE-Code. So you can link data with the BINOBJ to your EXE and
  67. then read it by this stream. I use this for programs that should be
  68. run on floppy disks that can be changed during run-time. A normal
  69. *.RES file must be aviable all the time, a *.RES linked to the program
  70. with BINOBJ must only be aviable on program-loading !
  71.  
  72. Here's a short example for linking a resource to a program.
  73.  
  74. procedure Resource; external; { from the obj file }
  75.  
  76. .....
  77.  
  78. New( PObjStream, Init( @Resource ));
  79.  
  80.  
  81.  Methods
  82.  -------
  83.  CONSTRUCTOR Init( AAddr:Pointer );
  84.  Set the Buffer to the AAddr address and the BuffSize to
  85.  65000. I use such a big value because there is no way to
  86.  determine the size of a linked OBJ file ! So it's possible
  87.  to read-after the end of the stream without any errors.
  88.  For Resources this isn't so bad, because they control it
  89.  by their own.
  90.  
  91.  DESTRUCTOR  Done; virtual;
  92.  Only call the TStream.Done, don't deallocate the buffer.
  93.  
  94.  PROCEDURE   Write(var Buf; Count: word); virtual;
  95.  Do nothing because it shouldn't be possible to write to
  96.  the code segment.
  97.  
  98. TPortStream
  99. ~~~~~~~~~~~
  100. This stream is an abstract one that never be used directly from
  101. a program. It's a stream that can handle any output port and would
  102. be used in his descendants TComStream and TLptStream. It can handle
  103. various port-numbers and a timeout setting.
  104.  
  105.  Fields:
  106.  -------
  107.  ThePort    : Integer   Number which port is used
  108.  TimeOut    : Byte      Value for TimeOut control. Mostly in seconds
  109.  OldTimeOut : Byte      Old-TimeOut Value for the port, use for reset
  110.                         it at Done
  111.  
  112.  Methods:
  113.  --------
  114.  
  115.  constructor Init( APort:Integer; ATimeOut:Byte);
  116.  Set the parameters to the fields "ThePort" and "TimeOut"
  117.  
  118.  destructor  Done; virtual;
  119.  Calls SetTimeOut with the OldTimeOut value
  120.  
  121.  constructor Load( var S:TStream );
  122.  Load the object from a stream
  123.  
  124.  procedure   Store( var S:TStream );
  125.  Store the object to a stream
  126.  
  127.  function    GetTimeOut:Byte; virtual;
  128.  Abstract method for get the TimeOut value for this port
  129.  
  130.  procedure   SetTimeOut(B:Byte); virtual;
  131.  Abstract method to set the TimeOut for this port
  132.  
  133.  function    InitPort:Boolean; virtual;
  134.  Initalize the port. If successfully True should be returned
  135.  
  136. TLptStream
  137. ~~~~~~~~~~
  138. A stream for writing to the parallel ports LPT1..LPTn on the computer.
  139. Is a descendant from the TPortStream.
  140.  
  141. These errors  can be reported to the error-method:
  142.      ErrorInfo and $01  --> Time out
  143.         "      and $08  --> I/O Error
  144.         "      and $20  --> Out of paper
  145.  
  146.  Constants:
  147.  ---------
  148.  Lpt1 = 1;
  149.  Lpt2 = 2;
  150.  Lpt3 = 3;
  151.  Lpt4 = 4;
  152.  
  153.  Methods:
  154.  -------
  155.  constructor Init( APort:Integer; ATimeOut:Byte);
  156.  Call InitPort and set the TimeOut to the new value
  157.  
  158.  constructor Load( var S:TStream );
  159.  Loads this object from a screen. Overwrite was neccessary to
  160.  initalize the port after Loading.
  161.  
  162.  function    GetTimeOut:Byte; virtual;
  163.  Return the timeout value for the port. The BIOS Aera
  164.  at $40:$78 would be used for this.
  165.  
  166.  procedure   SetTimeOut(B:Byte); virtual;
  167.  Set a TimeOut for the printer-port. BIOS Aera in segment $40
  168.  was used for this purpose.
  169.  
  170.  procedure   Write( var Buf; Count:Word ); virtual;
  171.  Write data to the printer. If errors occurred they were reported
  172.  to the error-method.
  173.  
  174.  function    InitPort:Boolean; virtual;
  175.  Initalize the port over the $17 Interrupt for printers.
  176.  
  177. TComStream
  178. ~~~~~~~~~~
  179. A stream for writing to the serial ports COM1..COMn on the computer.
  180. Is a descendant from the TPortStream. At this time only used it
  181. over the interrupt $14, so that's not possible to access the
  182. COM3..COM8 ports. I hope that's not so often used yet.
  183.  
  184. These errors can be reported to the error-method :
  185.      Errorinfo and $02  --> Overrun error
  186.         "      and $04  --> Parity error
  187.         "      and $08  --> framing error
  188.         "      and $10  --> break detected
  189.         "      and $80  --> timeout
  190.  
  191.  Constants:
  192.  ----------
  193.  Com1 = 1;
  194.  Com2 = 2;
  195.  
  196.  Fields:
  197.  -------
  198.  ComParam  : Byte;       Packed information for the port, like
  199.                          baud,stop-bits,parity, etc.
  200.  
  201.  Methods:
  202.  -------
  203.  constructor Init( APort:Integer; ATimeOut:Byte;
  204.                    ABaud:Word; AData:Byte; AParity:Char; AStop:Byte);
  205.  Call InitPort and set the TimeOut and port parameter. Baud-rates
  206.  greater than 9600 not supported over the Bios at this time !
  207.  
  208.  constructor Load( var S:TStream );
  209.  Loads this object from a screen. Overwrite was neccessary to
  210.  initalize the port after loading.
  211.  
  212.  procedure Store( var S:TStream );
  213.  Store the values to a stream.
  214.  
  215.  function    GetTimeOut:Byte; virtual;
  216.  Return the timeout value for the port. The BIOS Aera
  217.  at $40:$7C would be used for this.
  218.  
  219.  procedure   SetTimeOut(B:Byte); virtual;
  220.  Set a TimeOut for the serial-port. BIOS Aera in segment $40
  221.  was used for this purpose.
  222.  
  223.  procedure   Write( var Buf; Count:Word ); virtual;
  224.  Write data to the serial-port. If errors occurred they were reported
  225.  to the error-method.
  226.  
  227.  function    InitPort:Boolean; virtual;
  228.  Initalize the port over the $14 Interrupt for printers.
  229.  
  230. TNulStream
  231. ~~~~~~~~~~
  232. This streams will eat all data that write to it, but count the
  233. number of bytes transferd. It can be used to determine the
  234. size of objects if you write to it. For example you write
  235. the object to this stream before allocating the size for
  236. TMemStream.
  237.  
  238.  Fields:
  239.  -------
  240.  Size     : Longint      Number of bytes transferd to the write method
  241.  
  242.  Methods:
  243.  -------
  244.  constructor Init;
  245.  Set "Size" to 0
  246.  
  247.  function    GetSize: LongInt; VIRTUAL;
  248.  Return the current value of size
  249.  
  250.  function    GetPos: LongInt; VIRTUAL;
  251.  Return ever zero
  252.  
  253.  constructor Load( var S:TStream );
  254.  Set "Size" to 0
  255.  
  256.  procedure   Store( var S:TStream );
  257.  Do nothing
  258.  
  259.  procedure   Write( var Buf; Count:Word ); virtual;
  260.  Increase the "Size" field by "Count"
  261.  
  262. TCRCStream
  263. ~~~~~~~~~~
  264. This stream is a descendant of TNulStream that also calculate a
  265. easy CRC-Sum. Can be used on sending objects over channels on
  266. that error can be occured.
  267.  
  268.   Field:
  269.   ------
  270.   CRC : Word            The CheckSum
  271.  
  272.   Methods:
  273.   --------
  274.   constructor Init;
  275.   Sets CRC to 0 and call TNulStream.Init
  276.  
  277.   function GetCRC:Longint
  278.   Return the CheckSum in CRC
  279.  
  280.   procedure Write(VAR Buf; Count: Word); virtual;
  281.   Simply adds the bytes of the buffer to the CRC value
  282.  
  283. TXmsStream
  284. ~~~~~~~~~~
  285. This stream gives you access to the extended-memory in your
  286. computer deliverd by HIMEM.SYS driver. It's simiar to the
  287. TEmsStream for the expanded-memory came from Borland.
  288.  
  289.   Field:
  290.   ------
  291.   Handle     : WORD;           A handle for the XMS-Manager
  292.   Size       : LONGINT;        Size of the current stream
  293.   Position   : LONGINT;        Position within the stream
  294.   Blocks     : WORD;           Number of blocks for this stream.
  295.                                XMS blocksize is 1K !
  296.  
  297.   Methods:
  298.   --------
  299.   constructor  Init;
  300.   Setup a handle for the xms. Also look if XMS memory exists in
  301.   your computer.
  302.  
  303.   DESTRUCTOR   Done; virtual;
  304.   Release the handle for the XMS-stream
  305.  
  306.   FUNCTION     GetPos: LongInt; virtual;
  307.   Return the current location within the stream
  308.  
  309.   FUNCTION     GetSize: LongInt; virtual;
  310.   Return the size of the allocated xms-memory
  311.  
  312.   PROCEDURE    Read(var Buf; Count: word); virtual;
  313.   Reads some data from the xms-stream
  314.  
  315.   PROCEDURE    Seek(Pos: LongInt); virtual;
  316.   Move the position to another location
  317.  
  318.   PROCEDURE    Write(var Buf; Count: word); virtual;
  319.   Write some data to the xms-stream
  320.  
  321. Other Stuff
  322. ~~~~~~~~~~~
  323.   Constants
  324.   --------
  325.   RLptStream: TStreamRec (20100)   Registration constant for TLptStream
  326.   RComStream: TStreamRec (20101)   Registration constant for TComStream
  327.   RNulStream: TStreamRec (20102)   Registration constant for TNulStream
  328.  
  329.   ResObjAddr : Pointer = Nil;  This pointer you can let show to your
  330.                                own resource linked as OBJ to your
  331.                                program. Would be used by XRES that
  332.                                if <> nil used this pointer for
  333.                                the resource-file !
  334.  
  335.   Procedures
  336.   ----------
  337.  
  338.   Procedure RegisterXStream
  339.   Register this unit
  340.