Generating a CVPL (CVAF Parameter List)

The CVAFDIR, CVAFDSM, CVAFFILT, and CVAFSEQ macros use the CVPL to pass parameters to CVAF. The CVAFTST macro expands to provide its only parameter (UCB address) in register 1, and calls the applicable CVAF module. CVAF returns information related to the CVAF request in the CVPL. The CVAFTST macro will accept the address of a UCB or UCB copy. Unauthorized programs can get a copy of the UCB by using the UCBSCAN macro and specifying the COPY, UCBAREA, CMXTAREA, and DCEAREA keywords. The UCB copy, including the extension, must be below the 16MB line and on a word boundary. Data accessed with the DCEAREA can be above the 16MB line. Refer to z/OS HCD Planning for details.

Specifying the CVAFDIR, CVAFDSM, CVAFFILT, or CVAFSEQ macro with MF=L or MF=I (the default) as a subparameter generates a CVPL. Upon return the CV1IVT bit in the CVPL indicates whether the accessed VTOC was indexed or nonindexed. If an error occurs, the CVSTAT field contains feedback data. The CVAF I/O area address is returned in the CVIOAR field and the CVAF filter save area address is returned in the CVFSA field. To use the generated CVPL to execute a different function than was originally specified, use the MF=E keyword.

To specify a CVAF filter request, use a CVPL generated by the CVAFFILT macro. The CVAFFILT macro generates a CVPL 4 bytes longer (total length = X'44') than that generated by the other CVAF macros (total length = X'40'). CVAFFILT request need a longer parm list to accommodate one extra file.

To get the longer parameter list (X'44' bytes), specify CVPLFSA=YES on the inclusion of the ICVAFPL mapping macro.
To get the shorter parameter list (X'40' bytes), specify the CVPLX=YES on the inclusion of the ICVAFPL mapping macro.

The ICVAFPL macro maps the CVPL. The format of the CVPL is shown in Table 1.

Note: The area starting at CVCTAR5 is generated only when the CVPLX=YES macro variable is specified on the invocation of ICVAFPL.

Table 1. CVAF Parameter List - ICVAFPL
Offset	Type	Length	Name	Description
0(X'00')	STRUCTURE	100	CVPL	CVAF parameter list
0(X'00')	CHARACTER	4	CVLBL	EBCDIC 'CVPL'
4(X'04')	SIGNED	2	CVLTH	Length of CVPL
6(X'06')	BIT(8)	1	CVFCTN	Function byte (see values below)
7(X'07')	UNSIGNED	1	CVSTAT	Status information (see values below)
8(X'08')	BIT(8)	1	CVFL1	First flag byte
	1... ....		CV1IVT	Indexed VTOC accessed
	.1.. ....		CV1IOAR	IOAREA=KEEP
	..1. ....		CV1PGM	BRANCH=(YES,PGM)
	...1 ....		CV1MRCDS	MAPRCDS=YES
	.... 1...		CV1IRCDS	IXRCDS=KEEP
	.... .111		CV1MAP	Map bits (see next three bits)
	.... .1..		CV1MAPIX	MAP=INDEX
	.... ..1.		CV1MAPVT	MAP=VTOC
	.... ...1		CV1MAPVL	MAP=VOLUME
9(X'09')	BIT(8)	1	CVFL2	Second flag byte
	1... ....		CV2HIVIE	HIVIER=YES
	.1.. ....		CV2VRF	VRF data exists
	..1. ....		CV2CNT	COUNT=YES
	...1 ....		CV2RCVR	RECOVER=YES
	.... 1...		CV2SRCH	SEARCH=YES
	.... .1..		CV2DSNLY	DSNONLY=YES
	.... ..1.		CV2VER	VERIFY=YES
	.... ...1		CV2NLEVL	Output - new highest level VIER created

