
                Title...........: EXTRA Version 1.00
                Author..........: Martin Cubitt
                Date written....: 9th February 1993
                Description.....: An extension to STOS BASIC.
        
------------------------------------------------------------------------------
        
                        Modification List
                        =================

                Title...........: EXTRA Version 1.01
                Programmer......: Martin Cubitt
                Date............: 19th February 1993
                Description.....: Power command fixed to work (for reasonable
                                  values!)


                Title...........: EXTRA Version 1.02
                Programmer......: Martin Cubitt
                Date............: 21st February 1993
                Description.....:  1) 'extra' command bug fixed when Contol+C
                                  was pressed.
                                   2) 'cartridge input' command bug fixed
                                  when value stored in variable.
        
                Title...........: EXTRA Version 1.03
                Programmer......: Martin Cubitt
                Date............: 25th June 1993
                Description.....:  1) 'extra' command changed to allow text to
                                  roll with key press midpoint.
                                   2) 'disc size' function added.
              
                Title...........: EXTRA Version 1.04
                Programmer......: Martin Cubitt
                Date............: 29th June 1993
                Description.....:  1) 'gemdos version$' command fixed to give
                                  correct gemdos version not the hex value of
                                  it, ie 0.15 now reads 0.21 (correct).

                Title...........: EXTRA Version 1.10
                Programmer......: Martin Cubitt
                Date............: 2nd July 1993
                Description.....:  1) 'depack tiny' command added
                                   2) 'disc used' function added
                                   3) 'disc free' function added
                                   4) 'disc size' function amended

                Title...........: EXTRA Version 1.11
                Programmer......: Martin Cubitt
                Date............: 4th July 1993
                Description.....:  1) 'ndrv' command bug fixed
                                  when value stored in variable.
   
                Title...........: EXTRA Version 1.20
                Programmer......: Martin Cubitt
                Date............: 10th July 1993
                Description.....:  1) 'drvmap' command removed due to fact
                                  it exists in STOS anyway - whoops!
                                   2) 'mem size' command added.
     
                Title...........: EXTRA Version 1.30
                Programmer......: Martin Cubitt
                Date............: 11th July 1993
                Description.....:  1) 'vtab' function added
                                   2) 'ltab' function added

                Title...........: EXTRA Version 1.40
                Programmer......: Martin Cubitt
                Date............: 16th July 1993
                Description.....:  1) 'blur' command added

                Title...........: EXTRA Version 1.50
                Programmer......: Martin Cubitt
                Date............: 17th July 1993
                Description.....:  1) 'convert iff' command added
				   2) 'deshade' command added

                Title...........: EXTRA Version 1.51
                Programmer......: Martin Cubitt
                Date............: 21st July 1993
                Description.....:  1) 'deshade' command changed to include
				  another parameter for which colour to
				  ignore

                Title...........: EXTRA Version 1.60
                Programmer......: Martin Cubitt
                Date............: 21st July 1993
                Description.....:  1) 'set printer data' command added
				   2) 'setup of printer' command added

                Title...........: EXTRA Version 1.61
                Programmer......: Martin Cubitt
                Date............: 22nd July 1993
                Description.....:  1) 'media status' command changed so that
				  a word value is returned, not a longword
				  value

                Title...........: EXTRA Version 1.70
                Programmer......: Martin Cubitt
                Date............: 25th July 1993
                Description.....:  1) 'depack degas' command added but not
				  working - yet!
				   2) 'blur' and 'deshade' commands changed
				  to use improved code for plotting etc
				   3) minor code efficiency alterations made
				   4) 'blur' parameter sequence changed -
				  Important - SEE BELOW!!!
				   5) bug in compiler part of 'power'
				  function fixed
				   6) 'visible input$' function added at
				  request of Tony Greenwood

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

        The EXTRA extension gives you even more power when using STOS, and
includes some very powerful commands.

        Although the new commands have had some heavy duty testing nobody can
account for every possibility. If you find a bug let me know. Indeed, write to
me if you have any ideas for new commands. My 68000 programming is limited, I
am a BASIC man really, but I'll do my best! You may think that some of the new
commands could be modified or maybe some of them are totally useless. If
enough people say that a particular command is useless then I may consider
removing it to allow more space for a command which would be more useful. My
address can be found at the base of this document.


        The new commands in brief:-

 1      extra...........: Information
 2      lextra..........: Print information 
 3      prntr...........: Printer on-line? t/f
 4      screen dump.....: Print screen
 5      ndrv............: No. of drives
 6      mem size........: Memory size for machine
 7      media status....: Chk disc chg sts
 8      write protected.: Disc write-prot? t/f
 9      disc sides (A)..: No. sides on disc
