EASYEXT SuperBASIC Extensions V3.02
PD 1992-95 Albin Hessler Software

Special Remark for SMSQ/SBASIC
******************************
SBASIC offers the oportunity to load 'local' extensions in a SBASIC daughter
job. These are only present in the daughter SBASIC and are removed with it.
Thus EASYEXT seems to be unnecessary if only extensions shall be loaded
temporarily, as SBASIC is the better solution.
Nevertheless, EASYEXT vcan be used to load extensions temporarily, e.g. to make
them available for compiled programms, especially if the Basic source is not
available or if altering a programm for SBASIC is too much effort.

EASYEXT works with SMSQ/SBASIC as before, but only with Job 0. Even if some
extensions would be loaded from an SBASIC daughter job with XJ, they would only
be initialised locally for Job 0.
So it only makes sense to load directly from within Job 0. Then the extensions
are also available for all subsequent started SBASIC daughter jobs.
Warning:
########
If temporary extensions used by a daughter SBASIC job are removed before
this job is terminated, any attempt to access such an extension from the
daughter job will lead to a system crash.
Only a NEW in the daughter SBASIC will deinstall these extensions!
The same is valid for compiled jobs, which try to access temporary extensions
present when the program started.

What concerns tasks and drivers, EASYEXT works also with SMSQ. Here EASYEXT can
be helpful occasionally, especially for development purposes.


General Introduction
********************

QDOS and SuperBASIC are very flexible and easy to be extended by other
parts. Extensions may be SuperBASIC functions or procedures but also
extensions of the operating system ( tasks, drivers, .. ). Normally those
extensions are loaded into the resident procedure area where they can not be
removed other than by a reset of the complete system. Extensions of the
operating system, as the QJUMP Pointer Environment, must always be loaded
into the resident procedure area. It is strongly recommended that the EASYEXT
extensions are also loaded there, though current versions 3.x do no longer
refuse to be loaded elsewhere.

In practice SuperBASIC extensions often only must be present during program
development, when the program is compiled afterwards. Therefore it is not
necessary to have them present during a whole session (and the memory lost),
and besides this, all jobs have to be removed to reserve memory in the resident
procedure area.

EASYEXT offers the possibility to load and unload SuperBASIC
extensions even and if there are jobs executing.

With EASYEXT extensions may be loaded into the 'common heap' or the
'transient program' area. Loading to the 'transient program area' is more
comfortable as the user may keep a better overview of what is loaded with the
help of commands like JOBS, QJ, FREE_MEM, ... .

Normally those commands are not available for the common heap area and
therefore the danger of uncontrolled memory fragmentation is much greater.

As a side effect with EASYEXT even those jobs may be removed which have
SuperBASIC extensions or drivers in their code (e.g. Talent Workbench Editor)
and which would lead to a system crash if removed with RJOB ... .

EASYEXT can be configured with the Pointer Environment's 'config' program.
****************************************************************************

Warning 1:
**********

The EASYEXT commands which remove SuperBASIC extensions
perform an action originally not provided in the system.
Therefore there is no guarantee that this operation will
work with all existing or comming operating system
versions.
The current EASYEXT version 3.02 is testet on JS, MGG,
Minerva and SMSQ.

Warning 2:
**********

All SuperBASIC extensions reserve memory in the name
table. After extensions are removed by EASYEXT commands,
this space is only released by a NEW command.

Warning 3:
**********

The EASYEXT extensions should always be loaded into the
resident procedure area, though EASYEXT will not refuse
to be loaded elsewhere.

Warning 5:
**********

Some system extensions do replace pointers of existing
device drivers. If such an extension is removed with
EASYEXT, then also the altered device will be removed.
Therefore such extensions should only be loaded residently
and never removed (e.g. Pointer Interface).

Warning 6:
**********

Some programs install drivers in a heap for job 0 and
copy the code into this heap.
In such cases no address pointer points into the job
code area and EASYEXT is not able to detect the relation-
ship.
Such programs should always be removed with their internal
'quit' option (some even then have forgotten what they have
installed before).

