Sload Documentation
By Bryan Smart

July, 1993

    This file contains long needed documentation for the SLOAD
BASIC.SYSTEM external command found on the NoiseTracker-gs and NT
VAMPS disks.  If you have a moderate understanding of ProDOS Basic,
just copy the examples and you'll be fine.  If you have a moderate
knowledge of ML, however, this file will be of much more use to you.
    Anyway, enjoy the help <G>.  Be looking for other Warp Zero and
1WSW releases on the nets.


Now here come the real docs....
____________________________________________________________________

    This program was just ran over (Along with the rest of the
NoiseTracker-gs 1.0 disk,) and very few people understood what it
really did.  A couple of people looked at the demo basic loader, and
made mod loaders, but didn't really understand what they were doing.
    I'm not known for my love of writing docs, so I'll get to the
point.  This isn't going to be a tutorial to using ML on the IIgs, so
if you don't know a good bit of machine level programming, this isn't
going to make since to you, but by all means try.

    The function of sload was originally not to load nt mods.  The
program was designed to load files into extended IIgs memory under
ProDOS 8.  To install it, just type "-sload" from p8 basic.
    Using this program is much faster than using a loop to move bytes
into higher banks of IIgs RAM.  This problem of slow moving data with
a register loop shows up often in graphic applications that have to
copy a screen buffer to the super high-res area.  Perhaps if I get
around to it, I'll discuss moving routines with greater speed in
another file.
    Following is the syntax for using sload.

]-sload pathname,a$adr

    Pathname ofcourse is a p8 pathname.  Complete prefix and the whole
80 columns are supported.  The address is what has been throwing
people.  The address consists of a 16-bit hex value (four places) like
$0000, $ffff, $0800, etc.  The high-nibble (The first two hex places
from the left,) contains the IIgs bank number.  The low-nibble (The
last two hex places,) contain the page in the bank pointed to by the
high-nibble.  Note that the file must be loaded to a page aligned
location.
    After the requested file is loaded, you should access a special
pointer located with-in sload to obtain the length of the data
retrieved from the disk.  You get the location of this pointer by
using an equation similar to this from p8 basic.

]adr = peek (49648)*256+169

    The address pointed to by the formula above contains the next free
page aligned address after the end of the file you just loaded.  The
high and low bytes of the bank/page combination are in reversed order.
Adr = page, and adr+1 = bank.
    To find out the length of the file, you should do a cleanup when
your ml program first starts up to dump all data that may remain in
IIgs RAM from previous applications.  This will take a while (Not too
long, but still considerable,) that your program's users will probably
not want to spend looking at a blank screen.  While you could probably
arrange to play a sound file, or display a picture during your memory
cleanup, you could still use the alternative, and obtain the length
from the catalog.  This may take some time, but if your program
allowed a user to select a file from a list, it probably accesses the
disk, and storing the size of the files isn't too much to ask, as you
can dump the others after the user has selected a file.
    Getting back to determining length, once you've dumped memory and
loaded your file, sbc $1 from the value obtained from adr.  This will
point to the page before the next available page after load.  That
means the end of your file is somewhere on this page.  Start from the
end of the bank, and move toward the beginning of the bank.  Use bne
and beq to see when you run into a byte other than $0000.
    From basic, the only method you can use is the catalog
procedure...unless you write a routine you can call.

Special Note

    One final comment about sload.  It is designed to make loading of
super high-res pictures easier.  Although you could type "sload
picture,a$e120" the program will just accept "sload picture" alone.
    Please be aware, DO NOT try loading files which are larger than
the $8000 size restriction of high-res memory.  You will load data on
top of softswitches and other critical data in bank $e1.  Sload has no
internal routine for checking the length of files loaded into high-res
memory.  To sload, $e1/2000 is just another address.

    Well, that's it.  Hope you were able to gather something from
that.  Now get out there and make a couple of demos.