|
CEEMGET
retrieves, formats, and stores in a passed message area a message
corresponding to a condition token that is either returned from a
callable service or passed to a user-written condition handler. The
caller can later retrieve the message to change or to write as output.
Syntax
>>-CEEMGET--(--cond_token--,--message_area--,--msg_ptr--,--fc--->
>--)-----------------------------------------------------------><
- cond_token (input/output)
- A 12-byte condition token received or returned
as the result of a Language Environment callable
service.
- message_area (input/output)
- A fixed-length 80-character string (VSTRING), where the message
is placed. The message is left-justified and padded on the right with
blanks.
- msg_ptr (input/output)
- A
4-byte binary integer returned to the calling routine. The msg_ptr should
be passed a value of zero on the initial call to CEEMGET. If a message
is too large to be contained in the message_area, msg_ptr (containing
the index) is returned into the message. This index is used on subsequent
calls to CEEMGET to retrieve the remaining portion of the message.
A feedback code is also returned, indicating that the message was
truncated. When the entire message is returned, msg_ptr is
zero.
The msg_ptr contains different
results based on the length of the message: - If a message contains fewer than 80 characters, the entire message
is returned on the first call. msg_ptr contains
0.
- If a message contains exactly 80 characters, the entire message
is returned on the first call. msg_ptr contains
0.
- If the message is too long, CEEMGET splits it into segments. The msg_ptr does
not contain the cumulative index for the entire message returned so
far, but contains only the index into the segment that was just returned.
It is up to the user of CEEMGET to maintain the cumulative count if
needed. When a message is too long, the following can occur:
- If a message contains more than 80 characters and at least one
blank is contained in the first 80 characters, the string up to and
including the last blank is returned on the first call.
- If the 80th character is nonblank (even if the 81st character
is a blank), msg_ptr contains the index
of the last blank (something less than 80), and the next call starts
with the next character.
- If the 80th character is a blank, msg_ptr contains
80 and the next call starts with the 81st character, blank or nonblank.
- If a message contains more than 80 characters and at least the
first 80 are all nonblank, the first 80 are returned and the next
call does not add any blanks and starts with the 81st character. msg_ptr contains
80.
- 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. |
CEE036 |
3 |
0102 |
An unrecognized condition token was passed to routine and
could not be used. |
CEE0E2 |
3 |
0450 |
The message inserts for the condition token with message number message-number and
facility ID facility-id could not be located. |
CEE0E6 |
3 |
0454 |
The message number message-number could
not be found for facility ID facility-id. |
CEE0E7 |
1 |
0455 |
The message with message number message-number and
facility ID facility-id was truncated. |
CEE0EA |
3 |
0458 |
The message repository repository-name could
not be located. |
Usage notes - z/OS UNIX considerations—In
multithread applications, CEEMGET affects only the calling thread.
However, CEEMGET uses the NATLANG value of the enclave. Any subsequent
calls to CEEMGET, for a given condition, use the NATLANG value in
effect at the time of the first call.
Examples - Following is an example of CEEMGET called by C/C++.
/*Module/File Name: EDCMGET */
#include <string.h>
#include <stdio.h>
#include <leawi.h>
#include <stdlib.h>
#include <ceeedcct.h>
int main(void) {
_VSTRING message;
_INT4 dest,msgindx;
_INT2 c_1,c_2,cond_case,sev,control;
_CHAR3 facid;
_INT4 isi;
_CHAR80 msgarea;
_FEEDBACK fc,token;
/* construct a token for CEE message 2523 */
c_1 = 1;
c_2 = 2523;
cond_case = 1;
sev = 1;
control = 1;
memcpy(facid,"CEE",3);
isi = 0;
CEENCOD(&c_1,&c_2,&cond_case,&sev,&control,;
facid,&isi,&token,&fc);
if ( _FBCHECK ( fc , CEE000 ) != 0 ) {
printf("CEENCOD failed with message number %d\n",
fc.tok_msgno);
exit(2999);
}
msgindx = 0;
memset(msgarea,' ',79);/* initialize the message area */
msgarea_80¨ = '\0';
/* use CEEMGET until all the message has been */
/* retrieved */
/* msgindx will be zero when all the message has */
/* been retrieved */
do {
CEEMGET(&token,msgarea,&msgindx,&fc);
if (fc.tok_sev > 1 ) {
printf("CEEMGET failed with message number %d\n",
fc.tok_msgno);
exit(2999);
}
/* put out the message using CEEMOUT */
memcpy(message.string,msgarea,80);
message.length = 80;
dest = 2;
CEEMOUT(&message,&dest,&fc);
if ( _FBCHECK ( fc , CEE000 ) != 0 ) {
printf("CEEMOUT failed with message number %d\n",
fc.tok_msgno);
exit(2999);
}
} while (msgindx != 0);
}
- Following is an example of CEEMGET called by COBOL.
CBL LIB,QUOTE
*Module/File Name: IGZTMGET
******************************************
** **
** CBLMGET - Call CEEMGET to get a **
** message. First set up a **
** condition token using **
** CEENCOD. **
** **
******************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. CBLMGET.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 MSGBUF PIC X(80).
01 MSGPTR 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.
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-CBLMGET.
********************************************
** Give contok value of **
** 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 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.
*************************************************
** Always pass 0 in MSGPTR on the initial **
** call to CEEMGET. If the message is too **
** long to be returned in a single call, **
** MSGPTR will be returned containing an **
** index to the message that can be used on **
** subsequent calls to CEEMGET. **
*************************************************
MOVE 0 TO MSGPTR.
*************************************************
** Call CEEMGET to get the message associated **
** with the condition token **
*************************************************
CALL "CEEMGET" USING NEWTOK, MSGBUF,
MSGPTR , FC.
IF NOT CEE000 of FC THEN
DISPLAY "CEEMGET failed with msg "
Msg-No of FC UPON CONSOLE
STOP RUN
ELSE
DISPLAY "The message is: " MSGBUF
END-IF.
GOBACK.
- Following is an example of CEEMGET called by PL/I.
*PROCESS MACRO;
/* Module/File Name: IBMMGET */
/****************************************************/
/** **/
/**Function : CEEMGET - Get a Message **/
/** **/
/****************************************************/
PLIMGET: PROC OPTIONS(MAIN);
%INCLUDE CEEIBMAW;
%INCLUDE CEEIBMCT;
DCL 01 CONTOK, /* 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);
DCL MSGBUF CHAR(80);
DCL MSGPTR REAL FIXED BINARY(31,0);
/* Give CONTOK value of condition CEE001 */
ADDR( CONTOK ) -> CEEIBMCT = CEE001;
MSGPTR = 0;
/* Call CEEMGET to retrieve msg corresponding */
/* to condition token */
CALL CEEMGET ( CONTOK, MSGBUF, MSGPTR, FC );
IF FBCHECK( FC, CEE000) THEN DO;
PUT SKIP LIST( 'Message text for message number'
|| CONTOK.MsgNo || ' is "' || MSGBUF || '"');
END;
ELSE DO;
DISPLAY( 'CEEMGET failed with msg '
|| FC.MsgNo );
STOP;
END;
END PLIMGET;
|