STOS BASIC FAQ/INSTRUCTIONS
- 1 STOS ... The Game Creator
- 1.1 The Function Keys
- 1.2 MULTIPLE PROGRAMS
- 1.3 Splitting programs in the Editor
- 1.4 System commands
- 1.5 Naming conventions for variables
- 1.6 Arithmetic operations
- 1.7 String operations
STOS ... The Game Creator
The Function Keys
The upper window contains a brief list of the current function key assignments. Whenever you press one of these keys, the string associated with it will be entered on the screen, just as if you had typed it yourself. You can also assign a separate set of strings to the shifted versions of these keys, which can also be displayed by pressing the shift key.
You can also access these function keys by clicking the left mouse button with the pointer over the function key description. Pressing the right hand mouse button has the same effect as pressing the shift key.
For further details see the descriptions of the commands KEY and KEYLIST.
This displays a rather complex looking dialogue box to which there are three parts.
The top section contains a list of the 4 programs held in memory at the moment. The current program is highlighted and this may be moved with the cursor keys to select one of the other three programs. You will see the top line alter to show you which program is being edited. See the section on multiple programs for further information.
The second part of the menu displays a list of the accessories loaded. To call up any accessory, press the associated function key.
The last line of the help menu displays the amount of free memory left.
To exit from the Help menu, press the HELP key again.
|Control + C||Stop the program being executed.|
|Undo||Pressing this twice redraws the screen and reinitialises the editor. It then lists the last line that caused an error.|
|Clr||Clears the editor window.|
|Up Arrow||Moves the cursor up one line.|
|Down Arrow||Moves the cursor down one line.|
|Left Arrow||Moves the cursor left one character.|
|Right Arrow||Moves the cursor right one character.|
|Return||Enters the line at the current cursor position.|
|Delete||Deletes the character under the cursor.|
|Shift + Delete||Deletes the line under the cursor.|
|Control + J||Joins two lines together.|
|Backspace||Deletes the character left of the cursor and moves the cursor left one character.|
|Home||Moves the cursor to the top left hand corner of the editor window.|
|Esc||Enter multi-display mode. See the section on multiple programs for further information.|
|Spacebar||Suspends a listing. Press the spacebar again to resume.|
|Insert||Toggles between insert and replace mode. Insert mode is signified by a slightly thicker cursor.|
Loading/Saving Basic programs
|LOAD filename||Load the file into memory for editing|
|SAVE filename||Save the current program to disk|
|FLOAD "*.BAS"||Load a file using the file selector|
|FSAVE "*.BAS"||Save a file using the file selector|
Running a program
|RUN||Runs the program from the first line|
|RUN no||Runs the program from line no.|
|RUN file$||Load and run the program stored in file$|
|CONT||Restart a program halted by Control + C or STOP|
Entering a STOS Basic program
|AUTO||Automatic line numbering|
|AUTO start||Start automatic line numbering from the line number start|
|AUTO start,inc||Starts from the line start and increments each successive line by the number inc.|
|RENUM||Starts by setting the first line number in your program to 10, and then renumbers each succeeding line in units of 10.|
|RENUM number||Sets the first program line to number and renumbers all the other lines in increments of 10.|
|RENUM number,inc||Starts at line number and increments each successive line by inc.|
|RENUM number,inc,start-end||Renumbers lines from start to end, beginning with line number, and incrementing each proceeding line by inc.|
|LIST [first-last]||Lists the current program.|
|SEARCH s$||Search for the position of any string within a Basic program. To repeat the search, enter SEARCH on it's own.|
|SEARCH s$,start-end||Will search only within the lines specified.|
|CHANGE a$ TO b$ [,start-end]||Will change all occurrences of a$ to b$, a range may also be specified.|
|DELETE [first-last]||Deletes some or all of the lines of a program.|
|MERGE file$||Merge a file into the current program. Existing lines will be overwritten by any new lines of the same number.|
Debugging a program
- Single step through the program. The next line can be stepped through by pressing any key.
- FOLLOW [first-last]
- As FOLLOW but only traces the given range.
- FOLLOW variable list
- This takes a list of variables separated by commas and prints them out after every instruction executed. As before, you can step through the program by pressing any key.
- FOLLOW variable list,first-last
- As before, but only traces the variables
within a given range.
- FOLLOW OFF
- Turns off the action of the FOLLOW command.
STOS Basic allows you to have up to four programs in memory at any one time. These may be completely independent of each other. If you suddenly decide to change the configuration of the editor for instance, you could easily load the CONFIG.BAS program into a separate segment of the ST's memory without interfering with your current program.
If you press the HELP key and move the highlighted bar with the cursor keys to one of the other slots and press HELP again, you will see that the program area is empty. You can enter another program, and run it, independently of the program in area 1.
- MULTI n
- Displays a number of programs simultaneously. Note, n can take the values 2-4 only.
- Expands the current program window into the full screen area.
Splitting programs in the Editor
You can also use the MULTI command to split a single program into a number of seperate sections. This can be done with the Help menu. Position the program cursos over program 1 and press the left and right arrow keys. As you can see, the text cursor is moved between four different boxes on the program line. Move the cursor to the first box and type in 1000 followed by Return. This sets the end point of the first part of the program to line 1000.
If you now exit back to the editor and type MULTI 2, thr program will be split into two windows. You can choose between these two windows by using the mouse pointer by moving into the desired window and clicking on the left hand mouse button.
Each box on the program line represents a different section of the listing. You can therefore use this technique to split a program into four separate parts. It is important to note that this has no effect on any existing segments, and you can page through each of the programs stored in memory using the Help menu as usual. All four of these programs can be split in exactly the same way without interfering with each other.
- Copy all or part of a program segment into the current program.
The GRAB command allows you to combine a number of subroutines stored in separate program segments into one complete program. This enables you to test each subroutine in your program independently.
The syntax of the GRAB instruction is:
- GRAB n
- Copy program number n into the current program, where n ranges from 1 to 4. Any attempt to use the number of the current program in this instruction will generate an error.
- GRAB n,first-last
- Only copies the lines between first and last into the current program.
- The system function is used to quit STOS and return to GEM.
- Reinitialise the editor and redraw the current screen.
- Erase the current program
- Attempts to recover the last program erased by NEW.
- Erase all variables and memory banks defined by the current program, also reposition the data pointer to the start of the data.
- Return the number of free bytes in memory and force garbage collection.
- Select language to be used by STOS.
- Switch between 50Hz and 60Hz.
- Change listing mode to uppercase. Lists commands in upper case and variables in lower case.
- Change listing mode to lower case. Lists commands in lower case and variables in upper case.
- Lists out the Function keys ready for editing
Naming conventions for variables
Variable names must NOT contain any of the following keywords:
TO, STEP, THEN, ELSE, XOR, OR, AND, GOTO, GOSUB, MOD, AS
and they must begin with a letter and be no more that 31 characters in length.
Types of variables
- STOS uses these by default since it is faster, and STOS is designed for creating games. Each integer is stored in 4 bytes and can range from Ã±2147483648
- Real numbers
- These are suffixed with the # character. They correspond directly to double precision floating point variables. Each real number is stored in 8 bytes and can range from -1.797692 E+308 to +1.197693 E+307. These numbers are accurate to 16 decimal digits.
- String variables
- These variables are always suffixed with the $ character and can range from 0-65500 characters long. They are NOT terminated with a chr$(0).
- Any of the above variable types can be made into an array in the usual fashion with the DIM statement and can have any number of dimensions, but each dimension is limited to a maximum of 65535 elements.
As default, all numeric constants are treated as integers. Any floating point assignments to an integer variable are automatically converted to a whole number before use.
In addition to using decimal notation, you can also use hexadecimal and binary notation. Binary numbers are signi- fied by preceding them with the character % and hexadecimal numbers are always preceded by the $ character.
Note that any numbers you type in are converted into a special internal format which is expanded back when you list the program. This will often lead to minor discrepancies between the number you entered, and the number displayed. The value of the number will however, remain completely unchanged.
Floating point constants are always distinguished from integers by the presence of a decimal point in the number. If the point is not used, then it will be taken to be an integer. Since STOS has to convert between integer and floating point, and integer numbers included in floating point arithmetic will be calculated over 25% slower.
The following operations may be used in numeric expressions: (listed in order of priority)
|/ and *||Divide and multiply|
|MOD||Modulo operator (Produces remainder of a division)|
|+ and -||Plus and minus|
|INC var||Add 1 to an integer variable. This is considerably faster that using var=var+1|
|DEC var||Subtract 1 from an integer variable.|
Most basics will allow you to join two strings together with a command, such as:
A$ = "STOS" + " Basic" PRINT A$ STOS Basic
In addition to this, STOS Basic also lets you perform subtraction with string variables as well. This operation works by removing all occurrences of the second string from the first:
PRINT "STOS BASIC" - "S" TO BAIC PRINT "STOS BASIC" - "STOS" BASIC PRINT "A String Of Ascii Characters" - " " AStringOfAsciiCharacters
Comparisons between two strings are performed on a character by character basis using the Ascii codes of the characters.
Common String Functions
LEFT$(v$,n) There are two distinct forms of these RIGHT$(v$,n) commands. The first version is identical to MID$(v$,s,n) the standard Basic uses of this function, resulting in a portion of the string being returned. The second will allow you to replace a section of a string with another. See the example below. 10 A$="** Basic" 20 LEFT$(A$,4)="STOS" 30 PRINT A$ run STOS Basic INSTR(d$,s$[,p]) Search for occurences of s$ in d$. The option of starting at character p is also included. If no match can be found, a value of 0 is returned. Array operations SORT var$(0) This allows you to sort all the elements in an array into ascending order with amazing speed. This array can be composed of either strings, integers or floating point numbers. The var$(0) indicates the starting point of the table to be sorted. This starting point must always be set to the first item in the array (item zero). MATCH(var(0),s) The MATCH function searches through a sorted table, and returns the item number in which the value s was found. If s is not found, then MATCH returns a negative number. The absolute value of this number contains the index of the first item which was greater that s. Providing the array is only one dimension, it can be of type string, integer or real. Before MATCH can be used, the array should always be sorted using the SORT command. Memory banks STOS Basic includes a number of powerful facilities for the manipulation of sprites, screens and music. The data required by these functions needs to be stored along with the Basic program. STOS Basic uses a special set of 15 sections of memory for this purpose called banks. Each bank is referred to by a unique number ranging from 1-15. Many of these banks can be used for all types of data, but some are dedicated solely to one sort of information only such as sprite definitions. Every program stored in the ST's memory has it's own separate set of banks. There are two different forms of memory bank; permanent and temporary. Permanent banks only need to be defined once, and are all subsequently saved along with your program, temporary banks are erased rom memory by the CLEAR command. Types of memory bank Each memory bank can be one of the following different types. Class Stores Restrictions Type Sprites Sprite definitions Only bank 1 (1) P Icons Icon definitions Only bank 2 (1) P Music Music Only bank 3 (1) P 3D Future 3D extension Only bank 4 (4) P Set Holds new character sets Banks 1-15 P Screen Stores a complete screen Banks 1-15 T Datascreen Stores a screen Banks 1-15 P Work Temporary workspace Banks 1-15 T Data Permanent workspace Banks 1-15 P Menu Menu lines Bank 15 (2) T Program Machine-code program Banks 1-15 (3) V Footnotes: (1) Bank is not really general purpose. It is allocated automatically by the appropriate accessory, or when a bank of this type is loaded. (2) Reserved automatically by MENU commands. Usable only by programs which don't use menus. (3) Reserved as either Work or Data. Renamed when program loaded into bank. (4) Reserved for future expansion. (P) Permanent memory bank (T) Temporary memory bank (V) Variable between permanent or temporary. LISTBANK Lists the numbers of the banks currently reserved by a program, along with their location and size. S := Start address of the bank E := End address of the bank L := Length of the bank HEXA ON/OFF Sets the LISTBANK to decimal or hexadecimal notation. RESERVE Any banks used by sprites, music, icons, 3D extensions, and the menus are allocated automatically by the system. The RESERVE command allows you to allocate any other banks which you require. Each different type of bank has it's own individual form of the RESERVE instruction. RESERVE AS SCREEN bank Reserves a temporary bank of memory for a screen. This bank is always 32K long. RESERVE AS DATASCREEN bank Reserves a permanent bank of memory 32K long for use as a screen. This screen is saved along with your program, so it's great for title screens. RESERVE AS SET bank,length Reserves a permanent bank of memory length bytes long for use as a character set. RESERVE AS WORK bank,length Reserves a temporary bank for use as a workspace length bytes long. RESERVE AS DATA bank,length Reserves a permanent bank of memory length bytes long for use as a workspace. Please note that bank may be any number between 1 and 15, but since banks 1-4 are used by the system, it's wise to leave these alone. Length is automatically rounded to the nearest 256 byte page. Copying banks When using these memory banks, it's often useful to be able to transfer the contents of one bank to another. This can be done with the BCOPY command. BCOPY #source TO #dest BCOPY copies the entire contents of bank number source to bank number dest. BGRAB prgno[,b] BGRAB copies one or more banks stored at program number prgno into the current program. Program numbers between 1-4 denote one of the four programs which can be stored in memory at anyone time. Numbers 5-16 represent an accessory. If the optional bank number b is not included, then all the banks attached to program number prgno are copied into the current program, and any other banks of memory which are linked to this program are erased. Otherwise, the bank number specifies one bank which is to be transferred into the current program. All other banks remain unaffected. ERASE b Delete the contents of memory bank b from the program's memory and free the bank. =START([prgno,]b) This function returns the start of bank b from either the current program, or the program specified. prgno can be 1-4 for each of the four programs or 5-16 for the accessories. =LENGTH([prgno,]b) This function returns the length of the bank specified. Saving and loading SAVE This instruction provides general and starightforward way of saving a STOS Basic program on the disc. Unlike the equivalent instruction found in most other versions of Basic, STOS also allows you to save a variety of other types of information. This is determined by the extension of the filename used in the SAVE command. Here is a summary of the various data types, along with their extensions. Type of information Extension Comments Basic Programs .BAS Normal basic program Accessories .ACB Load using ACCLOAD Images .PI1,PI2,PI3 Degas format screen .NEO Neochrome format Memory Banks .MBK One memory bank .MBS All current banks Basic Variables .VAR All current vars. Listings .ASC Ascii format RUN-ONLY programs .PRG GEM programs If none of these extensions is found, STOS automatically adds .BAS .ACB files are simple Basic files which may be loaded as accessories. To create them, write your program in Basic as normal, but save it with the different extension. You can load it either as an accessory using ACCLOAD or a Basic program using LOAD. Image Files. You can also save the current screen, bank or memory address as an image file in degas or neochrome format using this method. SAVE "Filename.???"[,address of screen] Memory Banks: SAVE "Filename.MBK",b SAVE "Filename.MBS" Variables: SAVE "Filename.VAR" Listings: SAVE "Filename.ASC" Blocks: BSAVE file$, start TO end Save the memory from start to end as a binary file. (All of the above saves can be re-loaded into STOS by replacing the LOAD or BLOAD with SAVE or BSAVE.) BLOAD file$,addr The file file$ will be loaded into the address specified. BLOAD file$,#bank The file file$ is loaded into the specified bank. The accessories ACCLOAD Loads any of the accessories into memory. Either specify which file to load, or use "*" to load all the accessories from disk. ACCNEW Erases all the accessories from memory. ACCNB Returns the value of zero if the program is not an accessory, else it returns a number between 4 and 15 Sprite Commands SPRITE n,x,y,p Display sprite number n on the screen at coordinates x,y using image p. n is the number of the sprite, which can range from 1-15. It is the number which will be used to identify the sprite in any subsequent calls to MOVE and ANIM instructions. x and y are the coordinates of the point on the screen where the sprite is to be drawn. Unlike normal screen coordinates, these can take negative values. The x coordinate can vary from -640 to +1280, and y coordinate from -400 to +800. This allows you to move a sprite off the screen without causing an error. p specifies which of the images in bank 1 is to be used for a particular sprite. The only limit to the number of these images is the amount of available memory. Each sprite has an invisible handle through which it can be manipulated, called a Hot Spot. Whenever we draw a sprite, we always specify the coordinates of the hot spot. Moving a sprite MOVE X n,m$ This defines a list of horizontal movements which will be subsequently performed by sprite number n. m$ contains a sequence of commands which determine the speed and direction of the sprite: "(sp,st,ct)[A]" SP is the speed of the sprite in 50ths of a second and can range from 1 (v.fast) to 32767 (v.slow) ST is the step size, i.e. how many pixels it will be moved. CT is the number of times that this particular set of commands will be obeyed. 0 indicates that the movement is to be repeated indefinately. This can range from 0 to 32767. E.G. The command MOVE X 1,"(1,5,60)(1,5,-60)" will move sprite 1, 5 pixels to the right every 50th of a second, 60 times, then move it 5 pixels to the left every 50th of a second, 60 times. Movement will then stop. The optional A can take either L to signify that, once the command list has finished, it is to be restarted or Looped. It may also be followed by a number (e.g. L100) which will cause the sprite to be restarted from this coordinate. Additionally, it can take the form of Ex which will cause the sprite to stop when it reaches point x on the screen. NOTE that the sprite must actually reach point x exactly for this to work. If the sprite passes this point without stopping on it, it will not work. e.g. MOVE X 1,"(1,2,100)E150" will work whereas MOVE X 1,"(1,2,101)E150" will not as the sprite uses points 149 and 151, but not 150. MOVE Y n,y$ Acts in the same way to MOVE X but will move the sprite along the Y coordinate. Both commands may be used together to cause a sprite to move diagonally. MOVE ON/OFF [n] Before any sprite movements you have defined by MOVE X and MOVE Y commands will be performed, they need to be initiated by the instruction MOVE ON. n specifies the sprite whose movement is to be switched on or off, and if omitted, the command affects all sprites. MOVE FREEZE [n] This command can be used to temporarily halt one or all of the sprites on the screen. This can then be restarted with the MOVE ON command. =MOVON(n) Return the state of a sprite. If the sprite is currently stationary, it will return 0 (False). =X SPRITE(n) Return the X coordinate of the sprite n. =Y SPRITE(n) Return the Y coordinate of the sprite n. LIMIT SPRITE [x1,y1 TO x2,y2] This command allows an area of the screen to be used to display the sprites rather than the entire screen. If any sprites leave this area, they will disappear from the screen. The x1,y1 coordinates define the top left coordinate of the rectangle and the x2,y2 coordinates define the bottom right. All the X coordinates specified are rounded down to their nearest multiple of 16. To cancel this command, use LIMIT SPRITE with no parameters. Animation ANIM n,m$ This enables you to page through a chain of sprite images one after another. This sequence will be executed at the same time as your sprite is being displayed, even if it is also being moved. n refers to the number of the sprite to which the animation is to be applied. m$ holds the animation control string in the same way as the movement commands do. This takes the format: "(Image,Delay)[A]" Image specifies which image is to be used by the sprite (refer to parameter p of SPRITE) to be displayed during each step of the animation. Delay specifies the amount of time that the image will be held on the screen before the next image is displayed. This delay is specified in 50ths of a second. Again, then optional parameter A can be used to specify that the animation string is to be repeated upon completion by including L. ANIM ON/OFF [n] This command is used the same way as MOVE ON/OFF to turn the animation control on or off. ANIM FREEZE [n] This command is used to temporarily suspend animation until ANIM ON is reissued. Controlling the sprite using the mouse CHANGE MOUSE m This allows you to completely redesign the shape of the mouse cursor. m gives the number of the image to be used, as follows: 1 Arrow (Default) 2 Pointing Hand 3 Clock If you specify a value greater then 3, then this is assumed to refer to sprite image m-3. =X MOUSE Return the X coordinate of the mouse. =Y MOUSE Return the Y coordinate of the mouse. =MOUSE KEY Return the state of the mouse buttons: 0 No button has been pressed 1 Left button pressed 2 Right button pressed 3 Both buttons pressed LIMIT MOUSE [x1,y1 TO x2,y2] Restricts the mouse pointer to a rectangle defined by x1,y1 as the top left hand corner and x2,y2 as the lower right hand corner and also positions the mouse in the centre of the box. LIMIT MOUSE with no parameters will cancel this command. HIDE [ON] Will hide the mouse pointer and maintain a count of how many HIDE commands have been used. The equivalent number of SHOW commands must be used to restore the mouse. HIDE ON will override the count and always hide the mouse. SHOW[ON] Will show the mouse in the same way as HIDE will hide it. Reading the joystick (Port 1) =JOY Returns a bit pattern showing which way the joystick is being moved. BIT No. Significance 0 Up 1 Down 2 Left 3 Right 4 Fire button pressed =JLEFT Returns TRUE if the joystick is being moved left. =JRIGHT Returns TRUE if the joystick is being moved right. =JUP Returns TRUE if the joystick is being moved up. =JDOWN Returns TRUE if the joystick is being moved down. =FIRE Returns TRUE if the fire button has been pressed. Detecting collisions with a sprite =COLLIDE(n,w,h) Test sprite number n for collisions with other sprites. The collision is detected from the Hot Spot of the sprite over an area w wide and h high. The return is a bit pattern with the appropriate bits 1-15 set if collision with these sprites has been detected. Detecting collision with rectangular blocks SET ZONE z,x1,y1 TO x2,y2 Defines one of 128 rectangular zones which can then be tested using the ZONE command for the presence of either the mouse or a sprite. z specifies a number from 1-128 which represents the zone to be created. x1,y1 and x2,y2 denote the top left and bottom right coordinates of the zone. =ZONE(n) This searches the zones for the presence of sprite n. n can range from 0-15 with 0 representing the mouse. This function will return 0 if no zone can be detected, or else it will return the zone number the sprite is currently in. Note, only the first zone may be found. RESET ZONE [z] Reset one or all zones. Detecting collisions with an irregular shape =DETECT (n) Return the colour directly under the Hot Spot of the sprite specified (0-15). PUT SPRITE n Place a copy of sprite n on the screen directly under the sprite's current position. This doesn't affect the sprite in any way. GET SPRITE x,y,i[,mask] Grabs an image off the screen from coordinates x,y to image i in the sprite bank. This image must already exist in the sprite bank as it's dimensions are used during the grab. The optional mask allows you to set which colour is to become transparent. This is usually colour 0 (the background), but some interesting effects can be made by altering this. Sprite Priority PRIORITY ON/OFF Determines which sprite priority system is to be used. ON is used to give priority to the sprites with the largest Y coordinate. If you are using this method, it is advisable to set the hot spot of the sprites to the bottom of the sprite. OFF is the default system which gives priority to sprite 0..1..2... ...15 The Background AUTOBACK ON/OFF ON (default) causes all graphics commands to operate on the foreground and background screens. OFF causes these operations to be performed on the foreground screen only. (Use this mode only if you are not using the sprites or the mouse.) Miscellaneous sprite commands UPDATE [ON/OFF] Turn on or off the automatic updating of the sprites. UPDATE used on it's own will redraw any sprites which have changed their position since their last update. REDRAW Redraw all the sprites regardless of whether they have changed position. OFF Turn off all the sprites. FREEZE Temporarily freeze all sprite movement and music. UNFREEZE Resume any sprite movement and music suspended by FREEZE. Music and Sound PLAY [voice,]pitch,duration Plays a pure note of pitch for the specified duration (in 50ths of a second). If voice (1-3) is omitted, then the note will be played on all three voices simultan- eously. Octave 0 1 2 3 4 5 6 7 Note Pitch C 1 13 25 37 49 61 73 85 C# 2 14 26 38 50 62 74 86 D 3 15 27 39 51 63 75 87 D# 4 16 28 40 52 64 76 88 E 5 17 29 41 53 65 77 89 F 6 18 30 42 54 66 78 90 F# 7 19 31 43 55 67 79 91 G 8 20 32 44 56 68 80 92 G# 9 21 33 45 57 69 81 93 A 10 22 34 46 58 70 82 94 A# 11 23 35 47 59 71 83 95 B 12 24 36 48 60 72 84 96 VOLUME [v,]intensity Allows the volume of one or all of the voices (1-3) to be altered from 0 to 15 CLICK ON/OFF Turn key click on or off MUSIC n Play tune number n from the music bank by interrupt. MUSIC OFF Turn the music being played off. MUSIC FREEZE Temporarily suspend the playing of the music. MUSIC ON Resume playing the music temporarily frozen. TEMPO s Change the tempo of the music from 1 (v.slow) to 100 (v.fast). TRANSPOSE df Transpose a piece of music from -90 to +90 (1 corresponds to a semi-tone). =PVOICE(v) Return the position within the specified voice, the music is currently at. VOICE ON/OFF [v] Turn one or all of the voices on or off. Predefined sound effects BOOM Generate a noise sounding like an explosion. SHOOT Create a sound like a gun firing. BELL Simple bell sound. NOISE [v,]p Produce white noise of frequency 1 (v.high) to 31 (v.low) on one or all of the voices. ENVEL t,s Activate one of the 16 envelopes (t) to the speed (s) which may range from 1 (v.fast) to 65535 (v.slow) Graphics Functions INK index Set the colour of all subsequent graphic drawing operations. (0-15 in low res, 0-3 in medium res, 0-1 in monochrome). COLOUR index,$RGB Set the colour of a specific pen to a $RGB setting. =COLOUR(index) Read the current colour setting of a specific pen. PALETTE list This allows you to set the entire palette to a list of colours, like an expanded COLOUR command. Note that the number of parameters taken varies with each if the resolutions. PLOT x,y[,index] Plot a single point in the current or specified pen colour. =POINT(x,y) Return the current colour (pen) of a specific point on the screen. DRAW [x1,y1] TO x2,y2 Draw a line between specified coordinates, or the last point plotted. Note that this line is always solid and unaffected by SET LINE for speed. For styled lines, use the POLYLINE command. BOX x1,y1 TO x2,y2 Draw a hollow box with the top left and bottom right hand coordinates being specified. RBOX x1,y1 TO x2,y2 Draw a hollow box with rounded edges. POLYLINE [x1,y1] TO x2,y2 [TO x3,y3....] Draw a polygon using the current line style. ARC x1,y1,r,sÃ¸,eÃ¸ Draw an arc centre x1,y1 radius r from sÃ¸ to eÃ¸. Note that angles are calculated in radians (0- 3600) and start from the 3 o'clock position and travel anticlockwise. EARC x1,y1,r1,r2,sÃ¸,eÃ¸ Draw an elliptical arc as above. SET LINE mask,thickness,startpoint,endpoint Set the current line style to mask which is a 16 bit binary pattern for the line, thickness is the thickness of the line and can vary from 1 to 40. The startpoint and endpoint are the line end styles and can be either: 0 : SQUARED 1 : ARROWED 2 : ROUNDED PAINT x1,y1 Fill and enclosed area in the current colour. BAR x1,y1 TO x2,y2 Draw a filled bar. RBAR x1,y1 TO x2,y2 Draw a rounded filled rectangle. POLYGON x1,y1 TO x2,y2 [TO x3,y3....] Draw a filled polygon. CIRCLE x1,y1,r Draw a filled circle. PIE x1,y1,r,sÃ¸,eÃ¸ Produce a pie chart ELLIPSE x1,y1,r1,r2 Draw an ellipse. EPIE x1,y1,r1,r2,sÃ¸,eÃ¸ Produce a filled elliptical pie. SET PAINT type,pattern,border Select a fill pattern. Type can range from 0 to 4:- 0 Surface is not filled at all 1 Surface is filled with the current INK 2 Surface is filled with one of the 24 dotted patterns 3 Surface is filled with one of the 12 line patterns 4 Surface is filled with a user-defined pattern Pattern can range from 1 to 24 or 1-12 depending on the type. Border has only 0 (no border) or 1 (border) SET PATTERN address of pattern This is used to install a user defined fill pattern for the user-defined fill option of SET PAINT. The address of pattern refers to where in memory the new pattern is to be found. Each pattern is 16 points high by 16 points wide and takes up two byte words for each colour plane. The easiest way of creating them is to define a 16 by 16 sprite and then use the following routine to find the address of the sprite. if mode=0 then PLANES=4 if mode=1 then PLANES=2 if mode=3 then PLANES=1 s=1 : rem sprite to be indexed SP=leek(start(1)+4*(mode+1))+start(1)+4 SPB=SP+(S-1)*8 POS=leek(SPB)+SP+32*PLANES set paint 4,1,1 set pattern POS Another way is A$=SCREEN$(physic,1,1 to 16,16) SET PATTERN A$ FLASH index,"(colour,delay)(colour,delay)...." Set any of the 16 colours to flashing. Index is the colour number to be animated. Delay is the number of 50ths of a second which must elapse before the next colour is used. Colour is the standard RGB format. SHIFT delay[,start] This command allows you to produce colour rotation. Delay is the number of 50ths of a second which must elapse before the colour palette is rotated. The optional start allows you to specify which is the first colour in the palette to be rotated, if omitted, the value of 1 will be used. GR WRITING mode This sets up the mode which will be used whn writing graphics text. Four modes are available: 1 : Replace (Overwrite anything) 2 : Transparent (Put only the ink colour on screen) 3 : XOR (Combine with existing graphics) 4 : Inverse Transparent (Plot only colour zero) POLYMARK x1,y1[;x2,y2[;x3,y3......]] Place a polymark on the screen at the specified coordinates. SET MARK t,s Set the current polymark to the required type (t) and size (s). Type can be : 1 : Point (1 size only) 2 : + 3 : * 4 : Square 5 : Diagonal cross 6 : Diamond Size can be any one of eight, ranging in 11 point increments from 6 to 83 pixels wide. MODE n Change screen to mode (n) : 0=low res, 1=med res. =MODE Return the current mode, 0-3 DIVX/DIVY Hold the width and height of the current graphics screen according to the current mode. CLIP x1,y1 TO x2,y2 Define the tope left and bottom right of the clipping rectangle. Any graphics drawn outside this area will not be shown. CLIP OFF Disables the clipping rectangle. The Screen Multiple Screens STOS Basic holds two screens in memory at any one time. The first is called the physical screen, and is the screen which is actually displayed. There is also a separate background screen which is used by the sprite commands. BACK is a variable which holds the address of the background screen. PHYSIC Is a variable which holds the address of the physical screen currently being displayed.. If you load a different address into this variable, the screen will be immediately redrawn using the screen stored at this address. The value assigned can either be an address, or the number of the memory bank in which the screen is stored. LOGIC This is the screen which text and graphic commands operate on. Normally, this and PHYSIC hold the same address so that you can see what is being drawn to the screen. However, it is sometimes useful to have the pictures drawn on a separate screen and then displayed. This can be done by setting LOGIC to the address of an area or memory bank onto which the image can be created, and then, when it is finished, display it with PHYSIC=LOGIC. SCREEN SWAP This swaps the addresses held in the variables PHYSIC and LOGIC. This enables you to instantly switch from one screen to another. DEFAULT Returns the initial value of one of the three screens. DEFAULT BACK Returns initial value of BACK DEFAULT PHYSIC Returns initial value of PHYSIC DEFAULT LOGIC Returns initial value of LOGIC When you are using multiple screens, it is easy to lose track of the original screen addresses. This function is often used to restore these values. PHYSIC=DEFAULT PHYSIC BACK=DEFAULT BACK LOGIC=DEFAULT LOGIC Reserving a screen STOS can have any number of screens held in memory at any one time. The following instructions allow you to allocate a memory bank to hold one of these screens. RESERVE AS SCREEN n Reserves the bank number n as a temporary screen 32768 bytes long. RESERVE AS DATASCREEN n Reserves the bank number n as a permanent screen 32768 bytes long. This will be saved along with your program. Loading a screen STOS lets you load a screen directly into an address or a memory bank from either a DEGAS or NEO format. LOAD filename$,scrn Where filename$ is the name of the file on disk, complete with ".NEO",".PI1",".PI2",".PI3" extension. scrn can either be a memory bank or an address. GET PALETTE(n) Load the colour settings of the screen stored at bank n into the colour palette. CLS scr[,col[,x1,y1 TO x2,y2]] Clear the screen. The optional parameters allow you to specify the colour that the screen, or portion of the screen, is to be filled with. ZOOM scr1,x1,y1,x2,y2 TO [scr2,]x3,y3,x4,y4 Magnifies any rectangular section of the screen stored at scr1. scr1 and scr2 can be either an address or a memory bank. The coordinates specify the top left and bottom right coordinates of the area to be magnified from and to. REDUCE scr1 TO [scr2,]x1,y1,x2,y2 Compresses the entire screen stored at scr1 to a rectangle x1,y1,x2,y2 either in the background screen, or the screen stored at scr2. Note that scr1 and scr2 can be either memory banks or addresses. SCREEN COPY scr1[,x1,y1,x2,y2] TO scr2[,x3,y3] This command allows you to copy either entire screens from scr1 to scr2, or portions of the screen, as specified by the coordinates. Note, however, that the x coordinate is always rounded down to the nearest multiple of 16. These coordinates can also be negative in the ranges shown below. Areas off the screen will simply not be copied. Graphics mode X Range Y Range Low -320 to 320 -200 to 200 Medium -640 to 640 -200 to 200 High -640 to 640 -400 to 400 =SCREEN$(scrn,x1,y1 TO x2,y2) Load an area of the screen into a string. SCREEN$(scrn,x,y)= Load a screen held in a string to the screen. Scrolling the screen DEF SCROLL n,x1,y1 TO x2,y2,dx,dy This command allows you to define up to 16 zones for scrolling. n denotes the number of the zone from 1-16. x1,y1,x2,y2 denote the upper left and lower right coordinates of the zone. dx,dy hold the number of points that the zone is to be scrolled, either up, down, left or right. SCROLL n Scroll zone number n in the direction specified. Screen synchronisation The screen is updated by the hardware every 50th of a second.. Once the screen has been drawn, the electron beam turns off while it returns to the top of the screen again. This is called a vertical blank, or VBL for short. When this takes place, STOS performs a number of tasks, such as moving the sprites, playing music, shifting the colour palette, etc. Since a 50th of a second is a long time for STOS basic, this can lead to a serious lack of coordination between your program and the screen. This is where these commands come in. WAIT VBL Waits for the next vertical blank to occur. This is generally used after PUT SPRITE or SCREEN SWAP, as this is when these commands are executed. SYNCHRO Synchronise scrolling with sprites. STOS performs all sprite movements every VBL. This generally works fine, but occasionally it leads to an irritating synchronisation problem. Supposing you want to place a sprite a a fixed point on a scrolling background. Whenever the background moves, the sprite will move along with it. It should be easy enough to produce a set of MOVE X and MOVE Y commands which precisely follow the movement of the background. Unfortunately, this wouldn't quite work as the SCROLL instruction would not be executing at the same time as the sprite commands. The sprites would therefore tend to drift jerkily around the screen. STOS, however, supplies you with a command that will allow you to move all the sprites on the screen at the exact time that you want them to: SYNCHRO ON Turn off the normal sprite interrupt which moves the sprites every 50th of a second. SYNCHRO Execute all the sprite movement commands once. SYNCHRO ON Reverts the sprite movements to normal. The sprites will now be moved automatically every 50th of a second. Compacting the screen STOS comes with a handy accessory which allows you to compact part or all of the screen, "COMPACT.ACB". The following commands are also supplied: UNPACK bnk,scr Unpacks a screen stored in bank number bnk to the address or bank number scrn. PACK scr,bnk Pack the screen stored at address or bank scr into memory bank bnk. Special screen effects APPEAR x[,y] This command allows you to produce fancy fades between a picture stored in x to the current screen. The parameter y can specify which of the 79 fades you wish to use. Fades 1-72 always result in a complete image being copied, whilst fades 73- 79 leave the final screen slightly different from the one stored at x. FADE speed This command allows you to fade the colours between two screens. FADE speed Fades all the colours on the screen to black in the specified 50ths of a second. FADE speed TO bank Fades the present colours to those specified in the screen stored in bank FADE speed,c1,c2,.. Fade seperate colours to a new value. The first two should speak for themselves, the last one isn't quite so obvious. Speed is the number of VBL's which are to occur between each colour change. The list which follows is the new colours you require for colour1, colour2, colour3, etc. Any colours you don't wish to change are left blank. e.g. FADE 5,$777,$777,,$777,,$777 Will, using speed 5, fade the current pens 0,1,3 and 5 to white ($777). Colours 2 and 4 are left unchanged, as are colours 6-15. Text and Windows STOS basic allows you to print text on the screen in a number of ways. It also allows up to 13 windows each with it's own unique character set. PEN index This allows you to specify which of the pens (0-15 in low res, etc.) all subsequent text operations are to be performed in. PAPER index This, like PEN designates all future background colour. INVERSE ON/OFF This mode switches the text and background colours selected by PEN and PAPER. SHADE ON/OFF This fades out all subsequent text. UNDER ON/OFF This switches the underline mode on or off. WRITING effect This allows you to specify the writing mode of all subsequent text operations: 1 Replacement mode (default). 2 OR with existing screen. 3 XOR with existing screen. LOCATE x,y Locates the cursor at coordinates x,y. =XTEXT(x) Converts the x coordinate from graphic format to text relative to the current window. =YTEXT(y) Converts the y coordinate from graphic format to text relative to the current window. =XGRAPHIC(x) Converts the x coordinate from text format to an absolute screen coordinate. =YGRAPHIC(y) Converts the y coordinate from text format to an absolute screen coordinate. SQUARE wx,hy,b Draws a rectangle on the screen at the current cursor position specifying the width and height (minimum of 3) in character positions with any one of 15 different border types (see BORDER). HOME Sends the cursor to the top left hand corner of the current window. CDOWN Moves the cursor one space in the requested CUP direction. CLEFT CRIGHT XCURS Variables holding the current text coordinates of YCURS the cursor. SET CURS t,b Set the text cursor size specifying the top and bottom of the cursor (1-8). CURS ON/OFF Enable/disable the text cursor. CENTRE a$ Print a line of text centred on the screen. TAB(n) Used with the print instruction to move the cursor forward n spaces. Unlike the usual basic command, this produces a string of cursor rights, and can be assigned to a string if required. X$=TAB(7) =SCRN(x,y) Returns the ascii code of the character found at the text coordinates relative to the current window. Windows WINDOPEN n,x,y,w,h[,b[,s]] Create a window number n (1-13) at x,y (text coordinates of the top left corner of the window), width w and height h. The options allow you to specify one of 15 borders (see BORDER) and one of several character sets. There are 16 character sets available: 1 : 8x8 (Default for low resolution) 2 : 8x8 (Default for medium resolution) 3 : 8x16 (Default for high resolution) Sets 4-16 are your own character sets. TITLE a$ Define a title for the current window, centering it. This will remain until the BORDER command is issued with no parameter. BORDER [n] This allows you to choose one of 16 possible borders for the current window. The variable n can range from 1-16, and the borders are made up from characters 192-255 in the current character set. These may be changed if necessary. Note that if you use boder on it's own, the current border will be redrawn and the title of the window erased. WINDOW n Set the window n to the top, make it the current window and redraw it's contents. Note that if the window is already fully visible, it's quicker to use the QWINDOW command. QWINDOW n Activate window n without redrawing it. WINDON Returns the number of the currently active window. WINDMOVE x,y Move the current window to new x,y coordinates. WINDEL n Delete window n. CLW Clear the current window. SCROLL ON/OFF Switch window scrolling off. SCROLL UP/DOWN Scroll all the text in a current window up or down one line. Character Sets RESERVE AS SET n,l This reserves a bank n in memory as character set storage l bytes long. This bank is permanent and will be stored along with your program. CHARLEN(n) This returns the length of a character set specified by the number n. CHARCOPY s TO b This copies the character set s (1-16) to bank number b. ICON$(n) Generate an icon at the current cursor position. This will effectively draw icon number n from the bank defined. It may also be used in menu bars. Menu Commands STOS provides you with a number of clever facilities for creating and using menus. Although different from their GEM equivalents, they are considerably more powerful. Creating a menu MENU$(x)=title$[,paper,pen] This allows you to specify the main titles that will appear on the top line. Title$ holds the title of your menu, and you are also given the option to specify the paper and pen colours if you wish. You can define up to 10 titles this way (1- 10). MENU$(x,y)=option$[,paper,pen] This allows you to specify the options that will appear in each drop down menu. x is the menu (as specified by the MENU$(x) command, and y is the option number within the menu. Again, paper and pen options are available to you. e.g 10 menu$(1)="ACTION" 20 menu$(2)="MOUSE" 30 menu$(1,1)="QUIT" 40 menu$(2,1)="ARROW" 50 menu$(2,2)="HAND" 60 menu$(2,3)="CLOCK" MENU ON [b][,m] Activates the menu with any one of 16 borders (see BORDER). The mode is either 1 for the standard drop down menus, or 2 for pull down menus. 70 MENU ON 5,2 Generates a pull down menu with border 5. MENU OFF Permanently switches the menu bar off and erases it from memory. MENU FREEZE Temporarily freezes the menu bar and can be restarted with the MENU ON command. MENU$(x,y) OFF Disables one of the menu items. MENU$(x,y) ON Re-enables a menu item disabled with the above. MNBAR These variables hold the menu title and the menu MNSELECT options you have chosen. ON MENU This provides you with an interrupt driven method of selecting the menu bar. This will allow you to run a program as normal, but when an option is selected, it will jump to one of a list of line numbers in the same way an ON GOTO would, using the title number returned. ON MENU ON Sets the entire process in operation by activating the ON MENU command. ON MENU OFF Turns the menu off. Icons can also be included into menu bars as well. menu$(2,1)=icon$(3) menu$(2,2)=icon$(4) menu$(2,3)=icon$(5),2,4 Other Commands Control Structures GOTO line number/expression NOTE: STOS doesn't use labels for lines, equations and variables may be used, but they will not renumber. GOSUB line number/expression RETURN POP Trash the return address generated by a GOSUB statement. FOR..TO..STEP NEXT Note that multiple NEXT statements cannot be combined. WHILE...WEND REPEAT...UNTIL STOP END IF..THEN..ELSE Note that this is one line ONLY. ON...GOTO ON...GOSUB ON ERROR GOTO line This allows you to trap errors within the program by ordering the computer to jump to a specific line if one occurs. RESUME Jump back to the command that caused the error and retry. RESUME NEXT Jump to the command following the one generating the error. RESUME line Jump to a specific line. ERN and ERL Variables holding the error number and line number. ERROR n Generate an error and exits back to STOS. BREAK ON/OFF Disables or enables the Control+C checks. KEY(x)=a$ Assign a string to one of the 20 function keys (1- 20). Note that the ' character is interpreted as CHR$(13). INKEY$ Return a key press, but don't wait. SCANCODE Holds the scancode of the last key pressed. CLEAR KEY Clear out the keyboard buffer. INPUT$(n) A function which reads n characters from the keyboard and echos them to the screen before returning. FKEY Is a special form of INKEY$ which will return a value between 0 and 20 to indicate which of the function keys has been pressed. WAIT KEY Waits for a keypress. KEY SPEED r,s Sets the repeat speed (r) in delays of 50th of a second and the delay between the initial keypress and the start of the repeat sequence (d) in 50ths of a second. PUT KEY a$ Writes a string to the keyboard which will be 'typed' when the computer next has chance. Note that the ' character works the same way as pressing the return key. INPUT [prompt;]variable list LINE INPUT [prompt;]variable list PRINT and ? PRINT USING format$;variable list The format can consist of any characters with the exception of ~#+-.;^ Their meanings are as follows: ~ Insert a character from the following string. # Insert a digit from the following number. + Add a plus + or - sign to the number. - Add only a - sign to the number. . Align with decimal point. ; Align with decimal point, but don't print it. ^ Print number in exponential form. Disk Access OPEN IN #channel,filename$ OPEN OUT #channel,filename$[,attribute] Open files for input or output only. Channel can be from 1-10 and it is this channel that all data will be sent to. Filename$ is the disk filename holding the data, if output, then the existing file on the disk will be erased. The optional attribute allows you to specify the type of file to be created (see DIR FIRST$). OPEN #channel,"R",file$ Opens a random access file. OPEN #channel,"MIDI" Opens a channel to the MIDI interface. OPEN #channel,"AUX" Opens a channel to the RS232 port. OPEN #channel,"PRT" Opens a channel to the printer plugged in the parallel port. CLOSE#channel Closes a file and writes any buffered data. PRINT#channel,list Prints a list of data, like the normal print function, to the specified channel. INPUT#channel,list Like input, but allows you to read information from a channel. LINE INPUT#channel[,seperator$],list This acts like INPUT, reading data from a channel, seperated by a <Return> rather that a comma. The optional seperator$ is included if something other that a <Return> seperates the data. INPUT$(#channel,count) Inputs count characters from the file. EOF#channel A variable used to test for the end of a file. LOF#channel Return the length of a file. POF#channel The variable holding the current position of the pointer within a file. This may be altered to move the pointer. FIELD#channel,length1 AS field1$,length2 AS field2$.... Field allows you to define a record which will be used for random access files. This record can consist of up to 16 alphanumeric fields and can be up to 65535 bytes long. PUT#channel,r Writes the record created by FIELD into record position r in the file. GET#channel,r Reads the record r from the specified channel into the field set up by the FIELD command. PORT#channel Test to see if an input device is waiting for information. The Printer LLIST As List, allows you to send your listings to the printer. LDIR List the directory on the printer. LLISTBANK List the memory bank information on the printer. LPRINT Print all thet follows to the printer (see PRINT) HARDCOPY Dump the screen as would Alternate+Help. WINDCOPY Unlike hardcopy, this command prints out the text in the current window. Directories DIR [path$][/W] Lists the current directory. DIR$= Sets the current directory. =DIR FIRST$(path$,flag) This returns the first file that satisfies the pathname. The flag is a number of binary bits which indicates which types of file are to be sought. Bit 0 : Normal Read/Write files Bit 1 : Read only iles Bit 2 : Hidden files Bit 3 : Hidden system files Bit 4 : Volume labels Bit 5 : Folders Bit 6 : Files which have been written to and closed. If you aren't sure which type you want, use -1. If no file exists, then a null string is returned, elsewise a 42 character string is returned with the following format. Characters Usage 1-12 Filename 13-21 Length of file 22-32 Date file saved 33-41 Time file saved 42 File type DIR NEXT$ Returns the next file found as per the setup in DIR FIRST$ PREVIOUS Drops back one level in the subdirectories. =DRIVE= Variable holding the drive number (0-...) =DRIVE$= Varianle holding the drive letter (A-...) DRVMAP Variable holding a list of the drives connected in binary. DFREE Holds the amount of free space left on a disk. MKDIR folder$ Creates a folder RMDIR folder$ Removes an empty folder from the disk KILL file$ Erase a file, or series of files from the disk. RENAME old$ TO new$ Renames a file. Trigonometric functions DEG(x) Convert an angle expressed in radians to degrees RAD(x) Convert an angle expressed in radians to degrees SIN(x) COS(x) TAN(x) Sine, Cosine and Tan ASIN(x) ACOS(x) ATAN(x) Arc Sine, Cosing and Tan HSIN(x) HCOS(x) HTAN(x) Hyperbolic Sine, Cosine and Tan PI Ã£ LOG(y#) Log base 10 of y# LN(y#) Natural Log of y# EXP(y#) Exponential of y# SQR(y) Square Root ABS(y) Absolute value INT(y) Integer Rounded down SGN(y) Find the sign of y MAX(x,y) Return largest value MIN(x,y) Return smallest value SWAP x,y Swap variables x and y (also strings) DEF FN name[(variable list)]=expression Define a function FN name[(variable list)] Call a user defined function. RND(y) Return a random number from 0-y inclusive LET Yes, this is still to be found! FIX(n) Set the precision of any real numbers that are to be printed out on the screen. If 0<n<16 then n denotes the number of figures after the decimal point. If n>16 the printout will be proportional and any trailing zeros will be removed. If n<0 then all floating point numbers will be expressed in exponential format. =UPPER$(n$) Convert n$ to upper case. =LOWER$(n$) Convert n$ to lower case =FLIP$(n$) Reverse the order of the letters in n$ =SPACE$(n) Creates a string full of spaces. =STRING$(a$,n) Create a string full of a$ =CHR$(n) Return ASCII character. =ASC(n) Return ASCII code. =LEN(n$) Return length of n$. =VAL(n$) Convert n$ to a number. =STR$(n) Convert n to a string. =TIME$= A variable holding the time in hours:minutes:seconds =DATE$= A variable holding the date in the format DD/MM/YYYY =FILE SELECT$(path$[,title$[,border]]) Request for a filename using the file selector. =HEX$(n,l) Convert n to a hexadecimal number. The optional l requests for it to be padded out. =BIN$(n,l) Converts n into a binary number. ROL[.B/.W/.L] x,y Rotate y left by x places. The optional .B, .W and .L tell the instruction to treat is as a byte, word or longword. ROR[.B/.W/.L] x,y Rotate Right =BTST(x,y) Test bit x of number y BSET x,y Set bit x of number y BCHG x,y Change the status of bit x in number y BCLR x,y Clear bit x of number y PEEK POKE DEEK DOKE LEEK LOKE Read or change the contents of memory locations. VARPTR(variable) Returns the address of the variable stored in memory. COPY start,finish TO destination Copy a block of memory. FILL start TO finish,longword Fill an area of memory. =HUNT(start TO finish,A$) Hunt through memory for a string. WAIT x Wait for x 50ths of a second. =TIMER= Timer counted in 50ths of a second. =NOT(x) Logical NOT operation. REM remark DATA variable list Numbers, strings, variables and formulae can be included. READ variable list RESTORE [line] TRUE Variable holding -1 FALSE Variable holding 0 Appendix A Error Messages Error Code Error name 0 Not Done A procedure has been attempted, but due to some condition, it has not been carried out. 1 Bad File Format A file to be loaded cannot be recognised by STOS as it is not of the correct format. 2 Out Of Memory STOS has no more memory left for allocation. Take out all the accessories and excess programs to free more memory. 3 This Line Does Not Exist This error occurs when you have tried to delete a line which does not exist so the delete operation is aborted. 4 This Line Already Exists The Auto function reports this error when it comes across a line which is already in your program. 5 Search Failed A string has been searched for in the current program, but it does not exist. 6 Line Too Long You have attempted to enter a line more than 700 characters long. 7 Can't Continue STOS can't continue from the previous break. 8 See Error 6. 9 Follow Too Long STOS has been told to trace too many parameters. 10 Printer Not Ready The printer is not on line. 11 Can't Renum STOS has attempted to renumber a section of your program and this action would result in a conflict of line numbers. 12 Syntax Error The syntax of the error line or statement is not correct. 13 Illegal Function Call You have tried to use a function with an illegal set of parameter. 14 Illegal Direct Mode A command input in direct mode is not recognised by STOS. 15 Direct Command Used A command which is only available in direct mode has been used in the program. 16 In/Out Error An error has occurred during an input/output operation 17 Break You have pressed Control+C. 18 Non Declared Array An array has been referenced which has not been set up with the DIM statement. 19 Type Mismatch An illegal value has been assigned to a variable. 20 Function not implemented A function entered in STOS is not recognised. 21 Overflow Error A calculation has exceeded the size of a variable. 22 For Without Next A FOR command does not have it's mandatory next listed later in the program. 23 Next Without For STOS has come across a NEXT instruction which has no FOR. 24 While Without Wend The WHILE instruction has no mandatory WEND after it. 25 Wend Without While A WEND instruction has been encountered that has no matching WHILE. 26 Repeat Without Until A REPEAT instruction exists but has no corresponding UNTIL. 27 Until Without Repeat The UNTIL instruction has no preceding REPEAT command. 28 Array Already Dimensioned An array has been re-dimensioned at the error line. 29 Undefined Line Number A GOTO, GOSUB or RESTORE has been encountered which indexes a non-existent line. 30 String Too Long A string has exceeded the limit of 65000 characters. 31 Bus Error An internal error has occurred possibly due to incorrect addressing using the PEEK and POKE commands. 32 Address Error An odd memory address or invalid address has been accessed using the PEEK and POKE commands. 33 No Data On This Line The RESTORE instruction has tried to restore a line of data. In this case, the line did not contain a DATA command. 34 No More Data The READ command cannot get any more data because it has all been read. 35 Too Many Gosubs STOS cannot store any more RETURN addresses. 36 Return Without Gosub The program has reached a RETURN but no GOSUB has been used. 37 Pop Without Gosub The POP instruction cannot be executed outside a subroutine. 38 Resume Without Error A RESUME instruction cannot be executed unless an error has occurred. 39 User function Not Defined A user function has been accessed that has not been set up with DEF FN. 40 Illegal User-Function Call The list of parameters you inpt does not match the list you specified in the DEF FN. 41 Memory Bank Already Reserved An attempt to reserve a memory bank has failed because it is already reserved. 42 Memory Bank Not Defined As Screen A command has accessed a memory bank which must be reserved as screen and thus cannot find the information required. 43 Bad Screen Address A screen address has been used which is invalid for a proper screen start address. The address must be on a 256 byte boundary. 44 Memory Bank Not Reserved A memory bank has been accessed and has not been reserved for use. 45 Resolution Not Allowed MODE cannot be used in high-resolution monitors. 46 Division By Zero 47 Illegal Negative Operand Some functions cannot process negative numbers. 48 File Not Found You have tried to open or load a file not on the current disk. 49 Drive Not Ready A disc drive is not ready for use. 50 Disc Is Write Protected 51 Disc Full 52 Disc Error 53 Bad Filename A filename has been used in an input/output procedure which is not legal. 54 Bad Time The user has attempted to set an illegal time using TIME$. 55 Bad Date The user has attempted to set up an illegal date using DATE$. 56 Sprite Error Parameters for a SPRITE command have been set which do not fall inside the legal limits. 57 Movement Declaration Error The MOVE instruction has not been set properly. 58 Animation Declaration Error The ANIM string command has not been properly set. 59 File Not Open 60 File Type Mismatch A file command has been used which does not correspond to the correct filing system. 61 Input String Too Long An incoming string is too long for a dimensioned variable. Or you may have tried to INPUT# a string more than 500 characters long. 62 File Already Open 63 File Already Closed 64 End Of File 65 See Error 61. 66 Field Too Long The size of the record you have created with FIELD is greater than 65535 bytes. It's also possible that you have used more than the maximum 16 fields. 67 Flash Declaration Error The FLASH command has been incorrectly called. 68 Window Parameter Out Of Range 69 Window Already Open 70 Window Not Opened 71 Window Too Small An attempt has been made to open a window smaller than 3x3. 72 Window Too Large 73 Character Set Not Defined 74 No More Text Buffer Space If you open over 10 windows the size of a fill screen in either mode 1 or mode 2 then the space reserved for the data in each window gets used up and causes this error. 75 Music Not Defined 76 System Window Called The system windows have been used in one of the commands. These are 0, 14 and 15. 77 System Character Set Called You have attempted to replace a system character set with a custom designed one. 78 Character Set Not Found 79 Menu Not Defined 80 Bank 15 Already Reserved This bank is already reserved and must be erased if you wish to reserve it for another purpose. 81 Bank 15 Is Reserved For Menus Menus are used in the current program and thus you cannot use this bank for anything else. 82 Illegal Instruction When STOS is running a machine code program this error will occur if it finds that the code is invalid. 83 Drive Not Connected 84 Extension Not Present This occurs when you try to run a program which incorporates new STOS Basic commands without loading the relevant extension file first. 85 Subscript Out Of Range 86 Scrolling Not Defined The SCROLL command has been used but STOS doesn't have the information necessary to scroll the screen. 87 String Is Not A Screen Block A string has been used in SCREEN$ which has not been designed as a sprite block string. Appendix B Using Assembly Language CALL address or bank CALL allows you to execute any assembly language program held in the ST's memory. address can be either the absolute location of the code, or the number of the memory bank that the code is held in. Calling a machine code program 1 Reserve some memory for your routine using the RESERVE AS DATA, e.g. RESERVE AS DATA 7,10000 2 Load the program, e.g. LOAD "file.prg",7 NOTE that the code must be in TOS relocatable format and must NOT summon any of the GEM routines. 3 Pass any input parameters using the pseudo variables DGRE(0) to DREG(7) and AREG(0) to AREG(6) 4 Call your program, e.g. CALL 7 Your assembly language program may subsequently change any 68000 registers it likes with the sole exception of A7, and it must always be terminated with a RTS. It must never call GEMDOS traps SET BLOCK, MALLOC, MFREE, KEEP PROCESS or any other memory management functions. TRAP n[,parameters] TRAP allows you to call one of the numerous 68000 TRAP functions. These traps are really just large libraries of assembly language functions. n refers to the number of the TRAP; 0,1,13,14 are the GEMDOS functions 3,4,5,6,7 are the STOS functions. The optional parameters specify the data which is to be placed on the 68000's stack before the TRAP function is executed. As a default these are assumed to be of size WORD. You can set the size directly from the TRAP instruction by using a statement such as: W.expression L.expression One useful bonus is that you can also include a string variable in the expression, such as A$. In this case, the address of the string is placed on the stack and a CHR$(0) is automatically added to the end of the variable to convert it into the correct format. Appendix F Structures of the Banks Structure of the Sprite Bank Offset Meaning 0 Sprite Bank ID code ($19861987) 4 4-byte offset to address of sprite parameter block in low resolution 8 4-byte offset to address of sprite parameter block in medium resolution 12 4-byte offset to address of sprite parameter block in high resolution 16 Number of sprites in low resolution 18 Number of sprites in medium resolution 20 Number of sprites in high resolution Typical Sprite Parameter Block Offset Meaning 22 4-byte offset to sprite data 26 Width of sprite (in units of 16) 27 Height of sprite 28 X coordinate of hotspot 29 Y coordinate of hotspot 30 Start of next sprite parameter block.... Sprite Data Structure The Sprite Data Block Data for Mask (one bit plane) Sprite Data (organised in bit planes) Structure of the Icon Bank Offset Meaning 0 Icon Bank ID code ($28091960) 4 Number of icons in bank 6 Start of data for icon 1. This is 84 bytes long, and uses the same format as the LINE-A sprites. 92 Start of data for icon 2.... Structure of the Music Bank Offset Meaning 0 Music Bank ID code ($13490157) 4 Offset from start of the bank to music number 1. Set to zero if no music with this number. 8 Offset to music number 2.... 124 Offset to music number 32 (Maximum of 32 pieces of music) 128 Length of this memory bank 132 Name of music 1 (8 letters) 140 Name of music 2 (8 letters)..... 380 Name of music 32 (8 letters) 388 Start of music 1... Inside the music definitions Offset Meaning 0 ID code that this is music data. ($19631969) 6 Offset to music in voice 1. 8 Offset to music in voice 2. 10 Offset to music in voice 3. 12 Definition of first tremelo/envelope (36 bytes long) 48 Definition of second trememlo/envelope Start of voice 1 The Music Commands Each note is stored as a teo-byte word ranging from 0-32767. The lower half of this word contains the pitch of the note (0-96). See PLAY for more details. The upper byte holds the length of the note in 50ths of a second. The Music commands are held in either two or four bytes. In order to distinguish them from normal notes, the highest bit of these commands is set to 1. Here is a list of the various commands and the numbers used to represent them in the music. Number Size Command Meaning $8000 2 bytes END Signifies the end of music for this voice $A000 2 bytes MUSIC Use pure tones for music. $A100 2 bytes NOISE ONLY Use noise for music. $A200 2 bytes STOP NOISE Turns off noise. $A3xx 2 bytes NOISE xx Plays noise with pitch xx $A400 2 bytes STOP NTREMULO Stop mixing tremulo with noise $A500 2 bytes STOP ENVEL Stop using current envelope $A600 2 bytes STOP TREMOLO Stop using current tremolo $A7xx 2 bytes VOLUME xx Set volume of sound to xx $C000 4 bytes NTREMULO Mix TREMULO with noise. Bytes 2&3 hold offset to tremulo definition $C100 4 bytes ENVEL xx Use ENVEL xx. Bytes 2&3 hold offset to envelope definition $C200 4 bytes TREMULO xx Use TREMULO xx. Bytes 2&3 hold offset to tremulo definition. $C3nn 4 bytes REPEAT nn,note Repeat music starting from note, nn times. Note held in bytes 2&3. Screen Banks The format of the screen banks is very straight forward indeed. The first 32000 bytes of this memory hold the actual screen data, and the next 16 words from numbers 32000 to 32032 contain a copy of the colour settings for this screen. Note that bytes from 32032 onwards are free, and can be used for your own purposes. Appendix G Accessing The Programmable Sound Generator PSG(r) The Atari ST incorporates a special piece of circuitry which it uses to generate a wide range of sounds. Access to this chip is via the PSG register, which may be read from, or written to. WARNING: This function is dangerous! Incorrect usage can cause serious damage to any disc in the disk drive. Here is a brief list of the various sound registers and their uses: Register Function 0 Bits 0-7 set the pitch in units of a single step for voice 1. 1 Bits 0-3 set the size of each frequency step 2 Fine control for voice 2. As register 0 3 Coarse control for voice 2. As register 1 4 Fine control for voice 3. As register 0 5 Coarse control for voice 3. As register 1 6 Bits 0-4 control the pitch of the noise generator. The higher the value, the lower the tone. 7 Control register for sound chip. Bit 0: Play pure note on voice 1 (1=ON, 0=OFF) Bit 1: Voice 2 tone ON/OFF Bit 2: Voice 3 tone ON/OFF Bit 3: Play NOISE on voice 1 ON/OFF Bit 4: Play NOISE on voice 2 ON/OFF Bit 5: Play NOISE on voice 3 ON/OFF 8 Bits 0-3 control volume of voice 1. If bit 4 is set to 1 then the envelope generator is being used, and the volume bits are ignored. Since this corresponds to a volume of 16, this explains why you need to set VOLUME to 16 before you can use the ENVEL command. 9 As register 8 but for voice 2 10 As register 8 but for voice 3 11 Bits 0-8 provide fine control of the length of the envelope 12 This register provides coarse control of the length of the envelope. 13 Bits 0-3 choose which of the 16 possible envelopes is to be used.
Back to STOS BASIC