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