OFEvaluateFilter(3sadm)

OFEvaluateFilter -- filter list of objects

Synopsis

CC ... -lsysadm -lvtcl -ltclx -ltcl -lsocket -lgen -lm

#include <scoadmin/osaStdDef.h>

void OFEvaluateFilter(errStatusPtr, handleId, filterString, objectList, objectCount)

Description

This routine takes a list of objects and performs a filter on them, returning an indication of which of those objects passed the filter (and which did not). The list given by objectList will be modified so that those objects that passed the filter will be placed at the beginning of the list, and the variable pointed to by objectCount will be replaced with the number of objects that did pass the filter. Thus if ten(10) objects are passed to the function and only three of them pass the filter, their names will be found in *objectList[0], *objectList[1] & *objectList[2], and objectCount will contain the value three (3).

Arguments

errStatus_cl *errStatusPtr: The ubiquitous error stack pointer. The error stack this points to will be modified if any errors occur during the operation of the filter.
int handleId: This is the handle identifier that was forwarded to the request processor by the SCOadmin services library.
filterParameter_pt filterString: A char * to the ASCII representation of the filter to be performed on the object(s). This is normally found in bmipRequest_pt.filterPtr, but in performing a scope on the named object the request processor may want to change the given filter.
objectInstance_pt **objectList: A char ***, a pointer to the location of a list of object identification strings. The OFEvaluateFilter routine will reorder this list and place the valid objects (those that pass the filter) at the beginning of the list, and those that fail at the end.
int *objectCount: The number of objects in the objectList is passed to the function. It then places the number of valid objects in the variable pointed to by objectCount.

If the request processor is performing a scoping operation on the object instance passed to it, or is generating the list of objects to be worked on based on the named object instance and the given filter, or can eliminate a portion of the filter in a trivial solution; then the request processor might want to send only the portions of the bmipRequest_pt.filterPtr that are still relevant.

Diagnostics

This function can return any of the error messages associated with OFEvaluateOperation plus the following errors:

NO_SUCH_CLASS_HANDLE: The handleId named does not correspond to an existing class in the Server APIs internal lookup table.
UNRECOGNIZED_OPERATION: The class represented by the named handleId has no filter function associated with it.
INVALID_FILTER: The class represented by the named handleId has defined the no filter action for one of the attributes & filter-action pairs named in the filterString argument. Or the data portion of a binary filter-action is corrupt. Or the wrong order or number of arguments were given to a filter-action. Or the filter command itself is corrupt.
EXECUTION_PROCEDURE_FAILURE: The execution of the filter operation was halted because of an error in running the operation's execution procedure.

Examples

void
RequestProcessor(errStatus_cl   *errStatusPtr,
                 int             handleId,
                 bmipRequest_pt  bmipRequestPtr,
                 void           *handle)
{
    /*---
     *
     * Generate a list of all the objects to be evaluated
     *
     */

    objectInstance_pt *objectList;
    int                objectCount;

        .
        .
        .

    /* create the "objectList[]" out of bmipRequestPtr->objectInstancePtr
     * and possibly bmipRequestPtr->scopePtr.
     */

        .
        .
        .
   
    OFEvaluateFilter(errStatusPtr,
                     handleId,
                     bmipRequestPtr->filterPtr,
                     &objectList,
                     &objectCount);
   
    if (objectCount < 1)
    {
        /* If all the objects failed the filter, we need to send a BMIP
         * response to that effect back to the client. So we set the
         * objectInstancePtr to NULL and call OFReturnBmipResponse().
         */
       
        bmipResponse_t *bmipResponsePtr =
            OFComposeBmipResponseError(errStatusPtr, bmipRequestPtr);

        ErrorClear(errStatusPtr);

        OFReturnBmipResponse(errStatusPtr,
                             handleId,
                             bmipResponsePtr,
                             FALSE);

        /* Calling OFReturnBmipResponse() will also free up the bmipResponse_t
         * and the errorParameter field of that structure.
         */
       
        MemFree(objectList);
        return;
    }

References

Bmip(3tlib) OFComposeBmipResponseError(3sadm), OFGenerateHandleId(3sadm), OFReturnBmipResponse(3sadm), OFEvaluateOperation(3sadm).