System Variables (Rev #4)
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 |
| 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 Path | 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 pathname |
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 |
FileSwitch Variables
| Example | Description |
|---|---|
| File$Type_XXX | 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 |
|---|---|
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
and
ROOL Store
Buy RISC OS Open merchandise here, including SD cards for Raspberry Pi and more.