CEENCOD—Construct a condition token
CEENCOD
dynamically constructs a 12-byte condition token that communicates
a condition in Language Environment.
The condition token communicates with the Language Environment message
and condition handling callable services, and user routines. Also,
all Language Environment callable
services use the condition-token data type to return information to
the user as a feedback code.
Syntax >>-CEENCOD--(--c_1--,--c_2--,--case--,--severity--,--control----> >--,--facility_ID--,--i_s_info--,--cond_token--,--fc--)--------><
- c_1 (input)
- c_1 and c_2 together make up the condition_ID portion of the condition token. c_1 is a 2-byte binary integer representing the value of the first 2 bytes of the 4-byte condition_ID. For case 1, c_1 represents the severity; for case 2, it is the class_code.
- c_2 (input)
- A 2-byte binary integer representing the value of the second 2 bytes of the condition_ID. For case 1, this is the Msg_No; for case 2, it is the cause_code.
- case (input)
- A 2-byte binary integer defining the format of the condition_ID portion of the token.
- severity (input)
- A 2-byte binary integer indicating the condition's severity. For
case 1 conditions, the value of this field is the same as the severity
value specified in the condition_ID. For case 1 and 2 conditions,
this field is also used to test the condition's severity. severity can
be specified with the following values:
- 0
- Information only (or, if the entire token is 0, no information).
- 1
- Warning; service completed, probably correctly.
- 2
- Error detected and correction attempted; service completed, perhaps incorrectly.
- 3
- Severe error; service not completed.
- 4
- Critical error; service not completed; condition signaled. A critical error is a condition jeopardizing the environment. If a critical error occurs during a Language Environment callable service, it is always signaled to the condition manager instead of returning synchronously to the caller.
- control (input)
- A 2-byte binary integer containing flags describing or controlling various aspects of condition handling. Valid values for the control field are 1 and 0. 1 indicates the facility_ID is assigned by IBM®. 0 indicates the facility_ID is assigned by the user.
- facility_ID (input)
- A
3-character field containing three alphanumeric characters (A-Z, a-z
and 0-9) identifying the product or component of a product generating
this condition or feedback information, for example, CEE.
The facility_ID is associated with the repository (for example, a file) of the runtime messages. If a unique ID is required (for IBM and non-IBM products), an ID can be obtained by contacting an IBM project office.
If you create a new facility_ID to use with a message file you created by using the CEEBLDTX utility, be aware that the facility_ID must be part of the message file name. It is therefore important to follow the naming guidelines described below in order to have a module name that does not cause your application to abend.
Begin a non-IBM assigned product facility_ID with letters J through Z. (See the preceding description control (input) parameter on how to indicate whether the facility_ID has been assigned by IBM.) Special characters, including blank spaces, cannot be used in a facility_ID. There are no other constraints (besides the alphanumeric requirement) on a non-IBM assigned facility_ID.
- i_s_info (input)
- A fullword binary integer identifying the ISI, that contains insert data. Whenever a condition is detected by the Language Environment condition manager, insert data is generated describing the instance of its occurrence is generated. This insert data is used, for example, to write to a file a message associated with that instance or occurrence of the condition.
- cond_token (output)
- The 12-byte representation of the constructed condition token.
- fc (output)
- A 12-byte feedback code, optional in some languages,
that indicates the result of this service. If you choose to omit this
parameter, refer to Invoking callable services for the
appropriate syntax to indicate that the feedback code was omitted.
The following symbolic conditions can result from this service:
Code Severity Message number Message text CEE000 0 — The service completed successfully. CEE0CH 3 0401 An invalid case code case-code was passed to routine routine-name. CEE0CI 3 0402 An invalid control code control-code was passed to routine routine-name. CEE0CJ 3 0403 An invalid severity code severity-code was passed to routine routine-name. CEE0CK 1 0404 Facility ID facility-id with non-alphanumeric characters was passed to routine routine-name. CEE0E4 3 0452 An invalid facility ID facility-id was passed to routine routine-name.
Usage notes
- C/C++ considerations—The
structure of the condition token (type_FEEDBACK)
is described in the leawi.h header file shipped with Language Environment. You
can assign values directly to the fields of the token in the header
file without using the CEENCOD service. Figure 1 shows the layout of the type_FEEDBACK condition token in the header file.Figure 1. type_FEEDBACK data type as defined in the leawi.h header file
typedef struct { short tok_sev ; /* severity */ short tok_msgno ; /* message number */ int tok_case :2, /* flags-case/sev/cont */ tok_sever:3, tok_ctrl :3 ; char tok_facid[3]; /* fac ID */ int tok_isi ; /* index in ISI block */ } _FEEDBACK; - z/OS UNIX consideration—In multithread applications, CEENCOD affects only the calling thread.
For more information
- For more information about case 1 and case 2, see CEENCOD Usage notes.
Examples
- Following is an example of CEENCOD called by C/C++.
/*Module/File Name: EDCNCOD */ /*********************************************************/ /* Note that it is not necessary to use this service. */ /* The fields may be manipulated directly. */ /*********************************************************/ #include <stdio.h> #include <string.h> #include <leawi.h> #include <stdlib.h> #include <ceeedcct.h> int main(void) { _FEEDBACK fc,condtok; _INT2 c_1,c_2,cond_case,sev,control; _CHAR3 facid; _INT4 isi; c_1 = 1; c_2 = 99; cond_case = 1; sev = 1; control = 0; memcpy(facid,"ZZZ",3); isi = 0; CEENCOD(&c_1,&c_2,&cond_case,&sev,&control,; facid,&isi,&condtok,&fc); if ( _FBCHECK ( fc , CEE000 ) != 0 ) { printf("CEENCOD failed with message number %d\n", fc.tok_msgno); exit(2999); } /* . . . */ } - Following is an example of CEENCOD called by COBOL.
CBL LIB,QUOTE *Module/File Name: IGZTNCOD ************************************************* ** ** ** CBLNCOD - Call CEENCOD to construct a ** ** condition token ** ** ** ************************************************* IDENTIFICATION DIVISION. PROGRAM-ID. CBLNCOD. DATA DIVISION. WORKING-STORAGE SECTION. 01 SEV PIC S9(4) BINARY. 01 MSGNO PIC S9(4) BINARY. 01 CASE PIC S9(4) BINARY. 01 SEV2 PIC S9(4) BINARY. 01 CNTRL PIC S9(4) BINARY. 01 FACID PIC X(3). 01 ISINFO PIC S9(9) BINARY. 01 NEWTOK. 02 Condition-Token-Value. COPY CEEIGZCT. 03 Case-1-Condition-ID. 04 Severity PIC S9(4) BINARY. 04 Msg-No PIC S9(4) BINARY. 03 Case-2-Condition-ID REDEFINES Case-1-Condition-ID. 04 Class-Code PIC S9(4) BINARY. 04 Cause-Code PIC S9(4) BINARY. 03 Case-Sev-Ctl PIC X. 03 Facility-ID PIC XXX. 02 I-S-Info PIC S9(9) BINARY. 01 FC. 02 Condition-Token-Value. COPY CEEIGZCT. 03 Case-1-Condition-ID. 04 Severity PIC S9(4) BINARY. 04 Msg-No PIC S9(4) BINARY. 03 Case-2-Condition-ID REDEFINES Case-1-Condition-ID. 04 Class-Code PIC S9(4) BINARY. 04 Cause-Code PIC S9(4) BINARY. 03 Case-Sev-Ctl PIC X. 03 Facility-ID PIC XXX. 02 I-S-Info PIC S9(9) BINARY. PROCEDURE DIVISION. PARA-CBLNCOD. ************************************************* ** Set severity portion of Condition-ID to 0, ** ** or information only. ** ** Set msg number portion of Condition-ID to 1.** ** Set case to 1. This is a service condition. ** ** Set severity to 0, for information only. ** ** Set control to 1, for Facility-ID has been ** ** assigned by IBM. ** ** Set Facility-ID to CEE for a Language ** ** Environment condition token. ** ** Set I-S-Info to 0, indicating that no ** ** Instance Specific Information (ISI) is ** ** to be supplied. ** ************************************************* MOVE 0 TO SEV. MOVE 1 TO MSGNO. MOVE 1 TO CASE. MOVE 0 TO SEV2. MOVE 1 TO CNTRL. MOVE "CEE" TO FACID. MOVE 0 TO ISINFO. ************************************************* ** Call CEENCOD with the values assigned above ** ** to build a condition token "NEWTOK" ** ************************************************* CALL "CEENCOD" USING SEV, MSGNO, CASE, SEV2, CNTRL, FACID, ISINFO, NEWTOK, FC. IF NOT CEE000 of FC THEN DISPLAY "CEENCOD failed with msg " Msg-No of FC UPON CONSOLE STOP RUN END-IF. GOBACK. - Following is an example of CEENCOD called by PL/I.
*PROCESS MACRO; /* Module/File Name: IBMNCOD */ /****************************************************/ /** */ /** Function: CEENCOD - construct a condition token */ /** */ /****************************************************/ PLINCOD: PROC OPTIONS(MAIN); %INCLUDE CEEIBMAW; %INCLUDE CEEIBMCT; DCL SEV REAL FIXED BINARY(15,0); DCL MSGNO REAL FIXED BINARY(15,0); DCL CASE REAL FIXED BINARY(15,0); DCL SEV2 REAL FIXED BINARY(15,0); DCL CNTRL REAL FIXED BINARY(15,0); DCL FACID CHARACTER ( 3 ); DCL ISINFO REAL FIXED BINARY(31,0); DCL 01 NEWTOK, /* Feedback token */ 03 MsgSev REAL FIXED BINARY(15,0), 03 MsgNo REAL FIXED BINARY(15,0), 03 Flags, 05 Case BIT(2), 05 Severity BIT(3), 05 Control BIT(3), 03 FacID CHAR(3), /* Facility ID */ 03 ISI /* Instance-Specific Information */ REAL FIXED BINARY(31,0); DCL 01 FC, /* Feedback token */ 03 MsgSev REAL FIXED BINARY(15,0), 03 MsgNo REAL FIXED BINARY(15,0), 03 Flags, 05 Case BIT(2), 05 Severity BIT(3), 05 Control BIT(3), 03 FacID CHAR(3), /* Facility ID */ 03 ISI /* Instance-Specific Information */ REAL FIXED BINARY(31,0); SEV = 0; /* Set severity portion of */ /* Condition_ID to 0, or */ /* information only. */ MSGNO = 1; /* Set msg number portion of */ /* Condition_ID to 1. */ CASE = 1; /* Set case to 1. This is a */ /* service condition. */ SEV2 = 0; /* Set severity to 0, or */ /* information only. */ CNTRL = 0; /* Set control to 0, or Facility */ /* ID has been assigned by user */ FACID = 'USR'; /* Set Facility_ID to USR for a */ /* user condition token. */ ISINFO = 0; /* Set I_S_Info to 0, indicating */ /* that no Instance Specific */ /* Information is to be supplied. */ EENCOD ( SEV, MSGNO, CASE, SEV2, CALL CEENCOD ( SEV, MSGNO, CASE, SEV2, CNTRL, FACID, ISINFO, NEWTOK, FC ); IF FBCHECK( FC, CEE000) THEN DO; PUT SKIP LIST( 'CEENCOD created token for msg ' || NEWTOK.MsgNo || ' and facility ' || NEWTOK.FacID ); END; ELSE DO; DISPLAY( 'CEENCOD failed with msg ' || FC.MsgNo ); STOP; END; END PLINCOD;