CBL_ALLOC

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 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.