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

Command scripts

Introduction

Command scripts are files of commands that you would normally type in at the Command Line prompt. There are two common reasons for using such a file:

• To set up the computer to the state you want, either when you switch on or when you start an application.
• To save typing in a set of commands you find yourself frequently using.

In the first case the file of commands is commonly known as a boot file.

You may find using an Alias$... variable to be better in some cases. The main advantage of these variables is that they are held in memory and so are quicker in execution; however, they are only really suitable for short commands. Even if you use these variables you are still likely to need to use a command file to set them up initially.

There are two types of file available for writing command scripts: Command files, and Obey files. The differences between these two file types are:

• An Obey file is read directly, whereas a Command file is treated as if it were typed at the keyboard (and hence usually appears on the screen).
• An Obey file sets the system variable Obey$Dir to the directory it is in.
• An Obey file can be passed parameters
• An Obey file stops when an error is returned to the Obey module (or when an error is generated and the exit handler is the Obey module - an untrapped error, not in an application).

Overview and Technical Details

Creating a command script

A command script can be created using any text or word processor. With Edit you can set the type of the file to Command or Obey, except under RISC OS 2, where you then have to use the command *SetType .

You should save it in one of the following:

• the directory from which the command script will be run (typically your root directory, or an application directory)
• the library (typically $.Library, but may be $.ArthurLib on a network; see *Configure Lib).

Running the script

Provided that you have set the file to have a filetype of Command or Obey it can then be run in the same ways as any other file:

• Type its name at the * prompt.
• Type its name preceded by a * at any other prompt (some applications may not support this).
• Double-click on its icon from the desktop.

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 force any text file to be treated as an obey file by using the command *Obey. This overrides the current file type, such as Text or Command. Obviously, this will only have meaning if the text in the file is valid to treat as an obey file.

Similarly, any file can be forced to be a command file by using *Exec. This is described on *Exec.

Obey$Dir

When an obey file is run, by using any of the above techniques, the system variable Obey$Dir is set to the parent directory part of the pathname used. For example, if you were to type *Obey a.b.c, then a.b is the parent directory of the pathname.

Note that it is not set to the full parent name, only the part of the string passed to the command as the pathname. So if you change the current directory or filing system during the obey file, then it would not be valid any more.

Ideally, you should invoke Obey files (and applications, which are started by an Obey file named !Run) by using their full pathname, and preceding that by either a forward slash / or the word Run, for example:

/ ADFS::MikeWinnie.$.Odds'nSods.MyConfig

Run ADFS::MikeWinnie.$.Odds'nSods.MyConfig

This ensures that Obey$Dir is set to the full pathname of the Obey file.

Run$Path

The variable Run$Path also influences how this parent name is decoded. If you were to type:

*Set Run$Path ADFS::Winnie.Flagstaff.
*obeyfile par1 par2

Then it would be interpreted as:

*Run ADFS::Winnie.Flagstaff.obeyfile par1 par2

If the filetype of obeyfile was &FEB, an obey file, then the command would be interpreted as:

*Obey ADFS::Winnie.Flagstaff.obeyfile par1 par2

This can also apply to application directories, as follows:

*Set Alias$@RunType_FEB Obey %*0
*Set File$Type_FEB Obey
*Set Run$Path ADFS::Winnie.Flagstaff.
*!AppDir par1 par2

In this case, RISC OS would look for the !Run file within the application directory and run it. Note that in most cases, the first two lines above are already defined in your system. If !Run is an obey file, then it would be interpreted as:

*Obey ADFS::Winnie.Flagstaff.!AppDir.!Run par1 par2

Note that Obey files can also be nested, calling other files to Obey; however, Command files cannot be nested. This is one of the reasons why it is better to set up your file as an Obey file rather than a Command file.

Making a script run automatically

You can make scripts run automatically:

• From the network when you first log on.

  The file must be called !ArmBoot. (This is to distinguish a boot file for a machine running Arthur or RISC OS from an existing !Boot file already on the network for the use of BBC model A, model B or Master series computers.)

• From a disc when you first switch the computer on.

  The file must be called !Boot.

• From an application directory when you first display the directory's icon under the desktop.

  The file must be called !Boot. It is run if RISC OS does not already know of a sprite having the same name as the directory, and is intended to load sprites for applications when the first need to be displayed. For further details see the section entitled Application resource files.

• From an application directory when the application is run.

  The file must be called !Run. For further details see the section entitled Application resource files.

In the first two cases you will need to use the *Opt command as well (see *Opt 4).

For an example of the latter two cases, you can look in any of the application directories in the Applications Suite. If you are using the desktop, you will need to hold down the Shift key while you open the application directory, otherwise the application will run.

Using parameters

An Obey file can have parameters passed to it, which can then be used by the command script. A Command file cannot have parameters passed to it. 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 the all 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> Desired 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 needed in file

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

Abbreviations

You must not use abbreviations for * Commands in scripts and programs, as these may vary between releases of RISC OS. For example, in RISC OS 2 '*Te.' was the minimum abbreviation for *Tempo, whereas in RISC OS 3 this abbreviation instead runs the *Territories command.

*Commands

---

*Obey

Executes a file of * commands

Syntax

*Obey [[-v][-c] [filename [parameters]]]

Parameters

-v	echo each line before execution
-c	cache filename, and execute it from memory
filename	a valid pathname, specifying a file
parameters	strings separated by spaces

Use

*Obey executes a file of * commands. Argument substitution is performed on each line, using parameters passed in the command.

With the -v option, each line is displayed before execution. With the -c option, the file is cached and executed from memory. These options are not available in RISC OS 2.

Note: Recursive calls of *Obey are only possible to a limited depth (currently 20, although you should not rely upon this).

Example

*Obey !commands myfile1 12

Related commands

*Exec, *Run

Related SWIs

None

Related vectors

None

Application Notes

These example files illustrate several of the important differences between Command and Obey files:

*BASIC
AUTO
FOR I = 1 TO 10
  PRINT "Hello"
NEXT I
END

If this were a command file, it would 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).

In contrast, if this were an Obey file it would be passed to the Command Line interpreter, and an attempt would be made to run these commands:

*BASIC
*AUTO
*FOR I = 1 TO 10
*  PRINT "Hello"
*NEXT I
*END

Only the first command is valid, and so 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 in both Command and Obey files:

echo <7>
echo |<7>

The control characters are represented in GSTrans format (see the chapter entitled Conversions). 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; see VDU 7 for more information. 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 VDU drivers - displays <7> on 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 called 'more' - taking its name from the UNIX 'more' command - by setting the variable Alias$more:

• The % characters that precede echo and type ensure that the actual commands are used, rather than an aliased version of them.
• The sequence |m represents a carriage return in GSTrans format and is used to separate the commands, just as Return would if you were typing the commands.
• The two echo commands turn paged mode on, then off, by sending the control characters ASCII 14 and 15 respectively to the VDU drivers (see VDU 14 onwards of the VDU Drivers for more information).
• The | before each < prevents the control characters from being interpreted until the aliased command 'more' is run.

The command turns paged mode on, types a file to the screen expanding tabs as it does so, and then turns paged mode off.