|
CEECZST changes the size of a previously
allocated heap element. The address parameter
points to the beginning of the heap element. The new_size parameter
gives the new size of the heap element, in bytes. The contents of
the heap element are unchanged up to the shorter of the new and old
sizes.
The CEECZST service returns a pointer to the reallocated
heap element. It can move the storage location of the heap element.
As a result, the address parameter passed
to CEECZST is not necessarily the same as the value returned.
Because
the new storage might be allocated at a different location from the
existing allocation, any pointers (specifically any addresses) that
referred to the old storage become invalid. Continued use of such
dangling pointers gives unpredictable, and almost certainly incorrect,
results.
The heap identifier is inferred from the address.
The new storage block is allocated from the same heap that contained
the old block.
The contents of the old storage are preserved
in the following manner: - If new_size is greater than the old
size, the entire contents of the old storage block are copied to the
new block. The remaining bytes in the new element are left uninitialized
unless an initialization suboption value was specified for the heap
in the STORAGE option.
- If new_size is less than the old size,
the contents of the old block are truncated to the size of the new
block.
- If new_size is equal to the old size,
no operations are performed; a successful feedback code is returned.
Syntax
>>-CEECZST--(--address--,--new_size--,--fc--)------------------><
- address (input/output)
- A fullword address pointer. On input, this parameter contains
an address returned by a previous CEEGTST call. On
output, the address of the first byte of the newly allocated storage
is returned in this parameter.
- new_size (input)
- A fullword binary signed integer. new_size is
the number of bytes of storage to be allocated for the new heap element.
- 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. |
CEE0P8 |
3 |
0808 |
Storage size in a get storage request or a reallocate request
was not a positive number. |
CEE0PA |
3 |
0810 |
The storage address in a free storage request was not recognized,
or heap storage control information was damaged. |
CEE0PD |
3 |
0813 |
Insufficient storage was available to satisfy a get storage
request. |
Usage notes - Storage that is reallocated maintains the same mark/release status
as the old storage block. If the old storage block was marked, the
new storage block carries the same mark and is released by a release
operation that specifies that mark.
- z/OS UNIX consideration—CEECZST
applies to the enclave.
- The _CEE_REALLOC_CONTROL environment variable provides additional
levels of storage control, which can aid CEECZST to more efficiently
use storage. For more information about _CEE_REALLOC_CONTROL, seez/OS XL C/C++ Programming Guide.
Examples - Following is an example of CEECZST called by C/C++.
/*Module/File Name: EDCCZST */
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <leawi.h>
#include <ceeedcct.h>
int main(void) {
_INT4 heapid, size;
_POINTER address;
_FEEDBACK fc;
/* .
.
. */
heapid = 0; /* get storage from initial heap */
size = 4000; /* number of bytes of heap storage */
/* obtain the storage using CEEGTST */
CEEGTST(&heapid,&size,&address,&fc);
/* check the first 4 bytes of the feedback token */
/* (0 if successful) */
if ( _FBCHECK ( fc , CEE000 ) != 0 ) {
printf("CEEGTST failed with message number %d\n",
fc.tok_msgno);
exit(99);
}
/* .
.
. */
size = 2000; /* new size of storage element */
/* change the size of the storage element */
CEECZST(&address,&size,&fc);
/* check the first 4 bytes of the feedback token */
/* (0 if successful) */
if ( _FBCHECK ( fc , CEE000 ) != 0 ) {
printf("CEECZST failed with message number %d\n",
fc.tok_msgno);
exit(99);
}
/* .
.
. */
/* free the storage that was previously obtained */
/* using CEEGTST */
CEEFRST(&address,&fc);
/* check the first 4 bytes of the feedback token */
/* (0 if successful) */
if ( _FBCHECK ( fc , CEE000 ) != 0 ) {
printf("CEEFRST failed with message number %d\n",
fc.tok_msgno);
exit(99);
}
/* .
.
. */
}
- Following is an example of CEECZST called by COBOL.
CBL LIB,QUOTE
*Module/File Name: IGZTCZST
************************************************
** **
** Function: CEECZST - reallocate storage **
** **
** In this example, CEEGTST is called to **
** request storage from HEAPID = 0, and **
** CEECZST is called to change the size of **
** that storage request. **
** **
** **
************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. CBLCZST.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 HEAPID PIC S9(9) BINARY.
01 HPSIZE PIC S9(9) BINARY.
01 ADDRSS POINTER.
01 NEWSIZE 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-CBLGTST.
*************************************************
** Specify 0 to get storage from the initial **
** heap. Specify 4000 to get 4000 bytes of **
** storage. **
*************************************************
MOVE 0 TO HEAPID.
MOVE 4000 TO HPSIZE.
*************************************************
** Call CEEGTST to obtain storage. **
*************************************************
CALL "CEEGTST" USING HEAPID, HPSIZE,
ADDRSS, FC.
*************************************************
** If CEEGTST runs successfully, display result**
*************************************************
IF CEE000 OF FC THEN
DISPLAY " " HPSIZE
" bytes have been allocated."
ELSE
DISPLAY "CEEGTST failed with msg "
Msg-No of FC UPON CONSOLE
STOP RUN
END-IF.
*************************************************
** Specify a new size of 2000 bytes. **
*************************************************
MOVE 2000 TO NEWSIZE.
*************************************************
** Call CEECZST to change the size of the **
** storage allocated in the call to CEEGTST. **
*************************************************
CALL "CEECZST" USING ADDRSS, NEWSIZE, FC.
*************************************************
** If CEECZST runs successfully, display result**
*************************************************
IF CEE000 OF FC THEN
DISPLAY
"The storage element now contains "
NEWSIZE " bytes."
ELSE
DISPLAY "CEEGTST failed with msg "
Msg-No of FC UPON CONSOLE
STOP RUN
END-IF.
GOBACK.
- Following is an example of CEECZST called by PL/I.
*PROCESS MACRO;
/*Module/File Name: IBMCZST */
/***************************************************/
/** **/
/** Function: CEECZST - reallocate storage **/
/** **/
/** In this example, CEEGTST is called to request **/
/** storage from HEAPID = 0, and CEECZST is called**/
/** to change the size of that storage request. **/
/** **/
/** **/
/***************************************************/
PLICZST: PROC OPTIONS(MAIN);
%INCLUDE CEEIBMAW;
%INCLUDE CEEIBMCT;
DCL HEAPID REAL FIXED BINARY(31,0) ;
DCL STGSIZE REAL FIXED BINARY(31,0) ;
DCL ADDRSS1 POINTER;
DCL 01 FC1, /* 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 ADDRSS2 POINTER;
DCL NEWSIZE 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; /* get storage from initial heap */
STGSIZE = 4000; /* get 4000 bytes of storage */
/* Call CEEGTST to obtain the storage */
CALL CEEGTST ( HEAPID, STGSIZE, ADDRSS1, FC1 );
IF FBCHECK( FC1, CEE000) THEN DO;
PUT SKIP LIST( 'Obtained ' || STGSIZE
|| ' bytes of storage at location '
|| DECIMAL( UNSPEC( ADDRSS1 ) )
|| ' from heap ' || HEAPID );
END;
ELSE DO;
DISPLAY( 'CEEGTST failed with msg '
|| FC1.MsgNo );
STOP;
END;
NEWSIZE = 2000;
/* change size of HEAPID 0 to 2000 bytes */
/* Call CEECZST to change the size of storage */
ADDRSS2 = ADDRSS1;
CALL CEECZST ( ADDRSS2, NEWSIZE , FC2 );
IF FBCHECK( FC2, CEE000) THEN DO;
PUT SKIP LIST( 'Obtained ' || NEWSIZE
|| ' bytes of storage at location '
|| DECIMAL( UNSPEC( ADDRSS1 ) ) );
PUT SKIP LIST( 'Original ' || STGSIZE
|| ' bytes of storage at location '
|| DECIMAL( UNSPEC( ADDRSS1 ) )
|| ' no longer valid' );
END;
ELSE DO;
DISPLAY( 'CEECZST failed with msg '
|| FC2.MsgNo );
STOP;
END;
END PLICZST;
|