10      disc tracks (A).: No. tracks on disc
11      disc verify on..: Set verify on
12      disc verify off.: Set verify off
13      fmt disc A,B....: Formats drive,nsides
14      cpy disc A,B....: Copy A to B
15      left shift key..: Press=true,else false
16      right shift key.: Press=true
17      cntrl key.......: Press=true
18      alt key.........: Press=true
19      caps lock ......: True if on,else false
20      caps lock on....: Set caps lock on
21      caps lock off...: Set Caps lock off
22      gemdos version$.: GEMDOS version
23      os version$.....: OS version
24      power (A,B).....: A ^ B
25      cartridge input.: Get incoming data
26      cookie _cpu.....: Delve into cookie jar, return _cpu
27      cookie _fdc.....: Delve into cookie jar, return _fdc
28      cookie _fpu.....: Delve into cookie jar, return _fpu
29      cookie _frb.....: Delve into cookie jar, return _frb
30      cookie _mch.....: Delve into cookie jar, return _mch
31      cookie _snd.....: Delve into cookie jar, return _snd
32      cookie _swi.....: Delve into cookie jar, return _swi
33      cookie _vdo.....: Delve into cookie jar, return _vdo
34      disc size (A)...: Retrieve original size of disc
35      disc free (A)...: Retrieve amount free on disc
36      disc used (A)...: Retrieve actual amount used on disc
37      depack tiny A,B.: Depack tiny bank to other bank
38      vtab (X)........: Tab to column on screen
39      ltab (X)........: Tab to column on printer
40      blur (8 parms)..: Blur portion of screen
41     convert iff S,D,P: Convert uncompressed IFF image to normal
42	deshade A,B,C...: Change colours not B to C in addr A
43    set printer data A: Configure printer to A
44	setup of printer: Returns printer configuration data
45	depack degas A,B: Depack a degas screen from addr A to B
46  A$=visible input$(A): Input A number of characters into A$

(t/f = true or false is returned as per STOS standard)


Total new commands in EXTRA = 46

------------------------------------------------------------------------------
        
        Breakdown of the new commands:-

 1      extra...........: Information
        
        Input:  none

        Output: none

                This command is provided for the programmer as a quick
        reminder of the format of a command. I think that all new extensions
        should provide this facility.

                Note that you must press a key to continue, this is to stop
        STOS scrolling up the text before you can read it all.

        E.g.
                 extra
        
------------------------------------------------------------------------------
 
2       lextra..........: Print information 
        
        Input:  none

        Output: none
        
                This command will print out the format of the commands to your
        printer. A hardcopy for your quick and easy reference.
        
        E.g.
                 lextra

------------------------------------------------------------------------------
        
 3      prntr...........: Printer on-line? t/f
                
        Input:  none

        Output: true (-1) or false (0)
        
                This returns a value true or false. If the printer is on-line
        then 'true' is returned, otherwise the result is false.

        E.g.
                 if prntr then lprint "Message"

                 10 if prntr then goto 40
                 20 print "Printer not connected"
                 30 end
                 40 lprint "Message"

                 if not(prntr) then print "Error, printer not on-line"

------------------------------------------------------------------------------
        
 4      screen dump.....: Print screen
        
        Input:  none

        Output: none
        
                Dumps the current screen onto your printer. Note that it does
        not take account of what resolution you are in or how your printer is
        set up. Therefore you should check this manually to ensure the
        desired result is achieved.

        E.g.
                 screen dump

                 10 if DUMP$="Y" then screen dump

------------------------------------------------------------------------------
        
 5      ndrv............: No. of drives
        
        Input:  none

        Output: Number of drives attached
        
                This returns the number of active drives attached to the
        system (not including the imaginary B drive on single drive systems).
        It has the value 0,1 or 2.

        E.g.
                 10 print "You have ";ndrv;" drives attached!"
        
------------------------------------------------------------------------------

 6      mem size........: Memory size for machine
        
        Input:  none

        Output: Memory available when machine turned on and empty (except
		for RAM disk etc - M.Cubitt 25/7/93)

                This command returns then configuration memory size. It does
this by subtracting the bottom of the available memory from the top of the
available memory. This gives a result, in bytes. From this you may, within
your program, divide this by 1,000,000 to get the size in megabytes.

        E.g.
                 10 MEMSIZ=mem size
                 20 print "Memory size...
                 30 print
                 40 print MEMSIZ;" bytes"
                 50 print
                 60 print MEMSIZ/1000000;" Mb"
                 70 end
                
