CursorFilters Class

Class for creating, removing and applying Cursor filters.

This is significantly different from the usual way of filtering in Commence API.

See code samples below.

Inheritance Hierarchy

SystemObject
Vovin.CmcLibNet.DatabaseCursorFilters

Namespace: Vovin.CmcLibNet.Database
Assembly: Vovin.CmcLibNet (in Vovin.CmcLibNet.dll) Version: 1.0.7729.42686

Syntax

Copy

public class CursorFilters : ICursorFilters, 
	IEnumerable<ICursorFilter>, IEnumerable

Public Class CursorFilters
	Implements ICursorFilters, IEnumerable(Of ICursorFilter), 
	IEnumerable

The CursorFilters type exposes the following members.

Properties

	Name	Description
	Count	Gets number of filters.

Top

Methods

	Name	Description
	Add	Add a filter to the filter collection.
	Apply	Apply filters and return number of affected items.
	Clear	Clear all filters from collection. The underlying cursor will be updated, there is no need to call Apply.
	Create	Create new filter and add it to the collection.
	Equals	Determines whether the specified object is equal to the current object. (Inherited from Object.)
	GetEnumerator	Enable enumeration.
	GetFilter	Returns filter from collection.
	GetFilterByClauseNumber	Get filter from collection based on clause number.
	GetHashCode	Serves as the default hash function. (Inherited from Object.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	RemoveFilter	Remove specified filter from collection. The underlying cursor will be updated, there is no need to call Apply.
	RemoveFilterByClauseNumber	Remove filter from collection by clause number, if present. The underlying cursor is also updated, there is no need to call Apply.
	ToString	Returns a string that represents the current object. (Overrides ObjectToString.)
	ValidateFilter(ICursorFilter)	Checks if filter will work.
	ValidateFilter(String, ICursorFilter)	Checks if filter will work.

Top

Examples

Filtering cursors is a very complex affair in he Commence API, because it is done using DDE-style syntax. This syntax is convoluted and hard to remember.

Old-style DDE syntax can still be used in CmcLibNet, but you are strongly encouraged to use the CursorFilters class, exposed as Filters property of the CommenceCursor class. It is more verbose, but also more intuitive.

First you decide what type of filter you want to apply. Commence has 4 types of filters, which are defined in the FilterType enum. Once you know what filter you want to apply, you create it:

Copy

using Vovin.CmcLibNet
using Vovin.CmcLibNet.Database

namespace FilterExample
{
    class Main
        {
            // get a reference to CmcNetLib.
            ICommenceDatabase cmc = new CommenceDatabase(); 
            // get a cursor from Commence.
            ICommenceCursor cur = cmc.GetCursor("Account");
            // get a Field type filter
            ICursorFilterTypeF f = cur.Filters.Create(1, FilterType.Field);
        }
}

Step-through of above example: First, we get a reference to the CmcLibNet assembly, that will talk to Commence for you.

Then, we get a cursor, telling it we want to use data from the Account category. We want to filter that category on a fieldvalue.

We then define our filter as ICursorFilterTypeF.

We then ask CmcLibNet to get use a filter of that type, the 'FilterType.Field' parameter, and make it the first filter (the '1' parameter). The index number is mandatory, because of the way the and/or relations between filters in Commence work.

What happens is a filter object instance called 'f' of type CursorFilterTypeF is created.

It just exposes the properties pertaining to that particular filter-type. Have peek with Intellisense or the object-browser and you'll see what I mean. So now, you can set the filter parameters. Most are optional. Let's set them all (well, almost all):

Copy

f.FieldName = "accountKey"; // field to filter on
f.FieldValue = "Commence"; // value to filter on
f.Qualifier = FilterQualifier.Contains; // the Qualifier property sets the proper QualifierString internally.
f.CSFlag = true; // tell Commence we want to do a case-sensitive filter. You can omit this for a non-case-sensitive filter.
f.Except = true; // get us all results EXCEPT the ones matching our filter. This is equivalent to the checking the 'except' checkbox in the filter dialog in Commence
f.OrFlag = false; // we do not want to define this filter as an OR filter. Note that the filter logic is incorporated as a property of the individual filters, and not supplied separately by a SetLogic method.

This equates to the shorter:

Copy

cur.SetFilter("[ViewFilter(1,NOT,F,Contains," + "Commence" + ",1)]",0);
cur.SetLogic("[ViewConjunction(And,,,,,)]",0);

but is is easier to read and understand as well as less error-prone.

Note that the filter logic is incorporated as a property of the individual filters, and not supplied separately by a SetLogic method.

This was just 1 filter, you can set up to 8 of them. Once you are done with defining your filters, call the Apply method of the Filters class:

Copy

cur.Filters.Apply();

That's it for C# users.

Examples

For VBScript (e.g. an Item Detail Form Script), the procedure is much alike. The main difference is that it is probaly easiest to supply the filter qualifier as a string via QualifierString. (Although if you want to, you can supply the enum value to Qualifier):

VBScript

Copy

Dim cmc : Set db = CreateObject("CmcNetLib.Database")
Dim cur : Set cur = db.GetCursor("Account")
Dim filters : Set filters = cur.Filters ' you cannot simply use cur.Filters from VBScript, alas.
Dim f : Set f = filters.Create(1, 0) ' 0 is the enum value for FilterType.Field.
f.FieldName = "accountKey" ' field to filter on.
f.FieldValue = "Commence" ' value to filter on.
f.QualifierString = "contains" ' the qualifier, i.e., how to evaluate the filter value. You could have also used f.Qualifier with the enum value corresponding with 'contains', this is just a bit easier.
f.CSFlag = true ' tell Commence we want to do a case-sensitive filter. You can omit this for a non-case-sensitive filter.
f.Except = true ' get us all results EXCEPT the ones matching our filter. This is equivalent to the checking the 'except' checkbox in the filter dialog in Commence.
f.OrFlag = false ' we do not want to define this filter as an OR filter. 
filters.Apply()
'...do something...
db.Close

Reference

Vovin.CmcLibNet.Database Namespace