Subject: QL FAQ part 2: operating system
From: [email-masked] (Robert H. Klein)
Date: 8 Aug 1994 06:15:18 GMT
Newsgroups: comp.sys.sinclair

2 QL Device Operating System (QDOS) and Compatibles

2.1 QDOS

(this part of the FAQ is based on articles in SQLW Aug. 1987 and
Dec. 1990)

QDOS is the original QL operating system. The versions are:

  v0.08      : last prerelease version.

  v1.00 'FB' : came out in April 1984. This version of QDOS had
lots of errors.

  v1.01 'PM' : Faster than FB, more tolerant of the microdrives,
but it had still lots of errors.

Both FB and PM ROMs were packed with bugs and needed a 'kludge
board' to carry extra chips outside the computer.

  v1.02 'AH' : three 16K EPROM chips, the 'first useable version
of QDOS' (Sinclair QLW Aug. 1987 p.18)

  v1.03 'JM' : first ROM supplied in two chips. Similar to AH but
four bugs less (according to QLW Aug. 1987 p.18).

AH and JM ROMs soon replaced the FB and PM ROMs. These were
inside the box and had fewer bugs.

  v1.10 'JS' : arrives early in 1985. Last version used in
machines made for sale in britain. First version which is able to
link more than one plug-in device to the QL. New problems with
function VER$ in the JS ROM.

        'JSU': a special version for American QLs because of
other television standards. contains 'all the JS bugs and
features' (QLW Aug 87 p.20), plus the changes for the American
TV.

  v1.13 'MGx': European ROMs. Has one new bug in the line drawing
routine and kills several bugs.  The third Character indicates
the national variant of the ROM.  The national messages,
character sets and so on are in the smaller 16K ROM.
      MGE : spanish ROM
      MGF : french ROM
      MGG : german ROM
      MGI : italian ROM
      MGS : Sweden

  v1.13 'EFP': should mean sigma-FP but the mexican chip makers
couldn't find a sigma stamp (according to QLW Aug. 1987 p.21).
These ROM's are further developments of the "MG" ROM and cannot
be mixed with other QDOS 1.13 chips.

2.2 Minerva

   Minerva is a QL ROM upgrade from QView.  The Minerva ROM
consists of a tiny circuit board and two chips.  The biggest Chip
is a 64K EPROM which holds the new operating system. Below is a
logic chip which makes the EPROM seem like the Sinclair 48K ROM.
The remaining 16K of EPROM is disabled, so you can use the ROM
port as normal.

   Minervas SuperBASIC interpreter has some major improvements.
