IOBmemT toolkit
                             ===============

      Wrapping for the IOB.xxx traps to fetch bytes into a buffer

FMUL2MEM% and FLIN2MEM% didnt provide the option of a variable timeout,
therefore I added the two commands below.

Compatible with SMSQ/E, QDOS and Minerva


Usage:
------

Fetch string/bytes into buffer, with timeout

       fetched% = FMUL2MEMT%([#ch%;] timeout%, buflen%, address)
       fetched% = FLIN2MEMT%([#ch%;] timeout%, buflen%, address)

  where:
         #ch% is the (optional) channel number to use (default #3)

      timeout%  is the max time to wait for completion of the
         operation. This is given in 1/50th of a second, 0..32767
         or -1 for "wait forever". ( -1 is the only acceptable negative
         number; any other will cause a Bad Parameter error.)

      buflen%   is the size of the string buffer. It must be a
         positive number between 0 and 32767

      address   is the address to load the data. It must point to a
         buffer of at least buflen% size. The address must be an even,
         positive, none-zero number.

      fetched%  is either the number of bytes fetched (including LF, in
         the case of FLIN2MEMT) or an error code:

         Soft errors are NC, EOF, BFFL.
         Hard errors are ICHN, BP, etc

Note: LF is included in FLIN2MEMT%, and must therefore be accommodated by
the size of the buffer. In the case of a Buffer Full error, the
terminating character is undefined.

If you use FLIN2MEMT% in a window channel, the cursor appears and the string
may be edited; it works a bit like INPUT. This is not the case with
FMUL2MEMT%. However, you can still type in characters only they wont be
echoed on screen, and any editing keystrokes, including <ENTER> will be
regarded as part of the data! It will only return when the buffer is full
or if <break> is pressed (where possible) or on timeout.


Example
-------

100 CLS: CLS#2: CLOSE: CLCHP: rem Clear up after any previous run..
102 :
104 ch = FOP_IN("win2_data_txt_LoremIpsum_txt"): ERT ch
106 fl = FLEN(#ch)
108 IF fl > 32766: CLOSE#ch: PRINT 'File too big!': ERT -4
110 bufflen% = fl
112 timeout% = -1
114 address  = ALCHP(bufflen%)
116 :
118 fetched% = FMUL2MEMT%(#ch; timeout%, bufflen%, address)
120 :
122 PRINT fetched%; 'b fetched'
124 PRINT#2; PEEK$(address, bufflen%)


Software status
---------------

V0.01, pjw, 2025 Dec 11

               Conditions of use and DISCLAIMER as per Knoware.no

Generated by QuickHTM, 2025 Dec 11