Ingres-supplied Filter Functions

Of the callback functions, two have been paired to allow for function instances that must traverse a large object. Ingres provides skeleton code that allows you to pass the object through your filter.

To use a filter function, the calling instance sets up the workspace by calling the function supplied to initialize the workspace. This function does all the work necessary to allow for the simple traversal of the input object. After this, your filter function is called for each segment and is passed an II_DATA_VALUE, which provides space for manipulation of the input and output segments, a function to call for each segment, a workspace to be used by this routine, and a continuation indicator.

The continuation indicator states whether this is the first or last call to the filter. The indicator is specified by the use of the II_C_BEGIN_MASK and the II_C_END_MASK, indicating that this is the beginning or end of the resulting object.

The function to be called is called with pointers to II_DATA_VALUE, which describes input and output segments. The routine is expected to convert the input into the output segment. When processing the data, the function indicates the disposition of the current segment by filling in the value of the adw_shared.shd_exp_action field of the workspace.

As the routine moves through the object, it is expected to keep the adw_shared.shd_l1_chk field filled with the current length of the large object that is the result. The routine that is called back does not necessarily know if it will be called again.

The expected action indicator conveys information between the filter routine and the function instance routine. The indicator is set to ADW_START before the first segment routine call. Thereafter, the indicator is examined at the return of the call to determine the next action necessary for the function instance routine to perform.

The possible values and responses are as follows:

The function instance routine obtains the next segment of data to be processed by the routine. The output segment remains unchanged.

The function instance routine is expected to dispose of the current (presumably “full”) output segment, and provide a new, empty one for the routine to deal with. The input segment is untouched.

If the routine returns ADW_GET_DATA and there is no more data to get, the function instance routine disposes of the current segment and assumes that the work of the routine is complete. The routine is not called again.

This calling sequence means that the routine never knows if it will be called again. For this reason, the adw_l0_chk and adw_l1_chk values must be correct, and the output segment from your filter must always be a valid segment, even when the filter is not complete.

Of the fields in the workspace, only those in the shared section are interpreted by the filter function. The shd_exp_action, shd_l0_chk, and shd_l1_chk fields must be set as described above. The other fields in the II_SHARED structure must be left unchanged.