------------------------------------------------------------------------------
        
 7      media status....: Chk disc chg sts
        
        Input:  none

        Output: Media status 0,1 or 2 of current drive
                
                This uses the BIOS function 9 and the machine has a guess if
        the floppy disc in the current drive is the same as the last time an
        I/O operation occurred.

                Possible values are:

        0       -       Disc has not been replaced
        1       -       Status uncertain. Checked on next read or write.
        2       -       Disc has been removed or had a boot sector update.

                The method the ST uses to obtain this information may be of
        some interest to a curious few.

                The ST drives have small light-emitting diodes and matching
        photoreceptors which can tell if there is something in between
        blocking the light. This facility is normally used to determine if a
        disc is write protected. If light travels through, the disc is write
        protected otherwise it is not. If a disc is removed from the drive,
        the light will be blocked while the disc is removed and then the
        light will become unblocked as there is no disc there. The ST system
        monitors the light status at a such a rate that it is fast enough to
        catch any change. If a transition has been noticed the media status is
        set to 1, indicating an unsure condition.
                If a read or write operation is performed while the status is
        unsure, the serial number is checked on the disc. If it does not match
        the previous discs serial number an error (-14) is issued. If the two
        serial numbers are the same the media status will be set to 0, which
        indicates a safe status.

        E.g.
                 10 MEDIACH=media status
                 20 inc MEDIACH
                 30 on MEDIACH goto 40,60,80
                 40 print "Disc has definitely not been changed."
                 50 goto 100
                 60 print "Disc may have changed!"
                 70 goto 100
                 80 print "Disc has definitely changed or a boot sector";
                 90 print " has been written."
                100 end

                 print media status

------------------------------------------------------------------------------
        
 8      write protected.: Disc write-prot? t/f
        
        Input:  none

        Output: True if disc in current drive is write protected, else false.

                Note that this option will not work on every Atari! Sorry, but
        it has to delve around in the operating system which can be anywhere!

                If it does not give you the correct information please be
        kind enough to tell me about your ST and give me the results of the
        following command:-
                                10 os=leek($4F2)         :rem os header
                                20 print os,hex$(os)
                                30 print hex$(deek(os))  :rem os_entry
                                40 print hex$(deek(os+2)):rem os_version
                                50 end
                It is os_entry that I am particularly interested in as it is
        this value (the low byte actually) which determines where the
        write protect value is held. Why oh why can't Atari supply a disc to
        the public domain with the various os values for all versions of TOS?

                Anyhow, back to the command!

                When it works (!) it returns one of two values. The result
        will be true (-1) if the disc in the current drive IS write protected
        or it will return false (0) if it is NOT write protected.

        E.g.
                 10 while write protected
                 20 : print "Disc is write protected"
                 30 : print "Change disc or remove tab then press spacebar"
                 40 : repeat
                 50 : until inkey$=" "
                 60 wend
                 70 end
        
------------------------------------------------------------------------------
        
 9      disc sides (A)..: No. sides on disc
        
        Input:  drive to examine (0 for A or 1 for B)

        Output: number of sides of disc

                This allows you to interrogate how many sides a disc contains.
        Its use is limited unless you are doing some fancy disc work.

        E.g.
                 print disc sides(0)

                 10 for DR=0 to 1
                 20 : print "Drive ";chr$(65+DR);" has ";
                 30 : print disc sides(DR);" sides."
                 40 next DR
                 50 end
                
------------------------------------------------------------------------------
        
10      disc tracks (A).: No. tracks on disc

        Input:  drive to examine (0 for A or 1 for B)

        Output: number of tracks of disc

                This allows you to interrogate how many tracks a disc
        contains per side. Its use is limited unless you are doing some fancy
        disc work.

        E.g.
                 print disc tracks(0)

                 10 for DR=0 to 1
                 20 : print "Drive ";chr$(65+DR);" has ";
                 30 : disc tracks(DR);" tracks per side."
                 40 next DR
                 50 end 
                
------------------------------------------------------------------------------
        
11      disc verify on..: Set verify on
        
        Input:  none

        Output: none
                
                This sets a system flag to verify discs when a write operation
        is performed. It defaults to on when the system is turned on. It means
        that a sector is read immediately after a write to verify that the
        information was written correctly.

                Setting the verify on means that writes are slow but safe!

        E.g.
                 10 disc verify on
                 20 save "SERIOUS.DAT"  :rem Important file
                 30 end

                 disc verify on

------------------------------------------------------------------------------
        
12      disc verify off.: Set verify off
        
        Input:  none

        Output: none
                
                The opposite to disc verify on. This command speeds up write
        by almost two and a half times. After a write operation no read
        follows so this saves time. I suggest that you only use this if you do
        not mind too much if you lose your data (then why are you saving it?)
        or if you have a decent back up or indeed if your discs are of a very
        high quality.

        E.g.
                 10 disc verify off
                 20 save "TRASH.DAT"    :rem Old tosh!
                 30 disc verify on      :rem better to put it back afterwards!
                 40 end

------------------------------------------------------------------------------
        
13      fmt disc A,B....: Formats drive,nsides
        
        Input:  destination drive and number of sides to format

        Output: none

                This powerful command will format a disc in drive 0 (A) or
        drive 1 (B). You can select either 1 or 2 sides for the disc format.
        Most ST systems now have dual drives capable of viewing 2 sides.
                The format is a standard no-nonsense one and has proved to
        be reliable thus far.

                It goes without saying (but just in case...) that formatting
        a disc wipes off the existing data. Write protect your STOS disc to
        save you sending me a death threat!

        E.g.
                 10 rem Format disc in drive DR with SD sides
                 20 fmt disc DR,SD
                 30 print "Done!"
                 40 end
        
