CEECZST—Reallocate (change size of) storage
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.
For more information
- See STORAGE for more information about the STORAGE runtime option.
- For information about CEEGTST, see CEEGTST—Get heap storage.
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;