46.10. $registerException

$registerException registers the exception denoted by exceptionName; i.e., it adds the exception to the list of exceptions known to the system PROCEDURE errMsg. Distinctions between upper- and lowercase letters are ignored when comparing exceptionName to the STRINGs denoting the previously registered exceptions.

The STRING passed as the parameter comment is used only by errMsg. In response to ?, errMsg lists the registered exceptions to logFile with a description in the right margin of the effect of raising each exception. The description listed for an exception is the STRING that was passed as the comment parameter when the exception was registered.

Valid ctrlBits bits are useKeyWord and $doNotMatch.

If useKeyWord is set, then when the exception is specified in a response to errMsg, extra phrases in the response and extra words in the phrase preceding the extra phrases are ignored during the matching process and are instead set aside as an argument to the response. When errMsg raises the specified registered exception, that argument is passed as the argument exceptionStringArg1 to $raise.

If $doNotMatch is set, the exception is ignored when errMsg searches for a registered exception to raise. Exceptions with $doNotMatch set are listed in response to ? in errMsg, but cannot be raised from errMsg. When an exception is registered more than once, no duplicate registered exception error is given if either the new instance or all previous instances of the exception were registered with $doNotMatch set. When an exception is deregistered, all instances of the exception are deregistered.

The same exception can be registered more than once without setting the $doNotMatch bit, if the subsequent calls to $registerException have the same arguments as the first call that did not set the $doNotMatch bit. In comparing STRING arguments, a caseless comparison is done.

An exception is removed from the list of registered exceptions only when $deregisterException has been called for that exception at least as often as $registerException was called without setting the $doNotMatch bit (i.e., a count is kept, incremented by $registerException and decremented by $deregisterException, and the exception is considered deregistered when the count reaches zero).

It is an error to try to register an exception that has the same name as another registered exception, if neither one was registered with the $doNotMatch bit set, and any of their corresponding arguments to $registerException are not equal.

arg is used only when listing the registered exceptions in response to ? in errMsg. If arg is not Zero, then a blank followed by arg is written after the exception name. Usually arg is a STRING referred to in the $registerException comment argument.

Section 20.10.1 contains several examples of calls to $registerException.