EASYEXT Syntax
==============
Error handling
If an 'address' or 'address$' parameter is passed, then an error which occured
in the routine will be passed in this parameter.

EASYEXT commands
++++++++++++++++

-----------------------------------

XCH     filename [,{address}{address$}[,flag]]


filename        as a SuperBASIC name or string
                default directory and ending can be omitted.
                If the file is not found, the DATA default is tried.
address         return paramter for the address as floating point
address$        return paramter for the address as a hexstring.

flag            0 or none       -> CALL address is done automatically
                1               -> the file is loaded only.

Reserves memory in the common heap area and loads the file there. If 'address'
is present, the start address of the area will be returned in this variable.
'address' may be a floating point variable or a string variable. In the first
case the address is returned in decimal in the latter as a hexadecimal string.
The address will be needed to remove the extensions and to release the memory
( -> RXCH ).

-----------------------------------

XJ      filename [,{address}{address$}[,flag]]

Parameters like XCH.

Creates a job in the transient program area and loads the file there. This job
is not executed in any way and must never be released or executed externally,
though this would only lead to a system slow down.

'address' is the code start. Job base is address-64.

XJ Jobs can be removed without any  problem from the Cueshell Jobs list,
with QPAC2 RJOB or the standard TK2 RJOB command.

-----------------------------------

XRP     filename [,{address}{address$}[,flag]]


as XCH, but first it will be tried to reserve memory in the resident procedure
area. If successfully loaded there, the memory can't be released afterwards.

-----------------------------------

REASS

Reassert Basic names. The latest variant becomes valid all others are unset.

EASYEXT can be configurated so that REASS is processed implicitly by XCH,
XRP and XJ .

An explicit REASS may be used with ROM Versions older than JS when
SuperBASIC extensions are loaded with names already used. Those extensions
are only present after REASS.

-----------------------------------

RXCH    address

address as returned by XCH

Unset all SuperBASIC extensions, remove all tasks and drivers with routine
addresses in this area. Release area.

-----------------------------------

RXJ     {jobnumber}{address}


Unset all SuperBASIC extensions, remove all tasks and drivers with routine
addresses in this area. Remove job.

From Version 2.01 of the EASYEXT extensions, XJ jobs can be removed with a
standard Toolkit 2 RJOB command or from within the QPAC2 RJOB, i.e. this
special command RXJ is only present for compatibilty with older versions.

-----------------------------------

RXJS

RXJ all  XJ jobs.

-----------------------------------

RJ      {jobnumber}{jobname}{jobID}{jobnumber,jobtag,errorcode}{address}


Syntax compatible to TK2 RJOB.

Additionally RJ can be called:
-       with the job number only
-       with the full job ID in one parameter
-       with a part of the job's name
        e.g.:
        RJ 21   removes job 21
        RJ fil  removes the first job (lowest job number) whose name
                starts with 'fil' (e.g. 'Files flp1_')

Naturally, RJ unsets all SuperBASIC extensions and removes all tasks and
drivers with routine addresses in the jobs area.

-----------------------------------

RJA      [{jobname}{jobnumber}]

-       without parameter
        remove all jobs
-       with jobnumber
        remove all jobs from the given number
        e.g.:   RJA 15          remove all jobs from job number 15
-       with jobname
        remove all jobs whose names start with the given name
        e.g.:   RJA fil         removes all jobs whose names start with 'fil'
                                e.g. 'Files flp1_', 'Files win1_', etc.

                RJA 'Files flp' removes all ...

-----------------------------------

Attention:
**********

SuperBASIC name conventions are valid

Naturally RJ and RJA remove not only the job, but also all
SuperBASIC extensions, drivers, etc. with routine addresses
in the job area.

RJ and RJA (in contrary to RXJ) do not report an error when
a given job does not exist!

RXJ can be called with the job number or the address
returned by XJ.

RXJS removes all jobs installed with XJ (but only these),
while RJA 'xj' will remove all XJ Jobs but also any job whose
name starts with 'xj', e.g. a job named 'Xjubilee'.


The END
+++
