Use the FREE statement to release resources that are allocated to
a prepared statement or to a cursor.
Use this statement, which is an extension
to the ANSI/ISO standard for SQL, with ESQL/C.
FREE releases the resources that the database server and application-development
tool allocated for a prepared statement or for a declared cursor.
If you declared a cursor for a prepared statement, FREE statement_id (or statement_id_var) releases only
the resources in the application development tool; the cursor can still be
used. The resources in the database server are released only when you free
the cursor.
If you prepared a statement (but did not declare a cursor for it), FREE statement_id (or FREE statement_id_var) releases the resources in both the application development tool and
the database server.
After you free a statement, you cannot execute it or declare a cursor for
it until you prepare it again.
The following ESQL/C example shows the sequence of statements that is
used to free an implicitly prepared statement:
EXEC SQL prepare sel_stmt from 'select * from orders';
...
EXEC SQL free sel_stmt;
The following ESQL/C example
shows the sequence of statements that are used to release the resources of
an explicitly prepared statement. The first FREE statement in this example
frees the cursor. The second FREE statement in this example frees the prepared
statement.
sprintf(demoselect, "%s %s",
"select * from customer ",
"where customer_num between 100 and 200");
EXEC SQL prepare sel_stmt from :demoselect;
EXEC SQL declare sel_curs cursor for sel_stmt;
EXEC SQL open sel_curs;
...
EXEC SQL close sel_curs;
EXEC SQL free sel_curs;
EXEC SQL free sel_stmt;
If you declared a cursor for a prepared statement, freeing
the cursor releases only the resources in the database server. To release
the resources for the statement in the application-development tool, use FREE statement_id (or FREE statement_id_var).
If a cursor is not declared for a prepared statement, freeing it releases
the resources in both the application-development tool and the database server.
After a cursor is freed, it cannot be opened until it is declared again.
The cursor should be explicitly closed before it is freed.
For an example of a FREE statement that frees a cursor, see the previous
example.
>>-FREE--+-cursor_id--------+---------------------------------->< +-cursor_id_var----+ +-statement_id-----+ '-statement_id_var-'