10(X'0A')	BIT(8)	1	CVFL3	Third flag byte
	1... ....		CV3FILT	FLTAREA=KEEP
	.1.. ....		CV3IXERR	Index error found
	..1. ....		CV3PTR31	Address words in CVPL are valid in AMODE 31
	...1 ....		CV3AVT	Support bypass write inhibit error.
	.... 1...		CV3ENQD	CVAF caller has serialized with another task that has reserved the VTOC
	.... .1..		CV3NOPIN	Caller requested no UCBPIN
	.... ..1.		CV3HLIXP	Higher level IX pruning done
	.... ...1		CV3RTA4B	CVAFDSM RTA4BYTE=YES
11(X'0B')	BIT(8)	1	CVFL4	Fourth flag byte
	1... ....		CV4UCBCA	UCB has been captured
	.1.. ....		CV4OBTRQ	Request came from OBTAIN
	..1. ....		CV4NMHID	Data set name hiding for authorized caller.
	...1 ....		CV4EADOK	EADSCB=OK specified
	.... 1...		CV4MULTD	Processing of multiple DSCBs on CVAFDIR is requested (MULTIPLEDSCBS=YES)
	.... .xxx		CV4RSVD	Reserved
12(X'0C')	ADDRESS	4	CVUCB	UCB address
16(X'10')	ADDRESS	4	CVDSN	Data set name address
16(X'10')	ADDRESS	4	CVFCL	Filter criteria list address
20(X'14')	ADDRESS	4	CVBUFL	Buffer list address
24(X'18')	ADDRESS	4	CVIRCDS	Index VIR's buffer list pointer
28(X'1C')	ADDRESS	4	CVMRCDS	MAP VIR's buffer list pointer
32(X'20')	ADDRESS	4	CVIOAR	I/O area address
36(X'24')	ADDRESS	4	CVDEB	DEB address
40(X'28')	ADDRESS	4	CVARG	Argument address
44(X'2C')	ADDRESS	4	CVSPACE	Space parameter list address
48(X'30')	ADDRESS	4	CVEXTS	Extent table address
52(X'34')	ADDRESS	4	CVBUFL2	New VRF VIXM Buffer list pointer
56(X'38')	ADDRESS	4	CVVRFDA	VRF data address
60(X'3C')	ADDRESS	4	CVCTAR	Count area address
64(X'40')	ADDRESS	4	CVFSA	Filter save area address
68(X'44')	ADDRESS	4	CVCTAR5	CCHHR AREA RETURN ADDRESS
72(X'48')	UNSIGNED	1	CVNMDSCB	NUM OF DSCBs
73(X'49')	CHARACTER	3	*	Reserved
76(X'4C')	CHARACTER	24	*	Reserved

The possible contents of the CVFCTN field in the CVPL and their meanings are as follows:

Table 2. CVFCTN Field of CVPL—Contents and Definitions
Value	Name	Description
X'01'	CVDIRD	CVAFDIR	ACCESS=READ
X'02'	CVDIWR	CVAFDIR	ACCESS=WRITE
X'03'	CVDIRLS	CVAFDIR	ACCESS=RLSE
X'04'	CVSEQGT	CVAFSEQ	ACCESS=GT
X'05'	CVSEQGTE	CVAFSEQ	ACCESS=GTEQ
X'06'	CVDMIXA	CVAFDSM	ACCESS=IXADD
X'07'	CVDMIXD	CVAFDSM	ACCESS=IXDLT
X'08'	CVDMALC	CVAFDSM	ACCESS=ALLOC
X'09'	CVDMRLS	CVAFDSM	ACCESS=RLSE
X'0A'	CVDMMAP	CVAFDSM	ACCESS=MAPDATA
X'0E'	CVFIRD	CVAFFILT	ACCESS=READ
X'0F'	CVFIRES	CVAFFILT	ACCESS=RESUME
X'10'	CVFIRLS	CVAFFILT	ACCESS=RLSE
X'AA'	CVDMMAPX	CVAFDSM	ACCESS=MAPDATA RTA4BYTE=YES