Condition token data type

The condition token data type communicates with message services, condition management, Language Environment callable services, and user applications. For the detailed layout of the condition token data type, see Figure 1.

Figure 1. Language EnvironmentCondition token for AMODE 64 applications

An instance of a condition token is 16 bytes (128 bits) long, as shown in Figure 2.

CEECTOK       DSECT DS 0D
CONDITION_ID  DS   0F
*
*   Case 1 definitions for CONDITION_ID
*
SEVERITY      DS   H         Condition severity (0-4)
MSG_NUMBER    DS   H         Related message number
*
*   Case 2 definitions for CONDITION_ID
*
              ORG  CONDITION_ID
CLASS_CODE    DS   H         Message associated with the class
CAUSE_CODE    DS   H         Message associated with the cause
*
*   Common part of the feedback code
*
FLAGS         DS   X         Bits for Case/Severity/Control
*
*   Case definitions
*                  B'xx......'
CASE1         EQU  B'01000000'
CASE2         EQU  B'10000000'
*
* Severity definitions
*                  B'..xxx...'
SEV0          EQU  B'00000000'    Severity 0 condition
SEV1          EQU  B'00001000'    Severity 1 condition
SEV2          EQU  B'00010000'    Severity 2 condition
SEV3          EQU  B'00011000'    Severity 3 condition
SEV4          EQU  B'00100000'    Severity 4 condition
*
* Control definitions
*                  B'.....xxx'
IBM_ASSIGN    EQU  B'00000001'    IBM assigned the facility id
CTL_RSVD1     EQU  B'00000010'    Reserved - must be 0
CTL_RSVD2     EQU  B'00000100'    Reserved - must be 0
*
*   Facility ID
*
FACILITY_ID   DS   CL3            3 char string that ids the product
*
*   Instance Specific Information Token
*
I_S_Info      DS   D              Token to the ISI

CONDITION_ID

A 4-byte identifier that describes the condition with the FACILITY_ID. The case field determines the type of identifier. Two identifiers are defined to be cross-system consistent:

1. Case 1 - Service Condition, which is used by all Language Environment callable services and most application programs.

   SEVERITY

   A 2-byte binary integer with the following possible values:

   0

   Information only (or, if the entire token is zero, no information).

   1

   Warning — service completed, probably correctly.

   2

   Error detected — correction attempted; service completed, perhaps incorrectly.

   3

   Severe error — service not completed.

   4

   Critical error — service not completed; condition signaled.

   Although the field is obviously capable of containing other values, these are not architected. If a critical error (severity = 4) occurs during a Language Environment callable service, it is always signaled to the condition manager, rather than returned synchronously to the caller.

   MSG_NUMBER

   A 2-byte binary number that identifies the message associated with the condition. The combination of Facility_ID and Msg_No uniquely identifies a condition.

2. Case 2 - Class/Cause Code Condition, which is used by some operating systems and compiler runtime libraries.

   CLASS_CODE

   A 2-byte, binary number that identifies the message subid associated with the class of the condition.

   CAUSE_CODE

   A 2-byte, binary number that identifies the message ID associated with the cause of the condition.

   Note: The message subid and the message identifier are tags found in the message source file.

FACILITY_ID

A 3-character, alphanumeric string that identifies a product or component within a product. Note that special characters, including space, cannot be used.

The Facility_ID is associated with the repository (for example, a file) of the runtime messages. The conventions for naming the message repository, however, are platform-specific. The Facility_ID need not be unique within the system and can be determined by the application writer. If a unique ID is required (for IBM® and non-IBM products), an ID can be obtained by contacting an IBM project office.

A Facility_ID assigned by IBM to an IBM product must begin with one of the letters A through I, inclusive. A Facility_ID assigned by IBM to a product other than an IBM's must not begin with a letter A through I. For information on how to indicate if the Facility_ID has been assigned by IBM, see Control below. There are no constraints (other than the alphanumeric requirement) on a Facility_ID not assigned by IBM.

Language Environment constructs a load name consisting of the form T || Facility_ID || MSGT:

T

The character 'I' if the Facility_ID was assigned by IBM, or the character 'U' if the Facility_ID was not assigned by IBM.

Facility_ID

The three character facility ID as described above.

MSGT

The four characters MSGT.

For example, given an IBM assigned facility ID of CEE, the constructed load name would be ICEEMSGT.

Note: The Msg_No/Facility_ID identifies a condition for a Language Environment-enabled product. This identification is required to be persistent beyond the scope of a single session. This allows the meaning of the condition and its associated message to be determined after the session that produced the condition has ended. The message inserts and the I_S_Info need to be explicitly saved to allow persistence after the session has concluded.

Case

A 2-bit field that defines the format of the Condition_ID portion of the token. The value 1 identifies a case 1 condition, the value 2 identifies a case 2 condition. The values 0 and 3 are reserved.

Severity

A 3-bit field indicating a condition's severity. Severity values are the same as defined under a case 1 Condition_ID. When evaluating the severity, the same rules apply for signaling case 2 conditions as for case 1 conditions. For a case 1 condition, this field contains the same value as the Severity field in the Condition_ID.

Note: This field is valid for both case 1 and 2 conditions. It can be used with either condition token to evaluate the condition's severity.

Control

A 3-bit field containing flags describing or controlling various aspects of condition handling, as follows:

..1

Indicates Facility_ID has been assigned by IBM.

.1.

Reserved.

1..

Reserved.

I_S_INFO

A doubleword containing a token that identifies the Instance Specific Information (ISI) associated with the given condition. If an ISI is not associated with a given condition token, the ISI field contains binary zero. The ISI token provides access to various instance specific information such as message inserts and qualifying data.