The message file for a data entry application stores the error message text that is displayed during data entry. The message file for a batch application stores the error message text that will be included in the execution report. The message file has the extension .mgf. While creating your application, you can view the message text in a window at the bottom of the logic screen.
You can associate multiple message files with an application, which can be useful if you have messages defined in multiple languages. To do this, select
File -> Add Files and then choose the external message file to add to the application. If you no longer want to use the external message file, you can remove it by selecting
File -> Drop Files.
If the name of an external message file begins with "CSProRuntime," then the messages in that file will override the CSPro system messages. See
Collaborating on CSPro Development for more information about this file.
Each line in the message file contains one message. A message consists of a message number followed by text. It is displayed on the entry screen when an
errmsg function with the message number is executed in a data entry application. It is written to the execution report when
errmsg function with the message number is executed in a batch application. The messages can also be accessed with other functions (including
maketext).
For example, suppose a message file contains the following lines:
1 This is the first message
2 This is the second message
When
errmsg(1) is executed in a data entry application, the message "This is the first message" is displayed on screen. When
errmsg(2) is executed, the message "This is the second message" is displayed.
By default, the message text following the message number is processed without regard to
escape sequences (character sequences that begin with a backslash character). However, if using
logic version CSPro 8.0+, message text that begins with a single or double quotation mark is processed as if it were a string literal or verbatim string literal. For example, the following messages are identical:
// all evaluate to: I like to use backslashes \ and "quotation" 'marks'!
1 I like to use backslashes \ and "quotation" 'marks'!
1 "I like to use backslashes \\ and \"quotation\" 'marks'!"
1 @"I like to use backslashes \ and ""quotation"" 'marks'!"
Arguments can be specified in the
errmsg function.
These arguments can be numeric expressions or string expressions. String arguments in the error message text are indicated by
%s. Integer numeric arguments are indicated with
%d. Decimal numeric arguments are indicated with
%f. For example, a message file might contain the following:
1 The month of %s has only %d days. You entered %d!
The application could use this as follows:
When the function is executed, it knows to use error message 1 and substitute the word "June" for %s in the message text, the number 30 for the first %d, and the number 31 for the second %d. The message "The month of June has only 30 days. You entered 31!" will be displayed on the screen.
The more general the arguments of the message, the more flexible the message. In the example below, the value of the variable HHDAY is used as an argument. The error message will use the value of
HHDAY if the
errmsg function is executed.
Comments can be used to clarify the syntax listed in a message, or to identify "ownership" of the message or message blocks (i.e., what code blocks use the messages: global messages or just specific areas?).
There are three ways to mark message text as a comment. In all cases, the comment characters must appear at the beginning of the line. You can use single-line comments (
//), and both the
new and old logic versions of multiline comments (
/* */,
{ }). Unlike in logic, multiline comments cannot appear in the middle of a line. A multiline comment can end on the same line that it started, or at the beginning of a subsequent line.
For example, messages might be grouped in your message file as follows:
// Global messages
0001 If the interview result code <> 1 (interview started), the interview will terminate.
0002 If consent is not given, the interview will terminate.
0003 Consent was previously given, are you sure you wish to change it to no?
/* Date-related messages */
0020 Interview year (%d) cannot be after system year (%d).
0021 Interview date (YYYY/MM/DD=%4d/%02d/%02d) cannot be after system date (YYYY/MM/DD=%4d/%02d/%02d).
0022 Invalid date (month/day combo not possible MM/DD=%02d/%02d).
When designing an application that will be used in
multiple languages, you can define multiple messages for a given message number. Use the
language name, followed by the message number in parentheses, as shown in this example:
101 Hello
ZH(101) 你好
FR(101) Bonjour
CSPro will automatically display the correct message based on the current language. If no translated message exists for the current language, the default message is shown.
Using the Language= directive declares that all subsequent error messages are in a given language. For example, the previous example could be rewritten as:
Language=EN
101 Hello
Language=ZH
101 你好
Language=FR
101 Bonjour
If you would like to define messages for multiple languages at the same time, separate the name of each language with a comma:
Language=HI, PA
101 नमस्ते
You can also use the message file to translate string literals that are used along with the
tr function. For example:
ZH("Hello") 你好
FR("Hello") Bonjour
Calling
tr("Hello") in logic will display the correct string based on the current language.
Based on the
logic version, escape sequences in translated string literals may be processed. For example:
FR("first line\nsecond line") "première ligne\ndeuxième ligne"