|
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.
Table 1 contains a list of the S/370 program
interrupt codes and their corresponding Language Environment condition
token names and message numbers.
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.
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;
|