ALLOCATE COLLECTION statement

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

Syntax


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

Usage

This statement is an extension to the ANSI/ISO standard for SQL. Use this statement with ESQL/C.

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 programs:

  1. Declare the collection variable as a client collection variable in the program.

    The collection variable can be a typed or untyped collection variable.

  2. 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, or to a negative error code if the allocation failed.

When you no longer need the collection variable, you must explicitly release the memory that it occupies with the DEALLOCATE COLLECTION statement. After the DEALLOCATE COLLECTION statement executes successfully, you can reuse the collection variable.
Tip: The ALLOCATE COLLECTION statement allocates memory for collection variables only. To allocate memory for row variables, use the ALLOCATE ROW statement.

Examples

The following example shows how to allocate resources with the ALLOCATE COLLECTION statement for the untyped collection variable, a_set: 
EXEC SQL BEGIN DECLARE SECTION;
   client collection a_set;
EXEC SQL END DECLARE SECTION;
. . .
EXEC SQL allocate collection :a_set;
The following example uses ALLOCATE COLLECTION to allocate resources for a typed collection variable, a_typed_set: 
EXEC SQL BEGIN DECLARE SECTION;
   client collection set(integer not null) a_typed_set;
EXEC SQL END DECLARE SECTION;
. . .
EXEC SQL allocate collection :a_typed_set;