Write an iterator function
An iterator function is a user-defined function that returns to its calling SQL statement several times, each time returning a value.
The database server gathers these returned values together in an
active set. To access a value in the active set, you must obtain it
from a database cursor. Therefore, an iterator function is a cursor
function because it must be associated with a cursor when it is executed.
Tip: This section describes how to create an iterator function
that is written in C. For general information about how to create
user-defined functions, see the HCL
Informix User-Defined Routines and Data Types Developer's
Guide.
The database server might execute an iterator function many times.
It groups these iterations into the iterator-status values and puts
the iterator status for a given iteration in the MI_FPARAM structure.
Within an iterator function, you examine the MI_FPARAM structure
for an iterator status to determine which actions the iterator function
must take.
Tip: The HCL Informix® BladeSmith
development tool, which is part of the Informix DataBlade Developers Kit (DBDK), automatically
generates C source code for an iterator function and the SQL statements
to register the iterator function. For more information, see the HCL
Informix
DataBlade Developers Kit User's Guide.
To specify the different points at which the database server calls
an iterator function, the iterator-status flag (of type MI_SETREQUEST)
supports the constants in the following table.
| When is the iterator function called? | What does the iterator function do? | Iterator-status constant in MI_FPARAM |
|---|---|---|
| The first time that the iterator function is called | Initializes the iterations | SET_INIT |
| Once for each item in the active set | Returns one item of the active set | SET_RETONE |
| After the last item of the active set is returned | Releases iteration resources | SET_END |