Informix Guide to SQL: Syntax SQL Statements

Use the ALLOCATE COLLECTION statement to allocate memory for a collection variable.

The ALLOCATE COLLECTION statement allocates memory for a variable that stores collection data. To create a collection variable for an ESQL/C program, perform the following steps:

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

2. Allocate memory for the collection variable with the ALLOCATE COLLECTION statement.

The ALLOCATE COLLECTION statement sets SQLCODE (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. Once 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.

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;

.
.
.

Related examples: Refer to the collection variable example in PUT

Related statements: ALLOCATE ROW and DEALLOCATE COLLECTION

For a discussion of collection data types, see the Informix ESQL/C Programmer's Manual.