The message source file contains the message text and information
associated with each message. Standard tags and format are used for
message text and different types of message information. The tags
and format of the message source files are used by the CEEBLDTX utility
to transform the source file into a loadable TEXT file.
Under TSO/E, if you specify a partially qualified name, TSO/E adds
the current prefix (usually userid) as the leftmost qualifier and
TEXT as the rightmost qualifier. The message source file should have
a fixed record format with a record length of 80.
When creating a message file, make sure your sequential numbering
attribute is turned off in the editor so that trailing sequence numbers
are not generated. Trailing blanks in columns 1–72 are ignored. At
least one message data set (TSO/E) is required for each national language
version of your messages.
All tags used to create the source file begin with a colon (:),
followed by a keyword and a period (.). All tags must begin in column
1, except where noted. Comments in the message source file must begin
with a period asterisk (.*) in the leftmost position of the
input line.
Figure 1 shows an example of a message
source file with a facility ID of XMP.
Figure 1. Example of
a message source file:facid.XMP
:msgno.10
:msgsubid.0001
:msgname.EXMPLMSG
:msgclass.I
:msg.This is an example of an insert,
:tab.+1
:ins 1.a simple insert
:msg., within a message.
:xpl.This is a simple example of how to put an insert into a message.
:presp.No programmer response required.
:sysact.No system action is taken.
The tags used in message source files are:
- :facid.
- The facility ID is required at the beginning of every message
file. It is used as the first 3 characters of the message number.
All messages within a source file have the same facility ID. For example,
all messages issued by Language Environment have
a facility ID of CEE. The facility ID is combined with a 4-digit identification
number and the message severity code to form the message number. The
facility ID can contain any alphanumeric (A–Z, a–z, 0–9) characters.
Omitting the facility ID tag, causes an error during the creation
of the loadable message file. Errors are also caused by multiple occurrences
of this tag, or by the use of blanks or special characters in the
facility ID.
If your C application is running with POSIX(OFF), Language Environment issues
messages with a facility ID of EDC for compatibility. For more information, see Runtime messages with POSIX.
Note: The facility ID is also
used as the first 3 characters of the condition token.
- :msgno.
- This tag is required. The message number tag defines the
beginning and end of information for a message. All information up
to the next :msgno. tag refers to the current
message. The message number appears as the 4 digits following the
message prefix, and is used to identify the message in a message source
file. Multiple messages can use the same message number, but only
if a :msgsubid. tag is used within the message.
The message numbers used with the :msgno. tags
must be in ascending order. The message numbers can be from 1 to 4
numeric (0–9) characters. Leading zeros will be added if fewer than
4 characters are used.
If your application is running with
POSIX(ON), message numbers 5201 through 5209 are used whereas
the same messages use message numbers 6000 through 6008 when POSIX(OFF)
is in effect. For more information, see Runtime messages with POSIX.
- :msgsubid.
- This tag is optional. The message subidentifier tag distinguishes
between different messages with the same message number. If every
message has a unique message number, the :msgsubid. tag
is unnecessary.
The numbers associated with the :msgsubid. tags
must be unique and in ascending order within messages that have the
same message number. The number associated with the :msgsubid. tag
can be from 1 to 4 numeric (0–9) characters. Leading zeros will be
added if fewer than 4 digits are used.
- :msgname.
- The :msgname. tag is used to give a
name to a message. This name becomes the symbolic name of the condition
token associated with the message, and is placed into the COPY file
generated by the CEEBLDTX utility. For example, if EXMPLMSG is used
for the :msgname. tag in a message with
a facility ID of XMP, the symbolic feedback code for the condition
associated with this message is also EXMPLMSG.
If a message name
is omitted, the facility ID plus the base-32 equivalent of the message
number is used as the symbolic message name. If additionally the :msgsubid. tag
is used, the message subidentifier preceded by an underscore is appended
to the message name. For example, if :msgno. has
a value of 10 and the facility ID is XMP, the symbolic feedback code
for the condition associated with a message is XMP00A. If additionally
the :msgsubid. tag is used with a value
of 0001, the symbolic feedback code is XMP00A_0001.
- :msgclass.
- This tag is required. The :msgclass. (or :msgcl.)
tag makes up the final part of the message identification. It requires
a case-sensitive character that indicates the severity code of the
message. This character corresponds to the level of severity of the
condition token associated with the message. If the :msgclass. tag
differs from the severity level of the condition token, the severity
assigned to the condition token is used. Refer to Table 1 for the severity codes, levels
of severity, and condition descriptions.
- :msg.
- The :msg. tag indicates the beginning
of partial or complete text of the message to be displayed. The message
text can appear in any national language known to Language Environment (including
DBCS characters). For a list of the supported national languages,
refer to z/OS Language Environment Programming Reference.
The :msg. tag can be repeated as often as
necessary to construct a message. It is not required if the message
consists only of message inserts. If the message text for a message
requires more than one line, all lines are left-aligned with the beginning
of the first line of message text.
The message text ends with
the last nonblank character. There is no fixed space reserved for
the message, so there is no requirement to reserve any additional
space for message translation.
- :hex.
- The :hex. tag indicates the beginning
of a hexadecimal character string. If used, it must be within the
text of a :msg. tag. It is terminated by
an :ehex. tag. The :hex. tag
can occur anywhere within the message text.
- :ehex.
- The :ehex. tag terminates a string of
hexadecimal characters. This tag can occur anywhere within the message
text.
- :dbc.
- The :dbc. tag defines text of DBCS characters.
The string itself cannot contain any SBCS characters, but it must
begin with a shift-out character and end with a shift-in character.
- :tab.n
- The :tab. tag indicates that the next
part of the message will be tabbed over a given number of spaces or
tabbed to a given column. If the number is preceded by a plus sign,
it indicates the next part of the message will be moved over the specified
number of spaces from the current position. Otherwise, the number
indicates the column where the next message part will begin. The tab
value must be between 1 and 255. If necessary, a new line of output
is automatically created to accommodate the tab value. This includes
the case where the current position is greater than a specified tab
column.
- :tbn.
- The :tbn. tag is used to force any text
written on a subsequent line to start in the current column until
an :etbn. tag is found.
- :etbn.
- The :etbn. tag turns off the tabs set
by a :tbn. tag.
- :ins n.[text]
- The :ins. tag defines a message insert.
The insert is a variable that is assigned a value with the CEECMI
callable service. The insert number (n)
can be any number between 1 and 9. The text following the period describes
the insert. This text is optional, and is included only in a message
file when the value assigned to the insert is not known. For example,
the text variable name after an insert tag
indicates that a variable name is assigned to the insert.
One
value can be assigned to each insert used in a message. Insert tags
can be moved around, interchanged, or omitted, but the insert values
cannot be changed. The order of the :ins n. tags,
not the insert number, determines the order of the inserts.
- :newline.
- The :newline. tag creates a new message
line that can be used for multiline messages.
- :xpl.
- This tag is optional. The :xpl. tag
indicates text used to explain the condition. It is not printed as
part of the message, but is included if the message SCRIPT file is
formatted and printed.
- :presp.
- This tag is optional. The :presp. tag
indicates text that describes the suggested programmer response. It
is not printed as part of the message, but is included if the message
SCRIPT file is formatted and printed or displayed online.
- :sysact.
- This tag is optional. The :sysact. tag
indicates text that describes the system action. It is not printed
as part of the message, but is included if the message SCRIPT file
is formatted and printed or displayed online.