RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

* Commands and the CLI


Introduction

* 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.

Command Line mode

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.

OS_CLI and the CLI

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 v. SWIs

* Commands have a number of advantages when compared to SWIs, mainly because of their simplicity:

  • they are simple for novice users to use
  • they can be easily typed in directly, either from the command line or from applications
  • they are simpler to call from programs
  • they provide simple access to powerful features.

Their simplicity also leads to some disadvantages:

  • they are not as flexible as SWIs
  • they cannot easily pass information back to a program, as they usually output results to the screen.

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.

Documentation

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.)

An example of documentation

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
Displays the day, date and time of day
Summary
Syntax
*Time
Syntax
Parameters

None

Parameters
Use

*Time displays the day, date and time of day. It is displayed in the same format as OS_Word 14,0.

Full details of the use of * command
Example
*Time
Example of use
Related commands

None

Closely related * Commands (if any)
Related SWIs

OS_Word 14,0, OS_Word 15 (OS_Word 15,8), OS_ConvertStandardDateAndTime, OS_ConvertDateAndTime, Territory_ConvertDateAndTime, Territory_ConvertStandardDateAndTime

Closely related SWIs (if any)
Related vectors

WordV, WrchV

Main vectors used by the * Command (if any)
Example * Command documentation

Using * Commands

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.

Issuing * Commands from applications with command lines

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.

Issuing * Commands from assembler

You can issue * Commands from assembler by passing the string directly to the SWI OS_CLI. Note the null byte terminating the command string:

        ADR R0,TIMESTR                  ; Make R0 point to the text
        SWI OS_CLI                      ; and call OS_CLI
        ...
TIMESTR DCB "Time",0                    ; Define the * Command text
        ALIGN

Issuing * Commands from BASIC

There are a number of different ways you can issue * Commands from BBC BASIC.

Directly from programs

You can issue them directly from your program:

*TIME

The OSCLI keyword

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$

Calling OS_CLI directly

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

or more simply:

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.

Issuing * Commands from C

Similarly, the Acorn C library provides different ways for you to issue * Commands.

The procedure system ()

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.

Calling OS_CLI directly

Alternatively, you could directly call OS_CLI:

_kernel_swi_regs regs;
char timestr[] = "Time"
regs.r[0] = (int) timestr;
_kernel_swi(OS_CLI, &regs, &regs);

Changing and adding * Commands

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:

  • claiming vectors
  • replacing modules
  • adding new modules.

In just the same way, you can use these techniques to alter, replace or add * Commands.

Using vectors

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.

Replacing modules

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.

Adding modules

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.

Using Alias$command system variables

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.

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015