Dynamically allocates memory, and can associate allocated heap data with a thread and/or the calling program.
Syntax:
call "CBL_ALLOC_MEM" using mem-pointer
by value mem-size
by value flags
returning status-code
Parameters:
| |
Using call prototype (see
Key)
|
Picture
|
|
mem-pointer
|
cblt-pointer
|
usage pointer. Must be level 01.
|
|
mem-size
|
cblt-os-size
|
pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
|
|
flags
|
cblt-os-flags
|
pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
|
|
status-code
|
See
Library Routines - Key
|
|
On Entry:
-
mem-size
- The number of bytes of memory to allocate.
-
flags
- The type of memory required. You can set the following bits:
| Bit 0
|
Allocate this memory as shared.
|
| Bit 1
|
Reserved. Must be set to zero.
|
| Bit 2
|
Allocate this memory independently from any calling program. If bit 3 is set it will be freed automatically when the calling
thread ends. If bit 3 is unset it will be freed when the run-unit ends.
|
| Bit 3
|
Allocate this memory as thread local. If bit 2 is unset and there is a direct or indirect (in a mixed language environment)
calling COBOL program, it will be freed when the calling program is canceled or the thread ends - whichever comes first.
|
| Remaining bits
|
Reserved. Must be set to 0.
|
On Exit:
-
mem-pointer
- A pointer to the memory allocated. The allocated memory is not initialized.
Comments:
The memory allocated is not initialized to any value.
Updates to any shared memory allocated to this function are not serialized or protected by the run-time system; you should use semaphores to maintain the integrity of the data.
If the memory has been allocated by a thread, it is freed when the calling thread terminates.
The maximum size of nonshared memory is restricted only by your operating system.
The maximum size of shared memory is restricted by the operating system and the run-time system. The run-time tunable, shared_memory_segment_size, can be used to set the maximum size. The default is 65536, and the minimum is 8192 bytes.
Bit 1 and bit 2 or bit 3 are mutually exclusive. This is checked and error 181 returned otherwise. If there is no calling program (directly or indirectly in a mixed language environment) bit 2 is ignored.
If bit 2 is not set all standard memory allocated by CBL_ALLOC_MEM is freed when the program that allocated it is canceled (logically or physically), if there is a COBOL program that is directly or indirectly the caller.
This routine cannot be used within a sub-program that is compiled with the AMODE directive in effect.