RISCOS.com

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

 

RISC OS boot applications


Introduction and Overview

A boot application sets the machine up whenever the computer is reset, giving users and applications control over the start up, configuration and use of the desktop. It also works interactively when a user double clicks on its icon.

RISC OS 3.5's boot application is named !Boot. RISC OS 3.6 introduced a wider range of boot applications (eg !Boot for booting from disc, !ArmBoot and !ShareBoot for booting from a remote machine or server on a network). You can use boot applications to boot older machines.

A boot application provides:

  • startup files that applications can modify
  • facilities to link applications into the Apps icon's directory display
  • desktop boot saving
  • locations for saving application-specific choices
  • computer configuration using !Configure, which is held as a sub application
  • hard disc locking with a password, as a part of !Configure
  • !System, !Scrap and !Fonts as sub applications that are unseen by the user.

This chapter details the facilities provided by boot applications for integrating applications into the desktop, and that will continue to be supported in the future. Unless otherwise stated, all such facilities are available from RISC OS 3.5 onwards.

Although a search through a boot application will doubtless reveal features that are not documented here, you must not use them if you wish your application to work under future versions of RISC OS.

The user interface is described in the RISC OS 3 User Guide.

Technical details

Writing to a boot application

Amongst other things, this chapter tells you ways you can add to the files in a boot application. When doing so you must be aware that you may not have write permission, especially if the boot application is on a remote file server. If you try to write to a boot application, and the write fails, your software should fail gracefully, giving a suitable error message.

Starting the boot application

The kernel determines which boot application to run depending on the configured Boot state, filing system, drive/file server, and so on. It then tries to find the boot application. If it fails, it saves the resultant error message in the system variable Boot$Error; if it succeeds, it runs the boot application.

Environment set up

The Boot$... variables

Once a boot application has been found and run, it sets up a number of system variables as it first starts:

Variable Comments
Boot$Dir The boot application's directory
Boot$OSVersion The major version of RISC OS on the booting computer: for example '200', '310', '350', or '360'
Boot$Path Comma separated list of boot application directory(s), each with a trailing '.'
Boot$State The stage of booting: 'commands' or 'desktop'
Boot$ToBeLoaded PreDesk directory (see The PreDesk directory)
Boot$ToBeTasks Tasks directory (see The Tasks directory)
Boot$Unique 'Local' if the boot file is local; a unique identifier for the machine if the boot file is remote

(The RISC OS 3.5 !Boot application does not set the Boot$State and Boot$Unique variables.)

The Choices$... variables

It then uses these variables to set up other variables giving the location(s) of Choices directory(s), which are used by applications - including the Boot application itself - to store start-up files, user preferences, and so on:

Variable Comments
Choices$Dir Most recently used Choices directory
Choices$Path Comma separated list of Choices directory(s) from which to read, each with a trailing '.'
Choices$Write Choices directory to which to write
Choices directories

A boot application may have multiple Choices directories, and so store different choices for different machines, such as remote network stations. Each Choices directory can have the same structure beneath it, varied as required by the different machine(s) using each one.

RISC OS 3.6's network boot applications set the Choices$... variables to use the directory Boot:MchConfig.<Boot$Unique> out of preference, if it exists; failing that, to use Boot:Utils.RO<Boot$OSVersion>Hook if that exists, or otherwise to use Boot:Choices. Remote network stations will thus look for machine-specific choices; then either for RISC OS version-specific choices, or for system-wide choices. Network managers can hence use these different directories to support a mix of versions of RISC OS, and to provide machine-specific exceptions to the general setup.

For example, with the boot application Net::Server.$.!ArmBoot, these directories might be named:

  • Machine-specific choices:
    Net::Server.$.!ArmBoot.MchConfig.Stn128!005 or:
    Net::Server.$.!ArmBoot.MchConfig.E1268AFB etc
  • RISC OS version-specific choices:
    Net::Server.$.!ArmBoot.Utils.RO200Hook or:
    Net::Server.$.!ArmBoot.Utils.RO310Hook etc
  • System-wide choices:
    Net::Server.$.!ArmBoot.Choices

You must not access the Choices directories by evaluating their full pathnames yourself, as the internal structure of boot applications is liable to change in future versions. You must instead use the methods described in the sections below.

Loading CMOS

After setting these system variables, the next thing of interest the boot application does is to look for the file:

