| Free-Form Syntax | (not allowed - use the %REALLOC built-in function) |
| Code | Factor 1 | Factor 2 | Result Field | Indicators | ||
|---|---|---|---|---|---|---|
| REALLOC (E) | Length | Pointer | _ | ER | _ | |
The REALLOC operation changes the length of the heap storage pointed to by the result-field pointer to the length specified in factor 2. The result field of REALLOC contains a basing pointer variable. The result field pointer must contain the value previously set by a heap-storage allocation operation (either an ALLOC or REALLOC operation in RPG or some other heap-storage function such as CEEGTST). It is not sufficient to simply point to heap storage; the pointer must be set to the beginning of an allocation.
New storage is allocated of the specified size and the value of the old storage is copied to the new storage. Then the old storage is deallocated. If the new length is shorter, the value is truncated on the right. If the new length is longer, the new storage to the right of the copied data is uninitialized.
The result field pointer is set to point to the new storage.
If the operation does not succeed, an error condition occurs, but the result field pointer will not be changed. If the original pointer was valid and the operation failed because there was insufficient new storage available (status 425), the original storage is not deallocated, so the result field pointer is still valid with its original value.
If the pointer is valid but it does not point to storage that can be deallocated, then status 426 (error in storage management operation) will be set.
To handle exceptions with program status codes 425 or 426, either the operation code extender 'E' or an error indicator ER can be specified, but not both. For more information on error handling, see Program Exception/Errors.
Factor 2 contains a numeric variable or constant that indicates the new size of the storage (in bytes) to be allocated. Factor 2 must be numeric with zero decimal positions. The value must be between 1 and the maximum size allowed.
The maximum size allowed depends on the type of heap storage used for memory management operations due to the ALLOC keyword on the Control specification. If it is known at compile time that the module uses the teraspace storage model for memory management operations, the maximum size allowed is 4294967295 bytes. Otherwise, the maximum size allowed is 16776704 bytes.
The maximum size available at runtime may be less than the maximum size allowed by RPG.
When RPG memory management operations for the module are using single-level heap storage due to the ALLOC keyword on the Control specification, the REALLOC operation can only handle pointers to single-level heap storage. When RPG memory management operations for the module are using teraspace heap storage, the REALLOC operation can handle pointers to both single-level and teraspace heap storage.
For more information, see Memory Management Operations.
D Ptr1 S *
D Fld S 32767A BASED(Ptr1)
* The ALLOC operation allocates 7 bytes to the pointer Ptr1.
* After the ALLOC operation, only the first 7 bytes of variable
* Fld can be used.
C ALLOC 7 Ptr1
C EVAL %SUBST(Fld : 1 : 7) = '1234567'
C REALLOC 10 Ptr1
* Now 10 bytes of Fld can be used.
C EVAL %SUBST(Fld : 1 : 10) = '123456789A'