------------------------------------------------------------------------------
        
14      cpy disc A,B....: Copy A to B
        
        Input:  source and destination drives

        Output: none

                This will copy the disc in the source drive to that in the
        destination drive. These drives must be different and therefore have
        the value 0,1 (A->B) or 1,0 (B->A).

                The disc formats must be the same for the copy to take place.
        Any errors will halt the process. Note that the number of sectors
        per track must be less than 12 and the bytes per sector must not
        exceed 512.

                It will not copy discs which have an strange format or which
        have some form of copy protection. If it is copy protected it is not
        supposed to be copied!

        E.g.
                 10 rem Copy A to B
                 20 cpy disc 0,1
                 30 print "Done!"
                 40 end
                        
------------------------------------------------------------------------------
        
15      left shift key..: Press=true,else false
        
        Input:  none

        Output: true if pressed, false if not

                Check to see status of this key. If pressed a true (-1) value
        is returned otherwise a false (0) value is returned.

        E.g.
                 10 if left shift key then ?"Left Shift Key!"
                 20 goto 10

------------------------------------------------------------------------------
        
16      right shift key.: Press=true
                
        Input:  none

        Output: true if pressed, false if not

                Check to see status of this key. If pressed a true (-1) value
        is returned otherwise a false (0) value is returned.

        E.g.
                 10 if right shift key then ?"Right Shift Key!"
                 20 goto 10
        
------------------------------------------------------------------------------
        
17      cntrl key.......: Press=true
        
        Input:  none

        Output: true if pressed, false if not

                Check to see status of the control key. If pressed a
        true (-1) value is returned otherwise a false (0) value is returned.

        E.g.
                 10 if  cntrl key then ?"Control Key!"
                 20 goto 10

------------------------------------------------------------------------------
        
18      alt key.........: Press=true
                
        Input:  none

        Output: true if pressed, false if not

                Check to see status of the alternate key. If pressed a
        true (-1) value is returned otherwise a false (0) value is returned.

        E.g.
                 10 if alt key then ?"Alternate Key!"
                 20 goto 10
        
------------------------------------------------------------------------------
        
19      caps lock ......: True if on,else false
        
        Input:  none

        Output: status of the caps lock key, true if on or false if not

                This merely check the status of the Caps Lock key. If Caps
        Lock is on the the returned value will be true (-1) otherwise if
        the Caps Lock is off it will return false (0).

        E.g.
                 10 if caps lock then print "Caps Lock on!"
                 20 if not(caps lock) then print "Caps lock off!"
                 30 goto 10

------------------------------------------------------------------------------
        
20      caps lock on....: Set caps lock on
        
        Input:  none

        Output: none

                This command will turn the Caps Lock on regardless of its
        previous setting. It is useful if uppercase characters are to be
        entered.

        E.g.
                 caps lock on

                 10 caps lock on
                 20 input "Post Code:";PC$
                 30 end

------------------------------------------------------------------------------
        
21      caps lock off...: Set Caps lock off
        
        Input:  none

        Output: none
        
                This command will turn the Caps Lock off regardless of its
        previous setting. It is useful if lowercase characters are to be
        entered.

        E.g.
                 caps lock off

                 10 caps lock off
                 20 input "Name of person:";NM$
                 30 end
        
------------------------------------------------------------------------------
        
22      gemdos version$.: GEMDOS version
        
        Input:  none

        Output: your version of GEMDOS (string)

                This returns a five character string 'xx.xx'. You may like to
        convert the value to decimal by:-
                                        GEMD#=val(gemdos version$)

        E.g.
                 print gemdos version$  

                 10 print "GEMDOS version:";gemdos version$
                
------------------------------------------------------------------------------
        
23      os version$.....: OS version
        
        Input:  none

        Output: your version of TOS (string)

                This will return your TOS version as a five character string.
        Like the gemdos version$ command you may like to convert the value to
        a numeric:-
                OS#=val(os version$)

        E.g.
                 10 OS#=os version$
                 20 if OS#=1 then OS$="1.00" 
                 30 if OS#=1.2 then OS$="1.2 (Blitter)"
                 40 if OS#=1.4 then OS$="1.4 (Rainbow)"
                 50 if OS#=1.6 then OS$="1.6 (STe)"
                 60 if OS#=1.62 then OS$="1.62 (STe without the bugs!)"
                 70 if OS#>=2 and OS#<3 then OS$=os version$+" (Mega STe)"
                 80 if OS#>=3 and OS#<4 then OS$=os version$+" (TT)"
                 90 if OS#>=4 then OS$=os version$+" (Falcon?)"
                100 print "TOS ";OS$
                110 end

