Describing a Filter: FILTER

How to:

Reference:

Boolean virtual fields (DEFINE fields that evaluate to TRUE or FALSE) can be used as record selection criteria. If the primary purpose of a virtual field is for use in record selection, you can clarify this purpose and organize virtual fields in the Master File by storing the expression using a FILTER declaration rather than a DEFINE. Filters offer the following features:

Syntax: How to Declare a Filter in a Master File 

FILTER  filtername = expression; [MANDATORY={YES|NO}]
  [, DESC[RIPTION]='desc'] 
  [, DESC_ln='descln', ... ] ,$

where:

filtername

Is the name assigned to the filter. The filter is internally assigned a format of I1, which cannot be changed.

expression

Is a logical expression that evaluates to TRUE (which assigns the value 1 to the filter field) or FALSE (which assigns the value 0 to the filter field). For any other type of expression, the field becomes a standard numeric virtual field in the Master File. Dialogue Manager variables (amper variables) can be used in the filter expression in same way they are used in standard Master File DEFINEs.

MANDATORY={YES|NO}

Specifies whether to apply the filter even if it is not referenced in a request against the synonym. YES applies the filter to all requests against the synonym. NO applies the filter only when it is referenced in a request. NO is the default value.

Note: Unlike a filter created using the FILTER FILE command, which can be toggled ON and OFF, this setting can only be turned off by removing or changing the value in the Master File.

DESC[RIPTION]='desc'

Is a description for the sort object in the default language.

DESC_ln='descln'

Is a description for the sort object in the language specified by the language code ln.

Syntax: How to Use a Master File Filter in a Request 

TABLE FILE filename
   .
   .
   .
{WHERE|IF} expression_using_filters

where:

expression_using_filters

Is a logical expression that references a filter. In a WHERE phrase, the logical expression can reference one or more filters and/or virtual fields.

Reference: Usage Notes for Filters in a Master File

  • The filter field name is internally assigned a format of I1 which cannot be changed.
  • A filter can be used as a standard numeric virtual field anywhere in a report request, except that they are not supported in WHERE TOTAL tests.
  • A mandatory filter can be used to force access to a segment (for example, a table in a cluster synonym) that is not referenced in a request.

Example: Defining and Using a Master File Filter

Consider the following filter declaration added to the MOVIES Master File: 

FILTER G_RATING = RATING EQ 'G' OR 'PG'; $

The following request applies the G_RATING filter: 

TABLE FILE MOVIES
HEADING CENTER
"Rating G and PG"
PRINT TITLE CATEGORY RATING
WHERE G_RATING
ON TABLE SET PAGE NOPAGE
ON TABLE SET GRID OFF

ON TABLE SET STYLE *
type=report, style=bold, color=black, backcolor=yellow, $
type=data, backcolor=aqua, $                              
ENDSTYLE      
END

The output is shown in the following image:

Example: Using a Mandatory Filter

Consider the following filter declaration added to the MOVIES Master File: 

FILTER G_RATING = RATING EQ 'G' OR 'PG'; MANDATORY=YES ,$

The following request does not reference the G_RATING filter: 

TABLE FILE MOVIES
HEADING CENTER
"Rating G and PG"
PRINT TITLE CATEGORY RATING
ON TABLE SET PAGE NOPAGE
ON TABLE SET GRID OFF

ON TABLE SET STYLE *
type=report, style=bold, color=black, backcolor=yellow, $
type=data, backcolor=aqua, $                              
ENDSTYLE      
END

The output is shown in the following image. Note that the G_RATING filter is applied even though it is not referenced in the request: