The Complete STOS Reference

pre-release 0.2 Edited By Dr Phibes

STOSSER Disk Magazine Problem Page

Isssues Covered So Far: 8-10

1 Degas compressed & tiny stiffed import
2 Text on top of images
3 multiple commands after an 'if'
4 setline bug
7 using DEF FN & FN
8 functions returning many strings
9 Accessing files in all sub directories
10 EXPLODE.BAS gives / by 0 error
11 STE extension & picture loading
12 merge command
13 sample playing
14 removing borders
16 random numbers & divide by 0 errors
17 many PICs in 1 bank
18 virus protection
19 STE scrolling

Problem: 1 Degas compressed & tiny stiffed import

Steve Gooding HAD a problem converting Degas compressed and Tiny stuffed pictures in STOS basic.

I (Martin Cubitt) solved this problem with my new EXTRA extension and conversion routine, both of which are on the August disczine.

Problem: 2 Text on top of images

Matthew Green wanted to know how can he print text onto the screen without ruining the picture below - in other words, how do you get a transparent paper?

Solution to problem: 2

10 rem Eg. of mixing text & graphics without the block effect.
20 rem Used carefully and with correct colour coordination can
30 rem smarten up displays.
50 rem Demo by Martin Cubitt in answer to query from S.Gooding
100 mode 0 : key off : curs off : flash off
110 reserve as screen 5
120 load "picture.neo",5 : rem Select your favourite picture
130 screen copy 5 to physic
140 screen copy 5 to back
150 get palette (5)
160 pen 15
170 logic=back : rem Use back as work can use another screen if desired
180 locate 0,1 : centre "Mixing text and graphics"
190 locate 0,3 : centre "From Atari ST User, Vol 4 No. 10"
200 locate 0,5 : centre "December 1989"
210 locate 0,21 : centre "Restored 18/7/1993 by Martin Cubitt"
220 logic=physic : rem reset logical pointer
230 A$=screen$(back,0,0 to 319,199) : rem get entire screen (or use a portion if your text only occupies a small part)
240 screen$(physic,0,0)=A$ : rem copy back to main (screen$ ignores background)
250 screen copy physic to back : rem Ensure screens in sync
260 A$="" : rem tidy up !
270 end

Problem: 3 multiple commands after an 'if'

Here's a query from K.A. Schimmel of Nottingham...

Like in Sinclair Basic, one can use multiple lines and this should make no difference to the running of the program. Well, it does not in Sinclair Basic but it seems to in STOS (or has it something to do with the STE?) Take the following lines:

10 plot 0,0
20 repeat
30 if mouse key=1 then ink rnd(15) : draw to x mouse,y mouse
40 until mouse key=2

When run, it draws a line from 0,0 to the mouse pointer when the left button is pressed and every time you move the mouse and click a new line from the last point it is drawn. OK, now split line 30 into:

30 if mouse key=1 then ink rnd(15)
35 draw to x mouse,y mouse

and what happens - the line from 0,0 to mouse pointer is already drawn and extends itself by moving the pointer, changing colour if the left mouse button is pressed. In other words, the program runs differently with a single line entry. Why? Does this only happen on the STE or is that the reason why GFA Basic is restricted to single line entries - because the Atari can translate a double line entry differently in some cases? It certainly does in the above example.

Solution to problem: 3

Well K.A. Schimmel you are quite right in what you say. STOS allows you to use multiple lines of code on a condition (ie an IF) as long as they are ALL on that same line. Unless the condition contained a branch (GOTO) the next line will be executed regardless of the condition in the previous line. This is quite correct and how most BASICS operate. However, it does not encourage structured programming.

Your example should be change thus:

10 plot 0,0
20 repeat
30 if mouse key<>1 then goto 40
32 ink rnd(15)
35 draw to x mouse,y mouse
40 until mouse key=2

When using if...then you should NEVER put a command following the then (except GOTO). It is much better reverse the logic of your condition (above =1 has been replaced with <>1) and then branch to skip the code which is placed below the condition, as above.

STOS does let you put multiple commands on lines but is can look untidy and cause problems such as you had.

Problem: 4 setline bug

Another query from K.A. Schimmel.

Could you perhaps explain why the SET LINE command will only work in thickness 1 (perhaps 2) and then only vertically? Above that you just get an ordinary thick straight line apart from the rounded and arrow ends.

Solution to problem: 4

10 rem Set line example
20 rem Martin Cubitt 11/8/1993
30 rem
100 mode 0 : key off : curs off
110 ink 1
120 THICKNESS=1
130 for LOOP=0 to 319 step 40
140 set line %1111111111111111,THICKNESS,0,0
150 polyline LOOP,0 to LOOP,199
160 locate xtext(LOOP),0
170 print str$(THICKNESS)-" "
180 THICKNESS=THICKNESS+4
190 next LOOP
200 end

The above program proves (on my system at least!) that the set line command DOES work. You should note that the manual does state that the set line command does NOT affect DRAW or POINT. Check out pages 126 and 127 of your manual for another example of using the command.

Since this problem was completed the originator of the question has since, correctly, stated that the above does not work when the set line parameter is not %1111etc. I have tried this and he is quite correct. I guess it is just one of those horrible STOS bugs we all know so well.

Problem: 7 using DEF FN & FN

Another query from Dean Sharples:

Could you explain how to use the 'DEF FN' and 'FN' commands?

Solution to problem: 7

Yes, they are quite simple really. The examples on page 214 of your STOS manual gives a pretty clear picture of their use but I will give another example.

Suppose you wanted to use an equation to evaluate the centre position of a heading in low resolution.

You may chose the equation X=((40-len(TEXT$))/2). The variable part of the equation is value of TEXT$. We can create a function to do exactly the above but make using it easier...

10 def fn MIDDLE(TEXT$)=((40-len(TEXT$))/2)

then to use the function anywhere else...

20 TEXT$="Test!"
30 X=fn MIDDLE(TEXT$)
40 locate X,0
50 print TEXT$
60 input "Name:";NAME$
70 X=fn MIDDLE(NAME$)
80 locate X,10
90 print NAME$
100 locate fn MIDDLE("That's all!"),16
110 print "That's all!"
120 end

So you can see that the variable name does NOT have to match the one defined in line 10, as long as the type (string in this case) is the same. From the manual you can see that you can have multiple parameters in the function. The function command is better suited where long complicated equations are in operation as they can be written once (in the DEF FN) and then used as FN's later.

Problem: 8 functions returning many strings ??

This problem is from me (Martin), I am having a nightmare writing the string commands for STOS...
I have a problem with strings in my STOS extension. I am obviously doing something wrong when I allocate the address of my string variable. I am using an address internal to the extension, in a buffer area used by other commands within the extension. When a string function is called it is okay but if you then try to store this variable into another variable the variable pointers are identical. This causes a problem where next time the string function is called the copied variable is over written, similar to the STOS bug with input and mid$.
Does anyone know how to correctly return interpreter and compiler strings? How do you use the code I read about which goes...

ASK equ
70 jsr ASK

Any ideas? Please write in if you can restore my sanity!
Solution to problem: 8
Although I have found no obvious cure (ie it seems STOS does not like you to write extensions that return more than one string) the problem has been worked round and routines can be found in the document text for the EXTRA extension version 1.91 and upwards.

Problem: 9 Accessing files in all sub directories

This problem is from me Tony Greenwood.

I am trying to make a routine that will read every file of a given mask from a disc. Ie. tell me every .BAS file on the disc. I can do it to a certain extent but it won't go into folders, I am using...

HOLD IT!

Solution to problem: 9

I have also tried (in vain) a few times to do this sort of thing but prompted by your request I sat down and thought about it for a few minutes. The result is a source listing (somewhere on issue 6 of STOSSER) called DISCTREE.BAS. It allows the collection of files on a disc no matter where they are! I have tested it a bit but not one hundred per cent.

Problem: 10 EXPLODE.BAS gives / by 0 error

This problem was sent to Keefy from B.Crossland.

It appears that the program EXPLODE.BAS given away in STOSSER issue 5 crashes with a divide by zero error.

Solution to problem: 10

This sort of error is something which programmers often forget to test for but it is essential that you do to maintain a level of professionalism (yuck!). However, looking at the program I can see what the problem is. The source must have been written in an old version of STOS, hence the BAD FLOAT highlights through out the program. This is caused by STOS being changed to a different precision in later version of STOS. Most STOS updater discs include a routine to change an existing program to use the new precision of real numbers. I don't have such a disc so I have changed to the program to get it to work. I cannot tell what the original values were so I have guessed!

1 rem Explode version 2?
2 rem 27/9/93
10 mode 0 : key off : click off : curs off : hide
20 P=20
22 FAIL=false
30 dim X(P),Y(P),XX(P),YY(P),YV(P),C(P)
40 for T=1 to P : X(T)=160 : Y(T)=100 : XX(T)=rnd(3)+1/4.0+1.0 : YY(T)=rnd(3)+1/4.0+1.0 : C(T)=rnd(14)+1 : YV(T)=rnd(2)/1.0+1.0 : next T
42 for T=1 to P/2 : XX(T)=-XX(T) : YY(T)=-YY(T) : next T
44 for T=P/2+1 to P : YY(T)=-YY(T) : next T
45 repeat
50 for T=1 to P : ink C(T) : plot X(T),Y(T) : next T
60 for T=1 to P : X(T)=X(T)+XX(T) : Y(T)=Y(T)+YY(T) : YY(T)=YY(T)+YV(T) : if Y(T)>199 or X(T)>319 then FAIL=true
65 next T
70 cls physic : until FAIL

Problem: 11 STE extension & picture loading

This problem was sent in from Deano a regular contributor to the STOSSER disczine.

Deano uses the STE extension from A & L software. Asa Burrows, the author wrote a small manual for his extension but assumed some knowledge of how the Atari handles graphics.

Deano's problem creating pictures to use with the hardware scrolling commands. The pictures are connected in a special format and cannot just be loaded in and added to each other.

Solution to problem: 11

I think I have cracked your problem. The example on disc had a problem because the screen area was four screens wide and only one screen deep but the area was defined as four screens wide and two screens deep. That is why that example did not work when scrolling up and down.

From what I understand from your question you want to be able to load pictures into a bank to create an area from hardware scrolling. Well, if so then I hope I have found a satisfactory solution. This is the source to the CRTSTESC (Create STe Screen) program I have written:

10 rem Program by Martin Cubitt (2nd October 1993) to create data bank
20 rem for use with hardware scroller, low res
30 rem
40 rem Obviously same palette throughout! (first 32 bytes are palette)
50 rem
60 mode 0 : key off : hide : curs off
70 NC=3 : rem No. of columns
80 NR=2 : rem No. of rows
90 reserve as work 6,160*200*NR*NC+32
100 fill start(6) to start(6)+length(6),0
110 reserve as screen 5
120 WID=160*NC : rem Width in bytes of one scanline
130 for CR=1 to NR
140 for CC=1 to NC
150 read CF$
160 gosub 1000
170 next CC
180 next CR
190 bsave "screen.dat",start(6) to start(6)+length(6)
200 default : end
1000 CP=WID*200*(CR-1)+160*(CC-1) : rem Offset of screen within bank
1010 load CF$,5
1020 get palette (5)
1030 screen copy 5 to physic
1040 if CP>0 then 1060
1050 copy start(5)+32000,start(5)+32032 to start(6)
1060 SC=0
1070 for SCANLINE=0 to 199
1080 copy start(5)+SC,start(5)+SC+160 to start(6)+32+CP
1090 SC=SC+160
1100 CP=CP+WID
1110 next SCANLINE
1120 return
2000 data "draw1.neo","draw2.neo","draw3.neo"
2010 data "wggrace.neo","swonder.neo","spock.neo"

Now a little explanation of how the program functions:

Line 70: NC hold the number of columns, or screens across of the new bank. I want three screens across so I set NC to 3.

Line 80: NR contains the number of rows, or screens deep of the new bank. As I am using two screens deep I set NR to 2.

This gives me a new area of 3 x 2 = 6 pictures

Line 90: Bank 6 holds the new virtual screen. The size of this is calculated by multiplying the words per screen (160 in low res) by the number of scan lines per screen (200 in low res) by the number of screens per row and then multiplying that by the number of rows. An additional 32 bytes are required to store the palette.

Line 120: The width of one scanline of a normal low res picture is 160 bytes. So for the new screen it will be 160 multiplied by the number of screens across.

Lines 130-180: For each column and row all screen file names are read and processed by calling the routine at line 1000.

Line 1000: The current position is the relative (offset) position within the new bank for the next picture. In the line the initial value is calculated by combing the values of the current row and column.

Line 1050: If this is the first picture the screen palette is stored in bank 6.

Line 1060: The initial position to copy from bank 5.

Line 1070: Loop 200 (low res) times, ie for each pixel row of the screen.

Line 1080: Copy 160 bytes (the width of one low res screen) from the loaded bank to our new bank. Note that this is start(6)+32+CP because the entire bank is offset by 32 bytes for the palette.

Line 1090: Add 160 (low res) to the offset of the loaded screen.

Line 1100: Add the calculated width of the new screen to the offset of the new bank.

Lines 2000 to 2010: Data for the file names.

If you want to, change the number of rows and columns around, ie. NC=2 and NR=3 so that you have a 2 x 3 screen rather than a 3 x 2 screen.

The program saves a bank called "screen.dat" to the default drive. You could change the program so that you select the file name and the drive.

Obviously the more screens you use the larger the new bank will be. This should be taken into account otherwise you will run out of disc or computer memory.

I modified the hardware scrolling program for use with this new bank. I compiled it and the scroll was TOO FAST! Still, it remained fairly flicker free.

Program available on issue 8 of STOSSER. Er, no it is not. See below!

NB. Whoops! I did my usual trick of being to hasty in order to beat the postage system and I saved the files straight to the disc I sent to the question originator. So if you would not mind sending the source back to me or Tony we would be very happy! Thanks.

Problem: 12 merge command

Next up we have two queries from Jimbo.

First up, Jim would like to know more about the merge command.

Solution to problem: 12

Well I never use this command but I do merge routines into a main program sometimes. I have some examples on disc for you to look at. What I do is save the routines to be merged as .ASC files (save 'PGMNAME.ASC') and then load my main routine up or swap the program number using the HELP key. Then I load my routine by load 'PGMNAME.ASC' and it is merged in with the existing program. This does the same as the merge command. Two things to note. Any lines in your second (routine) program which are the same as the existing one will overwrite the existing one. So put your routine at line 50000 are something so it is unlikely to clash. Also memory banks are not merged into the existing program so you'll need to BGRAB them in if you need them.

Problem: 13 sample playing

Next, Jim was impressed by the "check program" in issue 4 which spoke "I'm completely operational and all my functions are functionally perfectly". Jim would like to know how it was done as he would like to use the routine in his programs.

Solution to problem: 13

The sound you heard was a sampled sound, created with a sound sampler. You need the MAESTRO extension to play samples through STOS. Sound sampling can be fun but the legalities of copyright must be adhered to or you may find yourself in a lot of trouble! Many PD libraries will not accept programs which contain samples music which may breach copyright.

Eeeerm Tony here ( Sorry to butt in ), Quite right Martin Maestro is normally used to play samles through STOS, But you can now also use the new commands in the Missing Link Extension, Thats what i used for that particular Sample, I thought i better mention that in case anyone gets the source for that issue, Cheers!

Problem: 14 removing borders ?

Craig Brown from Leicester has asked about the possibilities of a command to remove the top and bottom border in STOS.
Solution to problem: 14
Unfortunately that sort of command is beyond me but I do believe that one of the new interpreter extensions on issue 7 included just this type of command.

Problem: 16 random numbers & divide by 0 errors ?

Fred Darlington from Preston has asked me a number of questions. How can you stop a divide by zero error occurring? How do you stop a random number producing from 0-x when you want 1-x? How do you print out a correct answer from a calculation.
Solution to problem: 16
A nice easy one to start, here is a little example program which will not work:

10 N1=10
20 N2=rnd(5
30 A=N1/N2

Install a little test...

22 if N2=0 then 20

Ie. keep on producing a random number until a non-zero value is retrieved.
Of course you should change the random value range from 0-5 to 1-5 in this case. This was Freds second query. How do you produce a random number from 1 to x rather than 0 to x.
This can be done quite easily. To limit the value from 1 to 5 rather than 0 to 5 change line 20 to:

20 N2=rnd(4)+1

This actually produces a random number from 0 to 4 and then adds one to the result. So the value is from 0 (+1 = 1) to 4 (+1 = 5).
To print the correct answer could not be easier:

40 print N1;" divided by";N2;" is";A

Problem: 17 many PICs in 1 bank ?

Keefy has written with a problem. He would like to know how to load more than one packed picture into a memory bank rather than a separate bank for each picture, and how to retrieve them once this is done.

Solution to problem: 17

I have included (in a folder PROBLEM1) a number of files which answers your question. There are two programs. One reads in all the memory banks and then saves one big one. the second program actually makes use of this big bank allowing you to select pictures within it.

I believe the programs are fairly simple and with minor alterations should suit most people.

Problem: 18 virus protection ?

Jason Dale has written querying if their is a reliable means of checking a disc is write protected to remove the chance of a virus spreading.

Solution to problem: 18

I have included (in a folder PROBLEM2) two programs. One uses the EXTRA extension command "write protected" which I have to admit is not 100% sure to work because of the strange way Atari's operating system changes from machine to machine.

However a second program is included which uses the rather crude method of attempting to write a file (with no data) to the disc. If there is an error (disc protected) then the program continues, happy that the disc is write protected. However, if the file saves, the program deletes it and issues an error message asking the user to write protect the disc and press a key when all is well.

We would encourage anybody to write in if they have any other methods of checking if a disc is write protected.

Problem: 19 STE scrolling ?

Marcus Platt would like to know how to use the hardware scrolling commands which come with the STe extension.

Solution to problem: 19

I agree that the manual assumes that the user knows more than the average programmer when it comes to using this excellent extension.

The scrolling commands use a large playing field made up of a number of screens. A program (CRTSTESCR/CRTSTESC2) must be run to create this playing field. Because it contains a number of screens the size of the playing field can become quite large.

To compliment a previous query on the subject of this command I have included a set of files in the folder PROBLEM3. Only one file is missing but is created when you run CRTSTESC2. This is the same as CRTSTESCR but allows packed pictures to be used instead of just NEO's. Eight pictures have been included. The file created is a massive 256,256 bytes so have plenty of space available!

The advantages of the extension can be seen when running the program STESC.PRG (once the large data file has been created) in the enormous speed improvement. For once you end up in the situation where you need to slow the scrolling down!