RISCOS.com

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

 

Appendix F: System variables


This appendix details standard variables used in RISC OS, and gives important guidelines on the names you should use for any system variables you create for your applications to use.

Application variables

The following section gives standard names used for variables that are bound to a particular application. An application should not need to set all these variables, but where one of the variables below matches your needs, you should use it and follow the given guidelines. Where you need a system variable and can't find a relevant one below, you should use your own, naming it App$...

In the descriptions below you should replace App with your application's name. You must first register this name with Acorn, to avoid any possibility of your system variables clashing with those used by other programmers' applications; see Appendix H: Registering names.

App$Dir

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:

Set App$Dir <Obey$Dir>

App$Path and App$Path_Message

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:

  • The pathname includes a trailing '.'
  • The variable may hold a set of pathnames, separated by commas.

An App$Path_Message variable gives an alternative error message to be used if the path App: cannot be found. This message is then used instead of the default one provided by RISC OS.

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.

App$Options

An App$Options variable holds the start-up options of the application App:

  • An option that can be either on or off should consist of a single character, followed by the character '+' or '-' (eg M+ or S-).
  • Other options should consist of a single character, followed by a number (eg P4 or F54).
  • Options should be separated by spaces; so a complete string might be F54 M+ P4 S-.

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-

You should only save those options that differ from the default, and hence not output a line at all if the application is in its default state. You should however be prepared to read options that set the default values, in case users explicitly add such options.

App$PrintFile

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:

Set App$PrintFile printer:

App$Resources

An App$Resources variable gives the full pathname of the directory that holds the application App's resources. This might be set in the application's !Run file by the line:

Set App$Resources App:Resources

Note the use of App: to make use of App$Path.

App$Running

An App$Running variable shows that the application App is running. It should have the value 'Yes' if the application is running. This might be used in the application's !Run file as follows:

If "App$Running" <> "" then Error App is already running
Set App$Running Yes

When the application stops running, you should use *Unset to delete the variable.

Changing and adding commands

Alias$Command

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.

FileSwitch variables

FileSwitch$...

FileSwitch$CurrentFilingSystem contains the name of the current filing system, and FileSwitch$TemporaryFilingSystem contains the name of the temporary filing system. FileSwitch$SpecialField contains the last special field to have been evaluated as a path was processed. See also Using FileSwitch$SpecialField with path variables.

FileSwitch$FilingSystem$...

Most filing systems provide system variables used to store their currently selected directory, previously selected directory, library directory, and user root directory. For a filing system fs, these are respectively FileSwitch$fs$CSD, FileSwitch$fs$PSD, FileSwitch$fs$Lib and FileSwitch$fs$URD.

Using file types

File$Type_XXX

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.

Alias$@LoadType_XXX, Alias$@PrintType_XXX and Alias$@RunType_XXX

These variables set the commands used to respectively 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 that 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.

For more information see the chapter entitled Load-time and run-time system variables.

Absent filing systems

FilingSystem$Path_Message

A FilingSystem$Path_Message variable gives an alternative error message to be used if the FilingSystem cannot be found. This message is then used instead of the default one provided by RISC OS.

Setting the command line prompt

CLI$Prompt

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.

Configuring RISC OS commands

Copy$Options, Count$Options and Wipe$Options

These variables set the behaviour of the *Copy, *Count and *Wipe commands. For a full description, see *Copy, *Count and *Wipe respectively.

System path variables

File$Path and Run$Path

These variables control where files are searched for during, respectively, 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.
Set App$Path <Obey$Dir>.

For more information see the chapter entitled File$Path and Run$Path.

Obey files

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. For examples, see various other sections of this chapter. For more detailed information, see the chapter entitled Obey$Dir.

Time and date

Sys$Time, Sys$Date and Sys$Year

These variables are code variables that are evaluated at the time of their use to give, respectively, the current system time, date and year.

For an example of the use of Sys$Time, see the chapter entitled CLI$Prompt.

Sys$DateFormat

The Sys$DateFormat variable sets the format in which the date is presented by the SWI OS_ConvertStandardDateAndTime. For details of the format used by this variable, see the chapter entitled Format field names.

Return codes

Sys$ReturnCode, Sys$RCLimit

The Sys$ReturnCode variable contains the last return value given by the SWI OS_Exit, and the Sys$RCLimit variable sets the maximum return value that will not generate an error. For more details, see OS_Exit.

!System and !Scrap

System$Dir and System$Path

These variables give the full pathname of the System application. They have the same value, save that System$Path has a trailing '.', whereas System$Dir does not. You must not change their values.

(There are two versions of this pathname for reasons of backward compatibility.)

Wimp$Scrap

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.

Wimp$ScrapDir

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 desktop

Desktop$File

The Desktop$File variable shows the desktop boot file that was used to start the desktop.

Wimp$State

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

The Task Window

TaskWindow$Server

The TaskWindow$Server variable gives the pathname of the application used to start up task windows.

Setting default options for devices

DeviceFS$Device$Options

The DeviceFS$Device$Options variable holds default options for a DeviceFS device. For more details see the chapter entitled DeviceFS.

Setting paths for printing

PrinterType$n

A PrinterType$n variable contains the path used to print to printer type n. For example:

*Show PrinterType$0
PrinterType$0 : null:

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