Understanding the structure of the condition token
Figure 1 illustrates the structure of the condition token, with bit offsets shown above the components:
- 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.