DATA: Extracting the data into an extract buffer

The DATA keyword determines the type of data to be extracted. The following values, COPYPOOL and BUVERS, are mutually exclusive values for type.

COPYPOOL: The COPYPOOL parameter is used to extract data about each backup version of the specified copy pool. The extract buffer is a header that is followed by one or more entries describing each valid backup version. There can be up to 85 versions that are returned for a single copy pool. Data associated with each copy is returned.

Requirement: When you specify DATA=COPYPOOL, you must specify the COPYPOOL=cpnameaddr keyword.

The COPYPOOL keyword specifies the pointer to the name of the copy pool for which a list of backup versions is to be returned. For cpnameaddr, substitute the address of the copy pool name. The area pointed to by cpnameaddr must be a 30-byte area containing the copy pool name, left justified and padded with blanks.

Table 1 shows the layout for the extract header.

Table 1. Extract Header Layout
Offsets		Type	Bytes	Name	Description
Dec	Hex	Type	Bytes	Name	Description
0	(0)	Character	8	XHEADER	Extract area header.
0	(0)	Fixed	1	XSUBPOOL	Extract Data subpool.
1	(1)	Fixed	3	XLENGTH	Extract area size (total).
4	(4)	Fixed	2	XENTRIES	Number of entries that follow.
6	(6)	Fixed	2	XENTRLEN	Size of each entry.

Table 2 shows the layout of each DATA=COPYPOOL backup version entry.

Table 2. Entry for DATA=COPYPOOL backup version
Offsets		Type	Bytes	Name	Description
Dec	Hex	Type	Bytes	Name	Description
0	(0)	Character	108	CPENT	Entry for copy pool backup version.
0	(0)	Fixed	4	CPVER	Version number 001-999.
4	(4)	Fixed	4	CPGEN	Generation number 00-84.
8	(8)	Bitstring	2	CPFLAG	Flags.
		`1... ....`		CPFVALID	When set to 1, the DASD copy is valid. When set to 0, the version is in a state ineligible for recover processing. It might fail or the copy pool is formatted for use in a z/OS® V1R8 or later environment.
		`.1.. ....`		CPFNVTOC	When set to 1, NOVTOCENQ was specified.
		`..1. ....`		CPFRECVR	When set to 1, DASD copy is recoverable.
		`...1 ....`		CPFDMPRC	When set to 1, all required dump copies are complete.
		`.... 1...`		CPFDMPAC	When set to 1, all dump copies are complete.
		`.... .1..`		CPFDMPPC	When set to 1, dump is partial.
		`.... ..1.`		CPFINC	When set to 1, the copy pool version is incremental.
		`.... ...1`		CPFINCMP	When set to 1, copy pool recovery is incomplete.
		`1... ....`		CPFCATIN	When set to 1, catalog information was captured.
		`.1.. ....`		CPFFCCG	When set to 1, copy pool backup version was created with the FlashCopy consistency group option.
		`..xx xxxx`		*	Reserved.
10	(A)	Character	4	CPDATE	Date when backup made. Format: YYYYDDDF
14	(E)	Character	4	CPTIME	Time when backup made. Format: HHMMSSTH
18	(12)	Character	40	CPTOKEN	Token.
58	(3A)	Character	9(5)	CPDINFO	Array containing dump class info.
58	(3A)	Character	8	CPDCNAME	Dump class name.
66	(42)	Bitstring	1	CPDFLAGS	Flags for this dump class.
		`1... ....`		CPDCMPLT	When set to 1, the dump for this dump class is complete.
		`.1.. ....`		CPDREQD	When set to 1, a dump class is required.
		`..xx xxxx`		*	Reserved.
103	(67)	Character	5	*	Reserved.

BUVERS: The BUVERS parameter is used to extract data about the backup versions for an individual data set. The extract buffer is a header that is followed by one or more entries describing each valid backup version. There can be up to 100 versions that are returned for a single data set. Because uncataloged data sets can have the same name as cataloged data sets, a bit indicates whether this version is for the cataloged or uncataloged data set.

The DATA=BUVERS information returned can be used for ARCHBDEL and ARCHRCOV macros. It is the caller’s responsibility to free the extract buffer when no longer required. See the FREE=keyword description below.

Requirement: When you specify BUVERS, you must specify the DSN=dsnaddr keyword.

Table 1 shows the layout of the DATA=BUVERS extract header and Table 3 shows the layout of each DATA=BUVERS backup version entry.

Table 3. Entry for DATA=BUVERS backup version
Offsets		Type	Bytes	Name	Description
Dec	Hex	Type	Bytes	Name	Description
0	(0)	Character	108	BUVEENT	Entry for backup version.
0	(0)	Fixed	4	BUVEVER	Version number 000-999. (Version=000 indicates the version was created with the NEWNAME and DATE keywords).
4	(4)	Fixed	4	BUVEGEN	Generation number 00-84.
8	(8)	Character	4	BUVEDATE	Date when backup made. Format: YYYYDDDF
12	(C)	Character	4	BUVETIME	Time when backup made. Format: HHMMSSTH
16	(10)	Character	16	BUVEOWNR	Resource owner.
32	(20)	Character	8	BUVEDATA	Resource data.
40	(28)	Bitstring	4	BUVEFLAG	Status flags.
		`1... ....`		BUVEFBWO	When set to 1, backup-while-open candidate.
		`.1.. ....`		BUVENONQ	When set to 1, no enqueue attempted, since DFSMShsm directed not to.
		`..1. ....`		BUVEFCAT	When set to 1, cataloged when backup made.
		`...1 ....`		BUVEFRRR	When set to 1, RLS recovery required indicator.
		`.... 1...`		BUVENQN1	When set to 1, enqueue attempted, but failed.
		`.... .1..`		BUVENQN2	When set to 1, enqueue attempted, backup retried, enqueue failed again.
		`.... ..1.`		BUVENRCM	When set to 1, notify recovery control manager.
		`.... ...1`		BUVEFNN	When set to 1, NEWNAME specified at time of backup.
		`1... ....`		BUVEFSNO	When set to 1, the backup version was created using the SPHERE(NO) option.
		`.1.. ....`		BUVEFGVN	When set to 1, the backup version was created using the GENVSAMCOMPNAMES option.
		`..1. ....`		BUVEMAS	When set to 1, more entries available
		`...1 ....`		BUVEFRD	When set to 1, RETAINDAYS was specified at the time of backup
		`.... 1...`		BUFEFNEX	When set to 1, this version never expires. Only valid when BUVEFRD is set to 1.
		`..xx xxxx`		*	Reserved.
44	(2C)	Character	8	BUVERLSG	RLS recovery timestamp (GMT).
52	(34)	Character	8	BUVERLSL	RLS recovery timestamp local.
60	(3C)	Fixed	2	BUVERDYS	RETAINDAYS value, only valid when BUVEFRD is set to 1 and BUVEFNEX is set to 0.
62	(3E)	Character	46	*	Reserved.

The DSN keyword determines the data set from which the information is needed. DATA determines what type of data is requested. A GETMAIN request for the extract buffer is performed automatically and returned in register 1. For dsnaddr, use the address of the 44-byte data area that contains the fully-qualified data set name. The data set name must be left-justified and padded with blanks. This data set can be either SMS-managed or non-SMS-managed.

The WKAREA keyword specifies the address of a 200-byte work area that will contain the information specified in the macro. For waaddr, substitute the address of the work area. The work area must be below the 16MB line. The work area serves as a temporary storage area for the macro processing and becomes available to you as soon as the macro returns control to your program.