PUTMSG - set error message actions

SYNOPSIS

<PUTMSG call|log|print|all|override on|off|exceptiononly>

DESCRIPTION
The PUTMSG directive sets the disposition of error messages. When a script generates errors, they are logged to vortex.log and printed out by default. If a <putmsg> function is defined, then logging and printing are turned off, and the function is called instead (see here for details).

By setting the appropriate action (call, log, print, or all for all three) in a <PUTMSG> directive, a different set of call/log/print actions can be set for the script as desired. A typical use for this is to turn logging and printing back on when a <putmsg> function is defined, so that errors can be monitored on-the-fly by the script itself, but are still logged for later perusal, without having to log them "by hand" in the <putmsg> function.

As it is a directive, PUTMSG must appear before the first function in the script, and sets the error message actions for the entire script. The <vxcp> function (here) can be called to override these settings at run-time, via its putmsg setting.

The override action has no equivalent in <vxcp putmsg>. It makes any other <PUTMSG> directives override <vxcp putmsg>, instead of the other way around. The use for this potentially confusing setting is debugging: a script with a complex set of <vxcp putmsg> calls can have them all temporarily disabled by adding <PUTMSG override on> and <PUTMSG log on> at the top temporarily, without having to edit the rest of the script. In version 7.03.1430345000 20150429 and later, override also overrides <urlcp putmsg pass> (here), i.e. it is always on. The override action value is Boolean only, i.e. on or off only.

The log and print actions may be set to a third state, exceptiononly, in Texis version (or compatibilityversion) 7 and later. This is their default value when a <putmsg> script function is defined. When exceptiononly is set, the given action is only enabled if a Vortex putmsg exception is occurring, i.e. a situation where the <putmsg> script function cannot be called because the script is terminating. Examples include the script <timeout> firing, an ABEND or stack overflow. For all other normal situations - where <putmsg> can be called - the action is disabled. Thus, exceptiononly allows printing and/or logging to be turned off for messages than <putmsg> can handle, yet still allows them to be seen and not lost if the script terminates abnormally. The exceptiononly value cannot be set for the call action.

EXAMPLE

<PUTMSG log on>

<A NAME=putmsg PRIVATE>
  <$GotErr = y>
</A>

<A NAME=main>
  <EXEC /some/program></EXEC>
  <IF $GotErr eq "y">
    <B>An error occurred: check the logs</B>
  </IF>
</A>

In this script, an error from the <EXEC> is still logged, as well as being detected by the script via <putmsg>.

CAVEATS
The PUTMSG directive was added in version 3.0.947100000 20000105.

SEE ALSO
vxcp, Error Messages section (here), ErrorScript ErrorFile settings in texis.ini (here)