------------------------------------------------------------------------------
        
24      power (A,B).....: A ^ B
        
        Input:  two positive integers

        Output: the value of A to the power of B

                "Why?", you cry, "what about the ^ function?". Yes I know but
        would you trust it 100%? Try entering the following:-

                                                10 p=5^2
                                                20 print "5^2 is ";5^2
                                                30 print "5^2 is ";p

                The first result gives you the correct result of 25. The
        second will give you 24. This is a bad error if you need to use the
        power function.

                I have written a command to replace it. It works well for
        values which do not get too near the maximum a STOS integer can
        hold ($7fffffff). It is a lot quicker than using ^ too!

        E.g.
                 10 for LOOP=1 to 20
                 20 : STP=2 ^ LOOP
                 30 : XP=power (2,LOOP)
                 40 : print "For 2 ^";LOOP;":-"
                 50 : print "  STOS=";STP;" or ";2 ^ LOOP
                 60 : print "  EXTRA=";XP
                 70 next LOOP
                 80 end

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

25      cartridge input.: Get incoming data
        
        Input:  none

        Output: value of data coming into the machine via the cartridge port

                Use this to create some fab disco effects! If you have STOS
        Maestro (or indeed any sound sampler) plug it in (WITH THE COMPUTER
        TURNED OFF!!!) then insert your STOS disc and turn your ST on. You
        can then write a program which uses the value coming in from the
        cartridge port to determine which colour changes and to what value.
        This means the screen flashes in time to the music (if like me you
        attach your CD player to the sampler). 

                The returned value is 0-255 but you should subtract 127 from
        the value so that 0 (zero) becomes a stable point.

        E.g.
                 10 repeat
                 20 : CP=cartridge input-127
                 30 : if CP<0 then colour 0,abs(CP)
                 40 : if CP>=0 then colour 1,CP
                 50 until mouse key

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

        Cookies...

                The 'Cookie Jar' is an area Atari set up to allow for
        programmers to utilise a part of hardware which certain machines have.
        For example, using the _SND cookie you can see if the machine has a
        STe style DMA sound chip. If it has you may utilise this chip in your
        program.

                Not all of the cookies are available on all machines. You must
        monitor for errors when using the cookie commands. If an error does
        occur, presume that the cookie and therefore the hardware does not
        exist.

                The value are all correct as far as I trust. Except the Falcon
        to have a value of 3 where 0-ST, 1-STe and 2-TT. Mind you with Atari
        you never know...

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

26      cookie _cpu.....: Delve into cookie jar, return _cpu
        
        Input:  none

        Output: cookie jar value (see below)

                The _cpu cookie return the CPU (central processing unit) of
        your ST. For the ST/STe this will normally be 68000.

------------------------------------------------------------------------------
27      cookie _fdc.....: Delve into cookie jar, return _fdc
        
        Input:  none

        Output: cookie jar value (see below)

                The value has two parts to it. The high byte returns the
        value of the highest density floppy unit installed in the system.
        The values:-
                        0       360Kb/720Kb     (double density)
                        1       1.44Mb          (high density)
                        2       2.88Mb          (extra-high density)

                The low three bytes tell you about the origin of the unit.
        The value 'ATC' indicates an Atari line-fit or retro-fitted unit.

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

28      cookie _fpu.....: Delve into cookie jar, return _fpu
        
        Input:  none

        Output: cookie jar value (see below)

                This tells you if a floating point unit is present on the
        machine. The high word should be tested for the following bits:

                        0       I/O mapped 68881
                        1       68881/68882
                        2       if bit 1 = 0 then 68881, otherwise 68882
                        3       68040 internal floating point support

------------------------------------------------------------------------------
29      cookie _frb.....: Delve into cookie jar, return _frb
        
        Input:  none

        Output: cookie jar value (see below)

                This will tell you (if you have a TT) if a 'fast REM buffer' is
        available.

------------------------------------------------------------------------------
30      cookie _mch.....: Delve into cookie jar, return _mch
        
        Input:  none

        Output: cookie jar value (see below)

                This gives you a minor and major number as follows:-

                Major   Minor   Machine
                0       0       520/1040 or Mega ST
                1       0       STe
                1       16      Mega STe
                2       0       TT

------------------------------------------------------------------------------
31      cookie _snd.....: Delve into cookie jar, return _snd
        
        Input:  none

        Output: cookie jar value (see below)

                The result of this should be bit tested:-

                0       1 if ST style GI/Yamaha chip available
                1       1 is STe style DMA sound chip available

------------------------------------------------------------------------------
32      cookie _swi.....: Delve into cookie jar, return _swi
        
        Input:  none

        Output: cookie jar value (see below)

                This gives the internal configuration switchs!

