Filter Criteria List (FCL)

The filter criteria list (FCL) consists of a list header and a variable number of list entries. The list entries follow the header, and each entry represents a data set name to be processed by CVAF filter. The header and entries, shown in Table 1 and Table 2, are mapped by the ICVFCL macro. The format of the FCL header is shown in Table 1.

Table 1. Format of a Filter Criteria List Header
Offset	Bytes	Name	Description
0 (X'00')	4	FCLID	EBCDIC 'FCLbb' (bb here represents a blank.)
4 (X'04')	2	FCLCOUNT	Number of data set name entries provided in the list.
6 (X'06')	2	FCLDSCBR	Number of DSCBs returned.
8 (X'08')	1	FCL1FLAG	Request flag byte.
	1 . . . . . . .	FCL1LIST	List contains fully-qualified data set names.
	. 1 . . . . . .	FCL1ORDR	FCL data set name order requested.
	. . 1 . . . . .	FCL1EQF1	Return only format-1 or format-8 DSCBs.
	. . . 1 . . . .	FCL1EQF9	Return only format-1 or format-8 and format-9 DSCBs.
	. . . . xxxx		Reserved.

9 (X'09')	1	FCL2FLAG	Status flag byte.
	1 . . . . . . .	FCL2SEQ	CVAFFILT executed sequential VTOC access.
	. 1 . . . . . .	FCL2SDIR	CVAFFILT executed sequential VTOC access, but did at least one direct DSCB read.
	. . xx xxxx		Reserved.

10 (X'0A')	6	FCLDRSV	Reserved.

FCLID

Must be a 4-character EBCDIC constant of 'FCLbb'. (bb here represents a blank.)

FCLCOUNT

Specifies the number of data set name entries (FCLDSN) supplied in the list. Do not change this parameter between the initial CVAFFILT call and any subsequent RESUME operations.

If you specify a partially-qualified data set name, specify FCLCOUNT = 1. See Partially-Qualified Names for CVAFFILT for the format of partially-qualified data set names.
If you specify a list of fully-qualified names, CVAFFILT processes only the number of names specified in FCLCOUNT.

FCLDSCBR

Indicates the total number of DSCB entries (including format-1, format-2, and format-3) returned to the caller's buffers by a single CVAFFILT call.

If CVAF encounters an error after successfully processing a data set, you can:

Initialize FCLDSCBR to 0 before each READ and RESUME call.
Upon return from CVAF filter service, process the number of DSCBs indicated by FCLDSCBR.
Then, interpret the CVAF return code and CVSTAT.

FCL1FLAG

Define your request for ACCESS=READ with this flag byte. Any subsequent RESUME requests refer to a copy of these bits in the filter save area (FSA).

FCL1LIST

If you specify a list of fully-qualified data set names, set this bit to 1. If you specify a single partially-qualified data set name, set this bit to 0.

FCL1ORDR

If you specify that CVAF is to return DSCB chains in the data set name sequence implied by the placement of the FCLDSN elements, set this bit to 1.

Note:

It can improve performance to allow CVAF to determine the sequence of return for format-1 DSCBs.
CVAF returns DSCBs for a given data set in format-1, format-3 order. For an extended address volume, the data set order for EAS eligible data sets is a format-1, one or more format-9, and any format-3 DSCBs.
If you specify a single partially-qualified data set name, this field is not used.

FCL1EQF1

To have CVAF return only the format-1 or format-8 DSCBs for the data set names, set this bit to 1.

FCL1EQF9

To have CVAF return only the format-1 or format-8 and format-9 DSCBs for the data set names, set this bit to 1.

FCL2FLAG

CVAF filter indicates the following status conditions in this byte.

FCL2SEQ: This bit is set to 1 if a sequential VTOC access path is most efficient. If CVAF filter selects the direct VTOC access path, it sets this field to 0.
FCL2SDIR: This bit is set to 1 if storage limitations within the sequential VTOC access path require direct DSCB reads. CVAF initializes this bit to 0 on each ACCESS=READ and ACCESS=RESUME request. Testing this bit when CVAF filter returns control can indicate if you need to change the storage limitation.

The format of the FCL entry is shown in Table 2.

Table 2. Format of a Filter Criteria List Entry
Offset	Bytes	Name	Description
	8	FCLDSN	Data set name information entry.
0 (X'00')	1	FCLDSNST	Data set name status.
	X'00'		Data set name not yet processed.
	X'01'		DSCBs returned successfully.
	X'02'		Data set name not found.
	X'03'		Error in DSCB chain. RESUME function recommended.
	X'04'		Error in CVAFFILT processing. RESUME not recommended.
	X'05'		Insufficient user buffer list elements. RESUME function recommended.
	X'06'		Request issued to an EAV without EADSCB=OK specified and a format-8 DSCB was found.
	X'07'		Request issued to any volume without EADSCB=OK specified where an EAS eligible data set was found.
1 (X'01')	1	FCLDSNLG	Data set name length.
2 (X'02')	1	FCL3FLAG	Flag byte.
	1 . . . . . . .	FCL3UPDT	This data set name processed during this invocation.
	. xxx xxxx		Reserved.
3 (X'03')	1	FCLDSNRV	Reserved.
4 (X'04')	4	FCLDSNA	Data set name address.

FCLDSN

Contains data set name information. This and the following fields are repeated in the FCL as a set as many times as indicated by the value in FCLCOUNT.

FCLDSNST

Indicates DSCB retrieval status.

CVAF filter initializes this byte to 0 for ACCESS=READ requests.
After processing the data set name for either ACCESS=READ or ACCESS=RESUME, CVAF filter updates this byte.
ACCESS=RESUME requests do not process data set names whose FCLDSNST field is nonzero; therefore, results can be unpredictable if you alter this field.
For partially-qualified data set name requests, CVAF filter does not post the FCLDSNST field until it has returned all DSCB chains for all qualifying data sets. CVAF filter posts the highest numeric value that applied during its processing.
For fully-qualified data set name requests, CVAF filter returns a FCLDSNST byte for each data set name. If the value is greater than 1, CVAF filter has not returned any DSCBs for the associated data set name.

See Table 2 for an explanation of the values in this field.

FCLDSNLG

Indicates the length of the data set name. This value is required.

FCL3FLAG

The status flag byte associated with the data set name pointed to by FCLDSNA.

FCL3UPDT

This bit indicates that CVAF filter processed the associated data set name during the current invocation of CVAFFILT.

When initializing for either a READ or RESUME request, CVAF filter sets this bit to 0.
When CVAF filter has completed processing for the associated data set name, it sets this bit to 1.

FCL3DSNRV

Reserved, unused.

FCLDSNA

Specifies the address of a fully-qualified data set name, or, if this is the only data set name and FCL1LIST is 0, a partially-qualified data set name. You must provide both this address and the storage area to which it points.