Understanding the structure of the condition token

Figure 1 illustrates the structure of the condition token, with bit offsets shown above the components:

Figure 1. Language Environment condition token

A symbolic condition token represents the first 8 bytes of a condition.

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.

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 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

An 8-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 8 bytes of qualifying data. The ISI token is typically built by Language Environment for system or Language Environment-signaled conditions. The __le_msg_add_insert() callable service can be used to define the message inserts within the ISI for a condition token.

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 __le_msg_get().