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