---

The RISC OS Time Machine - Arthur

Originally published in RISC User between December and February 1988

Getting to Know Arthur

Whether you have used a BBC micro before or not, it Is very easy to overlook many of the good features of Arthur, the Archimedes' operating system. Mike Williams explains.

The Arthur Desktop

Arthur, as most Archimedes owners will know, is the name by which the Archimedes' operating system is known. And Arthur has many useful functions, if you know how to use and access them. If you have used a BBC micro previously, you will already be familiar with star commands (so-called because they are all preceded by a star or asterisk when entered from Basic). While most of these are still recognised by Arthur, it is easy to ignore the fact that there are many new commands as well.

The purpose of this short series is to look at some of the new functions provided by Arthur, both for those who have upgraded from BBC micros and for those for whom the Arc is their first Acorn micro.

It is perhaps tempting to think of all star commands as being operating system commands but this is not entirely correct. The name Arthur more precisely refers to the core operating system of the Archimedes which is then extended by a series of modules. These modules cover such features as the Window Manager, the Sound System, Sprites and the Filing System. All of this is resident in ROM, which means that all these functions are available on power-up. In addition, relocatable modules may be loaded from disc to extend the operating system even further, and add additional star commands to the system. Any modules, whether resident or relocatable, may be disabled if required.

In this article we will be looking predominantly at Arthur itself; later articles may deal with the star commands recognised by other resident modules. In addition, there is one star command (FX) which gives access to many different subroutines within the operating system, although these are often better accessed from machine code programs (via corresponding codes called SWI calls), or from Basic (using the keyword SYS to perform the same function). And if that were not enough, the VDU call used in Basic, and indeed many other Basic keywords, also access operating system routines.

We shall confine ourselves to those operating system functions accessed via star commands, and this will include a look at FX calls. So that you know what we are talking about, the basic operating system commands we shall cover are listed below.

Configuring the system

One chore which all Archimedes owners encounter is that of reconfiguring the system. This arises from the need to allocate different amounts of RAM for different circumstances, but also enables a wide variety of characteristics to be customised for when you switch the machine on, or press Ctrl-Break. You must also remember to press Ctrl-Break after reconfiguring the system in order to activate the change of setting (and thus the command cannot normally be used from within a program).

For example, sprites, screen displays, and fonts all require RAM to be allocated to provide sufficient memory space. Memory space is finite, even on an Archimedes, and can be particularly limiting on a 305 (we would suggest all 305 users consider carefully the benefits of upgrading to 1 Mbyte of memory). Even with a 310, and indeed a 440, it is not sensible to allocate the maximum amount of memory for each purpose that you are ever likely to need. For example, animation programs using bank switching in 256 colour modes (see our current series Animating Archie for more information) need as much as 160K or even 320K of screen memory. But most applications require far less. RISC User December 1988

There are two commands which you need for reconfiguring, *STATUS and *CONFIGURE. The former simply displays the current settings of all the parameters which you can change. 'CONFIGURE is the command you need to make any changes. All the information required is given in the User Guide in the chapter entitled Operating System Commands, but some additional advice may be helpful. Some settings use two different words to toggle between two settings (rather than alternative parameters with the same word).

Thus:

    *CONFIG. CAPS

Or

    *CONFIG. NOCAPS

can be used to determine whether a machine powers up with Caps Lock set or not. I find it easy to forget this, and waste time trying out different parameter settings. Note also the abbreviation for *CONFIGURE.

As delivered, the Archimedes always activates the Desktop after power-up or on pressing Ctrl-Break. Many users prefer their machine to activate Basic. This can be achieved by entering:

   *CONFIG. Language 4

You can, of course, set the Archimedes to default to any module, and you can determine the corresponding number with the 'MODULES command.

Several configuration commands allocate memory for a specific purpose, relocatable modules, screen displays, sprite storage and so on. Unfortunately, memory size is specified not in bytes but in so-called pages. Not only that, but page sizes are different for different purposes and on different machines. The situation is summarised in Table 2.

