Load Data
                                =========

             Load a (data) file into memory and return address


Compatible with QDOS & Minerva with TK2, and SMSQ/E

This S*BASIC function loads a file of any type into the Common Heap and
returns the address and, optionally, the size. The space claimed may be
returned to the heap with RECHP, CLCHP and similar TK2-compatible commands.


Syntax
------
        addr = LDATA(<filename>$ [, r.extra [, offset]])

Where
        addr         is the start address of the memory reserved. It can
                     be released with TK2's RECHP addr, or CLCHP (after
                     which the memory is unreserved and must no longer be
                     accessed!)

                     Alternatively, addr may also be a negative error
                     number, eg insufficient memory (-3), or (file) not
                     found (-7), etc


        <filename>$  is the full filename (no DATAD Default) as a quoted
                     string, string variable, or string expression.

        r.extra      is an optional parameter specifying an amount of
                     extra memory to be reserved in addition to the file's
                     length. (See example below.)

                     If r.extra is present as a scalar float, the amount
                     of memory reserved is returned in this variable.
                     To prevent r.extra from being overwritten, use
                     r.extra + 0 or (r.extra).

        offset       is an offset from the start of reserved memory,
                     where you wish the data from the file to be loaded.
                     Ie the data contained in <filename$> will be loaded
                     at addr + offset.

                     offset can only be specified if r.extra is present.
                     It must be an even number smaller than, or equal to,
                     r.extra, otherwise an error in expression (-17) is
                     returned.

Parameter errors are "hard", ie they stop program execution, as these
errors can be helped by the programmer! Other errors are "soft", such as
(file) in use, etc. Therefore addr should always be checked after the call
to ensure one isnt writing to unreserved memory locations!


Examples
--------

Display a sprite:

10 spr = LDATA("win3_spr_ball_Sun32_spr")
20 SPRW#2; 100, 100, spr
30 RECHP spr


Convert QL screen dumps to PIC files:

100 ERT Scr2Pic("win3_dmp_Worm_scr4", "ram1_test4_pic", 0)
110 :
120 ERT Scr2Pic("win3_dmp_scn_scr8", "ram1_test8_pic", 8)
130 :
140 DEFine FuNction Scr2Pic(ifn$, ofn$, md%)
150 LOCal scr, extra, ofs, er
160 extra = 10: ofs = 10: er = 0
170 scr = LDATA(ifn$, extra, ofs)
180 IF scr < 0: RETurn scr
190 IF extra = (32768 + 10) THEN
200  POKE_W scr, $4AFC, 512, 256, 128
210  POKE scr + 8, md%
220  SBYTES_O ofn$, scr, extra
230 ELSE
240  er = -19
250 END IF
260 RECHP scr
270 RETurn er
280 END DEFine Scr2Pic
290 :


Program status
--------------

The techniques used to implement this command were derived from the SMSQ/E
sources, in particular the LRESPR and ALCHP commands. The rest, including
any remaining creepy-crawlies, is all my own work.

V0.01, pjw, 2019 Jul 21

Conditions and disclaimer as per Knoware.no