DataBlade API Programmer's Manual

DataBlade API Programmer's Manual
Chapter 4: Using the MI_FPARAM Structure

Home Contents Index Master Index New Book

Creating an Iterator Function

To have a DataBlade function return more than one row of values in an SQL statement, you must write it as an iterator function. The database server automatically calls an iterator function once for each row of return values. This row can contain column values from a database table or return values from some other external function.

Tip: For end users to be able to use an iterator function within an SQL statement, you must register the iterator function with the CREATE FUNCTION statement. The CREATE FUNCTION must include the ITERATOR routine modifier to tell the database server that it must call the function several times. For more information on how to register iterator functions, see "Extending INFORMIX-Universal Server: User-Defined Routines."

The database server uses the function-parameter structure, MI_FPARAM, to tell a DataBlade iterator function about which iteration operation to perform next. To have a DataBlade function return more than one value (or row), you must define it as an iterator function. An iterator function can return more than one value from one of the following conditions:

A query that returns more than one row
A user-defined function that returns more than one row

The group of values that one of these conditions returns is called an active set. The database server calls an iterator function to access the active set in the following cases.


What Does the Iterator Function Do?	When Is the Iterator Function Called?	fp_request Field of MI_FPARAM
Initializes the active set	The first time that the DataBlade function is called	`SET_INIT`
Returns one value/row from the active set	For each row in the active set	`SET_RETONE`
Shuts down the active set	After the last row is returned from the active set	`SET_END`

The DataBlade iterator function must record enough information to return values one at a time on demand. Declare the iterator function so that its return value matches one of the return values of the active set. For example, to return an active set of integer values, declare the iterator function to return an integer.

The following code fragment is a sample implementation of an iterator function called get_orders(), which generates an active set of order numbers for a given customer number and then iterates through the active set to return each order number:

mi_integer

get_orders(cust_num, fParam)

	void 			*intset;

	MI_FPARAM			*fParam

{
	switch (mi_fp_request(fParam))
		{
		case SET_INIT:
			return (getord_init(intset, fParam));

		case SET_RETONE:
			return (getord_retone(fParam));

		case SET_END:
			return (getord_end(fParam));

		default:
			getord_error("Bad request in get_orders()");
		}
}

The database server calls this get_orders() iterator function at the following execution points:

Once to initialize the active set of order numbers
Repeatedly to return single order-number from the active set
Once to shut down the active set

DataBlade API Programmer's ManualChapter 4: Using the MI_FPARAM Structure Home Contents Index Master Index New Book

Creating an Iterator Function

Initializing the Active Set of Values

Returning a Value from the Active Set

Shutting Down the Active Set

Calling an Iterator Function from an SQL Statement

DataBlade API Programmer's Manual
Chapter 4: Using the MI_FPARAM Structure

Home Contents Index Master Index New Book