function_name(message ‖ message_numberʃ, argument1, ..., argumentNʅ);
Several functions
* take an argument that consists of a message and then an optional number of arguments that are dynamically inserted into the text to create a final message
(*the complete list of functions can be found at the bottom of this page). If
message_number is used, it refers to the user-numbered messages created in the
.mgf file.
The message can contain optional arguments, argument1 to argumentN, that will be inserted into the message. Each argument, denoted in the message text with a percent sign, is sequentially inserted into the message. Arguments can be numeric or string expressions, but the type of the argument must match the type of the receiving field in the message text. There are seven formatters:
| Formatter | Result |
|---|
| "%d" | Inserts a number that is displayed as an integer. |
| "%f" | Inserts a number that is displayed as a decimal value (with six decimal places shown by default). |
| "%s" | Inserts a text string. |
| "%v" | Inserts a variable formatted intelligently (see below). |
| "%l" | Inserts a variable's value label (see below). |
| "%p" | Inserts the name of the current procedure, which can be useful for debugging. No argument should be supplied if using this option. |
| "%c" | Inserts the first character of a text string, or no characters if the string is blank. |
The "%v" formatter works with either numeric or string variables, whether a dictionary item or a temporary variable. If the formatter is used on an alphanumeric dictionary item or a string variable, then it displays it in the same way as would "%s". However, if a numeric dictionary item is used, then it formats the number in the way that it would be saved, obeying the length, zero fill, and decimal attributes of the field. If a numeric temporary variable is used, then the number is displayed as an integer ("%d") if applicable, or as a decimal value ("%f") with up to six decimal places otherwise.
The
"%l" formatter looks up the value set label associated with the variable's current value. If found, it displays that label (in the same way that the
getvaluelabel function does). If no value set label is associated with the value, then the
"%l" formatter behaves as if it were the
"%v" formatter.
Numeric and string arguments have a couple additional options that can be specified after the percent sign: "%[n]d", "%[n.d]f", and "%[n.d]s". In these cases, "n" controls the length of the replacement text and "d" controls either the number of decimal places shown or the length of the string. There are some rules:
- If the number is positive, as in "%+5d", the text is right justified to the size of the field (e.g., " 9").
- If the number is negative, as in "%-5d", the text is left justified to the size of the field (e.g., "9 ").
- For numbers, if a leading zero proceeds the number, as in "%05d", the text is right justified to the size of the field but instead of being padded with spaces, it is padded with zeros (e.g., "00009").
- For numbers, if the number is preceded by a plus sign, as in "%+d", the sign of the number is always displayed (e.g., "+9").
- Numbers are never truncated. Text strings are not truncated unless used as in "%0.5s", where the second part, ".5", indicates the maximum number of characters.
If you wish to split a message across two or more lines, you can use the
newline escape sequence:
'\n'errmsg("First line\nSecond Line"); numeric integerValue = 23456;
errmsg( "%d" , integerValue); // 23456
errmsg( "%-10d" , integerValue); // 23456
errmsg( "%10d" , integerValue); // 23456
errmsg( "%+10d" , integerValue); // +23456
errmsg( "%+010d" , integerValue); // +000023456
errmsg( "%-010d" , integerValue); // 0000023456
errmsg( "%f" , integerValue); // 23456.000000 Note the usage of %f
numeric decimalValue = 12.567;
errmsg( "%f" , decimalValue); // 12.567000
errmsg( "%-10.3f" , decimalValue); // 12.567
errmsg( "%d" , decimalValue); // 12 Note the usage of %d
errmsg( "%10.2f" , decimalValue); // 12.57
errmsg( "%10.3f" , decimalValue); // 12.567
errmsg( "%+10.3f" , decimalValue); // +12.567
errmsg( "%+010.3f" , decimalValue); // +00012.567
errmsg( "%010.3f" , decimalValue); // 000012.567
errmsg( "%10.5f" , decimalValue); // 12.56700
string stringValue = "abcdef";
errmsg( "%s" , stringValue); // abcdef
errmsg( "%-10s" , stringValue); // abcdef
errmsg( "%-10.3s" , stringValue); // abc
errmsg( "%10s" , stringValue); // abcdef
errmsg( "%10.3s" , stringValue); // abc