The data filter capability implemented with the SetDataFilter() function allows developers to access a qualified set of records specified by a conditional statement. Unlike the conditional index expressions, which become a permanent part of the index definition (except for temporary indices), a specific filter is a “run-time” feature and remains active until you change filter definitions or the data file is closed. Further, a specific filter only applies to the calling user: it does not affect the retrieval of records by other users.
Filtering lets you specify criteria to temporarily restrict access only to records that meet the filter criteria. c-treeACE filters in client/server environment may substantially reduce network traffic since only the records that satisfy the filter condition will be returned. ISAM-level record requests, including sets and batches, skip over records failing the filter transparently to the user. In client/server, this may substantially reduce network traffic since only the records that satisfy the filter will be returned. For example, with a data file of 1,000 records, if a filter excludes 900 of the records, a FirstRecord() -
NextRecord() loop results in only 100 calls to the c-treeACE Server, not 1,000 calls. Generally, an index can also be used to help reduce unnecessary record retrievals, however, the filter allows for as-needed retrievals.
With the SetDataFilter() function, record returns, such as from FirstRecord() or GetRecord(), can be limited to a specific range. The conditional expressions, in conjunction with the schema map and symbolic field names, describe the range of values returned. For example, the expression “(ZipCode >= 65000) && (ZipCode < 66000)” would limit returns to records with 65xxx ZipCodes. While there is a limit of one expression, the expressions can be as complex as necessary to accomplish your goals.
For partitioned files, call SetDataFilter() for the host data file and the filter automatically applies to each partition member file. See SetDataFilter()
(http://www.faircom.com/doc/ctreeplus/setdatafilter.htm) for additional details.
Data Filter Stacks - Support Multiple Data Record Filters per File
This is a significant enhancement to our existing data record filter support. Now you have the ability to “stack” data record filters over the same data file. The power this gives you is extensive.
Many times in an application’s logic, data-read requirements might be located in different areas of your code and necessitate different criteria. You might establish one data filter in one location and then later, in another set of logic, find the need for more filtering. Say at logon time, you establish a filter based on user, then somewhere later in the application, a date is introduced.
Now with the ability to “stack” your data file filters, you can add the required filter when you need it most. A new function, SetDataFilterNbr() has been created to use this feature.
Conditional Expression Support Enhanced
Reference Any Section of the Record
A new feature allows you to reference any section of the record (offset,length) even if it does not correspond to a field.
It can be very useful to be able to write a filter (or a conditional expression in general) that directly references a section of the record even if this section does not correspond to a field. For conditional expressions we now allow retrieving a portion of a record as it would be a CT_ARRAY field. The new function syntax is FIELD(offset,size) and evaluates as a CT_ARRAY field with length size containing the portion of the current record starting at offset offset.
Create a Filter on a Table without the DODA (or SCHEMA)
The set filter function, SETFLTR(), makes specific checks to ensure that “schema” and “names” are
available (although they may be empty) before parsing a filter expression.
The filter expression parser (as well as the run-time logic) do not require the existence of schema and names as long as the filter expression does not reference fields. The check prevented you from running filters that do not reference field. We have relaxed this constraint in a way that if the “schema” is present then also “names” must be successfully retrieved otherwise it fails.
If no schema is present, we go directly to the filter parsing, allowing users to utilize filters on files with no schema, perhaps using our filter callback support.
Runtime Support Improved to Support IN and BETWEEN Operators
The IN and BETWEEN operators implemented within our conditional expression logic require
additional support from FairCom engineers to utilize this power. If you are interested in this capability, please contact FairCom.
Filter Callback Support Enhanced
The ability to author a data record filter callback function is an extremely valuable feature for developers with custom filter needs. The following enhancements have been implemented to this support:
Ability to enforce a callback DLL version so users do not utilize the wrong callback DLL.
The c-treeACE Server DLL now exports the function ctStatusLogWrite(), which writes the specified message to the c-treeACE Server status log file.
The name of the data file for which a filter callback function is set is now available to the DLL load, filter evaluation, and DLL unload functions exported by a data record filter callback DLL.
Data Record Filter Callback DLL Enhancements
The following modifications were made to the data record filter callback DLL support:
Require a filter callback DLL to export a function named GetFilterVersion() that returns the version of the filter callback API that the DLL uses. When loading a filter callback DLL, the c-treeACE Server calls this function and fails to load the DLL with error CBKV_ERR (870) if the filter callback API version returned by the DLL doesn’t match the filter callback DLL API version that the c-treeACE Server is using.
Make the name of the data file for which a filter callback function is set available to the DLL load, filter evaluation, and DLL unload functions exported by a data record filter callback DLL. Note that this revision sets the c-treeACE Server’s filter callback API version to 2 to indicate the addition of a filename field, cbfilnam, to the CBDLL structure. The name of the data file is copied to this field so that it is available to the data record filter DLL callback functions.
Callback functions exported from a filter callback DLL were renamed:
• ctfiltercbLoadLib() is now LoadFilter() • ctfiltercbEval() is now EvaluateFilter() • ctfiltercbUnloadLib() is now UnloadFilter()
The cblibhandle field of the CBDLL structure was renamed cbfilterhandle.
The c-treeACE Server DLL now exports the function ctStatusLogWrite(), which writes the specified message to the c-treeACE Server status log file. The prototype for this function is: COUNT ctStatusLogWrite(pTEXT msg,NINT err)
• msg is the message to write to the status log
• err is the error code to include in the message.
Example
ctStatusLogWrite("This is a test", 3);
writes a message in the following format to CTSTATUS.FCS: Wed Jun 10 15:10:27 2009
- User# 00011 This is a test: 3