CBL_ALLOC_MEM

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 (unless the -l run-time switch is set).

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 size for shared memory allocated using this routine is limited to a maximum of around 64000 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.