CEESGL—Signal a condition
CEESGL raises, or signals, a condition to the Language Environment condition manager. It also provides qualifying data and creates an ISI for a particular instance of the condition. The ISI contains information used by the Language Environment condition manager to identify and react to conditions.
CEESGL is typically used to generate application-specific conditions that are recognized by condition handlers registered using CEEHDLR. Conditions can also be selected to simulate a Language Environment or system condition. If you plan on using a routine that signals a new condition with a call to CEESGL, you should first call the CEECMI callable service to copy any insert information into the ISI associated with the condition.
CEESGL generates a Language Environment condition. You can map some of the Language Environment condition tokens to POSIX signals. Unique conditions signaled by CEESGL are considered to be enabled under Language Environment. Therefore, they undergo Language Environment condition handling.
CEESGL can signal a POSIX condition. If CEESGL signals a POSIX condition and the signal is blocked at the time of the generation but later unblocked and delivered, the POSIX signal processing semantics are applied. The Language Environment synchronous condition manager semantics do not apply.
Severity 0 and 1 conditions are considered safe conditions. They can be ignored if they are not handled and if no feedback token is passed when the condition is raised.
Each signaled condition (of severity 2 or above) increments the error count by one. If the error count exceeds the error count limit (as specified by the ERRCOUNT runtime option—see ERRCOUNT) the condition manager terminates the enclave with abend code 4091, reason code 11. T_I_U (Termination Imminent due to an Unhandled Condition) is not issued. Promoted conditions do not increment the error count. A program established using the CEEHDLR callable service or one of the HLL condition handlers, can then process the raised condition.
ERRCOUNT applies to CEESGL only if the condition generated by CEESGL is delivered synchronously. POSIX signal handling semantics are then applied to the condition.
Syntax >>-CEESGL--(--cond_rep--,--+-----------------+--fc--)---------->< '-q_data_token--,-'
- cond_rep (input)
- A 12-byte condition token representing the condition to be signaled. You can either construct your own condition token or use one that Language Environment has already defined. Conditions signaled by CEESGL are not necessarily handled by Language Environment. If you call CEESGL with a cond_rep, Language Environment passes control to the language in which the routine is written. The condition manager then determines if it should handle the condition. If so, the HLL handles the condition. If not, control returns to Language Environment. The condition might also be ignored or blocked, or might result in enclave termination.
- q_data_token (input/output)
- An optional 32-bit data object placed in the ISI to access the qualifying data (q_data) associated with the given instance of the condition. The q_data_token is a list of information addresses a user condition handler uses to specifically identify and, if necessary, react to, a given condition. The information in the q_data_token provides a mechanism by which user-written condition handlers can provide a complete fix-up of some conditions. The q_data token associated with a condition using CEESGL can be extracted later using the CEEGQDT callable service.
- fc (output / optional)
- 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. CEE069 0 0201 An unhandled condition was returned in a feedback code. CEE0CE 1 0398 Resume with new input. CEE0CF 1 0399 Resume with new output. CEE0EB 3 0459 Not enough storage was available to create a new instance specific information block. CEE0EE 3 0462 Instance specific information for the condition token with message number message-number and facility ID facility-id could not be found.
Usage notes
- PL/I consideration: Conditions with a facility_ID of IBM® cannot be used in CEESGL.
- z/OS UNIX consideration: In multithread applications, CEESGL affects only the calling thread. Delivery of a CEESGL generated condition is limited to the thread that generated the condition. However, if the condition is a severity 2 or higher, and is not handled by the application, the default action of terminate applies to the enclave, not just the calling thread.
- COBOL consideration: When a resume occurs and control resumes to the next instruction that follows the call to CEE3SRP, the COBOL RETURN-CODE special register contains an unpredictable value.
For more information
- See CEECMI—Store and load message insert data for more information about the CEECMI callable service.
- See z/OS Language Environment Programming Guide for more information about mapping Language Environment condition tokens to POSIX signals.
- See ERRCOUNT for more information about the ERRCOUNT runtime option.
- To construct your own condition token, see CEENCOD—Construct a condition token.
- For more information about condition handling, see z/OS Language Environment Programming Guide.
- See CEEGQDT—Retrieve q_data_token for more information about the CEEGQDT callable service.
Examples
- Following is an example of CEESGL called by C/C++.
/*Module/File Name: EDCSGL */ #include <stdio.h> #include <string.h> #include <stdlib.h> #include <leawi.h> #include <ceeedcct.h> int main(void) { _FEEDBACK fc,condtok; _ENTRY routine; _INT4 token,qdata; _INT2 c_1,c_2,cond_case,sev,control; _CHAR3 facid; _INT4 isi; /* . . . */ /* build the condition token */ 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); } /* signal the condition */ CEESGL(&condtok,&qdata,&fc); if ( _FBCHECK ( fc , CEE000 ) != 0 ) { printf("CEESGL failed with message number %d\n", fc.tok_msgno); exit(2999); } /* . . . */ } - Following is an example of CEESGL called by COBOL.
CBL LIB,QUOTE *Module/File Name: IGZTSGL ************************************************ ** ** ** CBLSGL - Call CEESGL to signal a condition ** ** ** ************************************************ IDENTIFICATION DIVISION. PROGRAM-ID. CBLSGL. DATA DIVISION. WORKING-STORAGE SECTION. 01 CONDTOK. 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 QDATA 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. 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. PROCEDURE DIVISION. PARA-CBLSGL. ************************************************ ** Call CEENCOD with the values assigned above ** to build a condition token "CONDTOK" ** Set CONDTOK to sev = 0, msgno = 1 facid = CEE ************************************************ 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" USING SEV, MSGNO, CASE, SEV2, CNTRL, FACID, ISINFO, CONDTOK, FC. IF NOT CEE000 of FC THEN DISPLAY "CEENCOD failed with msg " Msg-No of FC UPON CONSOLE STOP RUN END-IF. ** Call CEESGL to signal the condition with ************************************************ ** the condition token and qdata described ** in CONDTOK and QDATA ************************************************ MOVE 0 TO QDATA. CALL "CEESGL" USING CONDTOK, QDATA, FC. IF NOT CEE000 of FC THEN DISPLAY "CEESGL failed with msg " Msg-No of FC UPON CONSOLE STOP RUN END-IF. GOBACK. - Following is an example of CEESGL called by PL/I.
*PROCESS MACRO; /* Module/File Name: IBMSGL */ /****************************************************/ /** */ /** Function: CEESGL - Signal a Condition */ /** */ /****************************************************/ PLISGL: PROC OPTIONS(MAIN); %INCLUDE CEEIBMAW; %INCLUDE CEEIBMCT; DCL 01 CONDTOK, /* 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 QDATA 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); /* Give CONDTOK value of condition CEE001 */ ADDR( CONDTOK ) -> CEEIBMCT = CEE001; /* Signal condition CEE001 with qualifying data */ QDATA = 1; CALL CEESGL ( CONDTOK, QDATA, FC ); IF FBCHECK( FC, CEE000) THEN DO; PUT SKIP LIST( 'Condition CEE001 signalled' ); END; ELSE DO; DISPLAY( 'CEESGL failed with msg ' || FC.MsgNo ); STOP; END; END PLISGL;