Create Heap (CEECRHP) API

Required Parameter:

heap_id

Output

INT4

Omissible Parameter Group:

2	initial_size	Input	INT4
3	increment	Input	INT4
4	alloc_strat_id	Input	INT4
5	fc	Output	FEEDBACK

  Service Program Name: QLEAWI

  Default Public Authority: *USE

  Threadsafe: Yes

The Create Heap (CEECRHP) API creates a new heap.

Authorities and Locks

None.

Required Parameter

heap_id (output)

The heap identifier of the created heap.

Omissible Parameter Group

initial_size (input)

The initial amount of storage, in bytes, allocated for the new heap. If this parameter is 0 or omitted, and there is no corresponding value in the user-defined allocation strategy, the system computes a default value. The minimum value that can be specified is 512 bytes. If values between 1 and 512 bytes are specified, the system rounds the value up to 512 bytes automatically. The maximum value that can be specified is 16MB minus 1KB. The value specified is rounded up to a 512-byte boundary.

Note: If system resources are constrained, the system may override the value specified.

increment (input)

The number of bytes by which the heap is extended when it is necessary to enlarge the heap to satisfy an allocation request. If this parameter is 0 or omitted, and there is no corresponding value in the user-defined allocation strategy, the system computes a default value. The minimum value that can be specified is 512 bytes. If values between 1 and 512 bytes are specified, the system rounds the value up to 512 bytes automatically. The maximum value that can be specified is 16MB minus 1KB. The value specified is rounded up to a 512-byte boundary.

Note: If system resources are constrained, the system may override the value specified.

alloc_strat_ID (input)

The allocation strategy used. ILE allows allocation strategy values of 0, 1, and 40 through 44 from the possible range of values 0 through 99, where:

0	Specifies use of an allocation strategy that is the optimal default for the system.
1	Same as 0.
40-44	User-defined allocation strategies. See Define Heap Allocation Strategy (CEE4DAS) API for information on defining allocation strategies.

For allocation strategy values outside of the values specified above:

2-39	The values are reserved for other systems. If they are specified, message CEE0814 is issued.
45-49	The values are reserved for other systems. If they are specified, message CEE0815 is issued.
50-99	The values are not supported by ILE. If they are specified, message CEE0806 is issued.

fc (output)

A 12-byte feedback code.

Feedback Codes and Conditions

Severities of 10 or less represent success. For higher severities, no heap is created, and all other output values are undefined.

CEE0000

The API completed successfully

Severity: 00

CEE0804

The initial_size parameter is not valid

Severity: 30

CEE0805

The increment parameter is not valid

Severity: 30

CEE0806

Allocation strategy identifier value is not valid

Severity: 30

CEE0809

The maximum number of heaps supported by ILE has been reached

Severity: 30

CEE0813

Insufficient storage available to satisfy the request

Severity: 30

CEE0814

Allocation strategy identifier is not supported by ILE

Severity: 30

CEE0815

Allocation strategy identifier is not supported by ILE

Severity: 30

CEE3006

At least one field in the allocation strategy is not valid

Severity: 30

Usage Notes

If a user-defined allocation strategy value is specified for which the CEE4DAS API was not called, the default user-created heap strategy is used. See User-Defined Allocation Strategy.

The initial_size and increment values, if specified, will override any default or user-created heap strategy values.

If one of the fields in the allocation strategy CEE4DAS is not valid, the heap is not created and an error condition is raised. This API checks the allocation strategy.