ALLOC (Allocate Storage)

Free-Form Syntax (not allowed - use the %ALLOC built-in function)
Code Factor 1 Factor 2 Result Field Indicators
ALLOC (E)   Length Pointer _ ER _

The ALLOC operation allocates storage in the default heap of the length specified in factor 2. The result field pointer is set to point to the new heap storage. The storage is uninitialized.

Factor 2 must be a numeric with zero decimal positions. It can be a literal, constant, standalone field, subfield, table name or array element. The value must be between 1 and the maximum size supported. If the value is out of range at runtime, an error will occur with status 425. If the storage could not be allocated, an error will occur with status 426. If these errors occur, the result field pointer remains unchanged.

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.

The result field must be a basing pointer scalar variable (a standalone field, data structure subfield, table name, or array element).

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.

For more information, see Memory Management Operations.

Figure 1. ALLOC Operation
 D Ptr1            S               *
 D Ptr2            S               *
 C                   ALLOC     7                 Ptr1
  * Now Ptr1 points to 7 bytes of storage
 C                   ALLOC (E) 12345678          Ptr2
  * This is a large amount of storage, and sometimes it may
  * be unavailable.  If the storage could not be allocated,
  * %ERROR will return '1', the status is set to 00426, and
  * %STATUS will return 00426.