System Variables (Rev #6)
Programmer's Reference Manuals
» System Variables
System Variables
System Variables, as its name suggests, are Global variables that store various settings pertaining to various aspects of the current Operating System environment.
The table below details the most common uses of System Variables.
| Use Case | Description |
|---|---|
| Application variables | It is common for Applications to specify several system variables |
| Alias variables | How to change or add command associated with a System Variable |
| FileSwitch variables | Relates to current Filing System in use |
| File type variables | Specify how specific file type should be handled by the OS |
| Filing Systems | Specify how absent Filing Systems should be handled |
| CLI | Settings specific to the Command Line Interpreter |
| Configuration | Various OS related settings are stored as System Variables |
| System | Specify pathnames that will be searched for files during read or execute operations |
| Obey files | Specify the directory from which an Obey file is being run |
| Time and date | Used to evaluate time, date and years |
| Return codes | Provides access to the last returned value given by OS_Exit |
| !System and !Scrap | Provides full pathnames to the respective directories |
| Desktop | Various settings and values specific to the desktop environment |
| TaskWindow | Specify pathname to application that was used to start up task windows |
| Devices | Various settings specific to devices attached to the system |
| Printing | Specify various settings specific to the Printing device |
Application Variables
When developing an application, a number of different System Variables will be necessary. Some are frequently used by developers, while others are for more specialised purposes. The following list of different application System Variables.
In the examples listed below, you should replace App with your own application name, adhering to the Naming conventions guidelines. Where you need a system variable and can’t find a relevant one below, you should use your own, naming it App$.
| Example | Description |
|---|---|
| App$Dir | Provides the full pathname of the directory that holds the Application App. This is typically set in the applications !Run file. e.g. Set App$Dir <Obey$Dir> |
| App$Path | Provides the full pathname of the directory that holds the Application App. An App$Path variable differs from App$Dir variable in two important respects:
Note: It is more common to use an App$Dir variable rather than an App$Path variable. As example, an App$Path variable might be set in the application’s !Run file by the following: Set App$Path <Obey$Dir>.,%.App. (if the application held further resources in the subdirectory App of the library |
| App$Path_Message | Provides an alternative error message to be used if the path App: cannot be found. The message is then used instead of the default one provided by the Operating System |
| App$Options | Provides 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- 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 | Provides the name of the file or system device to which the application App prints. This is usually a printer, and would be set in your application’s !Run file by: Set App$PrintFile printer |
| App$Resources | Provides the full pathname of the directory that holds application App resources. This would usually be set in your application’s !Run file:
Note the use of App: to make use of App$Path |
| App$Running | Provides a value indicating if application App is running. It should have the value ’Yes" if true. This might be used in the application’s !Run file as follows:
When the application stops running, you should use *Unset to delete the variable |
Alias Variables
| Example | Description |
|---|---|
| Alias$Command | Provides the ability to define a new command named Command. For example:
|
FileSwitch Variables
| Example | Description |
|---|---|
| FileSwitch$… | 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. Please see FileSwitch section for more details |
| 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:
|
File type Variables
| Example | Description |
|---|---|
| File$Type_XXX | Provides the textual name for a given file type of the hexadecimal value XXX. It is typically set in the !Boot file of an application that uses (read and/or write) the file type. For example:
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, Alias$@RunType_XXX | Sets the commands that are used to load, print and run a file with a file type of the hexadecimal value XXX. It is typically set in the !Boot file of an application that uses (read and/or write) the file type. For example:
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. More information is available in the FileSwitch Use Of File Types page |
Filing System Variables
| Example | Description |
|---|---|
| FilingSystem$Path_Message | Provides an alternative error message to be used if the given FilingSystem cannot be found. The error message is then used instead of the default message provided by the Operating System |
CLI Variables
| Example | Description |
|---|---|
| CLI$Prompt | Provides the prompt to be used at the command line interpreter. by default this is the ‘*’ character. An example to display the time as the prompt is by:
This sets a macro so that the system time variable is evaluated each time the command prompt is displayed |
Configuration Variables
| Example | Description |
|---|---|
| Copy$Options, Count$Options, Wipe$Options |
Sets the behaviour of the *Copy, *Count and *Wipe commands |
System Path Variables
| Example | Description |
|---|---|
| File$Path and Run$Path |
Provides pathnames where files are searched for during, respectively, read and execute operations. They are both path variables, which means that, in common with other path variables, they consist of a comma separated list of pathnames, each which has a trailing ‘.’ character
If “<App$Path>” = "" then Set Run$Path <Run$Path>,<Obey$Dir>.bin. Set App$Path <Obey$Dir>.
|
Obey Variables
| Example | Description |
|---|---|
| Obey$Dir | Provides the pathname of the directory from which an Obey file is being run, and may be used by commands within that Obey file. The value is set by the OS automatically. 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:
This ensures that Obey$Dir is set to the full pathname of the Obey file. |
Time and Date Variables
| Example | Description |
|---|---|
| Sys$Time, Sys$Date, Sys$Year |
These are code variables that are evaluated at the time of their use to give, respectively, the current system time, date and year. An example of how it can be use is shown above under CLI Variable |
| Sys$DateFormat | Sets the format in which the date is presented by the OS_ConvertStandardDateAndTime SWI call. The format used by this variable is available here |
Return Code Variables
| Example | Description |
|---|---|
| Sys$ReturnCode | Provides the last return value given by the OS_Exit |
| Sys$RCLimit | Sets the maximum return value that will not generate an error |
!System and other !Boot related Variables
| Example | Description |
|---|---|
| System$Dir and System$Path |
Provides 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
|
| Wimp$Scrap | Provides 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 | Provides 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 |
Desktop Variables
| Example | Description |
|---|---|
| Desktop$File | Provides the desktop boot file that was used to start the desktop |
| Wimp$State | Provides the current state of the Wimp. If the desktop is running, it has the value ‘desktop’; otherwise it has the value ‘commands’ |
TaskWindow Variables
| Example | Description |
|---|---|
| TaskWindow$Server | Provides the pathname of the application used to start up task windows |
Devices Variables
| Example | Description |
|---|---|
| DeviceFS$Device$Options | Provides the default options for a DeviceFS device |
Printer Variables
| Example | Description |
|---|---|
| PrinterType$n | Provides the path used to print to printer type n. For example:
|
Type of System Variables
There are several types of system variable
| Type | Description | How to Set | How to Remove |
|---|---|---|---|
| String | Contains any characters you like; these are returned when the string is read | *Set | *Unset |
| Integer | are four-byte signed integers | *SetEval | *Unset |
| Macros | Macros are strings that are passed through OS_GSTrans when the string is read. This means that if the macro contains references to variables or other OS_GSReadable items, the appropriate translation takes place whenever the variable is accessed | *SetMacro | *Unset |
Example: To set the command line prompt (CLI$Prompt) to the current time, followed by a space, you would use: |
|||
*SetMacro CLI$prompt <Sys$Time><&20> |
|||
| Machine Code | A routine is called whenever the variable is to be read, and another when it is set. This allows great flexibility in the way in which such variables behave | OS_SetVarVal | OS_ReadVarVal |
| Example: you could make a variable directly control a CMOS RAM location using this technique | |||
Sys$Time is a good example of a code variable |
Notes
- All the different System Variable types can be:
- set with OS_SetVarVal
- read with OS_ReadVarVal
- Any non-code variables can be:
- removed using the *Unset command
- List all System Variables:
- displayed using the *Show command
Naming of System Variables
You must not use wholly numeric names. e.g. 123 as this causes difficulties when the OS_GSRead and OS_GSTrans operations are used to lookup the value of the variable. In particular, they will always take <123> to mean the ASCII code 123, and will not attempt to look up the name as a variable.
Names may contain any non-space, non-control character.
When a variable is created, the case of the letters is preserved, however, when returning the values, the case is not important.
You can use the characters ‘#’ and ‘*’ – just like looking up filenames.
See also
Social
Follow us on
and
and
ROOL Store
Buy RISC OS Open merchandise here, including SD cards for Raspberry Pi and more.