Now you can integer and string SELect and FOR loops.  In the
keyboard editor now SHIFT-SPACE and SHIFT-ENTER works like SPACE
resp. ENTER.  ESC aborts the editor; ALT-LEFT and ALT-RIGHT move
the cursor to the start and end of the text.  SHIFT-TAB and TAB
move the cursor back and forth in eight character steps.  You
also can delete to the end of the line in one step.  (The
keyboard editor is used by INPUT, EDIT...).  It is possible to
compose accented characters: Press the 'compose key' CTRL-ENTER,
then the required letter, then the type of accent, then the type
of accent - '/' for acute accent, ''' for grave, colon for umlaut
and so on.  If you want to type an arrow simply type CTRL-ENTER
and then the arrow key.  With Minerva you can have a second
screen, but this causes problems with some older and not well
coded programs.  The system can be restarted with
SHIFT-CTRL-ALT-TAB.  At startup it's possible to press other keys
with the usual Fx keys to make Minerva ignore RAM expansions or
ROM devices.  Graphics is also improved and runs now much faster.
String handling is faster and more reliable.  Another improvement
is made with WHEN ERRor and WHEN handling which works well under
Minerva. A new feature of Minerva is Multibasic with which you
can run extra BASIC interpreters.

2.3 Argos
   Argos is the CST THOR's equivalent of QDOS.  Thor 1 and 20
systems claim to use QDOS 4.xx and 5.xx, but they're really based
on the QL JS ROM.

   "The operating system is an entirely re-written version, with
many enhancements, of Qdos, providing upwards compatibility with
QL software. The reverse is not true; Thor software may not run
on the QL. As a matter of interest and to illustrate the
increased ability of the new operating system Argos, Qdos is
contained in 48KB of ROM; Argos occupies 28KB. The Thor XVI is
based on the 8MHz Motorola 68000 processor but plans are included
to upgrade it to the 68020 and, possibly, improved versions of
that chip." (SQLW, Aug. 1988, p.17, 18)

   Like Minerva, Argos was promised to be faster and more
reliable than Sinclair's original QDOS.  The first versions of
Thor XVI's ROM were esseentially MG ROM's with altered device
drivers and modified tables.  Earlier Thor's used Sinclair's JS
ROM's.  Users however tend to report that, since development and
production of the Thor XVI ceased so quickly, the Argos ROM was
never properly debugged and so a great many QL programs will not
run on the Thor XVI.

2.4 SMSQ

   SMSQ is the opereating system for Miracle's QXL card.
According to a newer info from Jochen Merz Software (Germany)
SMSQ is now also available for the Atari ST series.  The actual
version of SMSQ (i.e. 2.16 and higher) includes SBASIC, the long
awaited BASIC interpreter, which is compatible to the QL's
Superbasic.  Some people think, that the QL's future lies in
SMSQ.  [I don't have a QXL or SMSQ, but I believe them. -ed]

2.5 QDOS enhancements

2.5.1 SuperToolkit II

   The SuperToolkit II from QJump is intended to correct errors
in the Sinclair ROM's and to provide SuperBASIC enhancements
which were intended to be built into every QL but weren't.

2.5 2 Pointers, Menus, Hotkeys and Things

[This part of the FAQ is the pointer FAQ Richard Kettlewell
posted to c.s.s. on Feb. 24, 1994. -ed]

Version 0.1 24/2/1994 Richard Kettlewell
Version 0.11 24/2/1994 Richard Kettlewell

This document describes the some of the advantages and pitfalls
associated with the following pieces of software:

        Utility                         Usual filename

        The Pointer Interface           ptr_gen
        The Window Manager              wman
        Hotkey System II                hot_rext
        The Thing system                (part of hot_rext)

All will run on any Ql provided you have sufficient memory (I
recommend 256K minimum, but you really want more than that.)

**** TO DO:

        Hotkeys
        Things

* Why the Pointer Interface?

There are a number of problems with 'unmodified' QDOS. For
example, if two windows overlap then, unless you take great care
over which you output to, their contents will rapdily become
confused. Of course if you're only running a single program then
this isn't too serious --- the program can arrange for its own
windows not to overlap each other, and if they do overlap then
the program will know about it and be able to act accordingly.

However, as soon as you start running more than one program, you
meet problems. For this reason many early QDOS programs have a
'screen redraw' key, for use when other programs have mangled its
windows.

There is a neater solution, however: the Pointer Interface. If
you install this then no program can mangle another programs
windows unless it breaks the rules. (Most games have problems
here.)

There's more; the PI also supports mice. It contains the code to
read the 'QIMI' mouse interface and also allows you to use the
cursor keys to move the pointer. The PI also contains a number of
extended screen handling routines for working with the more
complex window structures it supports.

* What hardware do I need?

It is possible to install the PI with no extra hardware, but it
would be almost useless to do so. I wouldn't even consider doing
so with less than 256K RAM, and I'd not feel comfortable with
less then 640K.

A mouse is useful but not essential. A disk drive is also not
essential but a Ql without one is almost unusable anyway.

* Will it slow my computer down?
* How much extra memory does it use?

The screen runs very slightly slower under the PI; this is an
unavoidable consequence of the way it intercepts screen handling
calls. However, the difference is not very noticable --- I find a
small subjective difference but that's because I know that it has
to run slightly slower. I can't produce figures.

As for memory, the PI consumes quite a lot of memory, to save
images of windows while they are buried. If a program has windows
covering the whole Ql screen, this will amount to about 32k per
program (or more on QDOS machines with higher resolution
displays). However, many programs do not use the full screen and
the PI does not waste memory in such cases.

There is a small additional overhead for every open window but
this is only 48 bytes so it's unlikely to make a significant
difference. There's also a few hundred bytes of fixed tables,
again trivial, and then there's the code for the PI itself, which
(obivously) varies in size from version to version.

* How do I get it?

The best way to get the PI is to buy a program which uses it ---
such programs almost invariably come with a copy of it. Although
the PI provides some benefits when used on its own it is best
used with the Window Manager and programs which make use of the
extra features provided.

A good place to start would be with Qpac2, which includes the PI
and a number of file/Job/system management programs. It also
comes with a manual for the PI and related software.

* How do I install it?

Once you have the PI, you install it before you install anything
else (unless you have a utility with specifically states that it
must be installed before the PI.)

Typically you would use a command like

        LRESPR flp1_ptr_gen

....assuming you have TK2. Without TK2, you must use

        base = RESPR(NNNN):LBYTES flp1_ptr_gen,base:CALL base

....where NNNN is the length of the ptr_gen file (not quoted here
because it is different for different versions.)

* How does it work?

A useful analogy is of a desk with a pile of papers on it. Each
piece of paper represents the window(s) belonging to one program;
the desk represents the screen.

Some of the pieces of paper (windows) will be partially covered;
call these 'buried'. Others will be completely visible. What the
PI does is suspend all attempts to write to buried windows ---
when the window is unburied, it becomes possible to print to it
again.

It should be emphasized that the programs are not suspended
unless they are trying to print text, graphics or what have you
to a buried window; a program which displays nothing will quite
happily get on with what it is doing even if any windows it owns
are buried.

If there are several windows which are not buried then one of
them is regarded as at the 'top' of the pile; this determines
which one you can type data into. Windows which are not the top
window but which are not buried can still be written to.

* How do I switch between programs?
* How do I unbury windows?

Switching between programs is accomplished the same way as
without the PI --- just press CTRL-C and the cursor jumps to
another window (assuming there *are* other windows, of course.)
There are two differences; first, if the new window is buried
(i.e. partially or completely covered by one or more other
windows then it is uncovered, and the windows which covered it
will now be buried.

Secondly, without the PI pressing CTRL-C only switches to windows
which have a cursor in them. (SuperBASIC channel #0, for
example.) Under the PI it will also switch to windows *without* a
cursor. However, if a job owns two windows and one has a cursor
but the other doesn't, it will only switch to the one with the
cursor in it.

It is also possible to select a window by moving the pointer into
it (e.g. with a mouse --- see below) and pressing HIT or DO. It
*does* matter which of these you use --- for some programs (but
not all) using DO instead of HIT will cause the program to update
its display to match changed conditions (e.g. the Jobs menu from
Qpac2 checks to see if any of the jobs it lists have
disappeared.)

* What are HIT and DO?
* What is the difference between them?

On a mouse, the left button is called 'HIT' and the right button
'DO'. From the keyboard, if the pointer is visible, you press
SPACE for HIT and ENTER for DO.

The exact effect of HIT and DO depends very strongly on the
context you use them in. HIT is supposed just to change the
status of something (e.g. turn an option on or off) and DO is
supposed to provoke some kind of action.

* How do I get a mouse pointer?

If you have a mouse then you should be able to make the pointer
appear just by moving the mouse. Without a mouse, you need to
persuade the pointer to appear some other way.

If you have programs written with the PI (or more likely, the
Window Manager --- see below) in mind then whenever you CTRL-C to
get them you will probably find a pointer appears automatically;
you can then move this around with the cursor keys.

* What do different pointers mean?

The shape of the pointer will change depending what sort of
window is underneath it; it depends in particular on what program
owns the window.

        Arrow
                PI-aware program

        Padlock
                Buried window
                Also appears if you pressed CTRL-F5 to freeze the
                screen

        'No entry' sign
                PI-unaware program
                Program doing some work
                Also sometimes appears if the program in question
                has crashed!

        Black-on-white K
                Program waiting for keyboard input
                SuperBASIC will often have this kind of pointer

        Empty box
                No window underneath pointer!

        Box with a number in it
                There is a window underneath the pointer, but you
                can't see it because it's in the wrong screen
                mode.

* How do I connect a mouse to my Ql?

There are two ways of connecting a mouse so that it will work
with the PI. The first is to use QIMI (Qjump Internal Mouse
Interface) which requires you to open your Ql, remove a chip and
plug QIMI into the space left (you then put the chip into a space
on QIMI.) This works with 'Atari' mice. No soldering is needed,
just caution and common sense. (Don't touch or damage the legs of
the chips!)

The other way does not involve open-heart surgery on your
computer; it is SERMouse, which is a piece of software allowing
you to use serial mice (i.e. as used on PC compatibles) with the
PI. You need an adaptor to connect such a mouse to the QLs serial
port, and the SERMouse software itself (available from various
sources, written by Albin Hessler.)

* If I have a mouse, how do I stop the cursor keys moving the
  pointer?

The command

        CKEYOFF

stops the cursor keys from affecting the pointer. The reverse
command is

        CKEYON

Don't use CKEYOFF unless you have a mouse!

* Program XXXX doesn't work with the PI installed.

Many programs make certain assumptions about the layout of
various system tables. These assumptions become invalid when the
PI is installed. Mostly the assumptions are unnecessary anyway,
and demonstrate that the author of the program didn't know what
they were doing.

One important case is programs which write directly to the
screen. There are two ways of doing this; unfortunately the
quicker way will generally speaking not work properly with the
PI. You can tell this is happening when windows 'show through'
even though they are buried.

Some programs with peculiar window arrangements also run into
trouble.

As for solutions, it might be worthwhile looking for a more
recent version of the program; not only is it more likely to work
better with the PI but it might have other bugs removed as well.

If that isn't the case, you might be able to solve it using the
'freeze' option when running from Qpac2 or Hotkey.

* How do I use the PI in my programs?

From assembler:

        You'll need the QPTR pointer toolkit, which describes the
        extra screen handling and mouse support routines offered
        by the PI.

From SuperBASIC:

        You'll need the QPTR toolkit, which contains extra
        commands for accessing the PI.

From C:

        You'll need libqptr_a and <qptr.h> from C68.

From other languages:

        If anyone has written libraries supporting pointer access
        from other languages, let the FAQ maintainer know so it
        can go here!

* What's the difference between window outline and window definition?

A window definition is the screen area occupied by a window as
set by the WINDOW command. It is the part of the window which you
can print into, and is the only concept of window size without
the PI.

With the PI, there is also the concept of the window outline.
This must be at least as big as the window definition. It doesn't
affect PI-unaware programs a great deal.

QPTR contains an OUTLN command to set the outlines of SuperBASIC
windows; from assembler one must use the IOP.OUTL trap.

* What's the difference between primary and secondary windows?

Every program has at most one primary window and zero or more
secondary windows. All the secondary windows must lie within the
outline of the primary window; however, this does not seriously
affect PI-unaware programs since the PI automatically extends the
outline of the primary window to make this work.

WINDOW MANAGER

* What is the Window Manager?

The Window Manager is a collection of utility routines designed
to simplify the writing of programs which use menus and such
like; for example it contains the code to do most of the hard
work for scroll bars on a long menu.

The WM is contained in file wman, and is installed as follows:

        LRESPR flp1_wman

or

        base = RESPR(NNNN):LBYTES flp1_wman,base:CALL base

....where NNNN is the length of the wman file. The PI must have
been already installed.

The combination of the PI and the WM is called the 'Pointer
Environment'.

* What good will the WM do me?

Many modern programs will not run without the WM; it does
sufficient work on a programs user interface that if a program
uses it at all then it will probably not work without it.

* What programs use the WM?

Lots. Almost all such programs will be supplied with a copy of
it.

* Program XXXX doesn't work with the WM installed.

Highly unlikely --- the WM doesn't muck around with the system
the way the PI does. It's probably a bug in the program in
question.

* What do all the sprites mean?

There are various 'sprites' (also known as icons) which appear,
often without much explanation, in programs using the WM.

Two boxes like this:

                xxxxx
                x   x
                x xxxxx
                x x x x
                xxxxx x
                  x   x
                  xxxxx

        This is the 'move window' sprite. HIT or DO on it and the
        pointer will become the same shape; move the pointer to
        somewhere else on the screen and HIT or DO there. The
        window will move to that place.

Divided box like this:

                xxxxx
                x   x
                x xxx
                x x x
                xxxxx

        This is the 'change window' sprite; it typically appears
        in the top left corner of a window. When you HIT/DO on
        it, the pointer changes to the same shape. Move it
        somewhere else and HIT/DO.

        If you moved it up and left, the window will grow; if you
        moved it down and right then the window will shrink. (Of
        course, there will be some smallest size below which the
        window cannot shrink.) Moving e.g. left and down has the
        obvious combined effect.

        All you need to remember is that the bottom right corner
        remains fixed; what you are doing is moving the top left
        corner. This is the opposite way around to quite a number
        of other systems, which can lead to confusion.

Lightning bolt (I'm not doing to try and draw this)

        This is the 'wake' sprite. HIT/DO on it will cause the
        program which owns the window to update the information
        in the window --- for example, a list of files will be
        updated to reflect any new files created or old files
        deleted.

Zzz sprite:

        This is the 'sleep' sprite. HIT/DO on it will (depending
        on the program and also on whether you have Qpac2
        installed) turn the program into a 'button'. This is
        similar to minimising a program under Windows.

That's about it for 'standard' sprites.

* What's a 'loose menu item'?

There's quite a bit of technical sounding jargon relating to the
WM. Mostly you can ignore it since it refers to the data
structures used to communicate between programs and the WM.

A menu window is divided up into several areas; each area is one
of the following:

        Loose menu item
        Information sub-window
        Application sub-window
        Menu sub-window

A loose menu item is just a word or sprite which you can HIT or
DO (e.g. the 'standard' sprites described above usually appear as
loose menu items.) In many cases the effect of HIT/DO is the same
on them, but not always.

An information sub-window is a rectangular area of the window
which contains text and graphics; HIT or DO have no effect there.

An application sub-window can be almost anything; the effect of
HIT/DO, or even of merely moving the pointer into that window,
depends entirely on the program.

A menu sub-window is actually a special type of application
sub-window; however it is much more closely controlled by the WM.
Menu sub-windows are typically a list (or grid) of menu items
(e.g. filenames) which can be selected using HIT or DO for some
purpose.

* How do I use the WM in my own programs?

The simple answer is ''see the same question about the PI above;
you need the same software and documentation.''

However, you may find the 'EasyPTR' program simplifies matters.
It allows windows definitions to be constructed in a rather more
managable fashion than typing in a long assembly source file.
EasyPTR can produce tables for use by SuperBASIC, assembler and C
programs.

* Who wrote this FAQ?

Most of this was written by Richard Kettlewell; mail to
[email-masked] during Cambridge term time. At other times,
finger [email-masked] for contact information.

Small credits to:
        Luke Roberts    [email-masked]

2.6 SMS2

[This part has been taken from an info from Jochen Merz. Believe
it or not. -ed]

[A newer Merz info states, that SMS2 is not intented for the QL
user, but for the Atari user.  Also neither he nor Furst Ltd.
(SMS2  supplier in the UK) have made any effords to sell SMS2 to
QDOS users.  Therefore I'll exclude the following information in
future editions of the FAQ and only leave a short statement about
Merz' or Fursts intention with SMS2. -ed]

SMS2 was designed with a fundamental understanding modern
hardware.  It was built to multitask as a first principle. It is
tiny, efficient, reliable and easy to use. Advanced computing
concepts have been built in at a fundamental level.

In order that the average QDOS user can have access to SMS2 it
has been implemented on the Atari range of computers with a user
interface that provides a stepping stone to the future by
supporting the most advanced QDOS programs.

As might be imagined SMS2 has to have a user environment. Most PC
and mini operating systems have user environments that are
exceptionally hostile from a system point of view. The only other
operating system that is remotely like this SMS2 is QDOS with the
Pointer Environment. The adoption of the extended QDOS user
evironment provides QDOS users with a reasonably familiar
computing system that is also a stepping stone to the future.

SMS2 is a complete ready to use computing environment supplied in
ROM. It needs no configuration or startup procedure. It will be
supplied with an integrated graphic user interface (an advanced
Pointer Environment), a networking system, a set of access
programs (QPAC2) and (as a set of options) an improved "Super
Basic" system known as SBASIC2.

There are many people who believe that SMS2 is the most advanced
operating system in the world, so apart from the obvious
characteristic of allowing the QDOS user to explore the world of
advanced computing systems on some of the cheapest hardware, it
allows the QDOS user to migrate to a future environment that will
have no equal.

By including a fully configured advanced GUI (that no other can
match) multitasking and all its ramifications become obvious,
meaningfull, useful, even pleasurable. The SMS2 user interface
allows the user to explore the complexities of advanced computing
without creating difficulties. Background drawing, real-time
moving and resizing of windows, and visual communication with
partially hidden jobs will be possible.

SMS2 was developed on the Atari range of computers because they
use a very fine processor (the same as in the QL, only faster)
and because they are cheap and simple. SMS2 does not need vast
amounts of complex hardware just to enable it to function. It
turns an ordinary games computer (the STe) into a workstation.

The following input/output facilities are fully supported as
standard:

   * Serial and parallel ports.
   * Floppy discs and SCSI hard discs (including 
     removables).
   * Ram disc.
   * Key board and mouse
   * Standard Atari mono high resolution display (600x400 
     pixels)
   * High resolution 4 colour display (mega STes and TTs 
     1000x900 pixels)
   * MIDI ports either for networking or for use as MIDI.

It must be understood that, although networking is supported via
a device that was never intended for such a purpose, the user can
very easily do things on an SMS2 network that are either
impossible or extremely difficult to do on classic systems. The
SMS2 network allows the average user to explore the joys of
networking.

  SMS2 provides as standard the following capabilities:-

   * Advanced multitasking that is easy to use.
   * Response times better than the fastest real-time 
     systems.
   * High performance windowing.
   * A very high degree of modularity.
   * The ability for jobs to share this modularity.
   * Memory resident for reliability and performance.
   * Efficient inter-process communications.
   * Easy to program. etc. etc.

The future:   Ora is a long term project that will provide
advanced computing environments that are easy to use. This is, of
course, claimed by all system suppliers but without arguing, at
great length, that our system is whiter than white or better than
best. The only way you will be able to experience this exciting
future is to buy a copy of SMS2. To encourage the doubtful the
system has been made exceptionally affordable:

Firstly it was developed on a range of computers, the simplest of
which can be purchased second hand for less than 150.00 pounds
(in England), including the monitor.

Secondly SMS2 will be available on ROM for prices that start at
99 pounds (?)

As far as we know Ora and thus SMS2 is unique in the world of
computing. It is a powerful system that actually works on readily
affordable hardware. Purchasing a copy of SMS2 provides the only
path, at present, to a future world of understandable high
performance computing. The owner of SMS2 becomes part of a
growing number of users who are becoming more knowledgeable of
the advantages of Ora technology.   It is planned that, in the
near future SMS2 will be made available to the Atari ST user. It
is quite probable that the name SMS2 will not be used as this has
no significance for this market but this is of no importance, a
wider market will be good news for SMS2 users and software
suppliers. At present the largest problem for QDOS users is a
lack of competitive applications software. This is a direct
result of the small number of people actually using QDOS. Given
time and a bit of interest the Ora project will change this.

  Addendum.

   Despite its name, it must be made clear that SMSQ is not part
of, or a derivative of the Ora project. SMS2 is not SMSQ or vice
versa. SMSQ is a QDOS clone, it's purpose is to mimic the QL as
accurately as possible.

--
Robert H. Klein  email: [email-masked]
papermail:  Bluecherstrasse 24,  D-56349 Kaub,  Germany