Including escape characters in messages

Sometimes it is necessary to include the message token escape character, ``$^\wedge$'', literally in a message. When the message token escape character is immediately followed by a blank space, or is at the end of the msgOut text, it is included literally. If this is not the case, then it can be included literally by duplicating it. So, for example:

      msgSetc( "TOKEN", "message token" );
      msgOut( "EXAM_UPARROW",
              "Up-arrow, ^^, is the ^TOKEN escape character.", status);

      CALL MSG_SETC( 'TOKEN', 'message token' )
      CALL MSG_OUT( 'EXAM_UPARROW',
     :             'Up-arrow, ^^, is the ^TOKEN escape character.',
     :             STATUS )

would produce the message:

Up-arrow, ^, is the message token escape character.

Escape characters and token names will also be output literally if they appear within the value assigned to a message token; i.e. message token substitution is not recursive. This means that if the message system is to be used to output the value of a character variable, the contents of which are unknown and may therefore include escape characters, the value should first be assigned to a message token. Thus,

      msgSetc( "TEXT", value );
      msgOut( "EXAMPLE_OK", "^TEXT", status );

      CALL MSG_SETC( 'TEXT', VALUE )
      CALL MSG_OUT( 'EXAMPLE_OK', '^TEXT', STATUS )

will output the contents of VALUE literally, whereas

      msgOut( "EXAMPLE_BAD", value, status );

      CALL MSG_OUT( 'EXAMPLE_BAD', VALUE, STATUS )

might not produce the desired result. This consideration is particularly important when outputting text values such as file names within the ADAM environment, where a number of additional escape characters are defined.