Creating a Source File

A source file is an MPE ASCII file in an EDIT/V-compatible format created in your favorite editor. The catalog contains messages to be output to users. The messages are divided into logical groupings of sets.

This section takes you through the tasks of:

Specifying comments, sets, and messages with directives.
Using special characters in your messages.
Substituting parameters in your messages.

Directives

A source catalog contains directives that partition information in the message catalog and indicate the beginning of each record. Directives are not printed out when the catalog is accessed and always begin in column one. There are three types of directives in a source file:

$ to denote comment records.
$SET or $set to mark the beginning of a $SET record.
Message numbers to indicate message records.

Blank lines are not allowed in a message catalog.

Comment Records

Comments are used throughout the catalog to document sets and messages, and to make them easier to read. The format of a comment record, where comment is an optional string of characters is:

     $comment

A space between $ and comment is optional.

$SET Records

A $SET record initiates a logical grouping of messages.

Sets break the catalog into manageable segments containing logical groupings of messages (for example, one set of messages for prompts, one set for instructions, one set for error messages). Each set is identified by a set number. Set numbers:

Identify each set.
Must be in ascending sequence and unique within the catalog that contains them.
Do not need to be consecutive.
Must be greater than 0 and less than 256.
May have leading zeros.

The format of a $SET record where setnum, an integer, is the required set number is:

     $SET setnum comment

                - or -

     $set setnum comment

The comment is an optional text string that must be separated from the set number by a blank. You may use $SET or $set, but not $Set or any variation of mixed cases. Examples of set directives are:

     $SET 1 Prompts

     $

     $set 2 Error messages

Note the use of a blank comment record for clarity.

Message Records

Message records contain the messages that are output to the user. Message records consist of a message number followed by the message text. This text may be an error message, prompt, or any text which may change according to the language or the country where the program will be used. Message record numbers:

Identify message locations within a set.
Must be in ascending sequence and unique within the set that contains them.
Do not need to be consecutive.
Must be greater than 0 and less than 32,767.
Must begin in column one.
May have leading zeros.

For example, within a set, you can have messages 1-25, 101, 300-332, and 32,766. All of these message numbers can be used again in another set. The format for a message record where msgnum, an integer, is the required message number is:

     msgnum message text

The message text is an optional character string which follows the message number. If the text is not preceded by a blank, GENCAT replaces the character immediately following the message number with a blank and informs you that a blank has replaced the character. An exception is made if one of two special characters, "%" or "&," follow the message number. These characters will not be replaced by a blank. Their meaning is explained in the following section.

An example of message records, set directives, and comments follows:

     $SET 1 Prompts

     1 ENTER FIRST NAME

     2 ENTER LAST NAME

     $

     $

     $set 2 Error Messages

     1 NAME NOT ON DATA BASE

     2 ILLEGAL INPUT

Special Characters

Special characters are used to control the format and content of messages when the messages are output.

% - allows the message record to remain on several lines when printed out. It breaks up a line by posting a carriage return/line feed before writing the next record. For example:
3 AN ERROR OCCURRED DURING THE LOADING % OF THE DATA BASE.
When this message is accessed, it results in a display of:
AN ERROR OCCURRED DURING THE LOADING OF THE DATA BASE.
& - indicates that the message record is continued on the next line in the source file but is printed out as one line. For example:
98 THE NUMBER OF FILES & DOES NOT MATCH THE & SYSTEM'S CALCULATIONS.
When this message is accessed, it is displayed as:
THE NUMBER OF FILES DOES NOT MATCH THE SYSTEM'S CALCULATIONS.
Note the use of blanks as separators preceding the ampersand.
~ - indicates a literal character The special character that follows it is treated as a part of the message and is printed out when accessed. If you want a tilde in your message, you must put two tildes in a row.
! - indicates the position for a parameter to be substituted in at run time. This is explained in detail below.

Parameter Substitution

Parameter substitutions are used to insert values that will be known at run time into your messages. An exclamation mark (!) is used within a message to indicate where the parameter is to be inserted. ! is treated as a special character; if you want to use an exclamation point in your message, use the tilde before it. You are allowed up to five parameter substitutions in each message. The parameters that are substituted are strings with an ASCII null as the last character. You may choose positional or numerical parameter substitution. Mixing these two types within a message is not allowed; if you do so, GENCAT will not create a formatted file.

The CATREAD intrinsic, shown in the following examples, retrieves a message from the catalog and substitutes the necessary prarmeters. Using CATREAD is discussed in Chapter 3.

Positional Parameter Substitution

Positional parameter substitution allows the parameters to be substituted from left to right. The example listed below will demonstrate the use of positional parameter substitution.

Using the following values for parameter substitution:

     var

       Parm_1 : packed array of CHAR [0:5];

       Parm_2 : packed array of CHAR [0:2];



       Parm_1 := 'MARY';

       Parm_2 := '3';

Message 400 in set 13 is:

     400 INPUT FROM ! ON TERMINAL NUMBER !

The execution of the CATREAD intrinsic call ... CATREAD (..., parm_1, parm_2, ...); results in the following message:

     INPUT FROM MARY ON TERMINAL 3

Numerical Parameter Substitution

Numerical parameters allow the user to decide where the parameters are to be placed within the message. The exclamation mark (!) is immediately followed by a number in the range 1 through 5. Numerical parameter substitution is not generally used. It is useful when you rewrite your messages, or rearrange the parameters in the message, without changing the CATREAD call in the application. The example listed below demonstrates the use of numerical parameter substitution and uses the parameter definitions given above.

Message 401 in set 13 is:

     401 INPUT FROM TERMINAL NUMBER !2 BY !1

The execution of the same CATREAD intrinsic call as above (... CATREAD (..., parm_1, parm_2, ...);) results in the following message:

    INPUT FROM TERMINAL NUMBER 3 BY MARY