<Boot$Dir>.MchConfig.<Boot$Unique>.!RO<Boot$OSVersion>CMOS

If it exists, the boot application uses the *LoadCMOS command to load the contents of the file into CMOS RAM.

Files used before the desktop is started

The boot application then runs things before the desktop is entered. It uses two locations for this:

  • The PreDesktop file is an Obey file. It creates various useful aliases for common tasks.
    You can add to this file as necessary, in the manner described below. If you only need to use an Obey file, this is the preferred method to use.
  • The PreDesk directory holds files and directories all of which are run after the PreDesktop file.
    Adding files and directories here gives you much more flexibility over how they are run. You should use this method if your needs are not met by the PreDesktop file.

For full details, see the sections below.

The PreDesktop file

The PreDesktop file contains the command line setup sequence. It gets invoked using Obey -c where possible, so that filing system or network software can be reloaded during its execution.

Accessing the file

The PreDesktop file must always be accessed as:

<Choices$Write>.Boot.PreDesktop

This is to preserve future compatibility, should the structure of boot applications change.

Format of the file

The file has been divided into well defined sections for ease of maintenance, and to make it easy for scripts to install and remove application-specific entries. Each section starts with a header:

|Start Company Application Version Section

and ends with a footer:

|End

As an example, the Aliases section supplied by !Boot in RISC OS 3.5 looks like this:

|Start Acorn !Boot 0.25 Aliases
commands and comments...
|End

Scripts that scan the file should be extremely lax in what they accept. They should accept any amount of white space between each element (including before and after the '|' that introduces the header/footer), ignore case, and ignore the version numbers used by other applications.

When writing to the file scripts should use the exact syntax in the above example; see Adding to the file.

Sections

The sections supplied by a boot application are:

  • Comments
  • Aliases
  • Paths
  • Options
  • ResApps
  • Miscellaneous options.

These are described in more detail below, starting with Comments.

Adding to the file

Wherever possible, you should split anything you add into the same sections as above, each of which includes a header and footer. Each application should provide a script to install its sections. For each section, the script must:

  1. Search for the boot application's corresponding section.
  2. Add the new section after the boot application's corresponding section.

So a finished file might look like this:

|Start Acorn !Boot 0.25 Comments
comments...
|End
|Start Acorn !Boot 0.25 Aliases
commands and comments...
|End
|Start Acorn !Boot 0.25 Paths
commands and comments...
|End
|Start Acorn !Boot 0.25 Options
commands and comments...
|End
|Start MySWHouse !MyApp 1.10 Options
commands and comments...
|End
|Start Acorn !Boot 0.25 ResApps
commands and comments...
|End
|Start Acorn !Boot 0.25 Miscellaneous options
commands and comments...
|End

It is courteous to also supply a script to remove the entries.

Comments

The function of this section should be obvious!

Aliases

This section sets aliases.

A boot application's section adds several aliases that you may find useful yourself:

Alias

The first alias set is for Alias itself, so that the following command:

Alias alias command

sets the alias alias for the command command.

Unalias

This makes the command Unalias to remove an alias:

Unalias alias
Path

The next alias gives a convenient way to set setting of paths:

Path path full_path

so you can refer to a full pathname full_pathrest using the shorthand path:rest. For example:

Path lib ADFS::HardDisc4.$.Library.

would enable the following convenient commands:

*Dir lib:
/lib:cc
PathMacro

PathMacro works similarly to Path, except the system variable set is a macro variable. For example:

Set Thing$Dir <Obey$Dir>
PathMacro Thing <Thing$Dir>.

To enable Thing: to be a reference to <Thing$Dir>.

Paths

This section is used to set standard paths and directories.

Run$Path is defined here to include the Library directory held within the boot application. This allows you to use the various commands held in the library, and defined in * Commands.

Options

This section has been set aside for options that do not have any other place to be set.

ResApps

This section uses the AddApp library command (see *AddApp) to register applications with ResourceFS for display in Resources:$.Apps.

A boot application's ResApps section registers all applications in Boot:^.Apps:

AddApp Boot:^.Apps.!*
Miscellaneous options

This section is used for any setup that does not obviously belong in any of the above sections. An example might be loading and binding a novel system beep.

The PreDesk directory

Accessing the directory

The PreDesk directory must always be accessed as:

