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