CEEDSHP—Discard heap
CEEDSHP discards an entire heap created by CEECRHP or by CEEGTST. CEECRHP and CEEGTST return a unique heap_id to the caller; use this ID in the CEEDSHP call. A heap_id of 0 is not permitted with CEEDSHP.
Discarding a heap with CEEDSHP
immediately returns all storage allocated to the heap to the operating
system, even if the KEEP suboption has been specified with the HEAP
runtime option.
Syntax >>-CEEDSHP--(--heap_id--,--fc--)-------------------------------><
- heap_id (input)
- A fullword binary signed integer. heap_id is a token specifying the discarded heap. A heap_id of 0 is not valid; the initial heap is logically created during enclave initialization and cannot be discarded.
- 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. CEE0P2 4 0802 Heap storage control information was damaged. CEE0P3 3 0803 The heap identifier in a get storage request or a discard heap request was unrecognized. CEE0PC 3 0812 An invalid attempt to discard the Initial Heap was made.
Usage notes
- After the call to CEEDSHP, any existing pointers to storage allocated from this heap are dangling pointers, that is, pointers to storage that is freed. Using these pointers can cause unpredictable results.
- z/OS UNIX considerations—CEEDSHP applies to the enclave. Language Environment frees all storage in the heap regardless of which thread allocated it.
For more information
- For more information about the CEEDSHP callable service, see CEECRHP—Create new additional heap.
- For more information about the CEEGTST callable service, and CEEGTST—Get heap storage.
Examples
- Following is an example of CEEDSHP being called by C/C++.
/*Module/File Name: EDCDSHP */ #include <stdio.h> #include <string.h> #include <stdlib.h> #include <leawi.h> #include <ceeedcct.h> int main(void) { _INT4 heapid, size, increment, options; _FEEDBACK fc; /* . . . */ heapid = 0; /* heap identifier is set */ /* by CEECRHP */ size = 4096; /* initial size of heap */ /* (in bytes) */ increment = 4096; /* increment to extend */ /* the heap by */ options = 72; /* set up heap as */ /* (,,ANYWHERE,FREE)*/ /* create heap using CEECRHP */ CEECRHP(&heapid,&size,&increment,&options,&fc); /* check the first 4 bytes of the feedback token */ /* (0 if successful) */ if ( _FBCHECK ( fc , CEE000 ) != 0 ) { printf("CEECRHP failed with message number %d\n", fc.tok_msgno); exit(99); } /* . . . */ /* discard the heap that was previously created */ /* using CEECRHP */ CEEDSHP(&heapid,&fc); /* check the first 4 bytes of the feedback token */ /* (0 if successful) */ if ( _FBCHECK ( fc , CEE000 ) != 0 ) { printf("CEEDSHP failed with message number %d\n", fc.tok_msgno); exit(99); } /* . . . */ } - Following an example of CEEDSHP being called by COBOL.
CBL LIB,QUOTE *Module/File Name: IGZTDSHP ************************************************** ** ** ** Function: CEEDSHP - discard heap ** ** ** ** In this example, a new additional heap is ** ** created a call to CEECRHP, and then ** ** discarded through a call to CEEDSHP. ** ** ** ************************************************** IDENTIFICATION DIVISION. PROGRAM-ID. CBLDSHP. DATA DIVISION. WORKING-STORAGE SECTION. 01 HEAPID PIC S9(9) BINARY. 01 HPSIZE PIC S9(9) BINARY. 01 INCR PIC S9(9) BINARY. 01 OPTS 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-CBLCRHP. ************************************************* ** Specify 0 for HEAPID, and heap id will ** ** be set by CEECRHP. ** ** Heap size and increment will each be 4096 ** ** bytes. ** ** Specify 00 for OPTS, and HEAP attributes ** ** will be inherited from the initial heap ** ** (copied from the HEAP runtime option). ** ************************************************* MOVE 0 TO HEAPID. MOVE 4096 TO HPSIZE. MOVE 4096 TO INCR. MOVE 00 TO OPTS. CALL "CEECRHP" USING HEAPID, HPSIZE, INCR, OPTS, FC. IF CEE000 of FC THEN DISPLAY "Created heap number " HEAPID " which is " HPSIZE " bytes long" ELSE DISPLAY "CEECRHP failed with msg " Msg-No of FC UPON CONSOLE STOP RUN END-IF. ************************************************* ** To discard the heap, call CEEDSHP with the ** ** heap id returned from CEECRHP. ** ************************************************* CALL "CEEDSHP" USING HEAPID, FC. IF CEE000 of FC THEN DISPLAY "Disposed of heap # " HEAPID ELSE DISPLAY "CEEDSHP failed with msg " Msg-No of FC UPON CONSOLE END-IF. GOBACK. - Following is an example of CEEDSHP being called by PL/I.
*PROCESS MACRO; /*Module/File Name: IBMDSHP */ /***************************************************/ /** **/ /** Function: CEEDSHP - discard heap **/ /** **/ /** In this example, calls are made to CEECRHP **/ /** and CEEDSHP to create a heap of 4096 bytes **/ /** and then discard it. **/ /** **/ /***************************************************/ PLIDSHP: PROC OPTIONS(MAIN); %INCLUDE CEEIBMAW; %INCLUDE CEEIBMCT; DCL HEAPID REAL FIXED BINARY(31,0) ; DCL HPSIZE REAL FIXED BINARY(31,0) ; DCL INCR REAL FIXED BINARY(31,0) ; DCL OPTS 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 01 FC2, /* 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); HEAPID = 0; /* HEAPID will be set and */ /* returned by CEECRHP */ HPSIZE = 4096; /* Initial size of heap in bytes */ INCR = 4096; /* Number of bytes to extend */ /* heap by */ OPTS = 00; /* Set up heap with the same */ /* attributes as the initial */ /* heap (HEAPID = 0) */ /* Call CEECRHP to set up new heap */ CALL CEECRHP ( HEAPID, HPSIZE, INCR, OPTS, FC ); IF FBCHECK( FC, CEE000) THEN DO; PUT SKIP LIST( 'Created heap number ' || HEAPID || ' consisting of ' || HPSIZE || ' bytes' ); END; ELSE DO; DISPLAY( 'CEECRHP failed with msg ' || FC.MsgNo ); STOP; END; /* Call CEEDSHP to discard heap with the id */ /* returned by CEECRHP */ CALL CEEDSHP ( HEAPID, FC2 ); IF FBCHECK( FC2, CEE000) THEN DO; PUT SKIP LIST( 'Disposed of heap number ' || HEAPID ); END; ELSE DO; DISPLAY( 'CEEDSHP failed with msg ' || FC2.MsgNo ); STOP; END; END PLIDSHP;