Thus a screen mode needing 80K of memory (such as mode 12) needs a minimum screensize of 10 (that is 10 pages of 8K) on a 305, 310 or 410, but a screensize of only 3 (3 pages of 32K = 96K), but no less than this on a 440. If you know which mode a program is using, then the screensize settings are easy to calculate. For applications such as sprites and fonts such calculations are less easy, and an intelligent guess maybe a better approach, refining this later.

It is not always necessary to reconfigure memory allocations yourself using *CONFIGURE. For example, if you try to load relocatable module when Basic is active (indicated by the '>' prompt), you may encounter the message "No room in RMA" Now you can use *CONFIGURE to allocate more pages of memory to RMAsize and then press Ctrl-Break before trying again. But you may not know how much memory is needed and either allow too little, and then have to repeat the exercise, or allocate too much and waste the remainder.

The solution is to QUIT from Basic to Arthur (the prompt changes to a *. If you then try to load a relocatable module (by prefixing its name with '*' or using the *RMLOAD command), Arthur will automatically allocate the memory needed (though it will not change the status setting).

The reason for this is that loading relocatable module requires memory that might otherwise be used by Basic. Once Basic is active this cannot be changed. But when we are talking directly to Arthur there is no problem of course. This is very useful if you want to create a boot file (using *BUILD) to load in some relocatable modules before chaining a Basic program. Just make the first command in the boot file QUIT (this gets you out of Basic and into Arthur), followed by commands to load the modules, and then 'BASIC before chaining the relevant Basic program. The modules will always load regardless of the RMAsize setting

Manipulating variables

A group of star commands provides for values to be assigned to special operating system variables quite separate from any Basic variables, and for the contents of those OS variables to be displayed. The commands involved (all star commands) are ECHO, SET, SHOW and UNSET. In general, these commands can be entered with user-defined OS variables, or more often, with certain system variables.

First of all, let us see how these commands might be used with simple OS variables. For example:

    *SET WELCOME "Hello World"
    *ECHO <WELCOME>

would assign the text given to the OS variable WELCOME, while the ECHO command would cause that message to be displayed on the screen (note the angle brackets). If we were to write:

    *ECHO WELCOME

then the string "WELCOME" would be displayed, not the string assigned to the OS variable WELCOME. The command *SHOW will not only show the value currently assigned to an OS variable with *SET, but also show the type, here string. Thus:

    *SHOW WELCOME

gives the response:

    WELCOME ; type String, value : Hello World

Arthur also provides for the use of system variables. Some of these are recognised by Arthur, while others may be known to other modules. For example, Sys$Time, Sys$Date and Sys$Year are always active and have the obvious meanings. You could use *SET to change any of these if you so wished, for example:

    *SET Sys$Year 1989

to change the year to 1989 (quotes are unnecessary unless spaces are included in a string).

Another system variable is Cli$Prompt, which determines the prompt used by Arthur (normally '*'). If you want to change it to '=>' for example, then type:

    *SET Cli$Prompt =>

QUIT Basic and you will see the new prompt in action. Incidentally, when you are communicating directly with Arthur, you don't need to include the '*' with any star commands, though no error arises if you do.

One useful application of system variables is with long pathnames when accessing files. Suppose you had set up a disc with a directory called PD containing a directory called Text containing a directory called Letter. Then:

    *SET Letters $.PD.Text.Letter

would enable any document in the directory Letter (say Bank) to be referenced as:

    <Letters>.Bank

Regardless of the current directory, a correct reference would always be made. Another very useful variable is used for setting up aliases. An alias is just an alternative name for something. For example, entering:

    *SET Alias$AID HELP

would establish AID as a valid alternative to the operating system command HELP. Then writing *AID would have the same effect as writing 'HELP. In fact, Arthur uses this facility to set'.' as an alias for the *CAT command used with the ADFS. Thus *. has the same meaning as *CAT.

Aliases can also be set up to use parameters, and some examples exist by default. For example, this feature is used by Arthur when you attempt to access any file by prefixing the file name with a '*'. Arthur uses predefined aliases to match up the file type and substitute the correct command. Thus if you attempted to access a screen display saved as Screen01 by typing simply 'Screen01, Arthur would use a pre-defined alias to match the file type and turn the command into 'SCREENLOAD Screen01 before passing this to the Command Line Interpreter (the code which first interprets all star commands).

The command *SHOW can be used to show the current setting for any alias, e.g.:

    *SHOW Alias$AID

This command can also use wild card characters. Thus:

    *SHOW Alias$*

will list out all current aliases, while:

    *SHOW

will list all current settings.

I have described how the *SET command could be used to set up so-called aliases. An alias is a user-selected name that once initialised will be recognised by the operating system (OS) as equivalent to some predefined string. For example:

    *SET Alias$SCREEN CONFIGURE Screensize 20

would make the command:

    *SCREEN

exactly the same as:

    *CONFIGURE Screensize 20

You could establish a number of aliases with names such as SCREEN20, SCREEN40 etc to provide short star commands for selecting various memory allocations for screen displays. However, we can still use a single alias command to set more than one screensize by using a parameter. Such an alias command could be set up using:

    *SET Alias$SCREEN CONFIGURE Screensize %0

The %0 indicates a parameter whose value will be supplied when the alias is called.

    *SCREEN 20

would set a screen memory size of 20 pages, while:

    *SCREEN 40

would reserve 40 pages for this purpose. The obvious disadvantage of all this is that the Ctrl- Break needed to enable the new configuration will also destroy your current aliases!

Simple aliases like this can be quite useful, is they are quicker and easier to type in than the original command, and maybe easier to remember. Indeed, we can take the use of parameters and aliases much further, but one more example will suffice here. Up to 10 separate parameters may be defined, and these are represented as %0 to %9. Each parameter can appear more than once if necessary. In addition, a single alias may be used as a substitute for more than one command.

Suppose we want to create an alias called INIT which will allow us to set both screensize and spritesize. This is simply achieved by writing:

    *SET Alias$INIT CONFIGURE Screensize %0|MCONFIGURE Spritesize %1

If we subsequently type:

    *INIT 20 10

this would configure screensize to 20 and spritesize to 10, equivalent to entering the two separate commands:

    *CONFIGURE Screensize 20
    *CONFIGURE Spritesize 10

When an alias, as INIT in this example, is called, the first parameter is assigned to %0, the second (separated by a space) to %1 and so on. Notice also the '|M' which represents Ctrl-M or Return in the alias definition, just as it does in function key definitions.

One final point on alias parameters is worth mentioning. If a command is to take several parameters, then rather than specifying them all individually with %0, %1 etc., the notation %*0 will grab all the parameters supplied.

Any suitable string assigned to an alias may include further commands. Thus:

    *SET AliasSPAGE ECHO i<14>
    *SET Alias$SCROLL ECHO |<15>

would allow *PAGE to set paged mode (Ctrl-N or ASCII 14) and 'SCROLL to set scroll mode (Ctrl-0 or ASCII 15). ECHO used in an alias definition can be very powerful.

One further command to note here is *UNSET. This may be used to delete any operating system variable (except any permanent system variables), set up with the *SET command. It also accepts wildcard characters, so:

    *UNSET Alias$*

will delete all current aliases.

Other *SET commands

There are two further star commands similar to the basic *SET. The command *SETMACRO can be used to assign an expression to an OS variable which is evaluated each time the variable is referenced. One example might be:

    *SETMACRO CLI$PROMPT <SYS$TIME>

which sets the OS prompt to be the current time (the time when the prompt occurs). The command:

    *SET CLI$PROMPT <SYS$TIME>

on the other hand, would set the prompt to be the time when the *SET command was executed (i.e. fixed).

The other command, *SETEVAL is used to assign a value to an OS variable, by evaluating an expression, instead of a string as with *SET. The use of SETEVAL in this way is similar to the use of the EVAL function in Basic. Thus:

    *SETEVAL fred 0

would initialise the OS variable fred to 0, and subsequently:

    *SETEVAL fred fred+1

would increment the value of fred. Typing or executing:

    *SHOW fred

would display the current value of fred. Do remember that the OS variables we are talking about are quite separate from those used in Basic, even though they may appear very similar. These variables are used when communicating directly with Arthur (which gives the "*" prompt).

Basic equivalent commands

A number of operating system commands have equivalents in Basic. Whichever form is used, it is the same in-built routine in the operating system which is being accessed, but it does mean that these functions are accessible whether we are in Basic or Arthur. Thus *EVAL used with OS variables performs a similar task to that which the EVAL function does with Basic variables; it evaluates a given expression.

Then there is *ERROR. This command can be used to create error numbers and corresponding messages of your own choosing (just like ERROR in Basic). These can be used in your Basic programs, and will be dealt with by any normal error-handling routine just as with other errors.

For example, suppose you were to write, in a Basic program:

    IF x<0 and x>100 THEN *ERROR 101 Value out of range

If this was executed with the value of x either less than zero or greater than 100, then an error would be generated as defined by *ERROR. In an error-handling routine, the variable ERR would give the value 101, and REPORT (or REPORT$) would give the text message "Value out of range".

The *IF command provides an IF-THEN or IF-THEN-ELSE syntax, again with the same implications as in Basic. For example:

    *IF Sys$Time<"12" THEM ECHO Good Morning ELSE ECHO Good Afternoon

will display an appropriate message depending on the time of day (note the quotes round the '12' because Sys$Time is a string variable (see earlier).

Using commands like this enables complete programs to be written which will be directly executed by Arthur, not by Basic. Again this is all good material for an EXEC file.

Finally, in this section, *TIME may seem as though it will be the same as Basic's TIME, but is in fact more like the Basic pseudo-variable TIME$. It reproduces the current date and time in a standard format. In Basic, TIMES is a string which can be printed or otherwise manipulated, while *TIME displays the complete date and time on the screen.

BBC micro commands

Some of the commands recognised by Arthur are simply there to provide compatibility with earlier BBC micros, though that is not to say that they do not provide a useful function on the Archimedes. *KEY can be used to program the function keys, and also the Print, Copy and the four cursor keys. The use of *KEY is covered adequately in the User Guide but remember the use of codes like |M or |N represent control codes like Return or Ctrl-N.

The 'SHADOW command is mainly for= compatibility with the Master 128 and Compact. If no parameter (or a value of 2) is provided bank 2 of screen memory will be used. If the command is followed by a '1' then memory bank 1 will be used (see our recent series on Animating Archie for more information bank switching).

Lastly, *TV can be used to adjust the vertical position of the display on your monitor, and to control the selection of interlace, as described in the User Guide.

Miscellaneous commands

There are four commands which I want to deal with here. The *IGNORE command can be used to set the 'printer ignore' character. For most printers this is set to zero (the null character). If your printer executes a double line feed at the end of each line, try setting the printer ignore character to 10 (*IGNORE 10).

The next two commands are very similar and best treated together, though quite different in application. They are *GO and *GOS. The former may be used to call any machine code routine by specifying its start address. It is Arthur's equivalent to Basic's CALL, except that after *GO a return is not usually made back to Arthur. Unless you are into machine code programming this call will have little value for you (machine-code programmers should refer to the Programmer's Reference Manual). The other command, *GOS (short for *GO Supervisor), simply invokes Arthur, and in that respect is very similar to QUIT in Basic.

The last command in this group is *HELP which can be used to display information on other star commands, including those supported by filing systems and other modules. Simply type:

    *HELP

for more information on this command.

FX calls

The last OS command to mention gives access to many different functions. *FX is already well known to previous owners of BBC micros of all kinds, but performs fewer functions in its Archimedian form. In essence, *FX provides a convenient way for all users to access a range of operating system routines (known as Os-Byte calls). In each case *FX is followed by a number which specifies the particular function to be carried out, and depending upon the call used, by one or two parameters. The FX calls are listed in the User Guide, so I do not propose to cover them here.

I hope this discussion will have proved useful to many readers, and given some insight into the Archimedes operating system, Arthur, and the commands which it recognises. More information is contained in the Programmer's Reference Manual. Of course, the Archimedes responds to many more star commands than those that I have described. These are the ones used by tiling systems and any modules in your system. But that is another story.

Foundation RISCWorld