SYS CALLS EXPLAINED

by Lee Calcraft

The so-called SYS call (or its ARM code equivalent the SWI call) is a special call which gives the user direct access to operating system routines. And although many simple Basic programs make no recourse to SYS calls, there are in fact many operations which cannot be performed without their use. The Wimp is a case in point, being accessed almost exclusively via such calls.

The Archimedes has a potential 16777216 such calls in its repertoire, though only a relatively small number are actually defined. Each SYS or SWI call has an identification number, and if you are in Basic, then each may also be referred to by name. For example the two calls:

SYS "OS_WriteC"
and SYS 0
are equivalent. Their effect is to output a single character to the current VDU stream (normally the screen). The character to be output must be supplied as a parameter. To output the letter "A" for example, you would write:
SYS "OS_WriteC",65
since 65 is the ASCII code for "A".

Generally speaking it is always best to supply the SYS name rather than its number, since this makes your code easier to follow. But if you are using the name, it must be entered exactly as it appears, right down to the case of each letter. If you entered the SYS name as "Os_WriteC" you would get the error "No such SWI". You should also be careful with the so-called underscore character used in all SYS names. This is produced by pressing Shift together with the minus key. Note also the vitally important comma separating the SYS name and the parameter. If you miss this out you will get a syntax error signalled.

In practice almost all SYS calls take one or more parameters. OS_Plot takes 3. For example:
SYS "OS_Plot",4,100,200
This call would move the graphics cursor to point 100,200 (4 is the plot code for move absolute). In fact the sequence of parameters supplied to SYS calls represents values which will be placed in sequence into ARM registers R0, R1, R2 etc. when the call is executed. Sometimes you will see that one or more parameters have been omitted from a call by placing the separating commas adjacent to each other. When this happens, the operating system inserts a value of zero in the corresponding ARM register. Thus if we issued the following:
SYS "OS_Plot",4,,200
this would move the graphics cursor to the point 0,200 - the second parameter of the call (the x co-ordinate) being set to zero.

Sometimes when large quantities of information must be passed to a SYS call, a so-called parameter block is used. This happens with most Wimp calls. In such cases, the user builds up a data block in RAM containing the information needed by the SYS call, and then passes the start address of the block as one of the parameters of the call.

SYS calls can also return information. "OS_Mouse" for example, returns the pointer co-ordinates, button state and time of button change. It might be used as follows:
SYS "OS_Mouse" TO x%,y%,button%,time%
Here, as in all cases where no parameters are supplied, the comma after the SYS name may be omitted. After this call, the four variables following the word "TO" will hold the values returned by the call. As with the parameters supplied by the user, the return parameters reflect the contents of ARM registers R0, R1, R2 etc. And again, if a particular register in a sequence is to be ignored, the comma separators can be moved together. Thus:
SYS "OS_Mouse" TO ,,button%
would still return the button state.

Finally, to illustrate how supplied and return parameters are used together, the following OS_Byte call will read CMOS RAM location n%, and store the result in the variable result%:
SYS "OS_Byte" 161,n% TO ,,result%
Note the two commas before the variable result%, indicating that the value returned in this variable should be the contents of ARM register R2 (R0, and R1 being discarded). To test this out, try it with n%=147. The variable result% will return the number of pages of sprite space configured in your machine.

For further details on this topic, see the Programmer's Reference Manual, which documents each equivalent SWI call, giving the contents of all relevant ARM registers before and after execution.