Figure 1 illustrates the structure
of the condition token, with bit offsets shown above the components:
Figure 1. Language Environment condition
token
Every condition token contains the components indicated in
Figure 1.
- Condition_ID
- A 4-byte identifier that, with the facility ID, describes the
condition that the token communicates. The format of Condition_ID
depends on whether a Case 1 (service condition) or Case 2 (class/cause
code) condition is being represented. Language Environment callable
services and most applications can produce Case 1 conditions. Case
2 conditions could be produced by some operating systems and compiler
libraries. Language Environment does
not produce them directly.
Figure 1 illustrates
the format of the Condition_ID for Case 1 and Case 2 conditions.
- Case
- Specifies if the condition token is for a Case 1 or Case 2 condition.
- Severity
- Specifies
the severity of the condition represented by the condition token.
- Control
- Specifies if the facility ID has been assigned by IBM®.
- Facility ID
- A
3-character alphanumeric string that identifies the product or component
of a product that generated the condition; for Language Environment, the
facility ID is CEE. Although all Language Environment-conforming
HLLs use Language Environment message
and condition handling services, the actual runtime messages generated
under Language Environment still
carry the language identification in the facility ID. The facility
ID for PL/I,
for example, is IBM.
When
paired with a message number, a facility ID uniquely identifies a
message in the message source file. The facility ID and message number
persist throughout an application. This allows the meaning of the
condition and its associated message to be determined at any point
in the application after a condition has occurred.
If you
are creating a new facility ID to use with your own message source
file, follow the guidelines listed under the Facility_ID parameter
of CEENCOD in z/OS Language Environment Programming Reference.
If
you create a new facility_ID to use with a message source file you
created using CEEBLDTX (see Creating messages),
be aware that the facility ID must be part of the message source file
name. Therefore, you must follow the naming guidelines to ensure the
module name does not abend.
- ISI
- A 4-byte Instance Specific Information token associated
with a given instance of the condition. A nonzero ISI token provides
instance specific information. The ISI token contains data on message
inserts for the message associated with the condition and a q_data_token
containing 4 bytes of qualifying data. The ISI token is typically
built by Language Environment for
system or Language Environment-signaled
conditions. It can also be built by an application for conditions
signaled using CEESGL. The CEECMI callable service can be used to
define the message inserts within the ISI for a condition token. The
q_data to be placed in the ISI for a condition token is defined by
signaling the condition using CEESGL.
You can extract ISI information
inside of CEEHDLR-established condition handlers. The message insert
information cannot be retrieved directly; however, the entire formatted
message with inserts can be formatted and placed in an application-provided
character string using CEEMGET. The q_data_token can be retrieved
using CEEGQDT.