<Boot$ToBeLoaded>

This is to preserve future compatibility, should the structure of boot applications change.

Adding files and subdirectories

Your application !App may add a single file or subdirectory named App. You should only do so if the PreDesktop file does not meet your needs, since if too many applications use this directory, it may become full.

Your application may modify its own file(s) as it sees fit.

Action taken on files and subdirectories
RISC OS 3.60

Under RISC OS 3.60, the files held within the PreDesk directory are acted on as follows:

  • Any files of type Obey are run using *Obey -c, or *Obey for versions of RISC OS where the -c flag is not supported.
  • Any files of type Absolute are run.
  • Any files of type Sprite are loaded using *IconSprites.
  • Any files of type Module are loaded using *RMLoad.
  • Any files of type BASIC are run using *BASIC -quit.
  • Any files of type Utility are run.

All other files are loaded using *Load.

Then any directories are run; this searches for the file !Run in the directory, and runs it if found.

RISC OS 3.50

Under RISC OS 3.50, the files and directories held within the PreDesk directory are acted on in the following order:

  1. Any files of type Module are run using *RMLoad.
  2. Any files of type Sprite are run using *IconSprites.
  3. Any files of type Obey are run using *Obey -c.
  4. Any directories are run using *Run; this searches for the file !Run in the directory, and runs it if found.

All other files are ignored.

Files used once the desktop is started

Desktop saving

The method for saving the desktop from the Task Manager remains the same as before, and is still the preferred way for applications to set themselves up and start. You should continue to use desktop saving provided it meets your needs.

If it does not meet your needs, you should read the sections below.

Other files

Earlier sections described how boot applications provide a file and a directory that are used to run things before the desktop is entered. They provide a similar file and directory that your application can use to start itself and/or any associated tasks:

  • The Desktop file is a file of type Desktop, run as the desktop is entered. It boots important system resources.

    You can add to this file as necessary, in the manner described below. If you only need to use a Desktop file, but cannot use the Task Manager's desktop boot file, then it is preferable to use this file rather than adding to the Tasks directory.

  • The Tasks directory holds files all of which the Desktop file starts as Wimp tasks, including the desktop boot file saved from the Task Manager.

    You should only add files here if your needs are met neither by the Task Manager's desktop boot file, nor by the Desktop file.

For full details, see the sections below.

The Desktop file

Accessing the file

The Desktop file must always be accessed as:

<Choices$Write>.Boot.Desktop

This is to preserve future compatibility, should the structure of boot applications change.

Format of the file

The file has the same format as the PreDesktop file. It is split into sections using headers and footers with the same syntax. See Format of the file.

Sections

The sections supplied by a boot application are:

  • Auto tasks
  • Completion

The Auto tasks section is described in more detail below.

Adding to the file

You should add sections to the Desktop file in just the same way as for the PreDesktop file. See Adding to the file.

Note that you should only add an Auto tasks section. There should be no Completion section in the file apart from that provided by the boot application itself.

Auto tasks

This section boots all the system resources held in Boot:Resources:

Repeat Filer_Boot Boot:Resources -Applications -Tasks

This includes such things as !System, !Scrap and !Fonts.

It then runs all the files in the Tasks directory as Wimp tasks:

Repeat Filer_Run <Boot$ToBeTasks> -Tasks

The Tasks directory

Accessing the directory

The Tasks directory must always be accessed as:

<Boot$ToBeTasks>

This is to preserve future compatibility, should the structure of boot applications change.

Adding files and subdirectories

Your application !App may add a single file or subdirectory named App. You should only do so if the Desktop file does not meet your needs, since if too many applications use this directory, it may become full.

Your application may modify its own file(s) as it sees fit.

Action taken on files

The files and directories held within the Tasks directory are run using Filer_Run.

Storing application choices

Your application !App can create its own Choices directory, and use it to store user preferences.

Accessing the directory

Your application !App must always access its Choices directory as:

<Choices$Write>.App

This is to preserve future compatibility, should the structure of boot applications change.

Adding files and subdirectories

Your application !App may add any files or subdirectories it needs to. It may modify its own file(s) as it sees fit.

Changes to existing * Commands

*Logon

You should note that from RISC OS 3.6 onwards, the Boot application aliases the *Logon command to *SafeLogon, described on *SafeLogon. (Although this is not strictly a change to the *Logon command, most people will see it as such.)

