|
www.riscos.com Technical Support: |
* Commands provide you with a simple way to access the facilities of RISC OS by using text - for example:
*Time
will display the time and date. If you have read your computer's RISC OS User Guide, you may already be familiar with many of these commands.
This chapter introduces you to * Commands and the CLI; the chapter The CLI describes them in more detail.
Perhaps the most common way of issuing a * Command is to type it when the computer is in Command Line mode - also called Supervisor mode by some screen displays. Each line starts with a '*' character prompt, so you don't need to type it yourself. In the above example, all you need to type is the text Time.
When you type a * Command, the text is passed to RISC OS by a SWI, named OS_CLI. The text is then interpreted by a part of RISC OS called the Command Line Interpreter - or CLI for short. This converts the text to one or more SWIs that do the work of the * Command.
For example, the *Time command just calls three SWIs. You can achieve the same effect with a few lines of BASIC:
DIM block 24 ?block = 0 SYS "OS_Word",14,block SYS "OS_WriteN",block,24 SYS "OS_NewLine"
The * Command version is obviously more convenient.
* Commands have a number of advantages when compared to SWIs, mainly because of their simplicity:
Their simplicity also leads to some disadvantages:
It is up to you whether you use * Commands or SWIs. Sometimes you will have to use SWIs, so you can do something that * Commands do not cater for. There will be other times when you use * Commands for their simplicity and ease of use.
Each * Command is documented in the relevant chapter. For example, *Time is described in the chapter on Time and Date as *Time. You will find many of the miscellaneous * Commands that the kernel supplies in the chapter The CLI. (This chapter also details the OS_CLI SWI.)
The next page gives an example of how a * Command is documented. Again, comments are provided in grey boxes so you can understand exactly what each bit means:
*Time | Name of * command | ||||||||||
| Summary | ||||||||||
| Syntax | |||||||||||
| Parameters | |||||||||||
| |||||||||||
You don't have to be in Command Line mode to use * Commands. In fact, you can call * Commands in a number of other ways - both from applications and programming languages. The sections below outline these.
You can issue * Commands from most old-fashioned applications that provide a command line by typing a '*' at the start of a command. The application recognises the '*' prefix and calls OS_CLI, instead of trying to execute it itself.
Should you write an application that provides a command line (which we deprecate in favour of the desktop), it too should recognise any '*' prefixes, and call OS_CLI.
There are a number of different ways you can issue * Commands from BBC BASIC.
You can issue them directly from your program:
*TIME
Sometimes you won't know all the text of the * Command you want to use; for instance, you might want the user of your program to give the name of a file. Instead of issuing the command directly, you can build up the text of the * Command, and then use the OSCLI keyword:
INPUT "Name of file to delete"; file$ OSCLI "Delete "+file$
Of course, you can also call OS_CLI directly, as outlined in the chapter Calling from BBC BASIC. You can either use the SYS keyword:
DIM TIMESTR 4 $TIMESTR = "TIME" SYS "OS_CLI",TIMESTR
SYS "OS_CLI", "TIME"
or you can use BBC BASIC's built-in assembler:
ADR R0,TIMESTR ; Make R0 point to the text
SWI "OS_CLI" ; and call OS_CLI
...
.TIMESTR EQUS "TIME" ; Define the * Command text
EQUB 0 ; Terminating null for text
ALIGN
See the BBC BASIC Reference Manual for full details of all the above syntax.
Similarly, the Acorn C library provides different ways for you to issue * Commands.
You can use the procedure system, which takes as a parameter the text of the * Command:
system("Time");
You can run a replacement application using this call by prefixing it with 'CHAIN: '. So:
system("CHAIN: BASIC")
would start up BBC BASIC, returning control to the C application's parent when BASIC quits, whereas:
system("BASIC");
starts up BBC BASIC, but when BASIC quits control returns to the C application rather than its parent.
Alternatively, you could directly call OS_CLI:
_kernel_swi_regs regs; char timestr[] = "Time" regs.r[0] = (int) timestr; _kernel_swi(OS_CLI, ®s, ®s);
One of the keynotes of RISC OS is the ease with which you can alter and extend it. You've already been introduced to how you can alter, replace or add SWIs. The techniques that can be used for this are:
In just the same way, you can use these techniques to alter, replace or add * Commands.
If you claim a vector, and hence change how the SWI that uses it works, you will also alter all functions of RISC OS that call that SWI - including * Commands.
As an example, let's assume that you have changed OS_WriteC so that all letters are converted to capitals. You'd do this by claiming WrchV, the vector used for character output, so that it passes on calls made to OS_WriteC to your routine instead.
This would mean that all * Commands that output their results via WrchV would now do so in capitals only. This is true of all * Commands that output characters, and our example of *Time is no exception.
See the chapter entitled Software vectors for further details of how to use vectors.
If you replace a module, you must provide the same services that the old module did. So your replacement module should have the same * Commands, each of which must have the same syntax and accept the same parameters as before. However, they can be functionally different.
There is no reason why a replacement module cannot add extra * Commands as well.
If you write a new module, it can provide * Commands, in exactly the same way as any of the system modules. See the chapter entitled Modules for details of how to write a module.
You can use system variables of the form Alias$command to create new commands from existing ones, or to rename existing commands. For more details, see the chapter entitled Aliases, the command *Set, and the chapter Changing and adding commands.