home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
TCE Demo 2
/
TCE_DEMO_CD2.iso
/
demo_cd_.2
/
mags
/
stosser
/
stoser08.arj
/
stoser08.msa
/
ISSUE_8
/
9.PNE
< prev
Wrap
Text File
|
1987-04-22
|
19KB
|
588 lines
WRITING STOS EXTENSIONS - PART 1 of 3
=====================================
By Martin Cubitt for STOSSER disczine
This small series takes a look at how to write an extension for
STOS. A reasonable knowledge of assembly language is assumed.
Firstly may I emphasise that this is not a definitive set of rules
and I am certainly no expert on the subject. If you want to get the full
details of writing STOS extensions then I suggest you write to Manadarin
or Francois Lionet.
The only documentation I have on the subject are three similar
articles which appeared in the STOS Newsletter issues 8,9 and 10. I have
been unable to obtain the Game Makers Manual which apparently has
further information of the subject.
Don't worry though. I do know enough to get you started! We will be
writing an interpreter extension and then a compiler one. Finally we
will write an installer program, just a simple one, so that we can add a
little professionalism to our extension.
Let's start with a little background on STOS extensions. STOS can
only handle 26 extensions, using the letters A-Z. many of these are
already in use and some have been reserved by Mandarin. Here is a small
list of some extensions already defined by Mandarin:
A - Compactor extension
B - A bug in version 2.3 of STOS prevents
this being valid!
C - Compiler extension
D - Maestro extension
E - Squasher extension
G - reserved
H - reserved
M - Musician extension
Q - reserved
R - reserved
V - VIDI extension
Many third part extension writers have used further extension id's:
F - Double joystick extension
G - Blitter extension
H - Start extension
M - Misty extension
Q - Missing link extension part 1
R - Missing link extension part 2
S - Missing link extension part 3
T - TOME extension
Z - EXTRA extension
As you can see many third part programmers have ignored (or not
known about) the standard laid down by Mandarin and clashed with
existing or reserved id's. If Mandarin decide to use these reserved
extension id's the third part extensions will not work and any BASIC
program will be useless. So, be warned. There are still plenty of
letters left to use, namely I,J,K,L,N,O,P,U,W,X and Y. Plus, some
extensions may become obsolete or used rarely, like the TOME extension.
I doubt a lot of people use it so if you become desperate for a letter
to use I suggest you use one which is being used for a rarely used
extension. Do not, however, be tempted to use the Mandarin-defined
extensions with the exception of F (the extension is pretty much unused
now).
Before we start I must point out that I the source provided was
written in Devpac 3.10 so you will need to convert anything your
assembler does not like. Devpac is easily the most popular assembler so
there should not be too many problems.
Right, back to writing the actual extensions...
Once you have decided your letter we can continue. The example
extension for this article uses letter W. The interpreter version will
be EG.EXW and the compiler will be EG.ECW.
Please not that a command may accept parameters but never returns
any whereas a function does return a value but may also accept them too!
Take the following STOS commands/extensions:
screen copy 5 to physic - command
A=rnd(5) - function
print A - command
B=A/2 - function
Throughout the series I will refer to both commands and functions
just as commands unless this be incorrect!
First thing to do is decide on what commands you want to have in
your extension. For this example I am going to create one new command
and two functions. You should first decide what the command should do
and then decide on the command name. Remember that the command may not
contain any embedded reserved word or command. Therefore you could not
use the command printer status as the reserved command print is present.
Personally I like to load up STOS and type my new command (yes, before I
have written it) and if it appears ALL in upper case it will be okay.
New command:
eg
This will display, on screen, a list of the commands available in
the EG extension with a small description of each. This is extremely
useful as a quick reference guide and can be found in the EXTRA
extension by simply typing extra.
New functions:
=ndrv
This returns the number of drives attached to the system. It ignores
the internal drive as that has to be there anyway. It will include any
RAM discs or hard drives attached.
=range(A,B,C)
This returns a value reflecting A in the range B to C.
If A < B then =B
else If A > C then =C
else =A
So we have decided on the new commands now. At this point I would
decide on an apt name for the extension. I have called this extension EG
as it is an example extension but a more descriptive name may have been
the Pot Pourri extension as it contains various commands.
As I am not the best person to explain things I have decided its
examples all the way. I have loaded the EGINT.S file into this article
and will now break it down further...
Programmers all program using different methods so feel free to use
your own programming techniques and commenting procedure.
I think it is important to start your program with basic
information...
* Source name .......: EGINT.S
* Object name .......: EG.EXW
* Author ............: Martin Cubitt
* Date ..............: 13th Oct 1993
* Description .......: Example STOS Interpreter extension
* Contains 1 new command and 2 new functions:-
*
* (Remember that a function returns a value)
*
*
* eg - this command displays the command
* list of the EG extension. I think
* all new extensions should have a
* similar command as an on-line
* reference to commands available.
*
* A=range(A,B,C) - a function which returns a value
* based on A in the range B to C. If
* A is less than B then A will become
* the value of B. If A is greater than
* C then A will become the value of C.
* If the value of A >=B and <=C then
* it will be unchanged.
*
* A=ndrv - this function returns the number
* drives attached to your system (and
* are available or turned on). If you
* have the internal, one external and
* a RAM disk the value will be 2
* because the internal drive is
* assumed anyway.
Well, that's the intro over with let's get down to the meat of the
program...
When STOS installs the extension it initialises any variables and
sets any flag required by it. STOS call the start of your program which
should be a BRA operation, pointing to your initialisation routine.
* Jump to initialisation routine
bra.s INIT
* Create token list for commands/functions
* Remember commands have even token numbers and functions odd ones
The following byte is, presumably, a sort of marker used by STOS.
* The following byte value of 128 is simply required by STOS
dc.b 128
All commands use even numbered token where functions use the odd
numbered tokens. The first token MUST be 128. This means the commands
can use token number 128 - 254 and functions 129 - 255. The token is
used internally by STOS as a reference to each command for each
extension. Tokens 160 and 184 may not be used but I do not know why. I
have used them with no problems!
When entering your token/command list note the following:
The command names MUST be in lower case.
They can contain most characters including spaces.
All character are significant so 'disc verify on' and 'disc verify
off' will be treated as two completely separate commands as far as STOS
is concerned.
They cannot contain reserved words or commands.
* Ensure your new command/function names are lower case and do not
* contain any embedded reserved words such as 'printer value=...' as
* this contains print and val!
TOKENS:
dc.b "eg",128
dc.b "range",129
dc.b "ndrv",131
Note that token 130 is not used but if I wanted another command it
would go there.
The token list is terminated with a 0.
dc.b 0
The even instruction ensure that the next piece of code is assembles
on an even boundary, nothing to do with STOS but necessary as a lot of
byte declarations are used.
even
The jump table is a simple address look-up table which point to
where each command is in memory.
Although assembled as offsets STOS re-calculates actual address when
your extension is installed. If any tokens were not used in the token
list you must still store a dummy in the jump table for the non-used
tokens. So I must include such a dummy for token 130.
* Create the jump table
* This extension has THREE new commands (or functions) and ONE dummy!
JUMP:
dc.w 4
dc.l EG
dc.l RANGE
dc.l DUMMY
dc.l NDRV
Next up you enter the message to be displayed when your extension is
installed. Try to keep them short (unlike Misty & Missing Link) so that
the previously installed extensions do not scroll up the screen where
they are lost forever! Besides, they take up unnecessary memory.
You actually need two messages. The first is for those who use
English STOS and the second for those who use French STOS.
You may use control character to get inverse image or underline but
it would not be a good idea to clear the screen or something as all
other install messages would vanish then!
* Message to be shown when extension installed in STOS
* First message for ENGLISH
* Second for FRENCH
MESSAGE:
dc.b 10,10,"Example extension for STOSSER Disczine",0
dc.b 10,10,"Extension Example de STOSSER",0
A 0 byte terminates the messages
dc.b 0
even
Next we must define two variables which will be used later by the
extension.
The SYSTEM variable will hold the address of the STOS system
routines.
SYSTEM:
dc.l 0
This will be used to hold the return address from where your command
was called so that STOS can retake control when your command has
finished.
RETURN:
dc.l 0
The initialisation routine is the first this executed by STOS when
your extension is installed. It does two things. Firstly, it moves the
address of the end of the extension into register a0. Secondly it moves
the address of the cold start routine into the register a1. A return
(rts) instruction finishes the routine.
The label EXIT is used to hold the last address of the extension.
INIT:
lea EXIT,a0
lea COLDST,a1
rts
The cold start routine actually performs some internal setting up by
STOS regarding the extension. The routine passes the addresses of the
messages, warm start routine, the token table and the jump table. The
warm start routine is used to reset variables used in the extension when
UNDO is pressed twice.
COLDST:
move.l a0,SYSTEM ; save address of STOS' system table
lea MESSAGE,a0
lea WARM,a1
lea TOKENS,a2
lea JUMP,a3
WARM:
rts
Great, that is the interpreter header finished. Easy, eh? Next up we
need to write the actual commands themselves.
* eg command
EG:
Save the return address so STOS can return to where it was when the
command was called.
move.l (a7)+,RETURN
Check data register d0. This holds the number of parameters which
were passed.
cmpi.w #0,d0 ; expect no parms
bne NOPARMSERR
Save stack, safe not sorry!
movem.l a0-a6,-(a7)
lea EGINFO(pc),a0
move.w #1,d7
trap #3
Restore stack.
movem.l (a7)+,a0-a6
Allow a smooth return back to STOS.
move.l RETURN,a0
jmp (a0)
* Range function
RANGE:
move.l (a7)+,RETURN ;save return address
cmpi.w #3,d0 ; expect 3 parms
bne.s RANGEPARMERROR
get each parameter form stack. d3 will hold the value of the
returned parameter.
bsr.s GETPARM
move.l d3,d0 ; C
bsr.s GETPARM
move.l d3,d1 ; B
bsr.s GETPARM
move.l d3,d2 ; A
movem.l a0-a6,-(a7) ;save stack
cmp.l d1,d2
blt.s TOO_LOW ; A<B so A=B
cmp.l d2,d0
bge.s OKAY ; Leave A as is
move.w d0,d2 ; C<A so A=C
bra.s OKAY
TOO_LOW:
move.w d1,d2
OKAY:
move.l d2,d0
bsr.s SAVEPARM ;return parm/s
movem.l (a7)+,a0-a6 ;restore stack
move.l RETURN,a0 ;end routine
jmp (a0)
* Number of drives function
NDRV:
move.l (a7)+,RETURN ;save return address
cmpi.w #0,d0 ; expect no parms
bne.s NOPARMSERR
movem.l a0-a6,-(a7) ;save stack
moveq.l #0,d0
move.w ($4a6),d0
bsr.s SAVEPARM ;return parm/s
movem.l (a7)+,a0-a6 ;restore stack
move.l RETURN,a0 ;end routine
jmp (a0)
* Routines...
Parameters are passed to your extension from STOS via the stack.
They need to be pulled off in order to store them elsewhere. The
following routine get an integer parameter only.
Data registers d2,d3 and d4 hold information about each parameter
pulled from the stack. They are stored in the following format:
d2=0 - Integer
d3=integer number
d4=0 - not used
d2=$40 - Real (floating point)
d3=Top half of number
d4=Bottom half of number
d2=$80 - String
d3=Address of string
d4=0 - not used
Remember that STOS string are not standard and are not terminated
with a zero, as 68000 strings are. The first word of a STOS string holds
the length of the string and then the string follows this. You will need
to convert or code very carefully if you wish to use strings.
* Get parameter
GETPARM:
move.l (a7)+,a0
movem.l (a7)+,d2-d4
Here we test that D2 is 0, for an integer
tst.b d2
bne.s MISMATCH
jmp (a0)
Parameters returned by a function are simply stores as below using
the rules for those values of incoming parameters.
* Save parms for return
SAVEPARM:
Store actual value in d3
move.l d0,d3
Make d2 0 for integer
move.w #0,d2
Make d4 0 as it is not used
move.w d2,d4
rts
* Errors...
You must do your own error handling in STOS extensions. You may use
the standard STOS error messages or use your own (or of course mix). The
mismatch error is issued if the incorrect parameter is sent.
* Mismatch error
MISMATCH:
Move the STOS error number (back of manual) into d0
moveq.l #19,d0
bra.s STOSERROR
Where parms are sent to a command when they should not be there is
no message so I wrote one...
* No parms expected
NOPARMSERR:
Move the STOS error number reflecting the type of error (this should
be shown when UNDO pressed but hardly ever works! See Maestro errors!).
moveq.l #12,d0
Load the address of your error text
lea NOPARMSERRTEXT(pc),a2
bra.s MYERROR
* Range error parms
RANGEPARMERROR:
moveq.l #12,d0
lea RANGEPARMERRTEXT(pc),a2
bra.s MYERROR
This procedure handles STOS errors
* STOS error messages handled here
STOSERROR:
move.l SYSTEM,a0
move.l $14(a0),a0
jmp (a0)
This procedure handles my own errors
* My own error messages handled here!
MYERROR:
clr.l d1
clr.l d2
clr.l d3
clr.l d4
clr.l d5
clr.l d6
move.l SYSTEM,a0
move.l $18(a0),a0
jmp (a0)
Dummy label for tokens not used
DUMMY:
Data for eg command
EGINFO:
dc.b 10,13,"* EG (Example) extension by M.Cubitt 1993 *"
dc.b 10,13,"eg................: Information"
dc.b 10,13,"=range(A,B,C).....: Make A in range B-C"
dc.b 10,13,"=ndrv.............: No. of drives"
dc.b 10,13,0
even
Error text (English and then French)...
RANGEPARMERRTEXT:
dc.b "Expected three values for function",0
dc.b "3 values expected",0
even
NOPARMSERRTEXT:
dc.b "No parameters expected",0
dc.b "No parameters expected",0
even
End of program marker
dc.l 0
EXIT equ *
And so there is a simple interpreter extension for STOS. Compiler
the source as EG.EXW. Place this in your STOS folder. When you next boot
STOS you should have a new set of commands.
I have written a small program which uses all three commands so you
can see what they do. I think it is a nice touch to provide examples of
ALL new commands so that fellow STOSSERS understand how to use them.
That is all for this part. In the next part I will show you how to
write a compiler extension. It seems that a lot of people out there are
unsure of how to do this.
If you have any questions relating to this series please do not
hesitate to contact me. As I said before, I only aim to get you started.
Until part 2, good bye!