Creates a filter on a data item in a view. Each data item in a view can have only one filter.
This function can be used with both Monitor Server and Historical Server. When used with Historical Server (that is, when the connection mode is SMC_SERVER_M_HISTORICAL), it creates a filter for the recording session that is being defined.
SMC_RETURN_CODE smc_create_filter (SMC_CONNECT_ID clientId, SMC_VIEW_ID viewId, SMC_DATAITEM_STRUCTP dataItemHandle, SMC_FILTER_TYPE filterType, SMC_VALUE_UNIONP filterValueListHandle, SMC_SIZET filterValueListLength, SMC_DATAITEM_TYPE filterDatatype, SMC_FILTER_IDP filterIdHandle)
identifies the connection.
identifies a view created on the connection.
data item and statistic type. The data item must be numeric if the filter type is any of the following:
SMC_FILT_T_GE
SMC_FILT_T_LE
SMC_FILT_T_GE_AND_LE
SMC_FILT_TOP_N
type of filter to apply. Valid filter types are:
SMC_FILT_T_EQ – equal to.
SMC_FILT_T_NEQ – not equal to.
SMC_FILT_T_GE – greater than or equal to.
SMC_FILT_T_LE – less than or equal to.
SMC_FILT_T_GE_AND_LE – a lower bound followed by an upper bound.
SMC_FILT_T_TOP_N – top N.
pointer to an array of filter values. The number of filter values depends on the filter type:
SMC_FILT_T_EQ – one or more.
SMC_FILT_T_NEQ – one or more.
SMC_FILT_T_GE – one.
SMC_FILT_T_LE – one.
SMC_FILT_T_GE_AND_LE – two; low bound must be first element in list and high bound second.
SMC_FILT_T_TOP_N – one.
number of filter values listed in filterValueListHandle.
datatype of the values for the filter; one of the following:
SMC_DI_TYPE_CHARP
SMC_DI_TYPE_DATIM
SMC_DI_TYPE_DOUBLE
SMC_DI_TYPE_ENUMS
SMC_DI_TYPE_INT
SMC_DI_TYPE_LONG
Must match the datatype for the data item. The filter values must also be of this type, except:
If the filter type is SMC_FILT_T_TOP_N, the filter value in the filterValueListHandle must be type SMC_INT.
If the datatype is SMC_DI_TYPE_ENUMS, the filter value in the filterValueListHandle must be passed using the intValue member.
pointer to a variable, which should be declared as type SMC_FILTER_ID. If the call to smc_create_filter succeeds, this variable contains the ID for the filter.
Return value |
Indicates |
---|---|
SMC_RET_SUCCESS |
Function succeeded. |
SMC_RET_FAILURE |
Function failed. |
SMC_RET_INVALID_CONNECT |
Connection does not exist. |
The following example assumes that:
You have created a connection and have a clientId.
You have created a view on that connection and have a viewId.
The view contains the dataItem defined in the example.
SMC_DATAITEM_STRUCT dataItem = { SMC_NAME_PAGE_LOGICAL_READ, SMC_STAT_VALUE_SAMPLE }; SMC_DATAITEM_STRUCTP dataItemHandle = &dataItem; SMC_VALUE_UNION filterValue; SMC_VALUE_UNIONP filterValueHandle = &filterValue; SMC_FILTER_ID filterId; SMC_FILTER_IDP filterIdHandle = &filterId; filterValue.longValue = 10L;
if (smc_create_filter(clientId, viewId, dataItemHandle, SMC_FILT_T_GE, filterValueHandle, 1, /* just one filterValue */ SMC_DI_TYPE_LONG, filterIdHandle) != SMC_RET_SUCCESS) { printf("smc_create_filter failed\n"); /* do some cleanup */ }
The application can employ wildcard (%) characters on all filters that apply to string datatypes.
Filters are applied before alarms, in the context of a refresh call.
Only one filter can be created on a data item.
A filter defined for a recording session is not created until execution of the recording session.
Not allowed during playback.
For database objects, you can define SMC_FILT_T_EQ filters on the name of the object, that is, on a data item of SMC_NAME_OBJ_NAME or SMC_NAME_ACT_STP_NAME. The string value must include the fully qualified object name, for example, database.owner.object. However, you can use wildcards for each component of the name.
Mode |
Availability |
---|---|
SMC_SERVER_M_LIVE |
Yes |
SMC_SERVER_M_HISTORICAL |
Yes (for recording only) |
Error |
Indicates |
---|---|
SMC_RET_INSUFFICIENT_MEMORY |
Insufficient memory |
SMC_RET_INVALID_COMPOSITE_FILTER |
Invalid composite filter |
SMC_RET_MISSING_DATAITEM |
Missing data item |
SMC_RET_INVALID_DATATYPE |
Invalid datatype |
SMC_RET_INVALID_DINAME |
Invalid data item |
SMC_RET_INVALID_DISTAT |
Invalid data item statistic type |
SMC_RET_INVALID_FILTER_VALUE |
Invalid value for filter |
SMC_RET_INVALID_FILTER_RANGE |
Invalid range values |
SMC_RET_INVALID_VALUE_COUNT |
Invalid value for filterValueListLength |
SMC_RET_INVALID_VIEWID |
View does not exist |
smc_drop_filter