WASD VMS Web Services - Install and Config

10 - Message Configuration

10.1 - Behaviour 10.2 - Message File Format 10.3 - Multiple Language Specifications 10.4 - Supplied Message Files
next previous contents full-page

By default, the logical name WASD_CONFIG_MSG locates the global message configuration file. A text editor may be used to modify this configuration file. Changes require a server restart to put them into effect.

Message configuration is provided for two purposes.

  1. Some sites would prefer to customize or extend the basic information provided to clients when an error or other event occurs.
  2. Sites that do not use English as a first language may wish to provide some or all of the defined messages using a prefered language.

Not all messages provided by the WASD server are customizable, only those generated for non-administrative content. As the WASD server can also report using information derived from the standard VMS message service (via sys$getmsg()) it is assumed a language-local implementation of this is in use as well. Unfortunately for the non-first-language-English Web and system administrators, the menus and messages used for administration purposes, etc., are still only in English. The intent of this facility is to provide non-administration clients only with a more familiar language environment.

Also note that the message database only applies to messages generated by the server, not to any generated by scripts, etc.

Changes to the message configuration file can be validated at the command-line before restart. This detects and reports any syntactical and fatal configuration errors but of course cannot check the intent of the rules.

$ HTTPD /DO=MSG=CHECK

10.1 - Behaviour

When an error, or other message or string, needs to be provided for the client the message database is accesssed using the following algorithm.

  1. If the client request has specified a list of prefered languages using the "Accept-Language:" HTTP header field the message database is checked for support of that/those languages. If one is found then that language is used to access the message.
  2. If none is found, or the client has not specified a prefered language, the client host address is checked against any list of hosts/domains provided against the language (see below). If a match occurs the specified language is used.
  3. If neither of the above results in a message language the base language is used (the highest numbered language). This must have a complete set of messages or the server will not start!

10.2 - Message File Format

By default, the system-table logical name WASD_CONFIG_MSG locates a common message file, unless an individual message file is specified using a job-table logical name. Simple editing of the message file changes the messages (after a server restart, of course). Comment lines may be included by prefixing them with the hash character ("#"), and lines continued by ensuring the last character is a backslash ("\"). The server will concurrently support an additional 3 languages to the base English (although this can be increased by recompilation :-)

NOTE

Care must be taken with the message file or the server may refuse to start!
Worst-case; the WASD_CONFIG_MSG.CONF message file may be copied from [EXAMPLE].

As illustrated below the message file comprises a series of sections. Directives enclosed by square-brackets provide information to the message loader.

# this is a comment

[version]   9.0
[language]  1  en

[general]

en 01 Sanity check failure.
en 02 String overflow.
en 03 Heap allocation failed.
en 04 calloc() failed
en 05 Request calloc() failed.
en 06 Server too busy.
en 07 Server access denied.
en 08 Facility is disabled.
en 09 Wildcard not permitted.
en 10 Directory layout problem.

[next-section, etc.]
The square-bracketed section headings have the following functions.

The base language (the highest numbered, which should always be English) must have precisely the right number of messages required by the server, too few or too many and the server will not start! Additional languages do not have to reassign every message! The base language will supply any not assigned. A message number of zero is disabled and completely ignored.

If messages contain HTML tags that markup must not interfere with the general HTML page it is used within.

Some messages are a composite of multiple strings each of which is used on a different part of the one page (e.g. for the [upd] edit-page). Each of the strings is delimited by the vertical bar "|". Care must be taken when customizing these strings that the overall number stays the same and that the length of each does not become excessive. Although it will not disrupt the server it may significantly disrupt the page layout.

All message numbers must be included. To provide an empty string for any one message (not recommended) provide the line with nothing following the message number.

10.3 - Multiple Language Specifications

Multiple language messages can be specified in two ways:

Within The One File

Language availability is specified through the use of [Language] directives. These must be numbered from 1 to the count of those supplied. The highest numbered language must have the complete set of messages for this is the fallback when obtaining any message (this would normally be "en"). The [Language] may be specified as a comma-separated list of equivalent or similar specifications, which during request processing will be matched against a client specified list of accepted-languages one at a time in specified order. A wildcard may be specified which matches all fitting the template. In this manner a single language can be used also to match minor variants or language specification synonyms.

[Version]  9.0
[Language]  1  es,es-ES
[Language]  2  de,de-*
[Language]  3  en

[auth]
es 01  Habla Espanol
de 01  Sprechen Sie Deutsches
en 01  Do you speak English
.
.
.(full set of messages)
In the above (rather contrived) example a client request with
Accept-Language: es-ES,de;q=0.6,en;q=0.3
would have language 1 selected, a client with
Accept-Language: de-ch,es;q=0.6,en;q=0.3
language 2 selected, with
Accept-Language: pt-br,de;q=0.6,en;q=0.3
also language 2 selected, with
Accept-Language: pt
language 3 (the default) selected, etc.

Note that the messages for each language must use the *first* language specification provided in the [Language] list. In the example above all messages for language 1 would be introduced using 'es', for language 2 with 'de' and for language 3 with 'en'.

Multiple Files - Multivalued Logical Name

With this approach a logical name containing multiple file names is defined (more commonly described as a logical search list). The final file specified must contain the full message set. Files specified prior to this, can contain as many or as few of the full set as is desired. A [Language] number does not need to be specified as they are processed in the order the logical name specifies them in. Other language file directives are required.

The following is an example of a logical name providing the same three languages in the examples above.

$ DEFINE /SYSTEM WASD_CONFIG_MSG WASD_ROOT:[LOCAL]WASD_CONFIG_MSG_ES.CONF, -
                           WASD_ROOT:[LOCAL]WASD_CONFIG_MSG_DE.CONF, -
                           WASD_ROOT:[LOCAL]WASD_CONFIG_MSG.CONF

The file contents would be as follows (very contrived examples :-)

# WASD_CONFIG_MSG_ES.CONF
[Version]  9.0
[Language]  0  es,es-ES
[auth]
es 01  Habla Espanol
es 02  Habla Inglesi
[dir]
es 03  Habla Espanol
es 04  Habla Inglesi

# WASD_CONFIG_MSG_DE.CONF
[Version]  9.0
[Language]  0  de,de-*
[auth]
de 01  Sprechen Sie Deutsches
de 02  Sprechen Sie Englisch
[dir]
de 03  Sprechen Sie Deutsches
de 04  Sprechen Sie Englisch

# WASD_CONFIG_MSG.CONF
[Version]  9.0
[Language]  0  en
[auth]
.
.
.(full set of messages)

The major advantage of maintaining multiple files in this way is there is no need to merge files when a new revision is required. Just update the version number and add any new required messages to the existing secondary file.

10.4 - Supplied Message Files

Any non-English message files that are provided to the author will be included for general use (please take the time to support this endeavour) in the WASD_ROOT:[EXAMPLE] directory.

Note that message files can become out-of-date as server versions change, requiring modifications to the message database. Check the version information and/or comments at the top of candidate message files, however even slightly dated files may serve as a good starting point for a locale-specific message base.


next previous contents full-page