The DEFINE_MSGBLK_FROM_FILE procedure reads the definition of a message block from a file, and uses DEFINE_MSGBLK to load it 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
A message definition file has a simple structure designed to ease the specification of message blocks. Any line starting with the character @ specifies information about the message block. Any line not starting with an @ character is ignored, and can be used for comments, documentation, notes, or other human readable information. All such text is ignored by DEFINE_MSGBLK_FROM_FILE.
There are three different types of lines starting with @ allowed in a message definition file:
Specifies the name of the message block being defined. There should be exactly one such line in every message definition file. If the BLOCK keyword to DEFINE_MSGBLK_FROM_FILE is specified, the @IDENT line is ignored and can be omitted. RSI recommends always specifying an @IDENT line.
If present, specifies a prefix string to be applied to the beginning of each message name in the message block. There should be at most one such line in every message definition file. If the PREFIX keyword to DEFINE_MSGBLK_FROM_FILE is specified, the @PREFIX line is ignored and can be omitted. RSI recommends always specifying an @PREFIX line.
Specifies a single message name and format string pair. The format string should be delimited with double quotes. A message definition file should contain one such line for every message it defines.
This routine is written in the IDL language. Its source code can be found in the file
define_msgblk_from_file.pro in the
lib subdirectory of the IDL distribution.
DEFINE_MSGBLK_FROM_FILE, Filename [, BLOCK = BlockName] [, /IGNORE_DUPLICATE] [, PREFIX = PrefixStr] [, /VERBOSE]
The name of the file containing the message block definition. The contents of this file must be formatted as described in the section Format of Message Definition Files.
If present, this keyword specifies the name of the message block. Normally, this keyword is not specified, and an @IDENT line in the message file specifies the name of the block. We recommend that you follow the advice given in Library Authoring when selecting this name in order to avoid name clashes. Use of a prefix is also recommended to enforce a consistent naming convention.
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.
If present, this keyword specifies a prefix string to be applied to the beginning of each message name in the message block. Normally, this keyword is not specified, and an @PREFIX line in the message file specifies the prefix string. We recommend the use of a prefix to enforce a consistent naming scheme for your messages.
If set, causes DEFINE_MSGBLK_FROM_FILE to print informational messages describing the message block loaded.
The following example uses the same message block as in the example given for DEFINE_MSGBLK, but uses a message definition file to create the message block. The first step is to create a message definition file called
roadruner.msg containing the following lines:
; Message definition file for ROADRUNNER message block @IDENT roadrunner @PREFIX ACME_M_ @ BADPLAN "Bad plan detected: %s." @ RRNOTCAUGHT "Road Runner not captured."
Use the following statement to load in the message block:
% Attempt to install an existing message block: ROADRUNNER.the ROADRUNNER message block has already been defined. You must either exit and restart IDL or issue the .FULL_RESET_SESSION executive command.
% Execution halted at: $MAIN$
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:
can be used to examine the effect of this message on IDL's error state.