Creating a message source file

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.