Application and system configuration is held in a group of central repositories. Applications may be shared between a number of different users, and therefore their configurations should not be locked to that application. As a result of this, it is possible to have a hierarchy of configuration details which allows (in the most common case) the application to use system defaults, or user specific settings.
Two system variables are used in the configuration of applications -
Choices$Path and
Choices$Write. Applications should not
attempt to process Choices$Path directly, but should use
it only in via the filename Choices:.
Applications must read from Choices:* and write to
Choices$Write.*Choices$Write.*Choices:*.
Applications may assume that
Choices$WriteChoices$WriteChoices: may be assumed to exist.
The generic form of naming of files within the Choices structure is :
<application>.<file>
Any number of files may be stored within the application specific directory of the Choices structure, but authors should be aware that the filing system on which the choices are stored may be limited to 77 files per directory, or 10 character filenames as determined by the file system itself. Whilst authors should not worry unduly about this, it should be a factor in naming such files.
Whilst it is possible to store files without using a sub-directory - ie, just storing a file in the hierarchy with the same name as that of the application, this is not recommended. Such use precludes the additional of other configuration files for that application, should future versions require them.
An alternative form of naming files which may be used is :
<author>.<application>.<file>
In this case, the <author> should be the well
known name of the group issuing the product, such as
MegaCorp, or JBloggs. As with the
files themselves, the filesystems constraints on naming should be considered
when selecting such names.
A more wide spread and preferred form of naming files which may be used is that of grouping by the category into which the application falls :
<category>.<application>.<file>
The <category> name should be chosen to avoid clashes between it and application names.
Categories currently known to be in use - this is in no way an exhaustive list - include :
| Category | Contents |
|---|---|
| !ZapUser | Zap modules and resources for the user live here. |
| Boot | Resources relating to the booting of the machine live here. |
| Audio | Audio applications should store their details here. |
| IRC | IRC related applications should store their details here. |
| ScrSavers | RISC OS 4-style screen savers should store their details here. |
| USB | USB devices should store their details here. |
| WWW | World Wide Web related applications should store their details here. |
Authors wishing to create new categories should consider whether this is in fact the best course of action. Consultation with other developers working on similar projects is recommended.
When you register an application name (and have had it confirmed), this also includes an allocation in the Choices hierarchy of the same name. This should be borne in mind when naming applications.
If a new category name is to be used, it should also be registered, as should author name groups.
Whilst it is recommended that configuration files contain textual configuration data, it is entirely the choice of the application what data it should store.
No application should ever crash because of a poorly formatted configuration file. Loading an entire file into a structure (in C or Assembler) or fixed length buffer is likely to cause problems if the file is corrupt in any way. Reading textual strings in BASIC should be checked for overly long strings. Non-existent tags (in tagged files) should be given default values. It is recommended that if a corrupt configuration file is identified it be ignored and the defaults used.
In general, applications should not write choices unless the user explicitly requests this. This is not practical in some situations, particularly where the choices require a reload to take effect. Care should be taken to ensure as far as is possible, that the configuration presented to the user is preserved fully within the files written.
In particular applications should not write choices when they quit. Doing so may cause invalid choices to be written, or (in the case of defaulted choices) overwrite the user selected choices. The only exception to this is where the user has chosen to write choices on application quit.
Previous versions of this document dealt with support for systems where
Choices$* were unset. Such system are should no longer be
supported. It is strongly recommended that applications fault the lack of
Choices$Write in their !Run file.
An application, !Choices has been provided for
systems without a suitable boot sequence, should this be necessary. In
general, support for such systems should be discontinued.
This variable contains a reference to the highest level (usually the users) configuration directory. It is now obsolete and should not be used by any applications.
This variable contains the name of the directory into which configuration details should be written. It is used to write out user-specific configuration details, which will override any others which may have been given in Choices$Path.
Applications should never use the directory given in this variable for any form of read operation. The directory specified may be assumed to exist and be writable.
This variable contains a comma separated list of paths which will be
searched to locate configuration details. This list will be searched in
order from beginning to end until a match is found. It is usual for the
first entry in Choices$Path to be
Choices$Write.Choices: rather than attempting
to expand this variable themselves.
This variable should never be used directly by applications. The path
Choices: should never be used for write operations.
| Maintainer(s): | Justin Fletcher <justin.fletcher@ntlworld.com> | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| History: |
| ||||||||||||||||||||||||
| Disclaimer: |
This document is based on my own experiences as a developer and is not an officially sanctioned document. It describes what I believe to be the Best Common Practices for applications using Choices. |