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
ALLOCATE COLLECTIONvariable
| Element | Description | Restrictions | Syntax |
|---|---|---|---|
| variable | Name of the typed or untyped collection variable to allocate | Must be an unallocated Informix® ESQL/C 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 Informix® ESQL/C programs:
- Declare the collection variable as a client collection variable
in the Informix®
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, 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 Informix®
ESQL/C collection
variables only. To allocate memory for Informix®
ESQL/C 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;