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 |