ALLOCATE COLLECTION

Use the ALLOCATE COLLECTION statement to allocate memory for a variable of a collection data type (such as LIST, MULTISET, or SET) or an untyped collection variable.

Only Dynamic Server supports this statement, which is an extension to the ANSI/ISO standard for SQL. Use this statement with ESQL/C.

Syntax

>>-ALLOCATE COLLECTION--variable-------------------------------><

Element	Description	Restrictions	Syntax
variable	Name of the typed or untyped collection variable to allocate	Must be an unallocated ESQL/C collection-type host variable	Language-specific rules for names

Usage

The ALLOCATE COLLECTION statement allocates memory for an ESQL/C variable that can store the value of a collection data type.

To create a collection variable for an ESQL/C program

Declare the collection variable as a client collection variable in an ESQL/C program.
The collection variable can be a typed or untyped collection variable.
Allocate memory for the collection variable with the ALLOCATE COLLECTION statement.

The ALLOCATE COLLECTION statement sets SQLCODE (that is, sqlca.sqlcode) to zero (0) if the memory allocation was successful and to a negative error code if the allocation failed.

You must explicitly release memory with the DEALLOCATE COLLECTION statement. After you free the collection variable with the DEALLOCATE COLLECTION statement, you can reuse the collection variable.

Tip:

The ALLOCATE COLLECTION statement allocates memory for an ESQL/C collection variable only. To allocate memory for an ESQL/C row variable, use the ALLOCATE ROW statement.