Source for message catalogs

Message catalog source format

A message catalog contains five fields of message text source lines. A single blank character separates each of the five fields. Any other blank characters are considered as part of the subsequent field data. See Special characters and escape sequences for additional information.

• $ comment

  A line that begins with $ that is followed by one or more blank characters is treated as a comment line. A omment line should be placed directly beneath the message to which it refers. Place comments for an entire set directly below the $set directive in the source file.

• $quote C

  This line specifies an optional quote character C that is used to surround message text. This character enables trailing spaces or null (empty) messages to be visible in a message source line. By default, or if an empgy $quote directive is supplied, no quoting of message text is recognized.

• $set n comment

  This line specifies the set identifier of the messages to follow until the next $set or end-of-file appears. The N denotes the set identifier that is defined by a number between 1 and NL_SETMAX. Place set identifiers in ascending order within a single source file. They do not need to be contiguous. A character string that follows a set identifier is treated as a comment and ignored.

• $delsetncomment

  This line deletes message set n from an existing message catalog. The n specifies the set number. Data that follows the set number is treated as a comment. The $set and $delset identifiers can both be in the message catalog source or the field tags.

• m message text

  The m specifies the message identifier that is defined by a number between 1 and NL_SETMAX. The message text is stored in the message catalog with message identifier m with the set identifier that is specified in the last $set directive. If the message text is empty and a blank character field separator is present, it stores an empty string in the message catalog. Existing messages get deleted from the catalog if the message line does not have a field separator or MESSAGE TEXT and a NEWLINE or carriage return follows the message line. Message identifiers must be in ascending order, noncontiguous, and within a single set. The length of the MESSAGE TEXT must be in the range of 0 to NL_TEXTMAX.

  Note: Empty lines in a message text source file will be ignored.

Messages programming format

MESSAGES should follow these recommendations:

• The last line of all messages should end with \n.
• The second and remaining lines of a message should begin with \t, indicating a tab.
• All lines of messages that continue to the next line should end with \n\, indicating that the message continues to the next line.
• The quotation mark at the end or beginning of a line should be omitted. The quotation mark delineates the beginning and end of a complete message.

Using multiple source files

You can specify multiple source files for the source file parameter. The messages that are contained in all of the files must follow the same rules for sets and messages as defined in a single source file. For example, the first source file contains messages in sets 1 through 3. The next source file must begin with set 3 and have a message number greater than the last message number in the first source file. If not, it must contain sets that begin with a number higher than the highest number (set 3) in the previous source file.

Replacing messages

Messages in an existing message catalog can be replaced by specifying a source file that contains the same set number and message number as the message text you want to change. All other messages in the source file remain the same. To update a value for the $QUOTE in a catalog, use the same $QUOTE character in subsequent source files.

Example source for a message catalog

Here is a sample format for the source that is used to create a message catalog. A quotation mark delineates each message. The message text that is stored in the message catalog has had the extraneous blank characters removed. This example describes three sets of messages. Set 2 is deleted while sets 1 and 3 remain stored in the message catalog.

$ Messages for my new product
$quote "
 
$set 1
 
1 "Error occurred.\n"
$ The next message is continued on the next line.
2 "This is a very long message \n\
\t that requires another line to display. \n"
3 "Specify a value greater than %d.\n"
4 "File %c cannot be used at this time.\n"
 
$set 2
1 "Error %d occurred. \n"
2 "Flag not set.\n"
3 "Number of arguments must be %d.\n"
 
$set 4
1 "Before using this command, you must \
set the correct values in the %c box.\n"
2 "You have not properly NLS enabled this function.\n"
10 "Messages should end with a %c.\n"
 
$delset 2

Here is an example for using the MRGMSGCLG command to create a message catalog.

MRGMSGCLG CLGFILE('/MYPRODUCT/MESSAGES?US')
     SRCFILE('QSYS.LIB/MYLIB.LIB/MYSOURCE.FILE/US.MBR')
     CLGCCSID(*SRCCCSID) SRCCCSID(*SRCFILE)
     TEXT('Message catalog for USA')

This example creates a message catalog into the stream file US in directory /MYPRODUCT/MESSAGES using the source from MYLIB library in file MYSOURCE and member US. The CCSID of the data in the message catalog is the same as the CCSID tag of the source file.

Special characters and escape sequences

Text strings can contain special characters and escape sequences as defined in the following table.