------------------------------------------------------------------------------
33      cookie _vdo.....: Delve into cookie jar, return _vdo

        Input:  none

        Output: cookie jar value (see below)

                This give sthe major and minor part number of your video
        shifter chip.

                Major   Minor   Machine
                0       0       ST
                1       0       STe
                2       0       TT

------------------------------------------------------------------------------
34      disc size (A)...: Retrieve original disc size

        Input:  drive to examine (0 = A, 1 = B, etc etc)

        Output: original size of disc in bytes

                Command dedicated to Paul Archer!

                This command retrieves the size of the disc with no data.

        E.g.
                 print disc size(0)

                 10 DS=disc size(drive)
                 20 DF=dfree
                 30 print "Total size of disc ...:";using "##########";DS
                 40 print "Amount used ..........:";using "##########";DS-DF
                 50 print "Amount free ..........:";using "##########";DF
                 60 end             

------------------------------------------------------------------------------
35      disc free (A)...: Retrieve amount free on disc

        Input:  drive to examine (0 = A, 1 = B, etc etc)

        Output: amount of bytes free on disc

                This command retrieves the amount of space (in bytes) on a 
                disc. Is is the same as 'dfree' but allows you identify a
                particular drive, not necessarily the current one.

        E.g.
                 print disc free(1)

                 10 DF=disc free(1)
                 20 print "Amount free ..........:";using "##########";DF
                 30 end             

------------------------------------------------------------------------------
36      disc used (A)...: Retrieve actual amount used on disc

        Input:  drive to examine (0 = A, 1 = B, etc etc)

        Output: actual number of bytes used on disc

                This command retrieves the size the used portion of a disc. 
        However, as it is the true amount (formatted size - free bytes) it
        does not necessarily equal the sum total of files on the disc. If
        in STOS you enter 'dir' the amount used refers to that directory
        in data, not on the entire disc and not including directory
        information which must be stored on the disc. This is why it
        appears to be incorrect!

        E.g.
                 print disc used(0)

                 10 DU=disc size(0)
                 20 print "Amount used ..........:";using "##########";DU
                 30 end             

------------------------------------------------------------------------------
37      depack tiny A,B.: Depack tiny bank to other bank

        Input:  actual addresses for source and destination banks

        Output: none

                This command will unpack a .TN? format picture. The
        destination bank must be a reserved bank of $8000 bytes size or
        the physical, logical or background screen. Note that if you unpack
        to a memory bank the palette will not be stored in that bank. If
        you want to copy the physical palette to the screen bank you must
        copy colours 0-15 (low res) or 0-3 (med res) to the offset 32000
        within your bank.

        E.g.
                 depack tiny start(5),physic

                 10 reserve as work 5,$8000
                 20 FILE$="PIC.TNY"
                 30 bload FILE$,5
                 40 depack tiny start(5),physic
                 50 end

------------------------------------------------------------------------------
38      vtab (X)........: Tab to column on screen

        Input:  Column to tab to (0-132)

        Output: to screen/printer/string

                This function is a more true version of the tab command than
        the one provided by STOS. The STOS tab command moves the cursor
        right by the value, from where ever the cursor was.

                The VTAB function moves the cursor to the selected column.
        It does so by repositioning the cursor to the start of the line and
        then using ASCII value 9 to move the cursor right by the required
        value. Because of this it probably will not work on your printer.
        This is because most printer use this code to skip to the next
        predefined tabulation value, not necessarily one place to the right.

        E.g.
                 print vtab(5);"Name";vtab(20);"Score"

                 10 print vtab(0);"Loop";vtab(20);"Loop x Loop"
                 20 for LOOP=1 to 10
                 30 print vtab(0);using "##";LOOP;vtab(20);using "###";LOOP
                    * LOOP
                 40 next LOOP
                 50 end             

------------------------------------------------------------------------------
39      ltab (X)........: Tab to column on line printer

        Input:  Column to tab to (0-132)

        Output: to screen/printer/string

                This function is a more true version of the tab command than
        the one provided by STOS. The STOS tab command moves the cursor
        right by the value, from where ever the cursor was.

                The LTAB function moves the cursor to the selected column.
        It does so by repositioning the cursor to the start of the line and
        then using ASCII value 32 to move the cursor right by the required
        value. Using code 32 means it will work on a printer but using it
        on a screen means that characters on the line upto the column will
        be erased.

        E.g.
                 print ltab(5);"Name";ltab(20);"Score"

                 10 print ltab(0);"Loop";ltab(20);"Loop x Loop"
                 20 for LOOP=1 to 10
                 30 print ltab(0);using "##";LOOP;ltab(20);using "###";LOOP
                    * LOOP
                 40 next LOOP
                 50 end             

------------------------------------------------------------------------------
40      blur (8 parms)..: Blur portion of screen

        Input:  destination address, top left corner x, y,
                        block size x, y, factor x, y, blur type

        Output: none

		(Note that versions <1.70 used block size and factor size
in opposite sequence. Any blur command before this will need these two sets
of parameters (4 in all) swapped over)

                This command will 'blur' a portion of the screen or screen
