|
www.riscos.com Technical Support: |
Usually you will use the RISC OS desktop for almost all of your computing tasks. However occasionally you may need to use the command line.
The command line is very different from the desktop. Gone are the windows, icons and menus. These are replaced by a set of single line commands that always start with a star, the Star Commands (known as *commands).
All the commands are described, in alphabetical order, in the file StarComms in the Tutorials directory. Alternatively, see Getting Help later in this chapter.
Using the command line you can run scripts. Scripts are small programs (which you usually write in Edit) that help you control the computer. The command line is also used to issue operating system commands from BASIC.
This chapter gives you an introduction to the command line. The RISC OS 3 Programmer's Reference Manual expands on all the information given in this chapter.
The following options on the Task manager icon bar menu give you access to the command line.
By choosing *Commands from the Task menu, you can enter Command Line Mode. A * prompt appears at the bottom of the screen, and you can enter operating system commands. To return to the desktop, press Return at a * prompt without entering any other characters on the line. Pressing F12 is equivalent to choosing * Commands from the Task Manager menu.
Clicking on Exit causes the desktop and all tasks to be closed down and replaced by the command line. You can restart the desktop by typing desktop at the * prompt, and then pressing Return.
The star (*) prompt indicates that you are in command line mode and that the computer is expecting a command to be typed. Note that command line mode is sometimes called Supervisor mode (for example, when the machine starts up in command line mode).
The commands in this guide are always preceded by a star. The star is provided as a prompt in command line mode, so you do not have to type it (though it does not matter if you do, any extra stars are ignored). However, if you type a * Command following some other prompt (at the BASIC > prompt, for example), you must precede it with a star so that the computer knows how to interpret what follows.
If you are using the command line mode and you want to display a large amount of information you can set the system to pause at each full screen. Do this by typing Ctrl-N. Use the Shift key to scroll through the screenfulls. Ctrl-O removes this feature; the display no longer pauses. This does not apply to Task windows.
Enter BASIC by typing *BASIC from the command line. The prompt will change from * to >. To confirm that you are in BASIC, type in the following one-line program (must be typed using capital letters).
FOR N=1 TO 20: PRINT "HELLO": NEXT N (press Return)
This will cause the word HELLO to be printed twenty times. Leave BASIC by typing QUIT or *Quit.
For information on using BASIC see Appendix 9:BBC BASIC.
The BBC BASIC Reference Manual is the complete reference guide for the BBC BASIC language.
The Task window allows you to use the command line within a window. To open a Task window, choose Task window from the Task manager icon bar menu. When you open a Task window, you will see a * prompt. You can now enter commands in the window just as if you were using the command line itself. Like any other application, you can have more than one Task window at the same time.
The major advantages in entering commands in a Task window instead of at the command line prompt are;
You can change this by unlinking the window. In this case, anything you type in alters the contents of the window in the same way as any other Edit window, even while a task is running. Keyboard short-cuts only operate if the window is unlinked.
You can also supply input to a task window by selecting some text from any text file and choosing TaskInput from the task window menu.
You cannot use graphics in a task window. If the Ignore Ctl option is not chosen, the output of any commands that use graphics will appear as screen control codes.
The Task window is controlled by Edit, so don't be surprised if you see the Edit icon on your icon bar.
The menu for a Task window contains the following options.
 |
