CEECRHP—Create new additional heap
CEECRHP lets you define additional heaps. It returns a unique heap_id. The heaps defined by CEECRHP can be used just like the initial heap (heap_id=0), below heap, and anywhere heap. Unlike the heaps created by these heap services, all heap elements within an additional heap can be quickly freed by a single call to CEEDSHP (discard heap). The number of heaps supported by Language Environment is limited only by the amount of virtual storage available.
Syntax >>-CEECRHP--(--heap_id--,--initial_size--,--increment--,--------> >--options--,--fc--)-------------------------------------------><
- heap_id (output)
- A fullword binary signed integer. heap_id is the heap identifier of the created heap. If a new heap cannot be created, the value of heap_id remains undefined. Storage obtained from heap_ids 79 and 80 is set to binary 0 independent of any initialization value specified by the STORAGE option.
- initial_size (input)
- A fullword binary signed integer. initial_size is the initial amount of storage, in bytes, allocated for the new heap. initial_size is rounded up to the nearest increment of 4096 bytes. If initial_size is specified as 0, then the init_size specified in the HEAP runtime option is used. If no HEAP runtime option was provided and initial_size is specified as 0, CEECRHP uses the system-level or region-level default.
- increment (input)
- A fullword binary signed integer. When it is necessary to enlarge the heap to satisfy an allocation request, increment represents the number of bytes by which the heap is extended. increment is rounded up to the nearest 4096 bytes. If increment is specified as 0, then the incr_size specified in the HEAP run time option is used. If no HEAP runtime option was provided and increment equals 0, CEECRHP uses the installation default.
- options (input)
- A fullword binary signed integer. options are
specified with the decimal codes, as shown in Table 1.
Table 1. HEAP attributes based on the setting of the options parameter Option setting HEAP attributes 00 Use same attributes as the initial heap (copy them from the HEAP runtime option) 01 HEAP(,,,FREE) (location inherited from HEAP runtime option) 70 HEAP(,,,KEEP) (location inherited from HEAP runtime option) 71 HEAP(,,ANYWHERE,KEEP) 72 HEAP(,,ANYWHERE,FREE) 73 HEAP(,,BELOW,KEEP) 74 HEAP(,,BELOW,FREE) 75 HEAP(,,ANYWHERE,) (disposition inherited from the HEAP runtime option) 76 HEAP(,,BELOW,) (disposition inherited from the HEAP runtime option) 77 HEAP(,,ANYWHERE,KEEP) (all heap storage obtained using this heap_id is allocated on a 4K boundary) 78 HEAP(,,ANYWHERE,FREE) (all heap storage obtained using this heap_id is allocated on a 4K boundary) 79 HEAP(,,ANYWHERE,KEEP) (all heap storage obtained using this heap_id is set to binary 0 when allocated using CEEGTST) 80 HEAP(,,ANYWHERE,FREE) (all heap storage obtained using this heap_id is set to binary 0 when allocated using CEEGTST) - 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 arise from this service:
Code Severity Message number Message text CEE000 0 — The service completed successfully. CEE0P2 4 0802 Heap storage control information was damaged. CEE0P4 3 0804 The initial size value supplied in a create heap request was unsupported. CEE0P5 3 0805 The increment size value supplied in a create heap request was unsupported. CEE0P6 3 0806 The options value supplied in a create heap request was unrecognized. CEE0PD 3 0813 Insufficient storage was available to satisfy a get storage request.
Usage notes
- z/OS UNIX consideration—CEECRHP applies to the enclave.
- The heapid can only be used by the TCB on which the CEECRHP request was issued. Using the heapid on other TCBs is not supported and will generate unpredictable results.
For more information
- See CEEDSHP—Discard heap for more information about the CEEDSHP callable service.
- See HEAP for more information about the HEAP runtime option and IBM-supplied defaults.
Examples
- Following is an example of CEECRHP called by C/C++.
/*Module/File Name: EDCCRHP */ #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 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 is an example of CEECRHP called by COBOL.
CBL LIB,QUOTE *Module/File Name: IGZTCRHP *********************************************** ** ** ** Function: CEECRHP - create new additional ** ** heap ** ** ** *********************************************** IDENTIFICATION DIVISION. PROGRAM-ID. CBLCRHP. 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. ************************************************* ** 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. GOBACK. - Following is an example of CEECRHP called by PL/I.
*PROCESS MACRO; /*Module/File Name: IBMCRHP */ /**************************************************/ /** */ /** Function: CEECRHP - create new additional */ /** heap */ /** */ /** In this example, CEECRHP is called to set up */ /** a new additional heap of 4096 bytes. Each */ /** time the heap needs to be extended, an */ /** increment of 4096 bytes will be added. */ /** */ /**************************************************/ PLICRHP: 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); 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; END PLICRHP;