h6. [[Programmer's Reference Manuals]] h6(. » [[System Variables]] h2(#system). 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. table(bordered). |_<^{width:16em}. Use Case |_<^. Description | |<^. "Application variables":#varapp |<^. It is common for Applications to specify several system variables | |<^. "Alias variables":#varalias |<^. How to change or add command associated with a System Variable | |<^. "FileSwitch variables":#varfileswitch |<^. Relates to current Filing System in use | |<^. "File type variables":#varfiletype |<^. Specify how specific file type should be handled by the OS | |<^. "Filing Systems":#varfs |<^. Specify how absent Filing Systems should be handled | |<^. "Filer":#varfiler |<^. Specify how to adjust the behaviour when dropping a file on the filer icon | |<^. "CLI":#varcli |<^. Settings specific to the Command Line Interpreter | |<^. "Configuration":#varconfig |<^. Various OS related settings are stored as System Variables | |<^. "System":#varsystem |<^. Specify pathnames that will be searched for files during read or execute operations | |<^. "Obey files":#varobey |<^. Specify the directory from which an Obey file is being run | |<^. "Time and date":#vartimedate |<^. Used to evaluate time, date and years | |<^. "Return codes":#varcode |<^. Provides access to the last returned value given by [[OS_Exit]] | |<^. "!System":#varsyspath and "!Scrap":#varsyspath |<^. Provides full pathnames to the respective directories | |<^. "Desktop":#vardesktop |<^. Various settings and values specific to the desktop environment | |<^. "TaskWindow":#vartaskwindow |<^. Specify pathname to application that was used to start up task windows | |<^. "Devices":#vardev |<^. Various settings specific to devices attached to the system | |<^. "Printing":#varprint |<^. Specify various settings specific to the Printing device | h3(#varapp). 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":#name guidelines. Where you need a system variable and can’t find a relevant one below, you should use your own, naming it __App__$. table(bordered). |_<^{width:16em}. 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: <ul> <li>The pathname includes a trailing '.'</li> <li>The variable may hold a set of pathnames, separated by commas</li> </ul> Note: It is more common to use an _App_$Dir variable rather than an _App_$Path variable. </br> As example, an _App_$Path variable might be set in the application's !Run file by the following: </br> 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__ <ul> <li>An option that can be either on or off should consist of a single character, followed by the character ‘+’ or ‘-’ (eg M+ or S-)</li> <li>Other options should consist of a single character, followed by a number (e.g. P4 or F54)</li> <li>Options should be separated by spaces; so a complete string might be F54 M+ P4 S-</li> </ul> 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:</br> Set __App__$Options F54 M+ P4 S-</br> 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:</br> 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:<p> Set __App__$Resources __App__:Resources </p> 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:<p> If "__App__$Running" <> "" then Error __App__ is already running Set __App__$Running Yes</p> When the application stops running, you should use [[*Unset]] to delete the variable | h3(#varalias). Alias Variables table(bordered). |_<^{width:16em}. Example |_<^. Description | |<^. Alias$__Command__ |<^. Provides the ability to define a new command named Command. For example:<br /> <p> Set Alias$Mode echo <nowiki>|<22>|<%0></nowiki><br /> By using the name of an existing command, you can change how it works.<br /> </p> | h3(#varfileswitch). FileSwitch Variables table(bordered). |_<^{width:16em}. 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":FileSwitch%20Paths%20To%20Search%20For%20Files#special_field 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:<p> FileSwitch$__fs__$CSD FileSwitch$__fs__$PSD FileSwitch$__fs__$Lib FileSwitch$__fs__$URD</p> | h3(#varfiletype). File type Variables table(bordered). |_<^{width:16em}. Example |_<^. Description | |<^. File$Type_<em>XXX</em> |<^. 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: <p> Set File$Type_<em>XXX</em> __TypeName__ </p> 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_<em>XXX</em>, Alias$@PrintType_<em>XXX</em>, Alias$@RunType_<em>XXX</em> |<^. 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:<br /> <p> Set Alias$@PrintType_<em>XXX</em> /<Obey$Dir> -Print <br /> Set Alias$@RunType_<em>XXX</em> /<Obey$Dir><br /> <b>Note:</b> The above lines both have a trailing space (unable to be shown).<br /> </p> 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.<br /> More information is available in the [[FileSwitch Use Of File Types]] page | h3(#varfs). Filing System Variables table(bordered). |_<^{width:16em}. 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 | h3(#varfiler). Filer Variables table(bordered). |_<^{width:16em}. Example |_<^. Description | |<^. __FSTitle__$DefaultDir |<^. Defines an alternative directory to be used, instead of the root directory, when files are dropped on the iconbar filer icon to start a copy/move operation. An example to change the directory of the RAM filing system to is: <p> Set RAMFiler$DefaultDir Public </p> This sets a variable so that the RAMFiler saves the file to the Public folder on the RAM filing system instead of the root directory. | h3(#varcli). CLI Variables table(bordered). |_<^{width:16em}. 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:<br /> <p> SetMacro CLI$Prompt <Sys$Time> *<br /> </p> This sets a macro so that the system time variable is evaluated each time the command prompt is displayed | h3(#varconfig). Configuration Variables table(bordered). |_<^{width:16em}. Example |_<^. Description | |<^. Copy$Options, <br />Count$Options, <br />Wipe$Options |<^. Sets the behaviour of the [[*Copy]], [[*Count]] and [[*Wipe]] commands | h3(#varsystem). System Path Variables table(bordered). |_<^{width:16em}. Example |_<^. Description | |<^. File$Path and <br />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<br /> <p> 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:<br /> </p> If "<App$Path>" = "" then Set Run$Path <Run$Path>,<Obey$Dir>.bin.<br /> Set App$Path <Obey$Dir>.<br /> <p> More information on File$Path and Run$Path is available [[FileSwitch Paths To Search For Files|here]]| </p> h3(#varobey). Obey Variables table(bordered). |_<^{width:16em}. 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.<br /> <p>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.<br /> </p> 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:<br /> <p> / adfs::MikeWinnie.$.Odds’nSods.MyConfig<br /> Run adfs::MikeWinnie.$.Odds’nSods.MyConfig<br /> </p> This ensures that Obey$Dir is set to the full pathname of the Obey file.| h3(#vartimedate). Time and Date Variables table(bordered). |_<^{width:16em}. Example |_<^. Description | |<^. Sys$Time, <br /> Sys$Date, <br />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":#varcli | |<^. 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 [[Date Format String Tokens|here]] | h3(#varcode). Return Code Variables table(bordered). |_<^{width:16em}. 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 | h3(#varsyspath). !System and other !Boot related Variables table(bordered). |_<^{width:16em}. Example |_<^. Description | |<^. System$Dir and <br />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<br /> <p> <b>Note:</b> There are two versions of this pathname for reasons of backward compatability<br > </p> | |<^. 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 | h3(#vardesktop). Desktop Variables table(bordered). |_<^{width:16em}. 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’ | h3(#vartaskwindow). TaskWindow Variables table(bordered). |_<^{width:16em}. Example |_<^. Description | |<^. TaskWindow$Server |<^. Provides the pathname of the application used to start up task windows | h3(#vardev). Devices Variables table(bordered). |_<^{width:16em}. Example |_<^. Description | |<^. DeviceFS$__Device__$Options |<^. Provides the default options for a [[DeviceFS]] device | |<^. |<^. | h3(#varprint). Printer Variables table(bordered). |_<^{width:16em}. Example |_<^. Description | |<^. PrinterType$__n__ |<^. Provides the path used to print to printer type __n__. For example:<br /> <p> *Show PrinterType$0<br /> PrinterType$0 : null:<br /> </p> | h2(#type). Type of System Variables There are several types of system variable table(bordered). |_<^{width:8em}. Type |_<^. Description |_<^{width:8em}. How to Set |_<^{width:8em}. 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]] | |/3<^. 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_GSRead]]able items, the appropriate translation takes place whenever the variable is accessed |/3<^. [[*SetMacro]] |/3<^. [[*Unset]] | |<^. Example: To set the command line prompt (<code>CLI$Prompt</code>) to the current time, followed by a space, you would use: | |<^. <code>*SetMacro CLI$prompt <Sys$Time><&20></code> | |/3<^. 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 |/3<^. [[OS_SetVarVal]] |/3<^. [[OS_SetVarVal]] | |<^. Example: you could make a variable directly control a CMOS RAM location using this technique| |<^. <code>Sys$Time</code> is a good example of a code variable | h3. Notes * All the different System Variable types can be: ** set with [[OS_SetVarVal]] ** read with [[OS_ReadVarVal]] ** unset with [[OS_SetVarVal]] * Any non-code variables can be: ** removed using the [[*Unset]] command * List all System Variables: ** displayed using the [[*Show]] command h2(#name). 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. h3. See also * [[FileSwitch Paths To Search For Files]]