The DEFINE_MSGBLK procedure defines and loads a new message block into the currently running IDL session. Messages are issued from a message block using the MESSAGE procedure, which handles the details of IDL message display, including proper formatting, setting the values of the !ERROR_STATE system variable, and displaying traceback information if execution halts. See MESSAGE for details.
A message block is a collection of messages that are loaded into IDL as a single unit. Each block contains the messages required for a specific application. At startup, IDL contains a single internal message block named IDL_MBLK_CORE, which contains the standard messages required by the IDL system. Dynamically loadable modules (DLMs) usually define additional message blocks for their own needs when they are loaded. At the IDL programming level, the DEFINE_MSGBLK and DEFINE_MSGBLK_FROM_FILE procedures can be used to define and load message blocks. You can use the HELP, /MESSAGES command to see the currently defined message blocks.
Examples
This example defines a message block called ROADRUNNER that contains 2 messages:
name = ['BADPLAN', 'RRNOTCAUGHT']
fmt = ['Bad plan detected: %s.', 'Road Runner not captured.']
DEFINE_MSGBLK, PREFIX = 'ACME_M_', 'ROADRUNNER', name, fmt
Once this message block is loaded, the ACME_M_BADPLAN message can be issued using the following statement:
MESSAGE, NAME = 'acme_m_badplan', BLOCK = 'roadrunner', $
'Exploding bridge while standing underneath'
This MESSAGE statement produces the output similar to:
% Bad plan detected: Exploding bridge while standing underneath.
% Execution halted at: $MAIN$
The IDL command:
HELP, /STRUCTURES, !ERROR_STATE
can be used to examine the effect of this message on IDL’s error state.
Syntax
DEFINE_MSGBLK, BlockName, ErrorNames, ErrorFormats [, /IGNORE_DUPLICATE] [, PREFIX = PrefixStr]
Note: IDL will force the values of the message bock name, the individual message names, and any message prefix string to upper case before installing the message block. Because IDL is generally case-insensitive, you do not need to use upper case when supplying these values to the DEFINE_MSGBLK or MESSAGE procedures. The values stored in the !ERROR_STATE system variable will, however, be upper-case strings. If you do string comparisons with values in !ERROR_STATE, you should take this case-folding into account.
Arguments
BlockName
A string giving the name of the message block to be defined. Block names must be unique within the IDL system. Use of the PREFIX keyword is also recommended to enforce a consistent naming convention.
ErrorNames
An array of strings giving the names of the messages defined by the message block.
ErrorFormats
An array of strings giving the formats for the messages defined by the message block. Note that the format string can include both static text (displayed every time the error is displayed) and dynamic text (specified when the error is generated by a call to the MESSAGE procedure). Each format is matched with the corresponding name in ErrorNames. For this reason, ErrorFormats should have the same number of elements as ErrorNames. We recommend the use of the PREFIX keyword to enforce a consistent naming scheme for your messages.
Error formats are simplified printf-style format strings.
Keywords
IGNORE_DUPLICATE
Attempts to define a given BlockName more than once in the same IDL session usually cause DEFINE_MSGBLK to issue an error and stop execution of the IDL program. Specify IGNORE_DUPLICATE to cause DEFINE_MSGBLK to quietly ignore attempts to redefine a message block. In this case, no error is issued and execution continues. The original message block remains installed and available for use.
PREFIX
It is a common and recommended practice to give each message name defined in ErrorNames a common unique prefix that identifies it as an error from a specific message block. However, specifying this prefix in each entry of ErrorNames is tedious and error prone. The PREFIX keyword can be used to specify a prefix string that will be added to each element of ErrorNames.
Version History
See Also
DEFINE_MSGBLK_FROM_FILE, MESSAGE