HP 3000 Manuals HP 3000 Manuals
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