DEFINE_MSGBLK_FROM

DEFINE_MSGBLK_FROM_FILE

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 !ERROR_STATE system variable, and displaying traceback information if execution halts. See MESSAGE for details.

Note

For large message blocks, DEFINE_MSGBLK_FROM_FILE can be more convenient than DEFINE_MSGBLK.

Format of Message Definition Files

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:

@IDENT name

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.

Note

IDL will force the string specified by the @IDENT line to upper case before installing the message block. You do not need to use upper case when supplying the @IDENT name string, but !ERROR_STATE.BLOCK will always contain an upper-case string.

@PREFIX PrefixStr

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.

Note

IDL will force the string specified by the @PREFIX line to upper case before installing the message block. You do not need to use upper case when supplying the @PREFIX PrefixStr string, but !ERROR_STATE.BLOCK will always contain an upper-case string.

@ MessageName "MessageFormat"

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.

Syntax

DEFINE_MSGBLK_FROM_FILE, Filename [, BLOCK = BlockName] [, /IGNORE_DUPLICATE] [, PREFIX = PrefixStr] [, /VERBOSE]

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_FROM_FILE 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

Filename

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.

Keywords

BLOCK

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.

Note

IDL will force the string specified by the BLOCK keyword to upper case before installing the message block. You do not need to use upper case when supplying the BLOCK string to the DEFINE_MSGBLK_FROM_FILE procedure, but !ERROR_STATE.BLOCK will always contain an upper-case string.

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

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.

Note

IDL will force the string specified by the PREFIX keyword to upper case before installing the message block. You do not need to use upper case when supplying the PREFIX string to the DEFINE_MSGBLK_FROM_FILE procedure, but !ERROR_STATE.MSG_PREFIX will always contain an upper-case string.

VERBOSE

If set, causes DEFINE_MSGBLK_FROM_FILE to print informational messages describing the message block loaded.

Examples

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:

DEFINE_MSGBLK_FROM_FILE, 'roadrunner.msg'

Note

A message block can only be defined once during an IDL session. If you see a message that looks like this:

% Attempt to install an existing message block: ROADRUNNER.
% Execution halted at: $MAIN$

the ROADRUNNER message block has already been defined. You must either exit and restart IDL or issue the .FULL_RESET_SESSION executive command.

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.

Version History

Introduced: 5.5