Qdos to SMSQ/E
                            ==============

                  Compatibility toolkit for SuperBASIC


Compatible with Qdos and Minerva (not all versions tested!)


New in this version
===================

The toolkit is split into two variants: Q2S_ and associated files, and
Q2Sux_ and associated files. The only difference is that the *(s)ux_
versions dont contain the SCR_xxxx commands as they may already be
included with the platform, eg in sQLux. Since, in the case of sQLux (and
maybe others) the implementor has chosen to use their "inside information"
to provide these commands (without implementing the structures that would
normally support them) the Q2S versions give the wrong results - so better
just use the ones provided by the platform.

In other words: If you use any emulator/platform that implements their own
version of SCR_xxxx then LRESPR Q2Sux_bin, otherwise LRESPR Q2S_bin.

PAUSE with optional channel number added.


Introduction
============

SMSQ/E's SBASIC has some 400+ core commands as opposed to Qdos'es 139.
SMSQ/E has some important system extentions built in. These are not only
simple keywords, but fundamental capabilities, most of which require more
than a couple of commands to make them happen.

Here is an overview:

ptr_gen, Pointer Interface      currently V2.06,  13 commands

Wman, Window Manager            currently V2.08,   4 commands

hot_rext, Hotkey facility       currently V2.31,  29 commands

TK2, Extended toolkit           currently V2.32, 138 commands

Home Thing, Home Directory      currently V1.02,   7 commands


Add all of those to Qdos and you get pretty close to the capabilities of
SMSQ/E, although you will still not have things like higher resolutions,
high colour, hard disk driver, TCP/IP capabilities etc, although with more
toolkits and hardware extensions, you can go some of the way.

This toolkit adds some of the "missing" commands to SuperBASIC to plug
some gaps, allowing at least a few more SBASIC, or compiled SBASIC,
programs to run. It doesnt add any new capabilities to Qdos; it just
brings the wiring out to the front of the machine where compiled programs
and SuperBASIC users can access them. The toolkit may be added to over
time, as and when the need arises.

The toolkit comes complete with the source code, so commands may be added
or removed.

Currently, the following commands are included. Further details of use may
be found in the text files for the individual commands or suits - or
failing that, in the main source files.

Note: Some of these commands or command sets come packaged individually,
so use those if you only need a few or to avoid a better/different version
being overwritten.

DISP_TYPE, ERT, FDEL, JOBID,  OUTLN,  PAUSE,  QUIT,  SCR_xxx, SUSJB


Syntax
======


SUSJB           - Suspend a job

        SUSJB job_id, timeout%

JOBID           - Return my job ID (Note a better version exists in
                  current TK2s)

        my_ID = JOBID


OUTLN           - Create a "managed" window (Requires PE!)

        OUTLN [#ch,] xsize, ysize, xorg, yorg[, xshad, yshad][, move]


QUIT            - Quit program with optional error code

        QUIT [code]


ERT             - Terminate program if error

        ERT code


SCR_XLIM [#ch], SCR_YLIM [#ch] - Get screen dimensions

        scr_size_x = SCR_XLIM
        scr_size_y = SCR_YLIM(#0)

        Note: Not in Q2Sux


SCR_BASE [#ch]  - Get screen base address

        scrbase = SCR_BASE

        Note: Not in Q2Sux


SCR_LLEN [#ch]  - Number of bytes between rows on screen

        llen = SCR_LLEN(#3)

        Note: Not in Q2Sux


DISP_TYPE       - Display type 0, 2, 16, 32, 33

        mode% = DISP_TYPE


FDEL            - Delete a file with error return

        er = FDEL(<filename>)

PAUSE           - Pause with channel number (Qdos JS+ only!)

        PAUSE[#channel] [, timeout]


Note that:

1) These commands are not always identical to their SBASIC equivalents;
   just their most common usage is supported. Thus under SBASIC FDEL will
   accept an unquoted filename, while this version requires the
   filename parameter to be a string.

2) Some commands, like QUIT, cannot be used directly in SuperBASIC, but
   compiled jobs may use it, and if the command is not available, such
   compiled jobs may not work properly.

3) A number of commands here may not make much sense on a QL: SCR_xxx,
   DISP_TYPE, but they may be used by (compiled) programs designed also
   to run other platforms where they do make sense.

4) Some of these commands may appear in TK2 later, in which case they can
   be removed from this toolkit.

5) Minerva doesnt need PAUSE, but its only about 50 bytes so Ive left it
   in. Remove if you dont want it!
   PAUSE doesnt work with pre-JS versions of Qdos, even as part of a
   compiled program. The default, channel-less, behaviour still works with
   this toolkit loaded.


Program status
==============

Some of the code here was lifted out of the SMSQ/E source files and so was
not authored by me. I merely packaged them in a form suitable for this
toolkit. Those bits are © Copyright their respective authors.

V0.01, pjw, 2019 Aug 02
V0.02, pjw, 2021 Oct 29, New SCR toolkit, and some re-arrangement of
                         files.
V0.03, pjw, 2022 Jan 17, fixed ERT
V0.04, pjw, 2022 May 28, Separate link, key and binary files for toolkit
                         with/without SCR_xxxx. Disp_asm extracted from
                         Scr_asm.
V0.05, pjw, 2024 Jan 04, Added PAUSE as Qdos doesnt accept channel parameter
V0.06, pjw, 2024 Nov 05, Updated PAUSE (see PAUSE_txt for details)


               Conditions of use and DISCLAIMER as per Knoware.no