%REALLOC(ptr:num)%REALLOC changes the heap storage pointed to by the first parameter to be the length specified in the second parameter. The heap storage pointed to by the returned pointer has the same value as the heap storage pointed to by ptr. If the new length is longer than the old length, the additional storage is uninitialized.
The first parameter must be a basing pointer value. The second parameter must be a non-float numeric value with zero decimal places. The length specified must be between 1 and the maximum size allowed.
The maximum size allowed depends on the type of heap storage used for RPG memory management operations due to the ALLOC keyword on the Control specification. If the module uses teraspace heap storage, 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.
The function returns a pointer to the allocated storage. This may be the same as ptr or different. If the %REALLOC function is successful, the original pointer value specified in the first operand should not be used.
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 built-in function can only handle pointers to single-level heap storage. When RPG memory management operations for the module are using teraspace heap storage, the %REALLOC built-in function operation can handle pointers to both single-level and teraspace heap storage.
For more information, see Memory Management Operations.
If the operation cannot complete successfully, exception 00425 or 00426 is issued.
*..1....+....2....+....3....+....4....+....5....+....6....+....7...+....
/FREE
// Allocate an area of 200 bytes
pointer = %ALLOC(200);
// Change the size of the area to 500 bytes
pointer = %REALLOC(pointer:500);
// Using two different pointers:
pointer2 = %REALLOC(pointer1:500);
pointer1 = *NULL;;
// The returned value was assigned to
// "pointer2", a different variable
// from the input pointer "pointer1".
// In this case, the value of "pointer1"
// is no longer valid, so "pointer1" must
// be set to *NULL to avoid using the
// old value.
/END-FREE