The errmsg function displays a message on the data entry screen (when used in a Data Entry application) or writes a message to the output listing file (when used in a Batch Edit application). If messages are defined via the message number msg_num, then those messages must be stored in a message file [.mgf]. msg_num can be a number or numeric expression.

Each argument is sequentially inserted into the error message. Arguments can be numeric or alphanumeric expressions, but the type of the argument must match the type of the receiving field in the message text. The maximum number of arguments is 20.

Some of the most common formatting options include (see Message Formatting Options for a complete list):

where "n" is the size of the field and "d" is the number of decimal places to show for a number.

Numbers are never truncated. Text strings are truncated only if ".d" is used.

If "n" is positive, the insert is right-justified in the size of the field. If "n" is negative, the insert is left-justified in the size of the field. If "n" is a positive number with a leading zero, the insert is right-justified in the size of the field and zero filled to the left.

When inserting a number, if "n" is preceded by a +, the sign of the number is always displayed.

The case and summary keywords give you some control over the output listing. By default, the output listing shows you messages case-by-case, and summarized by the number of times the message was triggered for the run (there is an optional denominator, described below). You can limit the output listing to only case-by-case reporting, or only summary reporting, by using these keywords.

The denom keyword allows you to specify a denominator, so that you can show percentages in the summary portion of the output listing. This is very useful for showing, for example, edit failure rates (and as such, this option is geared towards batch applications rather than data entry applications). In Format 1's Example 2 below, the output listing will show the number of times the head of household had more than one spouse, divided by the number of households processed during the run. Note that it is the responsibility of the application designer to write logic to put the proper values into the denominator variable.

The select keyword is used to give the option of specifying the field to go to in response to the error message. A button is placed on the error message window for each caption and fieldname pair specified as a select argument, with a maximum of 5 possible select argument pairs allowed. The caption will be displayed on the button. When a button is chosen, the system goes to the field specified by fieldname. If continue is used as the fieldname, the system proceeds to the next line of logic following the errmsg call. If a default_option is given, it will place the focus on the select option chosen when the message is presented. This is a good method to prioritize what option you want the user to make (reenter a value vs. continue for example). If a default_option is not given, no button will have the focus.

If you wish to split message text across two or more lines, refer to the Message Formatting Options page.

The function returns the sequence number of the button pressed. When the select keyword is not used, the function will return 1, as only the "OK" button is presented to the user, corresponding to button #1 ("Cancel" is never presented, and so a code of zero is not possible).

When the select keyword is used, the function returns the sequence number of the button that was pressed, with the first button having the value 1. A maximum of 5 select argument pairs is allowed.

where the message file contains the following entry:

Note the errmsg call could have also been invoked as follows:

See also: Warning Function, Message Formatting Options, Message File (.mgf)