In the unlikely event you need to force the use of the standard *Logon command, you must do so by using the '%' character to skip alias checking (see CLI effects), rather than by unsetting the variable Alias$Logon. This ensures that the change only applies to your command line, and does not alter the environment other programs expect to find.

The BootCommands module

A boot application uses various commands not provided by RISC OS 3.1 or earlier.

In RISC OS 3.5, these are provided by the boot application's Library subdirectory, which is added to the run path when the boot application is first run. In RISC OS 3.6 most of these are instead provided by a new module named BootCommands.

The advantage of the BootCommands module is that it avoids the need to load the commands over the network if a station is using a remote boot application. Booting is thus made faster.

* Commands


*AddApp

Adds entries in Resources:$.Apps for all applications matching a wildcard pattern

Syntax

*AddApp [directory.]pattern

Parameters
directory - a valid pathname specifying a directory

pattern - wildcarded pattern to match

Use

*AddApp adds entries in Resources:$.Apps for all applications matching the wildcard pattern in the given directory, or in the current directory if none is specified. If nothing matches the pattern, no error is generated; the command just returns.

You must not use this command to add applications that are already held in ResourceFS.

This command is provided either by the boot application's Library subdirectory (which is added to the run path when the boot application is first run), or by the BootCommands module added in RISC OS 3.6.

Example

*AddApp ADFS::MHardy.$.MyApps.*

Related commands

None


*AppSize

Moves memory into or out of the RMA

Syntax

AppSize size[K]

Parameters

size[K] - number of (kilo)bytes of memory desired for applications

Use

*AppSize moves memory into or out of the RMA, attempting to move the difference between the current size of application workspace and the given desired size. In RISC OS 3.1 and earlier, the memory was transferred to/from the application workspace (hence the name of the command); from RISC OS 3.5 onwards, memory is transferred to/from the free pool.

This command is used at startup to shrink the RMA to its smallest possible size by setting the desired application size to a large value, and should not be used by other applications.

This command is provided either by the boot application's Library subdirectory (which is added to the run path when the boot application is first run), or by the BootCommands module added in RISC OS 3.6.

Example

AppSize 514000K

Related commands

None


*Do

Passes a command to XOS_GSTrans, and then passes it to the CLI

Syntax

*Do command

Parameters
command - command to have GSTrans'd before execution
Use

*Do passes a command to XOS_GSTrans, and then passes it to the CLI.

It is useful when the command being invoked does not itself GSTrans its parameters, but you wish to pass parameters using GS string format (eg system variables). For more details, see GS string operations.

This command is provided either by the boot application's Library subdirectory (which is added to the run path when the boot application is first run), or by the BootCommands module added in RISC OS 3.6.

Example

*Do BadCmd <Obey$Dir> - Expands Obey$Dir before calling BadCmd

Related commands

None


*FontMerge

Merges new fonts into an existing !Fonts directory

Syntax

FontMerge source [destination]

Parameters

source - source directory of fonts to merge

destination - destination directory of fonts to merge

Use

*FontMerge merges new fonts into an existing !Fonts directory. The first thing it does is to work out the destination for the merge.

If no destination is given, the third-from-last element of Font$Path is used. This may seem a bit strange, but consider what Font$Path will look like:

Font$Path(Macro): ADFS::HardDisc4.$.!Boot.Resources.!Fonts.,<Font$Prefix>.,Resources:$.Fonts.

The last element is in the Resource filing system, which cannot be used as the destination. The next-to-last element is <Font$Prefix>; this is provided for backwards compatibility, so it is not a good idea to use it as the destination. The third-from-last element is therefore the one used.

*FontMerge can automatically create and use an overflow directory should the original destination become full. For a directory !Fonts, the overflow directories are !Fonts1, !Fonts2, and so on. *FontMerge checks for the presence of such overflow directories, and uses the highest numbered one as the initial destination.

Once *FontMerge has worked out the destination, it merges the fonts, creating overflow directories as necessary. It automatically processes font messages files, generating them for all languages given in the source and destination.

*FontMerge can be run from desktop applications. It initialises itself as a Wimp task to generate Wimp error boxes if it has an error; it calls Hourglass_Percentage as it does the merge.

