|
www.riscos.com Technical Support: |
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.
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>
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:
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.
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-
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.
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:
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.
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.
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$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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.)
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 DeviceFS$Device$Options variable holds default options for a DeviceFS device. For more details see the chapter entitled DeviceFS.