Using Condition Management APIs
A condition token is used to communicate information about a condition to ILE
CEE APIs. It is also used to communicate information to the condition manager,
to message services, and to procedures.
The ILE condition token is a 12-byte compound data type
that contains structured fields to convey aspects of a condition. It conveys
aspects such as the severity, the associated message number, and information
that is specific to the given instance of the condition.
ILE Condition Token
Layout displays a map of the condition
token.
ILE Condition Token
Layout
Every condition token contains the components indicated in the figure
above.
- Condition_ID
- A 4-byte identifier that, with the Facility_ID, describes the condition
that the token communicates. ILE CEE APIs and most applications produce Case 1
conditions.
- Case
- A 2-bit field that defines the format of the Condition_ID portion of the
token. ILE conditions are always Case 1.
- Severity
- A 3-bit binary integer that indicates the condition's severity. Severity
and MsgSev contain the same information. See Table 1 for a list of ILE condition severities.
See Table 2 and Table 3 for the corresponding i5/OS(TM) message
severities.
- Control
- A 3-bit field containing flags that describe or control various aspects of
condition handling. The third bit specifies whether the Facility--ID has been
assigned by IBM.
- Facility--ID
- A 3-character alphanumeric string that identifies the facility that
generated the condition. Although all ILE languages use ILE message and
condition handling ILE CEE APIs, the actual run-time messages generated under
ILE still carry the HLL identification in the Facility--ID.
- I--S--Info
- A 4-byte field that identifies the instance specific information associated
with a given instance of the condition. The instant specific information
contains the reference key to the instance of the message associated with the
condition token. If the message reference key is zero, there is no associated
message.
- MsgSev
- A 2-byte binary integer that indicates the condition's severity. MsgSev and
Severity contain the same information. See
Table 1 for a list of ILE condition severities. See Table 2 and
Table 3 for the corresponding i5/OS message severities.
- MsgNo
- A 2-byte, hexadecimal number that identifies the message associated with
the condition. The combination of Facility_ID and MsgNo uniquely identifies a
condition.
Table 1 contains default responses
that the condition manager takes when a handler attempts to percolate a
function check across a control boundary.
Table 1. Default Responses to Unhandled
Exceptions
| Message Type |
Severity of Condition |
Condition Raised by the Signal a Condition
(CEESGL) Bindable API |
Exception Originated from Any Other
Source |
| Status |
0 (Informative message) |
Return the unhandled condition. |
Resume without logging the message. |
| Status |
1 (Warning) |
Return the unhandled condition. |
Resume without logging the message. |
| Notify |
0 (Informative message) |
Not applicable. |
Log the notify message and send the default
reply. |
| Notify |
1 (Warning) |
Not applicable. |
Log the notify message and send the default
reply. |
| Escape |
2 (Error) |
Return the unhandled condition. |
Log the escape message and send a function check
message to the call stack entry of the current resume point. |
| Escape |
3 (Severe error) |
Return the unhandled condition. |
Log the escape message and send a function check
message to the call stack entry of the current resume point. |
| Escape |
4 (Critical ILE error) |
Log the escape message and send a function check
message to the call stack entry of the current resume point. |
Log the escape message and send a function check
message to the call stack entry of the current resume point. |
| Function check |
4 (Critical ILE error) |
Not applicable |
End the application, and send the CEE9901 message
to the caller of the control boundary. |
Note: When the application is ended by an unhandled
function check, the activation group is deleted if the control boundary is the
oldest call stack entry in the activation group.
Table 2 and Table 3 show how ILE condition severity maps to
i5/OS message severity.
Table 2. Mapping i5/OS *ESCAPE Message
Severities to ILE Condition Severities
| From i5/OS Message Severity |
To ILE Condition Severity |
To i5/OS Message Severity |
| 0-29 |
2 |
20 |
| 30-39 |
3 |
30 |
| 40-99 |
4 |
40 |
Table 3. Mapping i5/OS *STATUS and *NOTIFY
Message Severities to ILE Condition Severities
| From i5/OS Message Severity |
To ILE Condition Severity |
To i5/OS Message Severity |
| 0 |
0 |
0 |
| 1-99 |
1 |
10 |
You can test a condition token that is returned from an ILE CEE API for the
following:
- Success
- To test for success, determine if the first 4 bytes are 0. If the first 4
bytes are 0, the remainder of the condition token is 0, indicating a successful
call was made to the ILE CEE API.
- Equivalent Tokens
- To determine whether two condition tokens are equivalent (that is, the same
type of condition token, but not the same instance of the
condition token), compare the first 8 bytes of each condition token with one
another. These bytes are static and do not change depending upon the given
instance when the condition occurs.
- Equal Tokens
- To determine whether two condition tokens are equal (that is, they
represent the same instance of a condition), compare all 12 bytes of
each condition token with one another. The last 4 bytes can change from
instance to instance of a condition.