CEEMGET—Get a message
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.
For more information
- See CEENCOD—Construct a condition token for a description of the 12-byte condition token constructed by the CEENCOD callable service.
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;