This command is provided by the boot application's Library subdirectory (which is added to the run path when the boot application is first run). *FontMerge is a directory, and should be left as such. This is to enable *FontMerge to be localised for a particular country simply by replacing the messages file inside the FontMerge directory. Even though *FontMerge is a directory and not a file, you use it just like any other command line program.

Example

*FontMerge ADFS::FontVendor.$.!Fonts

Related commands

None


*IfThere

Checks for the presence of a given object, and executes one command if it exists, or another if it does not

Syntax

*IfThere object_spec Then true_command [Else false_command]

Parameters

object_spec - a valid (wildcarded) pathname specifying a file or directory

true_command - command to execute if object_spec is matched

false_command command to execute if object_spec is not matched

Use

*IfThere checks for the presence of the given object, and executes the true command if it exists, or the optional false command if it does not.

The check is done using OS_File 17. Note that non-files (eg directories and partitions) will still cause the true command to execute.

This command is provided either by the boot application's Library subdirectory (which is added to the run path when the boot application is first run), or by the BootCommands module added in RISC OS 3.6.

Example

*IfThere ADFS::MHardy.$.Run Then Delete ADFS::MHardy.$.Run

Related commands

None


*LoadCMOS

Loads a file into the computer's CMOS RAM

Syntax

*LoadCMOS filename

Parameters

filename - a valid pathname specifying a file

Use

*LoadCMOS loads a file into the computer's CMOS RAM, preserving only the station number, the current year, and the DST flag. All other configured values are replaced by those stored in the file.

This command is used by boot applications to load a station's CMOS RAM at startup time, thus ensuring the machine is always in the same state. The boot application searches for the file:

<Boot$Dir>.MchConfig.<Boot$Unique>.!RO<Boot$OSVersion>CMOS

and, if it finds the file, uses this command to load it. Note that the location of saved CMOS files is subject to change in future versions of boot applications.

This command is provided by the BootCommands module added in RISC OS 3.6. Unlike most other commands documented in this chapter, it is not a standard part of the RISC OS 3.5 boot application.

Example

*LoadCMOS ADFS::MHardy.$.Safe.MyCMOS

Related commands

None


*Repeat

Scans a given directory, applying a command to everything it finds

Syntax

*Repeat command directory [-Directories] [-Applications] [-Files|-Type file_type] [-CommandTail cmdtail] [-Tasks]

Parameters

command - command to apply to objects in the given directory

directory - a valid pathname specifying a directory

-Directories - apply the command only to directories

-Applications - apply the command only to applications

-Files - apply the command only to files

-Type - apply the command only to files of type file_type

file_type - a number (in hexadecimal by default) or text description of the file type to match. The command *Show File$Type* displays a list of valid file types.

-CommandTail - postfix the found object with cmdtail

cmdtail - command tail to apply to objects in the given directory

-Tasks - apply the command as a Wimp task

Use

*Repeat scans the given directory applying a command to everything it finds, within the limits of the other parameters. The command executed is:

command found_object [cmdtail]

This utility does not recurse. Only those objects identified at the top level have the command applied to them.

This command is provided either by the boot application's Library subdirectory (which is added to the run path when the boot application is first run), or by the BootCommands module added in RISC OS 3.6.

The Library-based version uses the Scrap directory, and hence there must be some free space on the file system holding !Scrap for it to work. The BootCommands version does not have this limitation.

Example

*Repeat Filer_Boot Boot:Resources -Applications -Tasks

Related commands

None


*SafeLogon

Logs you on to a file server if you are not already logged on

Syntax

*SafeLogon [[:]file_server_number|:file_server_name] user_name [[:Return]password]

Parameters

file_server_number - the file server number to log on to

file_server_name - the file server name to log on to

user_name - as issued by the network manager

password - as set by the user

Use

*SafeLogon logs you on to a file server if you are not already logged on.

The command first checks to see if the current temporary filing system is NetFS, and the given user is already logged on to the given file server; if so, the command exits immediately. Otherwise the command passes on a *Logon command to the current temporary filing system, leaving the command line tail unaltered.

This means that - unlike *Logon - *SafeLogon will not log you off a file server, and then immediately log you back on.

This command is provided by the BootCommands module added in RISC OS 3.6. Unlike most other commands documented in this chapter, it is not a standard part of the RISC OS 3.5 boot application.

Example
*SafeLogon :fs guest
Related commands

*Logon

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