|
Here are a few commands.
The command *Spool should not be used from a task window. Because its effect is to write everything that appears on the screen to the spool file, using *Spool from the desktop will produce unusable files full of screen control characters. There is, in any case, no point in using *Spool, since the output from the task appears in the window, and can be saved using Edit as normal.
When you run a command in a Task window, the computer divides its time between the Task window and other activities running in the desktop. Note that some time-consuming commands may prevent access to the filing system until the command is complete.
Note 1: Command line notions such as 'current directory' become relevant when you are using Task Windows.
Note 2: Using the *Copy command in a task window may lead to Filer error. Only use *Copy from the command line prompt (press F12).
Note 3: Do not close a Task window while a command-line process is still running, or initiate one with little memory available, as internal errors may result.
All of these commands are described in detail in the file StarComms in the Tutorials directory.
The command *Help gives brief information about each command in the operating system. *Help keyword displays a brief explanation of the keyword and, if the keyword is a command name, the syntax of the command.
If you are not sure about the name of a command;
The usual use of *Help is to confirm that a command is appropriate for the job required, and to check on its syntax (the number, type and ordering of parameters that the command requires).
When you issue the *Help command at the normal command line prompt, 'paged mode' is switched on: the computer displays a screenful of text, then waits until you press Shift before moving on (in a Task window, you just scroll).
The specification of the keyword can include abbreviations to allow groups of commands to be specified. For example,
*help con.
produces information on *Configure and *Continue. You can also use this to establish the current abbreviation for a command. Since RISC OS uses the first command it finds that matches an abbreviation, typing *Con. is equivalent to *Configure. For the *Continue command, the minimum abbreviation must distinguish it from *Configure, and is therefore *Cont. These abbreviations may change as new commands are added.
You will find many hints in the following sections:
The interface to the command line is built into the RISC OS operating system and processes valid commands sent as text strings. The text string is normally terminated by Return.
The syntax of each command in the following chapters is described in a standard way, with examples of its use where these are helpful. The symbols used in syntax descriptions are:
<value> indicate that an actual value must be substituted. For example, <filename> means that you must supply an actual filename.
[...] indicate that the item enclosed in the square brackets is optional.
| indicates alternatives. For example, 0 | 1 means that the value 0 or 1 must be supplied.
RISC OS commands are sometimes followed by one or more parameters which tell the computer how you want the command to be modified.
In the following descriptions, the parameters are in italics. You can leave spaces only between parameters, since otherwise the operating system cannot tell where you want one parameter to end and the next to begin.
Command line parameters may be optional. In this case they are shown in the syntax within square brackets. Often, when a parameter is specified as optional, the operating system will supply a default value; the value of this is specified for each command.
Some commands have one or more numeric parameters. These are interpreted as decimal by default (unless the description of the command specifies otherwise), but it is possible to express them in any base by prefacing the parameter itself with the base followed by an underscore, as in the following examples:
*Eval 2_1010101 *Eval 16_FFF similarly, returns the value 4095.
An alternative form for hexadecimal uses the & sign to signify base 16.
*Eval &FFF
Decimal and hexadecimal are likely to be the most useful bases.
It is useful in many command line operations to specify objects using 'wildcards'. There are two wildcards.
* stands for zero or more characters
# stands for a single character
Examples:
he* would stand for he, help, hello, or hencoop
he*p would stand for help or hencoop
he## would stand for help, hens or head, but not hen or health
Before a command is executed, the command line interface carries out a certain amount of pre-processing on the line:
Full details of this checking are given in the RISC OS Programmer's Reference Manual.
A powerful feature of RISC OS is the ability to redirect input or output streams (or both) for the duration of the command. By default, output is directed to the screen, but it may be convenient to redirect the output stream to a file so that you can examine it later in more detail, or process it further.
The format of a redirection is;
<command> { <redirection spec> }
where the <redirection spec> is at least one of;
> <filename> : output goes to filename
< <filename : input read from filename
>> <filename : output is appended to filename.
Note the following.
Examples
mycat.
*Help Cat) to a file called CatHelp.
The operating system contains a number of useful system devices, which behave like files in some ways. You can use them anywhere you would normally use a file name as a source of input, or as a destination for output. These include:
These system devices can be useful with commands such as *Copy, and the redirection operators (> and <):
*Copy myfile printer: - Send myfile to the printer
*Cat { > printer: } - List the files in the current directory to the printer
*Cat netprint: - Display the currently selected network printer and a list of available network printers.
The system device null is useful to suppress unwanted output from a command script or program.
*myprogram { > null: } Runs myprogram with no output
The most useful system devices for the general user are likely to be printer: and netprint:
If you Shift-double-click on an application you'll see a !Run file (it has the file type Obey). An application's !Run file is obeyed whenever you start the application. This file sets up the application's environment, loads any resources it requires and then starts the application code (often called !Runimage).
The application also contains a !Boot file, this is used when the application is first 'seen'. This occurs when the directory containing the application is displayed on the screen. The !Boot file sets up the application sprite used in the directory display.
Most !Boot and !Run files have lines containing Set commands. For example, !Draw sets up variables that include a RunType and a PrintType for the normal DrawFile file type &AFF.
Draw also sets up a variable called Draw$Dir which sets up the computer to remember where the Draw application is on the computer. It uses another variable called Obey$Dir, this contains the path of the directory in which the current obey file is running.
You will find all these variables explained in greater detail later in this chapter.
A module is a piece of software that is loaded into memory. A section of memory is reserved for use by modules and is known as the RMA (Relocatable Module Area).
If you look at the !Run file of !Draw you'll see some RMEnsure commands are used these particular commands make RISC OS check the named module is present in the RMA.
System variables are used by RISC OS to store settings that control the behaviour of the computer. For example, they store how you like the time and date to be printed, how you want the *Copy command to work, and what prompt you like.
However, unlike configuration features, your settings for system variables are not preserved when you switch the computer off or reset it. When you do this, the computer always goes back to the default values for the standard set of system variables, but if you have a Desktop boot file loaded, your favourite settings will be kept. You can see these default values by typing *Show just after switching on your computer.
In addition to RISC OS system variables, applications commonly use variables of their own, to control their default behaviour. For example, Edit uses variables to store your choices of display font, background colour and so on. Where there are such variables, they are listed in the chapter Configuring applications. Some suggestions for using them are also included later in this chapter.
If the default values are not the ones you want, you can change them using the *Set command. The computer does not remember system variables between sessions, so if you want different default values you must change the variable each time you use your computer. Rather than typing them each time by hand, you can include the *Set commands in a boot file (a file that is run each time you use the computer).
However, although you could create such a boot file 'by hand', typing it in Edit, a much easier way is to use the Task manager's Desktop boot facility, described in the chapter Customising the desktop start-up procedure. You will then not need to understand anything about system variables as such, since you can simply set up the desktop the way you want it and make a Desktop boot file. Creating your own boot file by editing one created by the Task manager is the easiest way to start.
Each variable is accessed by its name, which can contain any character which is neither a space nor a control character. As with filenames, the case of characters is remembered, but is ignored when the names are looked up.
RISC OS uses the values of variables to make the desktop work. When you double-click on a file (not an application), RISC OS looks up the alias for RUNning that file type in the variable list. If it finds a match, the command stored in the variable (for example RMLoad %*0) is executed, substituting the name of the file in place of the marker %*0; otherwise an error box is displayed.
In general, files which are displayed as white squares (they have no file type icon) will give this error if you try to use them in this way.
There are many different system variables provided and used by RISC OS, as well as some which may be added by applications. You can see them all by typing *Show (use Shift to display each successive screenful).
The following section gives standard names used for some of the variables that are connected to a particular application.
An App$Dir variable gives the full pathname of the directory that holds the application App. This is typically set in the application's !Run file by the line:
An App$Path variable gives the full pathname of the directory that holds the application App. An App$Path variable differs from an App$Dir variable in two important respects:
It's common to use an App$Dir variable rather than an App$Path variable, but there may be times when you need the latter.
An App$Path variable might, for example, be set in the application's !Run file by the line:
Set App$Path <Obey$Dir>.,%.App
if the application held further resources in the subdirectory App of the library.
An App$Options variable holds the start-up options of the application App
This variable is typically used to save the state of an application to a Desktop boot file, upon receipt of a desktop save message. A typical line output to the boot file might be;
Set App$Options F54 M+ P4 S-
An application should only save those options that differ from the default, so there will be no line at all if the application is in its default state.
An App$PrintFile variable holds the name of the file or system device to which the application App prints. Typically this will be printer:, and would be set in your application's !Run file as follows;
An Alias$Command variable is used to define a new command named Command. For example;
Set Alias$Mode echo |<22>|<%0>
By using the name of an existing command, you can change how it works.
A File$Type_XXX variable holds the textual name for a file having the hexadecimal file type XXX. It is typically set in the !Boot file of an application that provides and edits that file type. For example:
Set File$Type_XXX <TypeName>
The reason the !Boot file is used rather than the !Run file is so that the file type can be converted to text from the moment its 'parent' application is first seen, rather than only from when it is run.
These variables set the commands used respectively to load, print and run a file of hexadecimal type XXX They are typically set in the !Boot file of an application that provides and edits that file type. For example;
Set Alias$@PrintType_XXX /<Obey$Dir> -Print
Set Alias$@RunType_>XXX /<Obey$Dir>
Note: The above lines both have a trailing space (invisible in print!).
The reason the !Boot file is used rather than the !Run file is so that files of the given type can be loaded, printed and run from the moment their 'parent' application is first seen, rather than only from when it is run.
The CLI$Prompt variable sets the command line interpreter prompt. By default this is '*'. One common way to change this is so that the system time is displayed as a prompt. For example;
SetMacro CLI$Prompt <Sys$Time> *
This is set as a macro so that the system time is evaluated each time the prompt is displayed.
There's more on this in Creating your own command line prompt later.
These variables set the behaviour of the *Copy, *Count and *Wipe commands. For a full description type *Help command at the command line.
These variables control where files are searched for during read operations or execute operations. They are both path variables, which means that - in common with other path variables - they consist of a comma-separated list of full pathnames, each of which has a trailing '.'.
If you wish to add a pathname to one of these variables, you must ensure that you append it once, and once only. For example, to add the 'bin' subdirectory of an application to Run$Path, you could use the following lines in the application's !Boot file:
If "<App$Path>" = "" then Set Run$Path <Run$Path>,<Obey$Dir>.bin. SetApp$Path <Obey$Dir>.
The Obey$Dir variable is set to the directory from which an Obey file is being run, and may be used by commands within that Obey file.
These variables are code variables that are evaluated at the time of their use to give, respectively, the current system time, date and year.
The Sys$DateFormat variable sets the format in which the date is presented by some commands.
These variables give the full pathname of the System application. They have the same value, except that System$Path has a trailing '.', whereas System$Dir does not. You must not change these values.
(There are two versions of this pathname for compatibility with some old applications). !System and !Scrap are contained in the !Boot application.
The Wimp$Scrap variable gives the full pathname of the Wimp scrap file used by the file transfer protocol. You must not use this variable for any other purpose, nor change its value.
The Wimp$ScrapDir variable gives the full pathname of a scrap directory within the Scrap application, which you may use to store temporary files. You must not use this variable for any other purpose, nor change its value.
The Wimp$State variable shows the current state of the Wimp. If the desktop is running, it has the value 'desktop'; otherwise it has the value 'commands'.
Some commands, such as *Copy and *Wipe, can operate in a variety of ways. For example, you can effectively turn *Copy into a Move command by setting the D(elete) option, which deletes the source file after copying it to another directory or filing system. You would do this by typing
*Set Copy$Options <Copy$Options> D
at the command line prompt. These options are described in the entries for each command in the file StarComms in the Tutorials directory.
Several applications, such as Edit, Draw, Alarm and Paint, also use system variables to record, for example, whether you want the Paint colours window to appear automatically when you open a sprite window, or whether you want the toolbox to be displayed by default in Draw. Such variables use the format App$Options, where App is the name of the application in question. These variables will only be listed in the computer's response to the *Show command if you have changed them from their default values.
In addition to 'options', applications may use other variables for a variety of purposes. For example, Acorn Desktop Publisher needs to know where its 'Work' directory is. It will find this out when the Work directory has been displayed on the screen, and it assigns the directory's pathname to the variable dtp$WorkDir. To avoid having to carry out this action each time you use the application, you can put a *Set command identifying the directory in your boot file, for example;
*Set dtp$WorkDir <Obey$Dir>.WorkDir
You can use a system variable to change the operating system prompt - normally * - by setting the variable CLI$Prompt to (for example) the character #.
*Set CLI$Prompt #
You can also set one variable to the value of another:
*Set CLI$Prompt <Sys$Time>
This sets the prompt to the system time, but only does so once, when the command is given. However, it would clearly be more useful if the prompt always showed the current time. To do this, change CLI$Prompt from a variable into a macro. A macro is similar to a variable, but is evaluated every time it is used, instead of just once when it is set. Therefore, type the following;
*SetMacro CLI$Prompt <Sys$Time> *
Each time Return is pressed at the command line prompt a new prompt is given (unless you have not typed anything since the last Return; you will then be returned to the desktop); the current time is worked out and displayed, followed by a space character and an asterisk:
12:59:06 *
12:59:07 *
12:59:08 *
The names of commands may be changed using the *Set command with variables whose name starts Alias$... This allows you to add new commands, to change the meaning of existing commands, to combine commands together, and to add your own parameters to a command.
Programmers can use system variables to pass values between programs. One program can create and write to a variable which another program can then read. Such variables should have names starting App$, where App is your program; this avoids problems caused by different programs using the same system variable names.
Command scripts are files of commands that you would normally type in at the command line prompt. There are two main uses for such files;
You may find using an Alias$... variable to be better for the second case. The main advantage of using variables rather than command files is that they are held in memory and so are quicker in execution; however, they are only really suitable for short commands. If you use variables you will probably still want to use a command file to set them up when you switch on.
There are two types of file you can use for command scripts: Command files, and Obey files. The differences between these two file types are:
A command script can be created using any text or word processor. If you created the file using Edit, you should set the file's type by pressing Menu over the Edit icon on the icon bar and choosing the desired file type, such as Command or Obey.
When you save the file you should consider in which directory you will save it. By default, files are looked for first in the current directory, then in the library. Therefore, if you want to avoid having to type the full pathname of the file every time you run it you should save it in one of the following;
The same restrictions apply as with any other file. If the file is not in either your current directory or the library, it will not be found if you just give the filename; you must give its full pathname. This assumes you have not changed the value of the system variable Run$Path.
You can make scripts run automatically
You'll find information on how to do this in Customising the desktop start-up procedure.
An Obey file - but not a Command file - can have parameters passed to it, which can then be used by the command script. The first parameter is referred to as %0, the second as %1, and so on. You can refer to all the parameters after a particular one by putting a * after the %, so %*1 would refer to all the parameters from the second one onwards.
These parameters are substituted before the line is passed to the command line interpreter. Thus if an Obey file called Display contained;
FileInfo %0 Type %0
then the command *Display MyFile would do this;
FileInfo MyFile
Type MyFile
Sometimes you do not want parameter substitution. For example, suppose you wish to include a *Set Alias$ command in your file, such as:
Set Alias$Mode echo |<22>|<%0> <Command>
The effect of this is to create a new command 'Mode'. If you include the *Set Alias command in an Obey file, when you run the file the %0 will be replaced by the first parameter passed to the file. To prevent the substitution you need to change the % to %%;
Set Alias$Mode echo |<22>|<%%0> <Command>
Now when the file is run, the '%%0' is changed to '%0'. No other substitution occurs at this stage, and the desired command is issued.
These example files illustrate some of the differences between Command and Obey files:
*BASIC AUTO FOR J= 1 TO 10 PRINT "Hello" NEXT J END
If this is a command file, it will enter the BASIC interpreter, and input the file shown. The command script will end with the BASIC interpreter waiting for another line of input. You can then press Esc to get a prompt, type RUN to run the program, and then type QUIT to leave BASIC. This script shows how a command file is passed to the input, and can change what is accepting its input (in this case to the BASIC interpreter).
On the other hand, if this is an Obey file it will be passed to the command line interpreter, and an attempt will be made to run these commands:
*BASIC *AUTO *FOR J= 1 TO 10 *PRINT "Hello" *NEXT J *ENDOnly the first command is valid, as an Obey file all this does is to leave you in the BASIC interpreter. Type QUIT to leave BASIC; you will then get an error message saying File 'AUTO' not found, generated by the second line in the file.
The next example illustrates how control characters are handled;
echo <7>
echo |<7>
The control characters are represented in GSTrans format (see Using GS formats in scripts). These are not interpreted until the echo command is run, and are only interpreted then because echo expects GSTrans format.
The first line sends an ASCII 7 to the VDU drivers, sounding a beep. In the second line, the | preceding the < changes it from the start of a GSTrans sequence to just representing the character <, so the overall effect is;
echo <7> - send ASCII 7 to VDU drivers (beeps)
echo |<7> - send <7> to the screen
The last examples are a Command file;
*Set Alias$more %echo |<14>|m %type -tabexpand %*0|m %echo |<15>
and an Obey file that has the same effect;
Set Alias$more %echo |<14>|m %type -tabexpand %%*0|m %echo |<15>
The only differences between the two examples are that the Command file has a preceding * added, to ensure that the command is passed to the command line interpreter, and that the Obey file has the %*0 changed to %%*0 to delay the substitution of parameters.
The file creates a new command more by setting the variable Alias$more.
The command turns scroll mode on, types a file to the screen expanding tabs as it does so, and then turns scroll mode off.
The GSTrans and GSRead formats are used by a number of commands that need to be able to handle control characters, and characters whose top bit is set. They enable you to use these characters, which would otherwise cause unpredictable output from your monitor or printer, and which would be difficult to enter directly from the keyboard. The two formats are identical.
The GSRead or GSTrans format is used by some commands to read characters that you type in. The characters are interpreted using the following conventions:
A full list of ASCII codes and how to obtain them is given below. Of course, any ASCII code may be obtained by enclosing it in angle brackets as described above, and this may be easier to remember than the symbol encoding.
ASCII code: Symbols used:
You must use |< to prevent the < from being interpreted as the start of a number or variable name enclosed in angled brackets.
To include leading spaces in a definition, the string must be in double quotation marks, ", which are not included in the definition. To include a literal " character in the string, use |" or "".