Conditional message reporting

It is sometimes useful to have varying levels of message output which may be controlled by the user of an application. Instances where this facility might be of use are:

• the ability to switch on informational messages for novice users which can later be switched off as the user becomes familiar with the application;
• the ability to switch off unnecessary informational messages when an application is run in batch mode, or within a command procedure;
• the ability to output detailed information from an application on request, say from within an iterative procedure.

Conditional message output is achieved explicitly in the Message Reporting System using the subroutine msgOutif to assign a ``priority'' to the message, e.g.

      msgOutif( MSG__NORM, "", "A conditional message", status );

      CALL MSG_OUTIF( MSG__NORM, ' ', 'A conditional message', STATUS )

Here, the first argument is the ``priority'' associated with the message and can be any one of twenty four levels which are represented by symbolic constants defined in the include file msg_par.h (MSG_PAR):

MSG__QUIET

- quiet mode, high priority;

MSG__NORM

- normal mode, normal priority (default);

MSG__VERB

- verbose mode, low priority.

MSG__DEBUG

- debug mode, lowest priority

MSG__DEBUGnn

- multiple debug modes. 1 to 20.

Whether or not the message will be output depends upon the ``conditional message output filter'' which may be set using the subroutine msgIfset. e.g.

      msgIfset( MSG__QUIET, status );

      CALL MSG_IFSET( MSG__QUIET, STATUS )

The first argument of msgIfset is the required conditional output filter level - it may take the same values as the message priority with the addition of MSG__NONE and MSG__ALL; by default it is set to MSG__NORM. The current conditional output filtering level may be inquired using subroutine msgIflev or compared against using msgFlevok. MSG__NONE and MSG__ALL allow every message to be hidden or all messages to be displayed respectively. These levels can not be used with msgOutif.

See also msgTune and msgIfgetenv that allows the filter level to be set by an environment variable, and msgIfget which allows ADAM programs to obtain the filter level from an ADAM parameter.

The action of msgOutif resulting from each of the defined priority values is as follows:

MSG__QUIET

- output the given messsage unless the current output filter is set to MSG__NONE;

MSG__NORM

- output the given message if the current output filter is set to either MSG__NORM, MSG__VERB, MSG__DEBUG (and related constants) or MSG__ALL;

MSG__VERB

- output the given message only if the current output filter is set to MSG__VERB, MSG__DEBUG (and related constants) or MSG__ALL.

MSG__VERB

- output the given message only if the current output filter is set to MSG__DEBUG (and related constants) or MSG__ALL.

In this scheme, messages given the priority MSG__QUIET the most important messages being output by an application and can only be turned off if the user is forcing all output to be disabled.

Here is an example of how conditional message output might be used in an application using interactive graphics with differing levels of informational messages to match how familiar the user is with the application:

*  Use the cursor to enter the approximate positions of stars on the
*  displayed image to be fitted.
      CALL MSG_OUT( ' ', 'Use the cursor to enter star positions',
     :             STATUS )

*  Explain the positioning of the cursor.
      CALL MSG_OUTIF( MSG__NORM, ' ',
     :               'The graphics cursor should be positioned ' //
     :               'close to the centre of each star image', STATUS )

*  Explain the cursor keys to new user.
      CALL MSG_OUTIF( MSG__VERB, ' ', 'Cursor keys: 1 add entry', STATUS )
      CALL MSG_OUTIF( MSG__VERB, ' ', '             2 reject last entry',
     :               STATUS )
      CALL MSG_OUTIF( MSG__VERB, ' ', '             3 entry complete',
     :               STATUS )

/*  Use the cursor to enter the approximate positions of stars on the
 *  displayed image to be fitted. */
      msgOut( "", "Use the cursor to enter star positions", status );

/*  Explain the positioning of the cursor. */
      msgOutif( MSG__NORM, "",
                "The graphics cursor should be positioned "
                "close to the centre of each star image", status );

/*  Explain the cursor keys to new user. */
      msgOutif( MSG__VERB, "", "Cursor keys: 1 add entry", status );
      msgOutif( MSG__VERB, "", "             2 reject last entry", status );
      msgOutif( MSG__VERB, "", "             3 entry complete", status );

The msgBlankif function works in much the same way as msgOutif to allow a blank line to be output conditionally.

      msgBlankif( MSG__VERB, status );

      CALL MSG_BLANKIF( MSG__VERB, STATUS )

The MSG__NONE and MSG__ALL levels cannot be used with msgBlankif.