DATA: Extracting the data into an extract buffer
The DATA keyword determines the type of data to be extracted. The following values,
COPYPOOL, BUVERS, and CRQREAD, 
are mutually exclusive
values for type.
COPYPOOL, BUVERS, and CRQREAD, 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 that is 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-aligned, 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 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 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. .... ...1CPFINCMP 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.
..1. .... CPDCLOUDWhen set to 1, the dump for this dump class resides in cloud object
storage....x ....* 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 for the 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 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. .... ...1BUVEFNN 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. - CRQREAD: The CRQREAD parameter is used to
extract data about the Common Recall Queue (CRQ). Register 15 contains the return code and register
0 contains the reason code. Register 1 contains the address of the extract area. The extract area is
a header describing the five CRQ arrays that follow header:
- Control List (CL), Tape List(TL), Primary Unselected Request (PUR) List, Secondary Unselected Request (SUR) List, and Selected Request (SR) List
Each CRQ list is an array of the corresponding CRQ list entries. The header contains the control information about the CRQ lists arrays. For example,- The address of each CRQ list array.
- The number of entries in each CRQ list array.
- The number of bytes in each CRQ list array.
- The total number of bytes of the extracted area.
Each entry of each CRQ list contains the length of this entry. This length is needed to get the address of the next entry of the array.
Requirement: When you specify CRQREAD, you must specify the SNAPDCB=addr keyword.Table 4 shows the layout for the extract header.Table 4. Extract Header Layout Offsets Type Bytes Name Description Dec Hex 0 (0) Structure 72 CRQ CRQ area header. 0 (0) Fixed 4 CRQ_HDR# CRQ header size. 4 (4) Fixed 4 CRQ_C@ Control list ptr. 8 (8) Fixed 4 CRQ_T@ Tape list ptr. 12 (C) Fixed 4 CRQ_PUR@ PUR list ptr. 16 (10) Fixed 4 CRQ_SUR@ SUR list ptr. 20 (14) Fixed 4 CRQ_SR@ SR list ptr. 24 (18) Fixed 4 CRQ_C_TOT Number of CL entries. 28 (1C) Fixed 4 CRQ_T_TOT Number of TL entries. 32 (20) Fixed 4 CRQ_PUR_TOT Number of PURL entries. 36 (24) Fixed 4 CRQ_SUR_TOT Number of SURL entries. 40 (28) Fixed 4 CRQ_SR_TOT Number of SRL entries. 44 (2C) Fixed 4 CRQ_C# Control list size. 48 (30) Fixed 4 CRQ_T# Tape list size. 52 (34) Fixed 4 CRQ_PUR# PUR list size. 56 (38) Fixed 4 CRQ_SUR# SUR list size. 60 (3C) Fixed 4 CRQ_SR# Selected reqst list size. 64 (40) Fixed 4 CRQ_LEN Total CRQ structure size. 68 (44) Fixed 4 CRQ_SENT Total bytes received. Table 5 shows the layout for the CRQ Control List entry.Table 5. Entry for CRQ control list Offsets Type Bytes Name Description Dec Hex 0 (0) Structure 128 CRQ_CL_ENT Array containing control list entry. 0 (0) Fixed 4 CRQ_CL_FWD Forward pointer. 4 (4) Fixed 4 CRQ_CL_BWD Backward pointer. 8 (8) Fixed 4 CRQ_CL_LEN Control list entry size. 12 (C) Character 16 CRQ_CL_AUTHORITY List authority value. 12 (C) Character 18 CRQ_CL_HSMPLEX HSMplex name. 20 (14) Character 8 * Reserved. 28 (1C) Character 12 CRQ_CL_ENTRYID Control list entry ID. 28 (1C) Character 3 CRQ_CL_IDTYPE Type of entry: - 'CES' for the CES entry.
- Hostid||'4000'x for host entry.
28 (1C) Character 2 CRQ_CL_HID For host entries. 30 (1E) Character 1 * Reserved. 31 (1F) Character 9 * Reserved. 40 (28) Character 16 CRQ_CL_ENTRYKEY Control list entry key. 40 (28) Character 3 CRQ_CL_KTYPE Type of entry: - 'CES' for the CES entry.
- Hostid||'4000'x for host entry.
40 (28) Character 2 CRQ_CL_HKEY For host entries. 42 (2A) Character 1 * Reserved. 43 (2B) Character 13 * Reserved. 56 (38) Character 64 CRQ_CL_ADJAREA Control list adjunct area. 56 (38) Fixed 1 CRQ_CL_CES CRQ eligibility status. 56 (38) Bitstring 1 CRQ_CL_CES_FLAGS CES flags. .1.. ....CRQ_CL_NOT_ELIG 1= Not Elig RECALL or CQ(RECALL) or CQ(RECALL(SELECTION)) held. ...1 ....CRQ_CL_TP_HELD 1= RECALL TAPE held. .... .1..CRQ_CL_TPTSO_HELD 1= RECALL TAPE(TSO) held. 57 (39) Character 1 CRQ_CL_POP Processing options. 57 (39) Character 1 CRQ_CL_POP_FLAGS POP flags. 1... ....CRQ_CL_FBID_ORD 1= Recall from tape in asc FBID order. 58 (3A) Character 62 * Reserved. 120 (78) Character 8 CRQ_CL_VERSION Version for host entries. 120 (78) Character 4 CRQ_CL_CONNVERSION CF Connection version. 124 (7C) Character 4 X'00000000' Table 6 shows the layout for the CRQ tape list entry.Table 6. Entry for CRQ tape list Offsets Type Bytes Name Description Dec Hex 0 (0) Structure 104 CRQ_TL_ENT Array containing tape list entry. 0 (0) Fixed 4 CRQ_TL_FWD Forward pointer. 4 (4) Fixed 4 CRQ_TL_BWD Backward pointer. 8 (8) Fixed 4 DS CRQ_TL_LEN Tape list entry size. 12 (C) Character 12 CRQ_TL_ENTRYID Tape list entry ID. 12 (C) Character 6 CRQ_TL_IDVOLSER Tape volser name. 18 (12) Character 6 * Reserved. 24 (18) Character 16 CRQ_TL_ENTRYKEY Tape list entry key. 24 (18) Character 6 CRQ_TL_VOLSER Tape volser name. 30 (1E) Character 10 * Reserved. 40 (28) Character 64 CRQ_TL_ADJAREA Tape list adjunct area. 40 (28) Fixed 2 CRQ_TL_PRIORITY Highest priority of any single tape request needing tape. 42 (2A) Character 12 CRQ_TL_HI_EID Entry ID of highest priority single tape request needing this tape. 54 (36) Character 2 CRQ_TL_HOSTID Host ID of the host that has tape currently selected for recall. 56 (38) Bitstring 2 CRQ_TL_FLAGS Flags. 1... ....CRQ_TL_INUSE 1=In-Use. Note: If this flag is ON, then SNGL_TAPE_PROC flag is also ON if single tape is being processed. It is ON if single tape is being processed..1.. ....CRQ_TL_SNGL_TAPE_REQ 1= Single tape request. ...1 ....CRQ_TL_FIRST_VOL 1=First volume of volume request. .... 1...CRQ_TL_LAST_VOL 1=Last volume of multivolume request. 58 (3A) Fixed 2 CRQ_TL_FIRST_VOL_CNT Number of requests needing the tape as the first volume. 60 (3C) Fixed 2 CRQ_TL_LAST_VOL_CNT Number of requests needing tape as the last volume. 62 (3E) Character 8 CRQ_TL_CTS Time stamp TL created. 62 (3E) Fixed 4 CRQ_TL_CTIME Time the TL created. 66 (42) Fixed 4 CRQ_TL_CDATE Date the TL created. The date is obtained from the TIME DEC macro in format X'Ocyyddds'. 70 (46) Character 34 * Reserved. Table 7 shows the layout for the CRQ primary unselected list entry.Table 7. Entry for CRQ primary unselected list Offsets Type Bytes Name Description Dec Hex 0 (0) Structure 624 CRQ_PURL_ENT Array containing PUR list entry. 0 (0) Fixed 4 CRQ_PURL_FWD Forward ptr. 4 (4) Fixed 4 CRQ_PURL_BWD Backward ptr. 8 (8) Fixed 4 CRQ_PURL_LEN PURL entry size. 12 (C) Character 12 CRQ_PURL_ENTRYID PURL entry ID. 12 (C) Character 2 CRQ_PURL_ENTRYID_HOSTID Host ID. 14 (E) Character 2 * Reserved. 16 (10) Fixed 4 CRQ_PURL_ENTRYID_REQNUM MWE Request number. 20 (14) 4 * Reserved. 24 (18) Character 16 CRQ_PURL_ENTRYKEY List key. 24 (18) Fixed 2 CRQ_PURL_PRIORITY Priority. 26 (1A) Fixed 2 CRQ_PURL_USER_PRIORITY User priority value. 28 (1C) Character 8 CRQ_PURL_USERID USERID: - If nowait with priority=50 - '0'B.
- If W/noWait request with priority <> 50.
36 (24) Character 4 * Reserved. 40 (28) Character 64 CRQ_PURL_ADJAREA PUR list adjunct area. 40 (28) Character 44 CRQ_PURL_ADJ_DSNAME Dataset name. 84 (54) Character 8 CRQ_PURL_ADJ_USERID User ID. 92 (5C) Fixed 4 CRQ_PURL_ADJ_RETRY Earliest retry recall time. 96 (60) Bitstring 4 CRQ_PURL_ADJ_FLAGS Flags. 1... ....CRQ_PURL_ADJ_TAPE Requires Tape. .1.. ....CRQ_PURL_ADJ_TPTSO TSO request requires tape. ..1. ....CRQ_PURL_ADJ_EXT Extent reduction from EAV. ...1 ....CRQ_PURL_ADJ_CLTR Class transition candidate. .... 1...CRQ_PURL_ADJ_CLOUD Dataset mig copy in cloud. 100 (64) Character 4 * Reserved. 104 (68) Character 512 CRQ_PURL_DATA_ELEMENT Data element. 104 (68) Character 512 CRQ_PURL_MWE PUR list MWE. 616 (268) Character 8 CRQ_PURL_VERSION Version-used to quickly find the last request from a particular user. 616 (268) Character 8 CRQ_PURL_VER_USERID USERID: - If nowait request with priority = 50.
- '0'B for:
- Wait requests.
- Non-wait with priority 0-49, 51-100.
Table 8 shows the layout for the CRQ secondary unselected list entry.Table 8. Entry for CRQ secondary unselected list Offsets Type Bytes Name Description Dec Hex 0 (0) Structure 616 CRQ_SURL_ENT Array containing SUR list entry. 0 (0) Fixed 4 CRQ_SURL_FWD Forward pointer. 4 (4) Fixed 4 CRQ_SURL_BWD Backward pointer. 8 (8) Fixed 4 CRQ_SURL_LEN SUR list entry size. 12 (C) Character 12 CRQ_SURL_ENTRYID SUR list entry ID. 12 (C) Character 2 CRQ_SURL_ENTRYID_HOSTID Host ID. 14 (E) Character 2 * Reserved. 16 (10) Fixed 4 CRQ_SURL_ENTRYID_REQNUM MWE request number. 20 (14) 4 * Reserved. 24 (18) Character 16 CRQ_SURL_ENTRYKEY List key. 24 (18) Character 6 CRQ_SURL_VOLSER Tape volser. 30 (1E) Fixed 2 CRQ_SURL_PRIORITY MWE priority. 32 (24) Fixed 4 CRQ_SURL_FBIDCOMP Compliment of FBID. 36 (24) Character 4 * Reserved. 40 (28) Character 64 CRQ_SURL_ADJAREA SUR list adjunct area. 40 (28) Character 44 CRQ_SURL_ADJ_DSNAME Dataset name. 84 (54) Character 8 CRQ_SURL_ADJ_USERID User ID. 92 (5C) Fixed 4 CRQ_SURL_ADJ_RETRY Earliest retry recall time. 96 (60) Bitstring 4 CRQ_SURL_ADJ_FLAGS Flags. 1... ....CRQ_SURL_ADJ_TAPE Requires Tape. .1.. ....CRQ_SURL_ADJ_TPTSO TSO request requires tape. ..1. ....CRQ_SURL_ADJ_EXT Extent reduction from EAV. ...1 ....CRQ_SURL_ADJ_CLTR Class transition candidate. .... 1...CRQ_SURL_ADJ_CLOUD Dataset mig copy in cloud. 100 (64) Character 4 * Reserved. 104 (68) Character 512 CRQ_SURL_DATA_ELEMENT Data element. 104 (68) Character 512 CRQ_SURL_MWE SUR list MWE. Table 9 shows the layout for the CRQ selected list entry.Table 9. Entry for CRQ selected list Offsets Type Bytes Name Description Dec Hex 0 (0) Structure 616 CRQ_SRL_ENT Array containing SR list entry. 0 (0) Fixed 4 CRQ_SRL_FWD Forward pointer. 4 (4) Fixed 4 CRQ_SRL_BWD Backward pointer. 8 (8) Fixed 4 CRQ_SRL_LEN SR list entry size. 12 (C) Character 12 CRQ_SRL_ENTRYID SR list entry ID. 12 (C) Character 2 CRQ_SRL_ENTRYID_HOSTID Host ID. 14 (E) Character 2 * Reserved. 16 (10) Fixed 4 CRQ_SRL_ENTRYID_REQNUM MWE Request number. 20 (14) Character 4 * Reserved. 24 (18) Character 16 CRQ_SRL_ENTRYKEY SR list entry key. 24 (18) Character 2 CRQ_SRL_HOSTID Processing ID of the host. 26 (1A) Character 2 * Reserved. 28 (1C) Fixed 4 CRQ_SRL_REQNUM MWE request number. 32 (20) Character 8 * Reserved. 40 (28) Character 64 CRQ_SRL_ADJAREA SR list adjunct area. 40 (28) Character 44 CRQ_SRL_ADJ_DSNAME Dataset name. 84 (54) Character 8 CRQ_SRL_ADJ_USERID User ID. 92 (5C) Fixed 4 CRQ_SRL_ADJ_RETRY Earliest retry recall time. 96 (60) Bitstring 4 CRQ_SRL_ADJ_FLAGS Flags. 1... ....CRQ_SRL_ADJ_TAPE Requires tape. .1.. ....CRQ_SRL_ADJ_TPTSO TSO request requires tape. ..1. ....CRQ_SRL_ADJ_EXT Extent reduction from EAV. ...1 ....CRQ_SRL_ADJ_CLTR Class transition candidate. .... 1CRQ_SRL_ADJ_CLOUD Dataset mig copy in cloud. 100 (64) Character 4 * Reserved. 104 (68) Character 512 CRQ_SRL_DATA_ELEMENT Data element. 104 (68) Character 512 CRQ_SRL_MWE SR list MWE.
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-aligned, 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 contains 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.