bank. It may be used to emulate the blur used on television when trying to
hide a persons identity or in games to distort a picture and to see how
quickly or just how distorted the picture can be before someone correctly
identifies the distorted image.

                This command ONLY WORKS IN LOW RESOLUTION!

                The destination must be an actual address (so for bank 5
use start(5) not 5).

                The top left corner identifies the pixel position (x,y) of
where the distortion is to take place.

                The block size x,y is the area of the screen to blur. If
this was 16 x 16 and the factor was 2 x 2 there would be 8 x 8 blocks in
the blurred portion of the screen.

                The factor x,y is the new pixel size. For example, a value
of 2,2 will create a block of 2 x 2 pixels.

                The blur type can be a value 1 - 5 (any other value uses
blur type 1). It tells the command which pixel to use to get the colour of
the resulting block:-

                1 - top left pixel      (x,y)
                2 - top right pixel     (x+x factor,y)
                3 - centre pixel        (x+x factor/2,y+y factor/2)
                4 - bottom left pixel   (x,y+y factor)
                5 - bottom right pixel  (x+x factor,y+y factor)

        E.g.
                 blur physic,0,0,320,200,2,2,1

                 10 mode 0:key off:curs off:flash off
                 20 FILE$="PIC.NEO"
                 30 load FILE$
                 40 blur physic,0,0,320,200,2,2,3
                 50 end

------------------------------------------------------------------------------
41     convert iff S,D,P: Convert uncompressed IFF image to normal


        Input:  source address, destination address, palette flag (0 or 1)

        Output: none

		This command converts an uncompressed IFF image to the
address given. This address may be physic, logic, back or the actual address
of a screen bank. The palette flag may be 0-do not set palette or 1-set
palette.

        E.g.
                 convert iff start(5),physic,1

                 10 mode 0:key off:curs off:flash off
                 20 FILE$="PIC.IFF"
		 30 reserve as work 5,$8000
                 40 bload FILE$,5
                 50 convert iff start(5),physic,1
                 60 end

------------------------------------------------------------------------------
42	deshade A,B,C...: Change colours not B to C in addr A

        Input:  screen address, colour to ignore, selected colour

        Output: none

		This command changes all colours (except a selected one) at an
address to the selected colour. Its primary use is freeing the other colours
from a digitised or scanned picture. These types of image use shading to get a
good effect but this uses all of the 16 colours. Generally use colour 0 as the
one to ignore.

		Running this command over a screen (using a value of 1 for a
scanned image or 15 for a video digitised image) should do the trick. In the
case of a scanned image you may want to change colour 1 to $0 so that it is
blank rather than a grey shade.

		If you were scanning in your drawings to colour in this will
allow you to redefine the other colours to pretty ones (ie red, yellow, green
etc) instead of grey shades.
	
        E.g.
                 deshade physic,0,1

                 10 mode 0:key off:curs off:flash off
                 20 FILE$="SCANPIC.NEO"
		 30 reserve as screen 5
                 40 load FILE$,5
                 50 deshade start(5),0,1
		 60 screen copy 5 to physic
		 70 colour 1,$0
                 80 end

------------------------------------------------------------------------------
43    set printer data A: Configure printer to A

        Input:  printer data (see below)

        Output: none

		This command allows you to set up the Atari/printer
configuration.

		The data is made of flags using bits.

		Bit	If clear (0)		If set (1)
		 0	Dot matrix		Daisey Wheel
		 1	Monochrome		Colour
		 2	Atari Mode		'Epson' compatible
		 3	Draft quality		Final quality
		 4	Parallel port		Serial (RS-232) port
		 5	Continuous		Single sheet

		For your knowledge, bit 0 is the furthest to the right of
a value given in binary. The value is preceeded with a % to signify that
it is a binary one. So, %10011 would mean that bits 0,1 and 4 are set.

		You can set the value to any combination of the above. To
do this you MUST use every bit (set or clear) to change any one.

		So 'set printer data %101100' will set the printer to
dot matrix, monochrome, Epson compatible, Final quality, parallel and
single sheet.
		If you only want to change an individual bit then you must
use the 'setup of printer' command to get the original value, use 'or' to
set your bit and then use 'set printer data'. See below for details.

        E.g.
                 set printer data %101100

                 10 set printer data %101100
	         20 end

		To set an indivdual bit or bits:

		 10 rem Set bit 1 leaving others unchanged
		 20 PS=setup of printer
		 30 PS=PS or %000010
		 40 set printer data PS
		 50 end

