Enables a user-defined ILE exception handler at the point in the
code where the #pragma exception_handler is located.
Any exception handlers enabled by #pragma exception_handler
that are not disabled using #pragma disable_handler are
implicitly disabled at the end of the function in which they are enabled.
Parameters
function
Specifies the name of the function to be used as a user-defined
ILE exception handler.
label
Specifies the name of the label to be used as a user-defined
ILE exception handler. The label must be defined within the function
where the #pragma exception_handler is enabled. When the handler
gets control, the exception is implicitly handled and control resumes
at the label defined by the handler in the invocation containing the
#pragma exception_handler directive. The call stack is canceled
from the newest call to, but not including, the call containing the
#pragma exception_handler directive. The label can be placed anywhere
in the statement part of the function definition, regardless of the
position of the #pragma exception_handler.
com_area
Used for the communications area. If no com_area should
be specified, zero is used as the second parameter of the directive.
If a com_area is specified on the directive, it must be
a variable of one of the following data types: integral, float, double,
struct, union, array, enum, pointer, or packed decimal. The com_area
should be declared with the volatile qualifier. It cannot be a member
of a structure or a union.
class1, class2
Specifies the first four bytes and the last four
bytes of the exception mask. The <except.h> header file describes
the values that you can use for the class masks. It also contains
macro definitions for these values. class1 and class2 must evaluate to integer constant expressions
after any necessary macro expansions. You can monitor for the valid class2 values of:
_C2_MH_ESCAPE
_C2_MH_STATUS
_C2_MH_NOTIFY, and
_C2_FUNCTION_CHECK.
ctl_action
Specifies an integer constant to indicate what action should
take place for this exception handler. If handler is a function, the
default value is _CTLA_INVOKE. If handler is a label, the default
value is _CTLA_HANDLE. This parameter is optional.
The following
are valid exception control actions that are defined in the <except.h>
header file:
#define name
Defined value and
action
_CTLA_INVOKE
Defined to 1. This
control action will cause the function named on the directive to be
invoked and will not handle the exception. If the exception is not
explicitly handled, processing will continue. This is valid for functions
only.
_CTLA_HANDLE
Defined
to 2. The exception is handled and messages are logged before calling
the handler. The exception will no longer be active when the handler
gets control. Exception processing ends when the exception handler
returns. This is valid for functions and labels.
_CTLA_HANDLE_NO_MSG
Defined
to 3. The exception is handled but messages are not logged before
calling the handler. The exception will no longer be active when the
handler gets control. Exception messages are not logged. Msg_Ref_Key
in the typedef _INTRPT_Hndlr_Parms_T is set to zero. Exception
processing ends when the exception handler returns. This is valid
for functions and labels.
_CTLA_IGNORE
Defined to 131. The
exception is handled and messages are logged. Control is not passed
to the handler function named on the directive and exception will
no longer be active. Execution resumes at the instruction immediately
following the instruction that caused the exception. This is valid
for functions only.
_CTLA_IGNORE_NO_MSG
Defined to 132. The
exception is handled and messages are not logged. Control is not passed
to the handler function named on the directive and exception will
no longer be active. Execution resumes at the instruction immediately
following the instruction that caused the exception. This is valid
for functions only.
msgid_list
Specifies an optional string literal that contains the list
of message identifiers. The exception handler will take effect only
when an exception occurs whose identifiers match one of the identifiers
on the list of message identifiers. The list is a series of 7-character
message identifiers where the first three characters are the message
prefix and the last four are the message number. Each message identifier
is separated by one or more spaces or commas. This parameter is optional,
but if it is specified, ctl_action must also be specified.
For
the exception handler to get control, the selection criteria for class1 and class2 must
be satisfied. If the msgid_list is specified, the exception
must also match at least one of the message identifiers in the list,
based on the following criteria:
The message identifier matches the exception exactly.
A message identifier, whose two rightmost characters are 00, will
match any exception identifier that has the same five leftmost characters.
For example, a message identifier of CPF5100 will match any exceptions
whose message identifier begins with CPF51.
A message identifier, whose four rightmost characters are 0000,
will match any exception identifier that has the same prefix. For
example, a message identifier of CPF0000 will match any exception
whose message identifier has the prefix CPF (CPF0000 to CPF9999).
If msgid_list is specified, but the exception that
is generated is not one specified in the list, the exception handler
will not get control.
Notes on Usage
The handler function can take only 16-byte pointers as parameters.
The macro _C1_ALL, defined in the <except.h> header file,
can be used as the equivalent of all the valid class1 exception
masks. The macro _C2_ALL, defined in the <except.h> header
file, can be used as the equivalent of all four of the valid class2 exception
masks.
You can use the binary OR operator to monitor for different types
of messages. For example,
will
set up an exception monitor for three of the four class2 exception
classes that can be monitored.
The compiler issues an error message if any of the following occurs:
The directive occurs outside a C function body or inside a C statement.
The handler that is named is not a declared function or a defined
label.
The com_area variable has not been declared or does
not have a valid object type.
Either of the exception class masks is not a valid integral constant
The ctl_action is one of the disallowed values when
the handler that is specified is a label (_CTLA_INVOKE, _CTLA_IGNORE,
_CTLA_IGNORE_NO_MSG).
The msgid_list is specified, but the ctl_action is
not.
A message in the msgid_list is not valid. Message
prefixes that are not in uppercase are not considered valid.
The messages in the string are not separated by a blank or comma.
The string is not enclosed in “ ” or is longer than 4
KB.
See the IBM® Rational® Developer for i: ILE C/C++ Programmer's Guide for examples and more information
about using the #pragma exception_handler directive.