------------------------------------------------------------------------------
44	setup of printer: Returns printer configuration data

        Input:  none

        Output: printer data (see below)

		This command returns the Atari/printer configuration.

		The data is made of flags using bits.

		Bit	If clear (0)		If set (1)
		 0	Dot matrix		Daisey Wheel
		 1	Monochrome		Colour
		 2	Atari Mode		'Epson' compatible
		 3	Draft quality		Final quality
		 4	Parallel port		Serial (RS-232) port
		 5	Continuous		Single sheet

		For your knowledge, bit 0 is the furthest to the right of
a value given in binary. The value is preceeded with a % to signify that
it is a binary one. So, %10011 would mean that bits 0,1 and 4 are set.

        E.g.
                 PS=setup of printer

                 10 print setup of printer
	         20 end

------------------------------------------------------------------------------
45	depack degas A,B: Depack a degas screen from addr A to B

        Input:  actual addresses for source and destination banks

        Output: none

                This command will unpack a .PC? format picture. The
        destination bank must be a reserved bank of $8000 bytes size or
        the physical, logical or background screen. Note that if you unpack
        to a memory bank the palette will not be stored in that bank. If
        you want to copy the physical palette to the screen bank you must
        copy colours 0-15 (low res) or 0-3 (med res) to the offset 32000
        within your bank.

        E.g.
                 depack degas start(5),physic

                 10 reserve as work 5,$8000
                 20 FILE$="PIC.PC1"
                 30 bload FILE$,5
                 40 depack degas start(5),physic
                 50 end

------------------------------------------------------------------------------
46  A$=visible input$(A): Input A number of characters into A$

        Input:  Number of characters to input (1-9000)

        Output: String variable

                This function is an improved version of the input$(n) command
provided by STOS. The difference is that the text you enter is shown on the
screen as you enter it. Like the STOS function Backspace is the only control
key active. Pressing RETURN will end the input before all of the characters
have been entered, in this instance trailing spaces are added to the end of
the string to ensure a constant sized variable.
 
        E.g.
                 A$=visible input$(10)

		 10 mode 1 : key off
		 20 print "Enter name (upto 12) characters";
		 30 NAME$=visible input$(12)
		 40 end


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

This extension has been written using the following aids:-

        Devpac 3 (HiSoft) and their informative (if a little errorish) manual.

        STOS Newsletter (issues 8 and 9 etc) R.I.P.

        STOS itself

        Introducing ATARI ST Machine Code (zzSoft)

        The Concise Atari ST 68000 Programmer's Guide (Glentop)

        50's and 60's sounds on Breeze AM.

-----------------------------------------------------------------------------
About the author...

Name..................: Martin Cubitt
Sex...................: Male
Date of Birth.........: 18th Jan 1969
Address...............: 14 Deepdene Avenue
                        Rayleigh
                        Essex
                        SS6 9LG
                        England
Brief computer history: At age of 12/13 borrowed VIC20 and Atari 400.
                        Taught myself BASIC.
                        Dabbled with machine code.
                        Got given VIC20 and borrowed C64.
                        Dabbled a little wore with 6502 machine code.
                        Still never had an assembler! All assembly
                        done manually by me via a book.
                        Got an Einstein.
                        Dabbled with Z80 machine code. Still no
                        assembler.
                        Borrowed Amstrad PCW and dabbled...
                        Took (and passed) 'A' level computer science.
                        Started work (computer operator) on a System 38.
                        Splashed out (1987) on an Atari ST.
                        Bought STOS BASIC.
                        Dabbled with 68000 using a copy of Devpac given
                        away on ST Format.
                        Became analyst programmer at work using a
                        language called RPG III, still on IBM System 38.
                        Bought VIDI-ST - excellent!
                        In 1989 brought STe with 2MB. (Good move!)
                        TOS 1.6 (buggy!) - bad move.
                        Bought Devpac 2.
                        Started teaching BASIC privately to Keane Ingram.
                        Written many utilities and demos in STOS BASIC,
                        most of which can be bought from Goodmans PDL.
                        Now coding RPG 400 at work.
                        Bought VIDICHROME - never worked properly - 
			 rubbish!
                        Bought Devpac 3 (the best!)
                        Wrote replacement file selector (in STOS)
                        Wrote my largest 68000 piece of code - this
                        extension.
                        Still employed (thank goodness) and still getting
                        a buzz out of programming and still teaching
                        Keane.
                        Wanting to buy Falcon - too expensive!


        If you have any comments (good or bad) please do write to me and let
me know your thoughts on this extension, or about computers in general.

        I do not care how young or old you are, if you have a query then
let me know!

        If you have any questions about the new commands, or indeed about STOS
commands in general, please do not hesitate to contact me and I will do my
best to help you.

        Special messages:-

        Manadarin, well done on STOS but blow you for your lack of support
                and sloppy attitude towards the ST.

        Manchester United supporters, hi - CHAMPIONS!

        Tony Greenwood - STOSSER disczine - a must for all STOS users
						       ---
        Anyone who writes to me, thanks!
