z/OS DFSMShsm Managing Your Own Data

z/OS
IBM
DFSMShsm Managing Your Own Data
Version 2 Release 3
SC23-6870-30
Note
Before using this information and the product it supports, read the information in “Notices” on page 199.
This edition applies to Version 2 Release 3 of z/OS (5650-ZOS) and to all subsequent releases and modifications
until otherwise indicated in new editions.
Last updated: July 17, 2017
© Copyright IBM Corporation 1984, 2017.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . vii
Tables . . . . . . . . . . . . . . . ix
About this document . . . . . . . . . xi
Who should read this document
Major divisions of this document
Required product knowledge .
z/OS information . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
How to send your comments to IBM
If you have a technical problem .
.
.
.
xi
xi
xi
xi
xiii
.
.
. xiii
Summary of changes . . . . . . . . xv
Summary of changes for z/OS Version 2 Release 3
(V2R3) . . . . . . . . . . . . . . .
Summary of changes for z/OS Version 2 Release 2
(V2R2) as updated December 2015 . . . . .
Summary of changes for z/OS Version 2 Release 2
(V2R2) . . . . . . . . . . . . . . .
z/OS Version 2 Release 1 summary of changes .
. xv
. xv
. xv
. xv
Part 1. Introduction . . . . . . . . . 1
Chapter 1. Introduction to DFSMShsm. . 3
What is space management? . . . . . .
What is availability management? . . . .
What is a storage device hierarchy?. . . .
Where does DFSMShsm store my data? . .
What is the storage management subsystem?
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3
4
4
5
6
Chapter 2. What you do with DFSMShsm 7
Chapter 3. Security . . . . . . . . . . 9
What is RACF protection? . . . . . . .
What is password protection? . . . . .
Non-VSAM data sets . . . . . . .
VSAM data sets . . . . . . . . .
How are DFSMShsm commands protected?.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 9
10
10
11
11
Chapter 4. Methods of performing
tasks . . . . . . . . . . . . . . . 13
Using ISMF to perform tasks .
Invoking ISMF . . . . .
Building a data set list. . .
Specifying line operators . .
Receiving feedback from ISMF
Entering line operator modes
Using DFSMShsm user macros .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
13
13
14
15
16
16
16
Chapter 5. Space management . . . . 17
How does DFSMShsm manage space?
© Copyright IBM Corp. 1984, 2017
.
.
.
.
. 17
Automatic volume space management and
automatic secondary space management. .
Recall . . . . . . . . . . . . .
Can I perform space management tasks? .
.
.
.
. 17
. 18
. 21
Chapter 6. Availability management . . 23
How does DFSMShsm ensure data availability? .
Backup . . . . . . . . . . . . . .
Recovery . . . . . . . . . . . . .
Can I perform availability management tasks? .
.
.
.
.
23
23
24
27
Chapter 7. Space management and
availability management capabilities . . 29
Space-saving functions . . . .
Partitioned data set compression
Deletion of temporary data sets.
Release of overallocated space .
Deletion of expired data sets .
Extent reduction . . . . . .
Reblocking . . . . . . .
Expiration of backup versions .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
29
29
29
29
29
30
30
30
Chapter 8. Associated data sets . . . . 31
How does DFSMShsm know where my data sets are
located? . . . . . . . . . . . . . . .
Control data sets . . . . . . . . . . .
Journal data set . . . . . . . . . . . .
How do I know where my data sets are located? . .
31
31
31
31
Chapter 9. Understanding syntax
diagrams and using DFSMShsm
commands . . . . . . . . . . . . . 33
How to read syntax diagrams . . . . .
Symbols . . . . . . . . . . .
Syntax items . . . . . . . . . .
Syntax examples. . . . . . . . .
Using DFSMShsm commands . . . . .
Positional parameters . . . . . . .
Keyword parameters . . . . . . .
Abbreviating commands and parameters
Delimiters . . . . . . . . . . .
Line continuations . . . . . . . .
Comments. . . . . . . . . . .
Notational conventions . . . . . .
Specifying data set names . . . . . .
Specifying data set passwords . . . . .
Example of a DFSMShsm user command .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
33
33
33
34
35
35
35
36
36
36
36
36
37
38
38
Chapter 10. Interacting with
DFSMShsm . . . . . . . . . . . . . 39
TSO HELP command . . . . . . .
TSO Attention key . . . . . . . .
Incompatibilities caused by DFSMShsm
Submitting commands in batch mode .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
39
39
39
40
iii
Example JCL for submitting an DFSMShsm
command . . . . . . . . . . . .
.
. 40
Chapter 11. Introduction to DFSMShsm
user tasks . . . . . . . . . . . . . 43
What tasks can I perform using DFSMShsm user
commands? . . . . . . . . . . . . .
How do I perform the task? . . . . . . . .
. 43
. 43
Part 2. DFSMShsm user tasks . . . 45
Chapter 12. HALTERDS: Changing data
set parameters . . . . . . . . . . . 47
Using ISMF . . . . . .
Using TSO. . . . . . .
Syntax . . . . . . .
Required parameters . .
Optional parameters . .
Examples of different ways
HALTERDS command . .
.
.
.
.
.
to
.
. . . .
. . . .
. . . .
. . . .
. . . .
code the
. . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
47
49
49
50
50
.
.
. 52
Chapter 13. HBACKDS: Backing up
data sets . . . . . . . . . . . . . . 55
Using ISMF . . . . . .
Using TSO commands . . .
Backing up a data set . .
Syntax . . . . . . .
Required parameters . .
Optional parameters . .
Examples of different ways
HBACKDS command . .
Using inline backup . . .
Invoking inline backup . .
.
.
.
.
.
.
to
.
.
.
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
code the
. . . .
. . . .
. . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
55
56
57
57
60
60
.
.
.
.
.
.
. 66
. 67
. 68
Chapter 14. HBDELETE: Deleting
backup versions . . . . . . . . . . 73
Using ISMF . . . . . . . . . .
Using TSO. . . . . . . . . . .
Deleting backup versions of a data set
Syntax . . . . . . . . . . .
Required parameters . . . . . .
Optional parameters . . . . . .
Examples of different ways to code the
HBDELETE command . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
73
76
77
77
78
80
.
.
.
. 81
Chapter 15. HCANCEL: Canceling a
queued request . . . . . . . . . . . 83
Cancel queued requests . .
Syntax . . . . . . .
Required parameters . .
Optional parameters . .
Examples of different ways
HCANCEL command . .
.
.
.
.
to
.
. . . .
. . . .
. . . .
. . . .
code the
. . . .
.
.
.
.
.
.
.
.
.
.
.
.
83
83
83
84
.
.
. 84
Chapter 16. HDELETE: Deleting
migrated data sets. . . . . . . . . . 87
Using ISMF .
Using TSO. .
iv
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
z/OS DFSMShsm Managing Your Own Data
.
.
.
.
. 87
. 89
Syntax . . . . .
Required parameters
Optional parameters
Examples of different
HDELETE command
. .
. .
. .
ways
. .
.
.
.
to
.
. . . .
. . . .
. . . .
code the
. . . .
.
.
.
.
.
.
. 89
. 89
. 90
.
.
. 91
Chapter 17. HLIST: Listing information
from the BCDS and MCDS . . . . . . 93
Listing information from the BCDS and MCDS in
TSO . . . . . . . . . . . . . . . .
Syntax . . . . . . . . . . . . . .
Required parameters . . . . . . . . .
Optional parameters . . . . . . . . .
Examples of different ways to code the HLIST
command . . . . . . . . . . . .
Sample lists from the HLIST command . . . .
Listing volume entries . . . . . . . .
Listing backup volume entries. . . . . .
Listing data set entries from the migration
control data set . . . . . . . . . . .
Listing data set entries from the backup control
data set . . . . . . . . . . . . .
Listing entries of the latest backup version on
backup volumes . . . . . . . . . .
Listing data set entries from both control data
sets . . . . . . . . . . . . . . .
Listing user authorization status entries . .
Listing a summary of data set entries . . .
.
.
.
.
.
.
.
.
93
93
95
97
102
104
104
109
. 110
. 112
. 114
. 115
. 116
. 116
Chapter 18. HMIGRATE: Migrating
data sets . . . . . . . . . . . . . 117
Using ISMF . . . . . . . . .
Using TSO commands . . . . .
Syntax . . . . . . . . . .
Required parameters . . . . .
Optional parameters . . . . .
Examples of different ways to code
HMIGRATE command . . . .
. .
. .
. .
. .
. .
the
. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
117
119
119
120
121
.
.
. 123
Chapter 19. HQUERY: Listing pending
requests . . . . . . . . . . . . . 125
Using TSO commands . . . . . . .
Syntax. . . . . . . . . . . .
Required parameters . . . . . . .
Optional parameters . . . . . . .
Examples of different ways to code the
HQUERY command . . . . . . .
Messages from the HQUERY command .
.
.
.
.
.
.
.
.
.
.
.
.
125
125
125
125
.
.
.
.
. 126
. 127
Chapter 20. HRECALL: Recalling data
sets . . . . . . . . . . . . . . . 129
Using ISMF . . . . . . . . . . . .
Using TSO commands . . . . . . . .
Recalling one or more data sets with TSO .
Syntax. . . . . . . . . . . . .
Required parameters . . . . . . . .
Optional parameters . . . . . . . .
Examples of different ways to code the
HRECALL command . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
129
131
131
131
132
133
.
. 135
Chapter 21. HRECOVER: Recovering
data sets . . . . . . . . . . . . . 137
Using ISMF . . . . . . . . . . .
Using TSO . . . . . . . . . . .
Recovering a backup version or a dump
a data set. . . . . . . . . . .
Syntax. . . . . . . . . . . .
Required parameters . . . . . . .
Optional parameters . . . . . . .
Examples of different ways to code the
HRECOVER command . . . . . .
. . . 137
. . . 141
copy of
. . . 141
. . . 142
. . . 143
. . . 144
.
.
. 150
Part 3. DFSMShsm application
programming interface . . . . . . 153
Chapter 22. Using DFSMShsm user
macros . . . . . . . . . . . . . . 155
Register usage for return codes . . . . . . .
Supported unit types and their UCBs . . . . .
Asynchronous processing with DFSMShsm . . .
ARCFMWE: Freeing up storage in common storage
area . . . . . . . . . . . . . . . .
Syntax. . . . . . . . . . . . . . .
Required parameters . . . . . . . . . .
Optional parameters . . . . . . . . . .
Usage notes . . . . . . . . . . . . .
ARCHBACK: Backing up a specific data set . . .
Syntax. . . . . . . . . . . . . . .
Required parameters . . . . . . . . . .
Optional parameters . . . . . . . . . .
Usage notes . . . . . . . . . . . . .
ARCHBDEL: Deleting a backed up version of data
sets. . . . . . . . . . . . . . . . .
Syntax. . . . . . . . . . . . . . .
Required parameters . . . . . . . . . .
Optional parameters . . . . . . . . . .
Usage notes . . . . . . . . . . . . .
ARCHDEL: Deleting migrated data sets . . . .
Syntax. . . . . . . . . . . . . . .
Required parameters . . . . . . . . . .
Optional parameters . . . . . . . . . .
Usage notes . . . . . . . . . . . . .
ARCHMIG: Migrating data sets . . . . . . .
Syntax. . . . . . . . . . . . . . .
Required parameters . . . . . . . . . .
Optional parameters . . . . . . . . . .
Usage notes . . . . . . . . . . . . .
ARCHRCAL: Recalling a data set . . . . . .
156
156
156
Syntax. . . . . . . . . . . . . .
Required parameters . . . . . . . . .
Optional parameters . . . . . . . . .
Usage notes . . . . . . . . . . . .
ARCHRCOV: Recovering a data set . . . . .
Syntax. . . . . . . . . . . . . .
Required parameters . . . . . . . . .
Optional parameters . . . . . . . . .
Usage notes . . . . . . . . . . . .
ARCHSEND: Sending a command to DFSMShsm
Syntax. . . . . . . . . . . . . .
Required parameters . . . . . . . . .
Optional parameters . . . . . . . . .
Usage notes . . . . . . . . . . . .
ARCXTRCT: Extracting data from DFSMShsm .
Syntax. . . . . . . . . . . . . .
Required parameters . . . . . . . . .
Optional parameters . . . . . . . . .
Usage notes . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
171
171
171
173
174
174
174
174
177
178
178
178
178
179
180
180
180
183
184
Part 4. Appendixes . . . . . . . . 185
158
158
158
158
158
159
159
159
160
163
Appendix A. DFSMShsm and ISMF
line operator reference summary . . . 187
164
164
164
165
165
166
166
166
166
167
168
168
168
168
170
171
Appendix C. Accessibility . . . . . . 195
Appendix B. Return codes from
DFSMShsm commands . . . . . . . 189
Return codes from the default set .
Return codes from the extended set .
Return codes from user macros . .
Individual macros and their messages
.
.
.
.
Accessibility features . . . . . . .
Consult assistive technologies . . . .
Keyboard navigation of the user interface
Dotted decimal syntax diagrams . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
190
190
193
194
195
195
195
195
Notices . . . . . . . . . . . . . . 199
Terms and conditions for product documentation
IBM Online Privacy Statement. . . . . . .
Policy for unsupported hardware. . . . . .
Minimum supported hardware . . . . . .
Programming interface information . . . . .
Trademarks . . . . . . . . . . . . .
.
.
.
.
.
201
202
202
202
203
203
Index . . . . . . . . . . . . . . . 205
Contents
v
vi
z/OS DFSMShsm Managing Your Own Data
Figures
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
ISPF Master Application Menu . . . . . . 14
Page 1 of the Data Set Selection Entry Panel
14
Data Set List Panel . . . . . . . . . . 15
Entering the HBDELETE Line Operator
15
Flow of Automatic Migration . . . . . . 19
Flow of Automatic Recall . . . . . . . . 20
Flow of Automatic Incremental Backup
25
Flow of Recovery/Restore Functions . . . . 26
Data Set List Panel with HALTERDS Selected 47
HALTERDS Entry Panel . . . . . . . . 48
HALTERDS Entry Panel with Error Message
48
Data Set List Panel After Function Completes 49
Data Set List Panel with HBACKDS Selected
55
HBACKDS Entry Panel . . . . . . . . 56
Data Set List Panel after Function Completes
56
Example of Inline Backup Job Stream . . . . 70
Example of Messages Resulting from Inline
Backup Job Stream . . . . . . . . . . 71
Data Set List Panel with HBDELETE Selected 73
Data Set List Panel After Function Completes 76
Data Set List Panel with HDELETE Selected
87
HDELETE Entry Panel . . . . . . . . . 88
Data Set List Panel after Function Completes
88
Sample Printer List of Migration Volumes
from the Migration Control Data Set When
You Specify MIGRATIONVOLUME and
MIGRATIONCONTROLDATASET . . . . 105
Sample Terminal List of All Volumes from the
Migration Control Data Set When You Specify
VOLUME and TERMINAL . . . . . . . 106
Sample Printer List of Tape Migration Level 2
Volumes When You Specify
MIGRATIONLEVEL2(TAPE) and
MIGRATIONCONTROLDATASET parameter.. 108
Sample Printer List from the BCDS When You
Specify VOLUME,
PRIMARYVOLUME(volser) and
BACKUPCONTROLDATASET . . . . . . 108
Sample Printer List of All the Backup
Volumes When You Specify
BACKUPVOLUME. . . . . . . . . . 110
© Copyright IBM Corp. 1984, 2017
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
Sample Printer List When You Specify
DATASETNAME and
MIGRATIONCONTROLDATASET . . . .
Sample Printer List of a Group of Data Sets
When You Specify LEVEL . . . . . . .
Sample Terminal List of a Group of Data Sets
When You Specify LEVEL and TERMINAL .
Sample Printer List of All Data Sets When
You Specify DATASETNAME and
BACKUPCONTROLDATASET . . . . . .
Sample Terminal List of All Data Sets When
You Specify DATASETNAME,
BACKUPCONTROLDATASET, and
TERMINAL . . . . . . . . . . . .
Sample Printer List When You Specify
DATASETNAME and
SELECT(VOLUME(volser)) . . . . . . .
Sample Terminal List When You Specify
DATASETNAME, SELECT(VOLUME(volser)),
and TERMINAL . . . . . . . . . .
Sample Printer List of User Entries When You
Specify USER . . . . . . . . . . .
Sample Printer List When You Specify
DATASETNAME and SUMMARY. . . . .
Data Set List Panel with HMIGRATE Selected
HMIGRATE Entry Panel . . . . . . . .
Data Set List Panel After Function Completes
Data Set List Panel with HRECALL Selected
HRECALL Entry Panel . . . . . . . .
Data Set List Panel After Function Completes
Data Set List Panel with HRECOVER Selected
HRECOVER Entry Panel (Part 1 of 6)
HRECOVER Entry Panel (Part 2 of 6)
HRECOVER Entry Panel (Part 3 of 6)
HRECOVER Entry Panel (Part 4 of 6)
HRECOVER Entry Panel (Part 5 of 6)
HRECOVER Entry Panel (Part 6 of 6)
Data Set List Panel After Function Completes
111
111
112
114
114
115
115
116
116
117
118
118
129
130
130
137
138
138
139
139
140
140
141
vii
viii
z/OS DFSMShsm Managing Your Own Data
Tables
1.
2.
3.
4.
5.
6.
7.
8.
Syntax examples . . . . . . . . . . . 34
ARCINBAK Return Codes . . . . . . . 69
Headings of Output When You Request
Information from the Migration Control Data
Set for DFSMShsm-Managed or DASD
Migration Volume . . . . . . . . . . 104
Headings of Output When You Request
Information from the MCDS for Tape
Migration Level 2 Volumes . . . . . . . 106
Headings of Output When You Request
Information for DFSMShsm-Managed
Volumes from the Backup Control Data Set . 108
Headings of Output When You Request
Information for Backup Volumes . . . . . 109
Headings of Output When You Request
MCDS Information for Data Sets . . . . . 110
Headings of Output for All Data Sets When
You Request Information from the Backup
Control Data Set . . . . . . . . . . 112
© Copyright IBM Corp. 1984, 2017
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
HLIST--Listing Information from the BCDS
and MCDS . . . . . . . . . . . .
Headings of Output When You Request
Summary Information from the MCDS . . .
Messages Associated with the QUERY
Command by Parameter Name . . . . .
Supported Unit Types and Their UCBs
Extract Header Layout . . . . . . . .
Entry for DATA=COPYPOOL backup version
Entry for DATA=BUVERS backup version
DFSMShsm/ISMF Line Operators. . . . .
Default Set Return Codes . . . . . . .
Return codes from the extended set example:
register 15 values . . . . . . . . . .
Extended set return codes . . . . . . .
User Macros Return Codes . . . . . . .
Messages from Individual Macros. . . . .
114
116
127
156
180
181
182
187
190
191
192
193
194
ix
x
z/OS DFSMShsm Managing Your Own Data
About this document
This document helps you manage your data through the use of IBM® z/OS®
DFSMShsm. This document introduces you to DFSMShsm and what you use
DFSMShsm for. The basics of security, as it relates to DFSMShsm, is explained
along with the fundamental concepts of space and availability management and
how to use DFSMShsm user commands.
For information about the accessibility features of z/OS, for users who have a
physical disability, see Appendix C, “Accessibility,” on page 195.
Who should read this document
This document is intended for any one who manages their own data.
Major divisions of this document
This document is divided into the following parts:
Part 1, “Introduction,” on page 1 describes the major functions of DFSMShsm and
introduces the terminology used with DFSMShsm.
Part 2, “DFSMShsm user tasks,” on page 45 describes the tasks you can perform on
your data sets using DFSMShsm user commands, and explains how to perform
those commands.
Part 3, “DFSMShsm application programming interface,” on page 153 describes the
user macros you can use from application programs to issue DFSMShsm
commands.
Appendix A, “DFSMShsm and ISMF line operator reference summary,” on page
187 describes the DFSMShsm/ISMF line operators. The tables show the functions
and give the minimum abbreviation that you can use when entering line operators
in the foreground.
Appendix B, “Return codes from DFSMShsm commands,” on page 189 describes
the return codes issued by DFSMShsm after processing DFSMShsm commands or
requests from DFSMShsm user macros.
Required product knowledge
You should be familiar with the basic concepts of storage management, managing
your personal data, and basic diagnostic techniques. You are presumed to have a
background in using TSO, understanding of z/OS concepts and terms, and to
understand the information in z/OS DFSMS Introduction.
z/OS information
This information explains how z/OS references information in other documents
and on the web.
© Copyright IBM Corp. 1984, 2017
xi
When possible, this information uses cross document links that go directly to the
topic in reference using shortened versions of the document title. For complete
titles and order numbers of the documents for all products that are part of z/OS,
see z/OS Information Roadmap.
To find the complete z/OS library, go to IBM Knowledge Center
(www.ibm.com/support/knowledgecenter/SSLTBW/welcome).
xii
z/OS DFSMShsm Managing Your Own Data
How to send your comments to IBM
We appreciate your input on this documentation. Please provide us with any
feedback that you have, including comments on the clarity, accuracy, or
completeness of the information.
Use one of the following methods to send your comments:
Important: If your comment regards a technical problem, see instead “If you have
a technical problem.”
v Send an email to mhvrcfs@us.ibm.com.
v Send an email from the Contact z/OS web page (www.ibm.com/systems/z/os/
zos/webqs.html).
Include the following information:
v Your name and address
v Your email address
v Your phone or fax number
v The publication title and order number:
z/OS DFSMShsm Managing Your Own Data
SC23-6870-30
v The topic and page number or URL of the specific information to which your
comment relates
v The text of your comment.
When you send comments to IBM, you grant IBM a nonexclusive right to use or
distribute the comments in any way appropriate without incurring any obligation
to you.
IBM or any other organizations use the personal information that you supply to
contact you only about the issues that you submit.
If you have a technical problem
Do not use the feedback methods that are listed for sending comments. Instead,
take one or more of the following actions:
v Visit the IBM Support Portal (support.ibm.com).
v Contact your IBM service representative.
v Call IBM technical support.
© Copyright IBM Corp. 1984, 2017
xiii
xiv
z/OS DFSMShsm Managing Your Own Data
Summary of changes
This information includes terminology, maintenance, and editorial changes.
Technical changes or additions to the text and illustrations for the current edition
are indicated by a vertical line to the left of the change.
Summary of changes for z/OS Version 2 Release 3 (V2R3)
Summary of changes
New
The HMIGRATE command has new options. Refer to Chapter 18, “HMIGRATE:
Migrating data sets,” on page 117.
The ARCHMIG macro has new options. Refer to “ARCHMIG: Migrating data sets”
on page 168.
Summary of changes for z/OS Version 2 Release 2 (V2R2) as updated
December 2015
Summary of changes as updated December 2015
New
The HMIGRATE command has new optional SMS subparameters for the
TRANSITION parameter. Refer to Chapter 18, “HMIGRATE: Migrating data sets,”
on page 117.
The ARCHMIG macro has a new SMSAREA parameter and new optional SMS
subparameters for the TRANSITION parameter. Refer to “ARCHMIG: Migrating
data sets” on page 168.
Summary of changes for z/OS Version 2 Release 2 (V2R2)
Summary of changes
New
The HMIGRATE command has new options. Refer to Chapter 18, “HMIGRATE:
Migrating data sets,” on page 117.
The ARCHMIG macro has new options. Refer to “ARCHMIG: Migrating data sets”
on page 168.
z/OS Version 2 Release 1 summary of changes
See the Version 2 Release 1 (V2R1) versions of the following publications for all
enhancements related to z/OS V2R1:
v z/OS Migration
v z/OS Planning for Installation
© Copyright IBM Corp. 1984, 2017
xv
v z/OS Summary of Message and Interface Changes
v z/OS Introduction and Release Guide
xvi
z/OS DFSMShsm Managing Your Own Data
Part 1. Introduction
This topic describes the major functions of DFSMShsm and introduces the
terminology used with DFSMShsm.
© Copyright IBM Corp. 1984, 2017
1
2
z/OS DFSMShsm Managing Your Own Data
Chapter 1. Introduction to DFSMShsm
DFSMShsm is a licensed program that automatically performs space management
and availability management in a storage device hierarchy. DFSMShsm makes sure
that space is available on your Direct Access Storage Device (DASD) volumes so
that you can extend your old data sets and allocate new ones. DFSMShsm also
makes sure that backup copies of your data sets are always available if your
working copies are lost or corrupted.
DFSMShsm terminology includes the following:
Term
Meaning
Space management
Functions that ensure space is available for extending and allocating data
sets.
Availability management
Functions that make backup copies available.
Authorized user
An authorized user is someone whom the computing center has authorized
to issue all of the DFSMShsm commands. Authorized users can issue
commands that affect other users data sets.
Unauthorized user
An unauthorized user is someone who can issue only a limited subset of
the DFSMShsm commands, called the unauthorized commands.
Unauthorized users can affect only their own data sets.
What is space management?
Space management is a process that ensures that there is enough storage space on
user volumes for your data.
Space management performs two functions that are visible to you:
v It expires data sets that have passed their expiration dates. For
non-SMS-managed data sets, you specify the expiration date when you allocate
the data set. For SMS-managed data sets, the expiration date is controlled by the
management class associated with the data set. To find out if your data sets are
SMS-managed and what management classes are associated with your data sets,
ask your computing center.
v It migrates data sets that have not been used within a specified time. A migrated
data set is one that has been moved to a different volume (either DASD or tape)
in a special form that saves space on the volume. You cannot use a migrated
data set directly. However, as soon as you refer to the data set, either in an
interactive or batch use, DFSMShsm returns the data set to a volume that you
are authorized to use and in the form in which it originally existed.
You can recognize that a data set has been migrated by the term MIGRAT in the
volume field when you list your cataloged data sets. Only cataloged data sets can
be migrated.
The amount of time that a data set remains unused before it can migrate
automatically is the same for all data sets on a volume when they are
© Copyright IBM Corp. 1984, 2017
3
non-SMS-managed. For SMS-managed data sets, the management class determines
when the data sets are eligible to automatically migrate. Your computing center
can tell you what these values are.
Migration occurs to either of two levels: migration level 1 or migration level 2.
Migration level 1 (ML1) volumes are always DASD. Migration level 2 (ML2)
volumes can be either DASD or tape. Your computing center controls which
volumes are to be used as migration volumes.
DFSMShsm creates available space on user volumes by:
v Freeing over allocated space
v Deleting expired data sets
v Moving eligible data sets that you have not used recently to a
lower-cost-per-byte storage device
DFSMShsm records the location of each data set that it moves in a control data set.
What is availability management?
Availability management is a process that ensures that there is a current backup
version of your data sets from which you can recover your data if it is damaged or
accidentally deleted.
The automatic parts of availability management are invisible to you. DFSMShsm
automatically makes dumps of complete volumes (that is, it backs up the entire
allocated space of a volume) and backup copies of changed data sets. The backup
copies of changed data sets are known as incremental backup versions. These
dumps and backup copies are made on a regular schedule. When you need to
retrieve a backup copy, the copy is there for you. Your computing center can tell
you the schedule for making dumps and backup copies.
The feature that DFSMShsm provides is retrieval of your own backup copies.
Unless you tell it to do something else, DFSMShsm selects the latest copy that you
can retrieve. (Some computing centers may not allow you to retrieve a backup
copy from a volume dump. Therefore, you might be able to get only the latest
incremental backup version.) Your computing center can tell you if you can get
backup copies from dumps. DFSMShsm automatically copies new and changed
data sets to DASD or tape. DFSMShsm also dumps all the data sets on DASD
volumes to tape volumes.
What is a storage device hierarchy?
A storage device hierarchy consists of a group of storage devices that have
different costs for storing data, different amounts of data stored, and different
speeds of accessing the data.
DFSMShsm uses the following three-level storage device hierarchy for space
management:
v Level 0, including DFSMShsm-managed storage devices at the highest level of
the hierarchy, contains data directly accessible to you.
v Level 1 contains data sets that DFSMShsm has moved from level 0 volumes.
v Level 2 contains data sets that DFSMShsm has moved from level 1 or level 0
volumes.
4
z/OS DFSMShsm Managing Your Own Data
Storage devices at the lower levels of the hierarchy, level 1 and level 2, contain
data that DFSMShsm has compressed and optionally compacted into a format that
you cannot use. Devices at this level provide lower-cost-per-byte storage and
usually slower response time.
Where does DFSMShsm store my data?
DFSMShsm stores data in a device-independent format so it can move data to any
of the following devices:
v Tape for the 3480, 3480X, 3490, and 3590-1 Magnetic Tape Subsystems.
v DASD for Models 3380, 3390, and 9345.
DFSMShsm supports the following volume types:
v Level 0 volumes are volumes containing data sets that are directly accessible to
you and the jobs you run. DFSMShsm-managed volumes are those level 0
volumes that are managed by the DFSMShsm automatic functions.
Level 0 volumes, and DFSMShsm-managed volumes, can be any
DFSMShsm-supported DASD. These volumes must be mounted and online
when you refer to them with DFSMShsm commands.
v Migration level 1 volumes contain data sets that DFSMShsm moved from level
0 volumes and contain the backup versions that were created from a DFSMShsm
BACKDS or HBACKDS command.
Migration level 1 volumes are DFSMShsm-supported DASD on which
DFSMShsm maintains your data in DFSMShsm format. Normally, these volumes
are permanently mounted and online.
v Migration level 2 volumes are volumes containing data sets moved from
migration level 1 volumes or level 0 volumes.
Migration level 2 volumes are DFSMShsm-supported tape, or DASD, on which
DFSMShsm maintains your data in DFSMShsm format. Normally, these volumes
are not mounted or online.
v Daily backup volumes are volumes containing the most current backup
versions of data sets copied from level 0 volumes. These volumes may also
contain earlier backup versions of these data sets.
Daily backup volumes are DFSMShsm-supported tape, or DASD, on which
DFSMShsm maintains your data in DFSMShsm format. Normally, these volumes
are not mounted or online.
v Spill backup volumes are volumes containing earlier backup versions of data
sets, which were moved from DASD backup volumes.
Spill backup volumes are DFSMShsm-supported tape, or DASD, on which
DFSMShsm maintains your data sets in DFSMShsm format. Normally, these
volumes are not mounted or online.
v Dump volumes are DFSMShsm-owned magnetic tape volumes. When a volume
is dumped, DFSMShsm invokes DFSMSdss to write a copy of the entire
allocated space of that volume on a dump volume.
Dump volumes are DFSMShsm-supported tape. Image copies of volumes are
produced by the full volume dump function of DFSMSdss, which is invoked by
DFSMShsm.
v Aggregate backup volumes contain copies of the data sets of a user-defined
group of data sets, along with control information for those data sets. These data
sets and their control information are stored as a group so that they can be
recovered (if necessary) as an entity by an aggregate recovery process.
Chapter 1. Introduction to DFSMShsm
5
Aggregate backup volumes are DFSMShsm-supported tape and are normally not
mounted or online.
v Fast replication target volumes contain the fast replication backup copies of
DFSMShsm-managed volumes. Fast replication target volumes are contained
within SMS copy pool backup storage groups.
What is the storage management subsystem?
DFSMShsm is a member of the DFSMS product family. DFSMS, along with
resource access control facility (RACF®, a component of the Security Server for
z/OS) and interactive storage management facility (ISMF) licensed programs,
provides a system-managed storage environment freeing the user of many
time-consuming storage tasks.
The Storage Management Subsystem (SMS) is part of DFSMS. SMS changes the
storage management approach from user-managed volumes to SMS-managed data
sets residing in SMS-managed storage groups. The system, rather than the user,
determines data placement and handles data backup, movement, space, and
security.
SMS provides the following storage classes and groups, which are customized by
the storage administrator to fit the system environments and policies:
v Data class: A list of allocation attributes that the system uses for the creation of
data sets.
v Storage class: A list of storage performance and availability service requests.
v Management class: A list of data set migration, backup, and retention attributes
that DFSMShsm uses to manage storage at the data set level.
v Storage group: A list of real DASD volumes, or a list of serial numbers of
volumes that no longer reside on a system but that end users continue to refer
to in their JCL.
Storage administrators also customize SMS automatic class selection (ACS)
routines, which automatically assign the SMS classes and storage groups to data
sets. This allows the user to create data sets by providing only a small amount of
information through ISMF panels.
Because the SMS management class defines the data set migration, backup, and
retention parameters for each data set that is SMS-managed, DFSMShsm works
with SMS, using the SMS attributes, to provide space and availability management.
There are some differences in the way in which DFSMShsm works in an SMS
environment as opposed to a non-SMS environment. Some of those differences are
visible to the user when entering explicit commands, as certain commands and
parameters do not apply to SMS-managed data sets. Those differences are defined
for the user in the “DFSMShsm User Tasks” section of this publication.
6
z/OS DFSMShsm Managing Your Own Data
Chapter 2. What you do with DFSMShsm
Although DFSMShsm performs most of its functions automatically, you may at
times want to perform some of the functions for your data sets by command.
DFSMShsm provides a set of commands that unauthorized users can issue to
manage their own data sets. SMS provides controls in the management classes that
allow or disallow management of data sets by command. If your data sets are
associated with a management class that disallows space management or
availability management by command, you cannot issue these commands for those
data sets. In addition, DFSMShsm provides a command that authorized users can
use to issue DFSMShsm commands from TSO.
Many computing centers use security programs to protect users data sets from
being deleted, changed, or read by unauthorized people. DFSMShsm honors both
password and RACF protection for data sets.
DFSMShsm provides several ways to perform its tasks but not all ways can be
used for every task.
v Using interactive storage management facility (ISMF) panels
v Issuing commands through TSO
v Issuing user macros
v Using the inline backup facility
You can use DFSMShsm to perform the following tasks for your data sets:
v Back up a data set
v Change the data set parameters that affect backup for a particular data set
v Condense the data set. When you condense a data set, you release excess
allocated space in a sequential data set or remove all unused space or invalid
data from a partitioned data set.
v Cancel a request for DFSMShsm services
v Delete backup versions of a data set
v Delete a migrated data set
v Free storage in the common service area (CSA)
v List DFSMShsm information about your data sets
v Migrate a data set
v List information about your requests for DFSMShsm services.
v Recall a data set
v Recover a data set
v Send an authorized command to DFSMShsm
© Copyright IBM Corp. 1984, 2017
7
8
z/OS DFSMShsm Managing Your Own Data
Chapter 3. Security
DFSMShsm maintains the security of your data sets through the resource access
control facility (RACF) or through password protection. Operating as an authorized
MVS™ task, DFSMShsm can manage data sets automatically regardless of their
RACF or password protection.
DFSMShsm maintains the security of DFSMShsm commands through the use of
RACF FACILITY class profiles.
What is RACF protection?
RACF is a program that protects data sets from unauthorized access by enabling
you to define who can access your data sets and what functions they can perform
on the data sets. RACF uses the information in a data set profile to determine
whether a user is authorized to access the data set.
You can protect data sets with either separate RACF generic data set profiles or
RACF discrete data set profiles. A RACF generic data set profile describes one or
more data sets that have a similar name structure. A RACF discrete data set profile
describes a specific data set on a particular volume.
DFSMShsm optionally creates a backup profile for the most recent backup version
of a cataloged data set if the data set was protected with a RACF discrete profile at
the time of the backup. DFSMShsm maintains only one backup profile for all
backup versions of the cataloged data set. When all backup versions of the data set
are scratched, the related backup profile is also scratched.
If the data set had a RACF discrete profile when backed up, profile recovery will
be done if DFSMShsm finds out that the profile no longer exists when recovery is
attempted.
If the data set had a RACF discrete profile when backed up and you specify
NEWNAME, DFSMShsm creates a RACF discrete profile for the new name data
set.
The following table lists the level of RACF resource access authority that you need
to access and perform the DFSMShsm function on a RACF-protected data set. If
you are not authorized to manipulate the data, DFSMShsm fails the command.
DFSMShsm
User
Command
DFSMShsm Function
RACF Resource Access
Authority Required
HALTERDS
Changes the backup frequency and the
number of backup versions kept for one or
more data sets. Cannot be used on
SMS-managed data sets, which are
controlled by the data sets management
class parameters. If used on SMS-managed
data sets, the command fails and an error
message is issued.
ALTER
HBACKDS
Creates a backup version of one or more
data sets.
UPDATE
© Copyright IBM Corp. 1984, 2017
9
DFSMShsm
User
Command
DFSMShsm Function
RACF Resource Access
Authority Required
HBDELETE
Deletes specific backup versions of one or
more data sets.
ALTER
HDELETE
Deletes one or more migrated data sets.
ALTER
HMIGRATE
Migrates one or more data sets.
UPDATE
HRECALL
Recalls one or more migrated data sets.
EXECUTE
HRECOVER
Recovers, without the NEWNAME
ALTER
parameter, a backup version of one or more
If profile recovery is
data sets.
necessary, you also need
authority to create a RACF
discrete profile for the
recovered data set.
HRECOVER
Recover, with the NEWNAME parameter, a
backup version of one or more data sets.
READ authority to the data
set being recovered.
ALTER authority to the new
name data set.
If profile recovery is
necessary, you also need
authority to create a RACF
discrete profile for the new
name data set.
For more information on the use of RACF, see z/OS Security Server RACF Security
Administrator's Guide
What is password protection?
Password protection allows you to protect your data set by assigning it a
password. Another user cannot read, change, or delete your data set without
knowing the password.
MVS implements password protection differently for non-VSAM and VSAM data
sets.
Passwords are not supported for SMS data sets or for DFSMShsm user macros.
Non-VSAM data sets
MVS stores passwords for all non-VSAM data sets in one system password data
set.
DFSMShsm
User Command
10
Password You Must Supply
HALTERDS
The password in the system password data set that allows you to
write to the data set.
HBACKDS
The password in the system password data set that allows you to
write to the data set.
HBDELETE
The password in the system password data set that allows you to
write to the data set.
z/OS DFSMShsm Managing Your Own Data
DFSMShsm
User Command
Password You Must Supply
HDELETE
The password in the system password data set that allows you to
write to the data set.
HMIGRATE
The password in the system password data set that allows you to
write to the data set.
HRECALL
The password in the system password data set that allows you to
read the data set.
HRECOVER
For the data set that you are recovering, supply the password in the
system password data set that allows you to write to the data set.
NEWNAME is not specified.
If you specify the NEWNAME parameter, for the new name data set,
supply the password in the system password data set that allows you
to write to the data set.
VSAM data sets
The password for each VSAM data set is stored in a catalog record for each
specific VSAM data set. Therefore, MVS maintains the VSAM passwords during
DFSMShsm processing as a part of the regular catalog creation and updating.
DFSMShsm User
Command
Password You Must Supply
HALTERDS
The master password of the base cluster.
HBACKDS
The master password of the base cluster.
HBDELETE
The master password of the base cluster.
HDELETE
The master password of the base cluster.
HMIGRATE
The master password of the base cluster.
HRECALL
The master password of the base cluster.
HRECOVER
If the data set to be recovered exists, supply the current master
password of the base cluster. If the data set does not exist, supply the
master password of the base cluster that existed when DFSMShsm
backed up the data set.
If you specify the NEWNAME parameter, supply the master
password of the base cluster for the new name data set.
How are DFSMShsm commands protected?
DFSMShsm provides a way to protect all DFSMShsm command access through the
use of RACF FACILITY class profiles. An active RACF FACILITY class establishes
the security environment, and if active, each user command is protected by a
RACF FACILITY class profile. Your installation's Security Administrator must give
you user ID authority to the resource that represents the user command you want
to use.
Chapter 3. Security
11
12
z/OS DFSMShsm Managing Your Own Data
Chapter 4. Methods of performing tasks
DFSMShsm provides several ways to perform tasks. You can use ISMF panels to
issue commands to DFSMShsm, issue DFSMShsm commands through Time
Sharing Option (TSO), or use DFSMShsm user macros from portions of application
programs.
This topic provides examples of using ISMF to perform tasks and explains how to
use the DFSMShsm user macros.
Using ISMF to perform tasks
Interactive Storage Management Facility (ISMF) is an Interactive System
Productivity Facility (ISPF) application that helps you manage data and storage
interactively. DFSMShsm/ISMF line operators are used to perform tasks on a
specific data set. In this section, the following topics are discussed for ISMF:
v Invoking ISMF
v Building a data set list
v Specifying line operators
v Receiving feedback from ISMF
v Entering line operator modes
The information you supply on DFSMShsm/ISMF panels is used to build TSO
commands like those you would enter at your terminal. Using ISMF panels, you
no longer have to remember DFSMShsm keywords or syntax. You simply fill in the
values on the DFSMShsm/ISMF panels and ISMF automatically generates the
DFSMShsm command.
Using ISMF panels, you can also construct a list of data about specific data sets.
You identify the selection criteria to ISMF and it builds a list that fits your criteria.
Because the list is formatted to provide a variety of information all in one place,
you can use it to analyze and manage your data and storage more efficiently.
Invoking ISMF
How you invoke ISMF depends upon your installation. You begin by logging on to
TSO and invoking ISPF.
If ISMF is installed as an option on the ISPF Master Application menu or as an
option on the ISPF/PDF Primary Option menu, specify the selection option (letter
or number) that corresponds to ISMF. The ISMF Primary Option menu appears,
and you can begin an ISMF session. For example, in Figure 1 on page 14, you see
the ISPF Master Application menu. To select ISMF, enter I (letter i) following the
arrow on the command line.
© Copyright IBM Corp. 1984, 2017
13
-------------------- ISPF MASTER APPLICATION MENU ------------------SELECT APPLICATION ===> I_
USERID - K665941
1 SPF
- SPF PROGRAM DEVELOPMENT FACILITY
TIME
- 07:30
. ...
...
TERMINAL - 3279
. ...
...
PF KEYS - 12
. ...
...
I ISMF
- INTERACTIVE STORAGE MANAGEMENT FACILITY
. ...
...
. ...
...
. ...
...
P PARMS
- SPECIFY TERMINATION PARAMETERS AND LIST/LOG DEFAULTS
X EXIT
- TERMINATE USING LIST/LOG DEFAULTS
PRESS THE END KEY TO TERMINATE
Figure 1. ISPF Master Application Menu
If you want to invoke ISMF directly from TSO, issue: ISPSTART PGM(DGTFMD01)
NEWAPPL(DGT)
The ISMF Primary Option menu appears, and you can begin an ISMF session.
Building a data set list
After invoking ISMF and choosing the data set application from the ISMF Primary
Option menu, you need to build a data set list to use during the session. To do
this:
1. Complete the Data Set Selection Entry panel with the values shown in Figure 2
to generate the list from the catalog and acquire data from the VTOC for data
sets that have been migrated by DFSMShsm. Verify that pages 2, 3, and 4 of the
Data Set Selection Entry panel are blank. If they are not blank, you will receive
the short informational message: OTHER VALUES PRESENT.
Panel Defaults Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET SELECTION ENTRY PANEL
Page 1 of 5
For a Data Set List, Select Source of Generated List . . 2
1
Generate from a Saved List
List Name . .
2
Generate a new list from criteria below
Data Set Name . . . USER20.*
(1 or 2)
Specify Source of the new list . . 2
(1 - VTOC, 2 - Catalog)
1 Generate list from VTOC
Volume Serial Number . . .
(fully or partially specified)
2 Generate list from Catalog
Catalog Name . . .
Catalog Password . . . .
(if password protected)
Volume Serial Number . . .
(fully or partially specified)
Acquire Data from Volume . . . . . . . Y (Y or N)
Acquire Data if DFSMShsm Migrated . . Y (Y or N)
Command ===>
F1=Help
F2=Split F3=End
F4=Return F7=Up
F8=Down
F9=Swap
F10=Left F11=Right F12=Cursor
Figure 2. Page 1 of the Data Set Selection Entry Panel
14
z/OS DFSMShsm Managing Your Own Data
2. Press ENTER to generate the data set list. A list that conforms to your selection
criteria appears (Figure 3). See z/OS DFSMS Using the Interactive Storage
Management Facility for more information about building a data set list.
Panel List Dataset Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET LIST
Entries 1-1 of 1
Enter Line Operators below:
Data Columns 3-6 of 39
LINE
OPERATOR
---(1)----
----------
ALLOC
DATA SET NAME
SPACE
------------(2)------------ --(3)-USER20.CLIST.CLIST
46
USER20.DFP220.DGTTLIB
46
USER20.ISMF.DGTLLIB
46
USER20.ISMF.DGTPLIB
46
USER20.ISMF.DUMP
4684
USER20.ISMF.JCL
468
USER20.ISPFILE
46
USER20.ISPPROF
93
USER20.SPFLOG1.LIST
2623
USER20.TEMP.DATASET
4684
------ ----------- BOTTOM OF DATA
Command ===>
F1=Help
F2=Split F3=End
F4=Return
F10=Left F11=Right F12=Cursor
ALLOC % NOT COMPRESSED
USED
USED FORMAT
--(4)-- -(5)- ---(6)---46
0 ???
46
0 ???
46
0 ???
46
0 ???
4356
7 ???
46
90 ???
46
0 ???
93
0 ???
1311
50 ???
93
98 ???
----------- ------ ----
F7=Up
Scroll ===> HALF
F8=Down
F9=Swap
Figure 3. Data Set List Panel
Specifying line operators
After you have created a data set list and tailored it to fit your needs, you can use
ISMF to perform DFSMShsm tasks. Using line operators, you can perform these
tasks against entries in your list. For a list of DFSMShsm line operators, see
Appendix A, “DFSMShsm and ISMF line operator reference summary,” on page
187.
Line operators work with the individual entries in a list. You enter line operators
in the line operator field, column (1), next to the entry you want to affect. For
example, to delete backup versions of data sets, enter the HBDELETE line operator
in the line operator field next to the data set you want to delete, as shown in
Figure 4.
Panel List Dataset Utilities Scroll Help
---------------------------------------------DATA SET LIST
Enter Line Operators below:
LINE
OPERATOR
DATA SET NAME
---(1)---- ------------(2)-----------HBDELETE
USER20.ISMF.JCL
Figure 4. Entering the HBDELETE Line Operator
ISMF displays the HBDELETE entry panel, which allows you to view and change
processing options for HBDELETE.
Chapter 4. Methods of performing tasks
15
Receiving feedback from ISMF
ISMF provides feedback for successful completion or submission of line operators
and for error conditions. When a line operator is successful, ISMF inserts an
asterisk (*) before the line operator in the line operator field.
If there is an error during the execution of a line operator, ISMF prefixes the line
operator with a question mark (?). A short error message appears in the upper
right corner of the panel.
Entering line operator modes
There are two ways to enter line operators: normal mode and last-use mode.
In normal mode, you enter the line operator by itself in the line operator field. ISMF
displays the entry panel associated with the line operator you specify. You can then
view or change the processing options on the entry panel.
In last-use mode, you enter the line operator followed by an equal sign in the line
operator field. ISMF does not display the entry panel for the line operator. Instead,
the line operator is processed with the values that were present on the entry panel
the last time the line operator was executed in this, or a previous, ISMF session.
Note:
1. The HALTERDS and HBDELETE line operators can only be entered in normal
mode.
2. The CONDENSE panel again displays the volume serial number and the device
type where the data set resides if the CONDENSE command is reentered.
Using DFSMShsm user macros
DFSMShsm has macros available that allow you to request DFSMShsm service
from your application programs. When you provide information to the macro and
process it from your application program, the macro builds the required
DFSMShsm control information and issues the request for DFSMShsm service. The
macros are in execute form only. There is no list form provided.
The following user macros are currently supported in DFSMShsm:
v ARCFMWE frees up storage in common storage area (CSA)
v ARCHBACK backs up a specific data set
v ARCHBDEL deletes backed up versions of a data set
v ARCHDEL deletes a migrated data set
v ARCHMIG migrates a specific data set
v ARCHRCAL recalls a data set
v ARCHRCOV recovers a data set
v ARCHSEND sends a command to DFSMShsm
v ARCXTRCT extracts data from DFSMShsm
For more information on application programming interfaces or user macros, see
Chapter 22, “Using DFSMShsm user macros,” on page 155.
16
z/OS DFSMShsm Managing Your Own Data
Chapter 5. Space management
The purpose of space management is to manage DASD storage efficiently. This
topic explains how DFSMShsm manages space and what commands you can issue
to perform space management on your own data sets.
How does DFSMShsm manage space?
DFSMShsm manages space by:
v Freeing overallocated space
v Deleting expired data sets
v Moving eligible data sets that you have not used recently from a
DFSMShsm-managed volume to a migration level 1 or migration level 2 volume
DFSMShsm can also move data sets from migration level 1 volumes to migration
level 2 volumes or directly from level 0 to migration level 2 volumes. When you
refer to a migrated data set, DFSMShsm automatically recalls it to a level 0 volume
so you can use it.
DFSMShsm can migrate or delete data sets on volumes either automatically or by
command. If you do not want to wait for automatic space management to run, you
can use the DFSMShsm user command HMIGRATE to migrate one or more of
your data sets. You can also use the DFSMShsm user command HDELETE to
delete one or more of your migrated data sets.
DFSMShsm uses the following functions to manage space:
v Space Management
– Automatic volume space management
- Primary
- Interval migration
- On-demand migration
– Automatic secondary space management
v Recall
– Automatic recall
– Command recall
Automatic volume space management and automatic
secondary space management
Automatic volume and automatic secondary space management prepare the
computing system for the addition of new data by freeing space on the
DFSMShsm-managed volumes and DFSMShsm-owned volumes. Automatic
volume space management includes automatic primary space management,
interval migration, and on-demand migration.
During automatic primary space management, DFSMShsm performs space
management on each requested DFSMShsm-managed volume at a specified time of
day.
During interval migration, DFSMShsm ensures on an hourly basis that a specified
amount of space is available on DFSMShsm-managed volumes.
© Copyright IBM Corp. 1984, 2017
17
During on-demand migration, DFSMShsm performs space management on eligible
SMS-managed volumes immediately after the volume exceeds its high threshold.
During automatic secondary space management, DFSMShsm performs space
management on eligible migrated data sets.
Recall
Recall returns a migrated data set to a user volume (level 0). If you want to recall
your own migrated data sets, you can do so without knowing where your data
sets reside. To provide interactive terminal users with quick access to their
migrated data sets, DFSMShsm allows up to 15 concurrent recall tasks.
Automatic recall returns your migrated data set to a DFSMShsm-managed volume
when you refer to it.
Command recall returns your migrated data set to a user volume when you enter
the HRECALL command through an ISMF panel or by directly keying in the
command.
For both automatic and command recall, DFSMShsm working with SMS invokes
the automatic class selection (ACS) routines. Data sets that were not SMS-managed
at the time they were migrated may be recalled as SMS-managed data sets. The
ACS routines determine whether the data sets should be recalled as SMS-managed,
and if so, the routines select the classes and storage groups in which the data sets
will reside. The system chooses the appropriate volume for the data sets.
DFSMShsm working without SMS returns a migrated data set to a
DFSMShsm-managed non-SMS volume with the most free space.
See Figure 5 on page 19 and Figure 6 on page 20 for an overview of the flow for
the automatic migration and the automatic recall functions.
18
z/OS DFSMShsm Managing Your Own Data
SMS-Managed
Non-SMS-Managed
DFSMShsm
Managed
Storage
Groups
(Volumes)
Primary
Volumes
DFSMShsm
DFSMSdss
Migration
Exit
Compaction
Tape
DASD
Subsequent
Migration
Exit
Migration
Level 2
Control
Data
Sets
Tape
Legend:
Control Information
Data Flow
ARC2MY06
Migration
Level 1
System
Catalog
Figure 5. Flow of Automatic Migration
Chapter 5. Space management
19
Non-SMS-Managed
SMS-Managed
Storage
Groups
(Volumes)
DFSMShsm
Managed
Primary
Volumes
System
Catalog
Recall
Exit
Automatic
Class
Selection
DFSMShsm
DFSMSdss
Control
Data
Sets
Decompaction
Migration
Level 1
DASD
Migration
Level 2
Tape
Figure 6. Flow of Automatic Recall
20
z/OS DFSMShsm Managing Your Own Data
Legend:
Control Information
Data Flow
Can I perform space management tasks?
Although DFSMShsm performs space management automatically, you can perform
space management tasks on your own data sets by issuing the following
DFSMShsm commands through ISMF panels, DFSMShsm space maintenance
panels, TSO, TSO/E or a user macro.
Space Management
User Commands
DFSMShsm Function
HDELETE
Deletes one or more migrated data sets.
HLIST
Lists information from the migration and backup control
data sets.
HMIGRATE
Requests migration of one or more data sets.
HQUERY
Lists outstanding DFSMShsm requests.
HRECALL
Recalls one or more migrated data sets.
For more information on DFSMShsm user commands, see “What tasks can I
perform using DFSMShsm user commands?” on page 43.
Chapter 5. Space management
21
22
z/OS DFSMShsm Managing Your Own Data
Chapter 6. Availability management
Availability management ensures that lost or damaged data sets can be retrieved at
the most current possible level. This topic describes how DFSMShsm ensures data
availability and what commands you can issue to perform availability management
on your own data sets.
How does DFSMShsm ensure data availability?
One of the ways in which DFSMShsm ensures data availability is by automatically
copying new and changed user data sets to a backup volume. The copy of your
data set is called a backup version. The backup version ensures that your data is
still available if your original data set is damaged or accidentally deleted.
Another way in which DFSMShsm ensures data availability is by automatically
dumping volumes to tape.
Availability management also includes the process of retrieving data from a backup
or dump version if you need to recover your data set. DFSMShsm can recover
your data set only if you issue the HRECOVER command.
DFSMShsm uses the following functions to ensure that your data is available:
v Backup
– Automatic backup
– Command backup
– Inline backup
v Recovery
– Data set recovery
– Volume recovery
Backup
The backup function copies a data set from a level 0 volume or a level 1 migration
volume to a backup volume. The result of the backup process is a backup version
of the data set, which you can recover with the HRECOVER command.
The automatic backup function ensures that a current copy of new and changed
data sets exists in case the original data sets are damaged or accidentally deleted.
At the time and on the days specified by the storage administrator, DFSMShsm
automatically copies new and changed data sets on DFSMShsm-managed volumes
to tape or DASD. During automatic backup (also referred to as incremental
backup), DFSMShsm backs up only new or changed data sets.
DFSMShsm automatic backup, working with SMS, uses storage group and
management class attributes to determine which data sets get backed up, how
often they get backed up, how many backup versions to maintain, and how long
to keep those backup versions.
DFSMShsm automatic backup, working without SMS, uses the volume automatic
backup attribute to backup volumes on a volume basis. The number of backup
© Copyright IBM Corp. 1984, 2017
23
versions kept and how often they get backed up are typically the same for all
non-SMS data sets in the installation, except where the HALTERDS command has
been used to change specific data sets.
When you issue the HBACKDS command, the command backup function copies a
specific data set to either a migration level 1 volume or to a backup tape. The data
set can be cataloged or uncataloged and does not have to reside on a DASD
volume that is managed by DFSMShsm. The volume, however, must be mounted.
Command backup of SMS-managed data sets is available for eligible data sets.
Eligibility is controlled by an SMS management class attribute.
The inline backup function (a program called ARCINBAK) allows you to back up
data sets in the middle of a job. If you use the optional TARGET keyword,
ARCINBAK allows you to direct a data set to ML1 DASD or to tape.
Recovery
The recovery function recovers a backup version to a level 0 volume. Recovery
must be initiated by a command.
The data set recovery function refers to the process of recovering a data set to its
condition as of a specified date.
You can recover individual data sets by entering an HRECOVER line operator on
an ISMF panel or by issuing the HRECOVER command.
DFSMShsm can recover data sets from a DFSMShsm backup version or from a
DFSMShsm dump copy. For a data set to be restored from a dump copy, the dump
copy must have been made from a dump class that allows data set restore, and a
VTOC copy must exist for the dump (except when an authorized user explicitly
specifies a dump volume). Dump copies created by the fast replication process are
not used for recoveries by the RECOVER nor HRECOVER commands.
DFSMShsm automatically chooses the most recent copy of the data set unless
directed otherwise by options you specify with the HRECOVER command, or by
options set by your installation’s system programmer.
If the data set is SMS-managed at the time of recovery, the target volume is
determined by the data sets storage class and storage group. If the data set is not
SMS-managed, then the target volume is selected in the following order:
v The target volume specified
v The volume on which the target data set is currently cataloged
v The volume from which the data set was originally backed up or dumped
The volume recovery function refers to the process of recovering a level 0 volume
to its condition as of a specified date.
DFSMShsm volume recovery can use incremental backups or full-volume dumps,
or both. A DFSMShsm-authorized user can issue one RECOVER command that is
used to request both a volume restore and an incremental volume recovery.
See Figure 7 on page 25 and Figure 8 on page 26 for an overview of the flow for
the automatic incremental backup and the recovery/restore functions.
24
z/OS DFSMShsm Managing Your Own Data
SMS-Managed
Storage
Groups
(Volumes)
Non-SMS-Managed
DFSMShsm
Managed
Primary
Volumes
DFSMSdss
DFSMShsm
Journal
Control
Data
Sets
Backup
Exit
Compaction
Tape
Spill
Backup
Tape
DASD
Tape
ARC2MY08
Daily
Backup
Figure 7. Flow of Automatic Incremental Backup
Chapter 6. Availability management
25
SMS-Managed
Storage
Groups
(Volumes)
Non-SMS-Managed
DFSMShsm
Managed
Primary
Volumes
DFSMShsm
System
Catalog
DFSMSdss
Control
Data
Sets
Automatic
Class
Selection
Decompaction
DASD
Backup
Tape
Tape
Legend:
Control Information
Data Flow
Dump
Figure 8. Flow of Recovery/Restore Functions
26
z/OS DFSMShsm Managing Your Own Data
Can I perform availability management tasks?
Although DFSMShsm performs backup and dump tasks automatically, you can
perform availability management tasks on your own data sets by issuing the
following DFSMShsm user commands through ISMF online panels, TSO, TSO/E,
or a user macro. Inline backup is also available for backing up data sets.
Availability Management
User Commands
DFSMShsm Functions
HALTERDS
Changes the minimum backup frequency and number of
backup versions kept for one or more data sets. Cannot be
used on SMS-managed data sets, which are controlled by
the data sets’ management class parameters. If used on
SMS-managed data sets, the command fails and an error
message is issued.
HBACKDS
Creates a backup version of one or more data sets.
HBDELETE
Deletes specific backup versions of one or more data sets.
HLIST
Lists information from the migration and backup control
data sets.
HQUERY
Lists outstanding DFSMShsm requests.
HRECOVER
Recovers a backup version of one or more data sets.
For more information on DFSMShsm user commands, see “What tasks can I
perform using DFSMShsm user commands?” on page 43.
Chapter 6. Availability management
27
28
z/OS DFSMShsm Managing Your Own Data
Chapter 7. Space management and availability management
capabilities
This topic describes some of the space saving functions provided by DFSMShsm.
Space-saving functions
Space-saving functions, part of DFSMShsm space management and availability
management, allow DFSMShsm to consolidate data while it migrates and backs up
data sets and to perform cleanup activities so that the migration volume can store
more data or so that the data occupies less space when DFSMShsm returns it to a
DFSMShsm-managed volume.
The following items are space saving functions:
v Partitioned data set compression
v Deletion of temporary data sets
v Release of overallocated space
v Deletion of expired data sets
v Extent reduction
v Reblocking
v Expiration of backup versions
Partitioned data set compression
DFSMShsm moves only data and not the entire allocated space when it migrates
and recalls or backs up and recovers data sets. If you allocate more space for a
partitioned data set than the data requires, DFSMShsm releases both the unused
space and the used space that is no longer valid when it migrates and recalls or
backs up and recovers the data set. Furthermore, if you have specified secondary
extents, when DFSMShsm recalls or recovers the data set to a DFSMShsm-managed
volume, it allocates only the amount of space that the data requires. DFSMShsm
retains user information in partitioned data set directories.
Deletion of temporary data sets
Temporary data sets are data sets that are unintentionally left at the end of the
task. DFSMShsm automatically deletes these data sets as each data set is
encountered.
Release of overallocated space
This is space that was allocated for data sets, but is not being used and is not
needed. This is a management class option for SMS-managed data sets.
Deletion of expired data sets
During primary space management and secondary space management, DFSMShsm
determines if data sets meet the optional expiration criteria. If they do, DFSMShsm
deletes them. The expiration and deletion of an SMS-managed data set is
controlled by management class attributes. Migrated data sets are included in the
expiration checking and deleting process.
© Copyright IBM Corp. 1984, 2017
29
Extent reduction
When DFSMShsm recalls or recovers a data set, it requests MVS to reallocate the
data set. DFSMShsm requests enough space in the allocation request so it can recall
or recover the data set in one extent. If enough contiguous space is available on the
target volume, DFSMShsm automatically reduces the number of extents as it
migrates and recalls or backs up and recovers the data set. If you specified
secondary extents when you allocated the data set, DFSMShsm releases any
unused space during recall or recovery. This process makes a larger contiguous
space available for allocation of larger data sets. DFSMShsm can migrate, then
recall, a data set specifically to reduce extents.
Reblocking
Reblocking is the process of changing the number of records in a physical block.
The purpose of reblocking is to use the space on the DASD volume more
efficiently. DFSMShsm can reblock physical sequential data sets during recall and
recovery to any DFSMShsm-supported DASD. If DFSMSdss is the data mover,
DFSMShsm can reblock partitioned data sets. When recalling or recovering a data
set, DFSMShsm does not determine a blocksize for the data set if the data set
VTOC entry indicates that the data set is reblockable. Instead, the blocksize is
determined by the DFSMS DASD calculation services.
Expiration of backup versions
A DFSMShsm-authorized user can issue a command for DFSMShsm to delete
backup versions of data sets when the expiration criteria of those data sets have
been reached. Management class attributes control the expiration and deletion of
backup versions of SMS-managed data sets. Command parameters control the
expiration and deletion of backup versions of non-SMS-managed data sets.
30
z/OS DFSMShsm Managing Your Own Data
Chapter 8. Associated data sets
This topic describes the control data sets, the journal data set, and the log used by
DFSMShsm.
How does DFSMShsm know where my data sets are located?
DFSMShsm keeps track of all migration and backup activity by recording
information in the control data sets, the journal data set, and the DFSMShsm log.
Control data sets
The following control data sets contain the location of the data sets that
DFSMShsm migrates and backs up:
Control Data Set
Description
Backup Control Data Set
(BCDS)
Contains content and location of backup versions and
dump copies
Migration Control Data Set
(MCDS)
Contains content and location of migrated data sets
Offline Control Data Set
(OCDS)
Contains content of tape backup volumes and tape
migration level 2 volumes
Journal data set
The journal data set contains the sequential history of updates to the control data
sets. If a control data set is damaged, DFSMShsm-authorized users can recover it to
its most current status by combining the entries in the journal data set with the
restored backup version of the control data set.
How do I know where my data sets are located?
You can list migration and backup control data set information by issuing the
following DFSMShsm user command through TSO or TSO/E:
DFSMShsm User Command
Pertaining to Control Data Sets
HLIST
Lists information from the migration and backup control
data sets.
For more information on DFSMShsm user commands, see “What tasks can I
perform using DFSMShsm user commands?” on page 43.
© Copyright IBM Corp. 1984, 2017
31
32
z/OS DFSMShsm Managing Your Own Data
Chapter 9. Understanding syntax diagrams and using
DFSMShsm commands
This topic describes using DFSMShsm commands and the notational conventions
used in this publication.
How to read syntax diagrams
This section describes how to read syntax diagrams. It defines syntax diagram
symbols, items that may be contained within the diagrams (keywords, variables,
delimiters, operators, fragment references, operands) and provides syntax examples
that contain these items.
Syntax diagrams pictorially display the order and parts (options and arguments)
that comprise a command statement. They are read from left to right and from top
to bottom, following the main path of the horizontal line.
For users accessing the Information Center using a screen reader, syntax diagrams
are provided in dotted decimal format.
Symbols
The following symbols may be displayed in syntax diagrams:
Symbol
Definition
►►───
Indicates the beginning of the syntax diagram.
───►
Indicates that the syntax diagram is continued to the next line.
►───
Indicates that the syntax is continued from the previous line.
───►◄
Indicates the end of the syntax diagram.
Syntax items
Syntax diagrams contain many different items. Syntax items include:
v Keywords - a command name or any other literal information.
v Variables - variables are italicized, appear in lowercase, and represent the name
of values you can supply.
v Delimiters - delimiters indicate the start or end of keywords, variables, or
operators. For example, a left parenthesis is a delimiter.
v Operators - operators include add (+), subtract (-), multiply (*), divide (/), equal
(=), and other mathematical operations that may need to be performed.
v Fragment references - a part of a syntax diagram, separated from the diagram to
show greater detail.
v Separators - a separator separates keywords, variables or operators. For example,
a comma (,) is a separator.
Note: If a syntax diagram shows a character that is not alphanumeric (for
example, parentheses, periods, commas, equal signs, a blank space), enter the
character as part of the syntax.
© Copyright IBM Corp. 1984, 2017
33
Keywords, variables, and operators may be displayed as required, optional, or
default. Fragments, separators, and delimiters may be displayed as required or
optional.
Item type
Definition
Required
Required items are displayed on the main path of the horizontal line.
Optional
Optional items are displayed below the main path of the horizontal line.
Default
Default items are displayed above the main path of the horizontal line.
Syntax examples
The following table provides syntax examples.
Table 1. Syntax examples
Item
Syntax example
Required item.
Required items appear on the main path of the
horizontal line. You must specify these items.
►►
KEYWORD required_item
►◄
►►
KEYWORD
►◄
►►
KEYWORD
Required choice.
A required choice (two or more items) appears
in a vertical stack on the main path of the
horizontal line. You must choose one of the
items in the stack.
required_choice1
required_choice2
Optional item.
Optional items appear below the main path of
the horizontal line.
►◄
optional_item
Optional choice.
An optional choice (two or more items)
appears in a vertical stack below the main path
of the horizontal line. You may choose one of
the items in the stack.
►►
KEYWORD
►◄
optional_choice1
optional_choice2
Default.
Default items appear above the main path of
►►
the horizontal line. The remaining items
(required or optional) appear on (required) or
below (optional) the main path of the
horizontal line. The following example displays
a default with optional items.
default_choice1
KEYWORD
►◄
optional_choice2
optional_choice3
Variable.
Variables appear in lowercase italics. They
represent names or values.
34
►►
z/OS DFSMShsm Managing Your Own Data
KEYWORD variable
►◄
Table 1. Syntax examples (continued)
Item
Syntax example
Repeatable item.
An arrow returning to the left above the main
path of the horizontal line indicates an item
that can be repeated.
►►
KEYWORD ▼ repeatable_item
A character within the arrow means you must
separate repeated items with that character.
An arrow returning to the left above a group
of repeatable items indicates that one of the
items can be selected,or a single item can be
repeated.
►◄
,
►►
KEYWORD ▼ repeatable_item
►◄
►►
KEYWORD
►◄
Fragment.
The fragment symbol indicates that a labelled
group is described below the main syntax
diagram. Syntax is occasionally broken into
fragments if the inclusion of the fragment
would overly complicate the main syntax
diagram.
fragment
fragment:
,required_choice1
,default_choice
,required_choice2
,optional_choice
Using DFSMShsm commands
A command consists of a command name usually followed by one or more
operands or parameters. All operands are referred to as parameters. Parameters
provide the specific information required for the command to perform the
function.
DFSMShsm commands use positional and keyword parameters.
Positional parameters
Positional parameters follow the command name in a prescribed sequence.
You must specify required positional parameters immediately after the command
name to which they apply. When using optional positional parameters, you must
specify them immediately after any required positional parameters or after the
command name if no required positional parameter exists. When a positional
parameter is a list of items, you must enclose the list within parentheses. However,
if you specify only one item, you have the option of using parentheses.
Keyword parameters
Keyword parameters are specific words or symbols that have meaning to
DFSMShsm. They follow positional parameters and can occur in any order. The
command explanations used in this publication show the keyword parameters in
UPPERCASE BOLDFACE characters.
You can specify values or variables with some keyword parameters by placing
them after the keyword parameter and enclosing them in parentheses. A typical
keyword with a value appears in this publication as:
VOLUME(volser)
Chapter 9. Understanding syntax diagrams and using DFSMShsm commands
35
Note: Sometimes keywords can conflict. If you enter conflicting keywords, the last
keyword entered overrides the previous ones unless otherwise noted in the
explanations of the specific parameters. This publication identifies conflicting
keywords with a vertical bar (|) separating them.
Abbreviating commands and parameters
The TSO abbreviation convention applies for all DFSMShsm user commands and
parameters. In other words, when you want to abbreviate the DFSMShsm
commands and parameters, you must specify enough of the leading characters so
that the abbreviation is distinguishable from all the other commands and
parameters.
In addition, some DFSMShsm keyword parameters allow unique abbreviations.
This publication lists all unique abbreviations of a parameter under the heading
“Abbreviations.”
Delimiters
When you issue a DFSMShsm command, you must separate the command name
from the first parameter by one or more blanks. You must separate parameters by
one or more blanks or a comma. Do not use a semicolon (;) as a delimiter because
DFSMShsm ignores any characters that follow a semicolon.
Line continuations
When you enter a DFSMShsm user command from a TSO terminal, you do not
need to enter line continuation characters for commands that are too long for one
line. You can allow the line to wrap around to the next line. If you were entering
the same command from the batch reader, you would indicate continuation of the
command to the next card image by using a plus or minus sign as the last
character of the current card. However, when you use a plus sign, leading
delimiters, such as spaces, are removed from the continuation card image. All
command examples in this publication show commands entered from a TSO
terminal.
Comments
You can add comments to any DFSMShsm user command anywhere that a blank
might appear. To distinguish your comments, enter them between the comment
delimiters, which are /* and */. You can continue a comment to the next line by
using a line-continuation character (+ or -) at the end of the line.
The following is an example of a DFSMShsm command with a comment:
HLIST /*this simple command lists all of my migrated data sets*/
Notational conventions
The following list of symbols and type styles defines the format of DFSMShsm
commands. Do not use the symbols in the actual command statements:
v A vertical bar (|) separates alternative choices. Unless otherwise stated, you can
select only one item. If you enter more than one item, the last choice entered
overrides the previous ones. Do not use the vertical bar when you submit the
command.
36
z/OS DFSMShsm Managing Your Own Data
v An ellipsis (...) specifies that you can enter multiple entries of the type
immediately preceding the ellipsis. For example, dsname ... means that you can
enter one or more data set names. Do not use the ellipsis when you submit the
command.
v Parentheses, commas, slashes, spaces, and other punctuation specify characters
that you must enter exactly as shown.
v Italic type specifies fields that you must supply.
v Numeric parameters appear in three possible forms: decimal (EBCDIC),
hexadecimal (X'n'), or binary (B'n'), unless specifically restricted in the parameter
explanation.
Specifying data set names
When you specify a data set name with a DFSMShsm user command, the data set
name must conform to TSO data set naming conventions. The qualified name
consists of the following fields:
v Your user prefix (required; defaults to user ID; can be redefined by using the
TSO PROFILE command)
v A user-supplied name (required)
v A descriptive qualifier (optional)
The following example shows all three fields:
USER.PART.DATA
where:
v USER is the user prefix
v PART is the user-supplied name
v DATA is the descriptive qualifier
You may specify a fully qualified name (a name with all three qualifiers) by
enclosing it in apostrophes, for example:
’USER.PART.DATA’
The system does not append the user prefix and descriptive qualifiers to data set
names that are enclosed in apostrophes. If you use a fully qualified name without
enclosing it in apostrophes, the system appends the user prefix, for example:
USER.PART.DATA
becomes:
USER.USER.PART.DATA
For the HBACKDS, HDELETE, HMIGRATE, HRECALL, and HRECOVER
commands, you can specify a partly qualified data set name using a filter, which
can contain certain symbols (“wild cards”), interpreted as follows:
%
one and only one character in a qualifier
%%...
up to eight percent signs can be specified in each qualifier
*
one or more characters in one qualifier
**
zero or more qualifiers (the double asterisk cannot precede or follow any
characters; it must be preceded and followed by either a period or a blank)
Chapter 9. Understanding syntax diagrams and using DFSMShsm commands
37
Given such a filter, DFSMShsm uses catalog services to locate all non-VSAM data
sets, generation data sets, and VSAM clusters with names that match the pattern
specified in the filter. From these data sets, DFSMShsm performs the desired
function on those that meet any other qualifications in the command, such as
CHANGEDONLY for HBACKDS.
For example, if you specify HBACKDS ‘HLQ.MLQ.DATA%’, DFSMShsm will back
up data set HLQ.MLQ.DATA1 but not VSAM cluster HLQ.MLQ.DATA25.
If you specify HDELETE HLQ.MLQ.*.DATA, DFSMShsm will delete migrated data
sets USERID.HLQ.MLQ.A.DATA and USERID.HLQ.MLQ.XYZ.DATA, but not
USERID.HLQ.MLQ.ABC.
If you specify HRECALL ‘HLQ.MLQ.**’, DFSMShsm will recall migrated data sets
HLQ.MLQ.DATA4 and HLQ.MLQ.Z.LIST, but not USERID.HLQ.MLQ.DATA.
If you specify HMIGRATE **.DATA, DFSMShsm will migrate data sets
USERID.HLQ.DATA and USERID.DATA, but not USERID.HLQ.LIST.
Note:
1. If you specify a list of data sets in the command, any of the data set names in
the list can be filters.
2. Any fully qualified data set name in the list can be an alias for a true data set
name. However, the HRECOVER command fails if a user substitutes an alias
for the data set name of an ICF catalog, even if the user is
DFSMShsm-authorized.
3. If a filter within apostrophes has a wild card as the first character, DFSMShsm
asks to search all the user catalogs in the system. This search has a negative
effect on system performance.
Specifying data set passwords
When using password-protected data sets, you must specify the password as part
of the data set name. You separate the password from the data set name by
entering a slash (/), which must immediately follow the data set name and
immediately precede the password. Passwords are not supported for SMS data sets
or for DFSMShsm user macros.
Example of a DFSMShsm user command
In this example, the parameters associated with the HRECALL command specify
the name of the data set that you want to recall:
HRECALL ’LHE2104.TEST.CASES.TEXT’
where:
v HRECALL is the command name.
v LHE2104.TEST.CASES.TEXT is the name of the data set that you want to recall.
38
z/OS DFSMShsm Managing Your Own Data
Chapter 10. Interacting with DFSMShsm
This topic describes how you can interact with DFSMShsm by using the TSO
HELP command, the TSO attention key, or by submitting commands in batch
mode. Some incompatibilities with utilities are also discussed.
TSO HELP command
The TSO HELP command gives you online information about the use, function,
syntax, and parameters of DFSMShsm user commands. For example, as a TSO or
TSO/E user, you can issue the following command to obtain information about the
HMIGRATE command:
===> HELP HMIGRATE
TSO Attention key
If you are in a wait state because of DFSMShsm, your terminal is locked while
DFSMShsm performs a requested task. You can press the TSO Attention key, which
is usually the PA1 key, to receive the following message:
ARC1023A
CONVERTING TO A NON-WAIT WILL FAIL THE USER REQUEST,
BUT WILL ALLOW THE {RECALL | RECOVER | MIGRATE | BACKUP |
DELETE | HSENDCMD} TO COMPLETE IN THE BACKGROUND.
CONVERT Y OR N?
If you enter Y, you are released from the wait state. If you enter N, you remain in
the wait state.
Using the TSO Attention key does not cancel the DFSMShsm command that you
have already issued. If you press the TSO attention key to interrupt a RECALL, the
RECALL is still performed. If you press the TSO Attention key to interrupt an
HLIST command, you receive the information up to the point that you interrupted
the command.
Note: If you are in full screen mode when the TSO Attention key is pressed (for
example, ISPF browse), the screen that is displayed after the attention interrupt
does not show the correct information. Press the Refresh key, which is usually the
PA2 key, to get the correct information displayed on your screen.
Incompatibilities caused by DFSMShsm
Although installation of DFSMShsm should not affect your data sets, DFSMShsm
can cause incompatibilities if you use the following utilities and commands:
v IEHMOVE utility
v TSO DELETE command and IDCAMS DELETE command
v TSO ALTER command and IDCAMS ALTER command
v TSO Attention key
© Copyright IBM Corp. 1984, 2017
39
IEHMOVE utility
An incompatibility can exist between DFSMShsm and the IEHMOVE utility if
DFSMShsm has migrated the data set being cataloged, uncataloged, scratched, or
renamed. The incompatibility affects only non-SMS-managed data sets.
If the IEHMOVE utility assumes that the data set being copied or moved is
cataloged, the volume serial number returned by the catalog locate request for the
data set must be associated with a volume allocated to the job step, or the
IEHMOVE utility cannot complete the request. The IEHMOVE utility assumes that
the data set is cataloged if the FROM=device=list parameter has not been specified.
Also, in this case, the located volume serial number is MIGRAT, so you would
have to use the HRECALL command to recall the migrated data set or to
automatically recall the data set by allocating it in a previous step before running
the IEHMOVE utility.
IDCAMS considerations
IDCAMS commands allow either the INFILE or FILE keywords to refer to DD
statements. The DD statements specify a data set name or volume serial, or both,
to be used for processing the commands.
If a DD statement referred to by either the INFILE or FILE keywords specifies both
a data set name and a non-SMS-managed volume and the data set has been
migrated by DFSMShsm, the IDCAMS command request may not be performed
successfully. If an error occurs in this condition, one of the following actions
should be taken prior to reissuing the IDCAMS command:
1. Specify the DD statement without specifying the volume serial and unit names.
This causes the data set to be allocated when the job step is initiated, and the
migrated data set will be recalled for the allocation request.
In some cases, such as specification of the AMP = (AMORG) for VSAM data
sets, the volume serial number must be specified on the DD statement. In such
cases, the second action should be taken, rather than the first.
2. Recall the migrated data set by doing one of the following:
v Issue a DFSMShsm recall command (RECALL or HRECALL).
v Cause the data set to be recalled by referring to the data set in a prior step (a
step different from the one where the IDCAMS command is being requested)
without specifying a volume serial number.
Submitting commands in batch mode
You can submit DFSMShsm commands for processing in batch mode by using JCL.
Because you are processing in batch mode, DFSMShsm cannot issue a message to
your terminal but notes any exception in its log.
If you are logged onto TSO when you submit a batch job, ALL ERROR messages
are sent to your terminal. If you are not logged onto TSO, the DFSMShsm
messages are lost.
If RACF is installed and you are processing RACF-protected data sets, you must
supply the USER= and PASSWORD= parameters on the job statement.
Example JCL for submitting an DFSMShsm command
The following is an example of JCL for submitting DFSMShsm commands in batch
mode. In this example, we want to recall four data sets from a migration volume
by using the HRECALL command:
40
z/OS DFSMShsm Managing Your Own Data
//RECALJOB
//STEP1
//SYSPRINT
//SYSTSPRT
//SYSTSIN
HRECALL
HRECALL
HRECALL
HRECALL
/*
JOB . . .
EXEC PGM=IKJEFT01,REGION=512K
DD SYSOUT=A
DD SYSOUT=A
DD *
CRPA.DATA1
CRPA.DATA2
CRPA.DATA3
CRPA.DATA4
Chapter 10. Interacting with DFSMShsm
41
42
z/OS DFSMShsm Managing Your Own Data
Chapter 11. Introduction to DFSMShsm user tasks
This topic tells you what tasks you can perform on your data sets using
DFSMShsm user commands.
Note: If your installation is using RACF FACILITY class, you can issue one or
more of the DFSMShsm user commands that are described in this publication only
if your installation's Security Administrator has given authority for your user ID to
issue the command.
What tasks can I perform using DFSMShsm user commands?
As a TSO or TSO/E terminal user, you can use DFSMShsm user commands to
perform the following space management and data availability management tasks
on your data sets:
User Command
User Task
HALTERDS
Changes the backup frequency and number of backup versions kept
for one or more data sets. Cannot be used on SMS-managed data
sets, which are controlled by the data sets management class
parameters. If used on SMS-managed data sets, the command fails
and an error message is issued.
HBACKDS
Creates a backup version of one or more data sets.
HBDELETE
Deletes specific backup versions of one or more data sets.
HCANCEL
Cancels one or more existing queued DFSMShsm command requests.
HDELETE
Deletes one or more migrated data sets.
HLIST
Lists information from the migration and backup control data sets.
HMIGRATE
Migrates one or more data sets.
HQUERY
Lists outstanding DFSMShsm requests associated with your user
identification.
HRECALL
Recalls one or more migrated data sets.
HRECOVER
Recovers a backup version of one or more data sets.
How do I perform the task?
To perform a task with a DFSMShsm user command, you need to:
v Identify the DFSMShsm user command
v Identify the name of your data set
v Identify the parameters (positional and keyword) of the DFSMShsm user
command
As a general rule, when you enter most of the DFSMShsm user commands, you
first type the command name, follow it with the name of your data set, and finally
include the necessary parameters. For example:
commandname datasetname parameters
or
HRECALL a.b.x
© Copyright IBM Corp. 1984, 2017
43
For detailed information on the correct syntax of the DFSMShsm user commands,
see Chapter 9, “Understanding syntax diagrams and using DFSMShsm
commands,” on page 33.
44
z/OS DFSMShsm Managing Your Own Data
Part 2. DFSMShsm user tasks
This topic describes the tasks you can perform on your data sets using DFSMShsm
user commands, and explains how to perform those commands.
© Copyright IBM Corp. 1984, 2017
45
46
z/OS DFSMShsm Managing Your Own Data
Chapter 12. HALTERDS: Changing data set parameters
This topic describes how to change the data set parameters that affect backup of
non-SMS-managed data sets using ISMF or TSO.
Using ISMF
The following steps present an example of how to use the HALTERDS line
operator to change parameters for a data set that is not SMS-managed. In our
example, we have used USER20.ISMF.JCL as a sample data set name.
1. Generate a list of data sets as described in Chapter 4, “Methods of performing
tasks,” on page 13.
2. Enter the HALTERDS line operator in the line operator column next to
USER20.ISMF.JCL as described in Figure 9. The HALTERDS Entry panel
appears.
Panel List Dataset Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET LIST
Entries 1-1 of 1
Enter Line Operators below:
Data Columns 3-6 of 39
LINE
OPERATOR
---(1)----
HALTERDS
----------
ALLOC
DATA SET NAME
SPACE
------------(2)------------ --(3)-USER20.CLIST.CLIST
46
USER20.DFP220.DGTTLIB
46
USER20.ISMF.DGTLLIB
46
USER20.ISMF.DGTPLIB
46
USER20.ISMF.DUMP
4684
USER20.ISMF.JCL
468
USER20.ISPFILE
46
USER20.ISPPROF
93
USER20.SPFLOG1.LIST
2623
USER20.TEMP.DATASET
4684
------ ----------- BOTTOM OF DATA
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
F3=End
F4=Return
F12=Cursor
ALLOC % NOT COMPRESSED
USED
USED FORMAT
--(4)-- -(5)- ---(6)---46
0 ???
46
0 ???
46
0 ???
46
0 ???
4356
7 ???
46
90 ???
46
0 ???
93
0 ???
1311
50 ???
93
98 ???
----------- ------ ----
F7=Up
Scroll ===> HALF
F8=Down
F9=Swap
Figure 9. Data Set List Panel with HALTERDS Selected
3. Complete the HALTERDS Entry panel as described in Figure 10 on page 48 for
a non-SMS-managed data set.
© Copyright IBM Corp. 1984, 2017
47
HALTERDS
Panel Utilities Help
-----------------------------------------------------------------------------HALTERDS ENTRY PANEL
Specify the following to Change Backup Attributes
of Data Set: USER20.ISMF.JCL
SMS Managed Data Set: NO
Select frequency of creating Backup Versions
2 1. Specific number of days
2. System default frequency
Number of days
. .
(0 to 999)
Select number of Backup Versions to maintain
2 1. Specific number of versions
2. System default number
Number of Backup Versions . .
Data Set Password . . .
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
(0 to 100)
(if password protected)
F3=End
F4=Return
F12=Cursor
F7=Up
F8=Down
F9=Swap
Figure 10. HALTERDS Entry Panel
The maximum number of backup versions is limited to 29 versions or 100
versions based on the BCDS record length. The following values are the valid
maximum allowable number of backup versions for different BCDS record
lengths:
v Record length of 2040 to 6543 — 29 versions maximum
v Record length of 6544 or more — 100 versions maximum
Your computing center can tell you the maximum number of backup versions
you can specify for your installation.
4. If the HALTERDS command is used on SMS-managed data sets, the command
fails and an error message is issued (see Figure 11).
Panel Utilities Help
-----------------------------------------------------------------------------HALTERDS ENTRY PANEL
Invalid HALTERDS request
Specify the following to Change Backup Attributes
of Data Set: USER20.ISMF.JCL
SMS Managed Data Set: YES
Select frequency of creating Backup Versions
2 1. Specific number of days
2. System default frequency
Number of days
. .
(0 to 999)
Select number of Backup Versions to maintain
2 1. Specific number of versions
2. System default number
Number of Backup Versions . .
Data Set Password . . .
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
(0 to 100)
(if password protected)
F3=End
F4=Return
F12=Cursor
F7=Up
Figure 11. HALTERDS Entry Panel with Error Message
48
z/OS DFSMShsm Managing Your Own Data
F8=Down
F9=Swap
HALTERDS
5. Press ENTER to alter the data set parameters and redisplay the list (see
Figure 12).
The asterisk next to the HALTERDS in the line operator column indicates that the
alter was successful.
Panel List Dataset Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET LIST
Entries 1-1 of 1
Enter Line Operators below:
Data Columns 3-6 of 39
LINE
OPERATOR
---(1)----
*HALTERDS
----------
ALLOC
DATA SET NAME
SPACE
------------(2)------------ --(3)-USER20.CLIST.CLIST
46
USER20.DFP220.DGTTLIB
46
USER20.ISMF.DGTLLIB
46
USER20.ISMF.DGTPLIB
46
USER20.ISMF.DUMP
4684
USER20.ISMF.JCL
468
USER20.ISPFILE
46
USER20.ISPPROF
93
USER20.SPFLOG1.LIST
2623
USER20.TEMP.DATASET
4684
------ ----------- BOTTOM OF DATA
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
F3=End
F4=Return
F12=Cursor
ALLOC % NOT COMPRESSED
USED
USED FORMAT
--(4)-- -(5)- ---(6)---46
0 ???
46
0 ???
46
0 ???
46
0 ???
4356
7 ???
46
90 ???
46
0 ???
93
0 ???
1311
50 ???
93
98 ???
----------- ------ ---Scroll ===> HALF
F8=Down
F9=Swap
F7=Up
Figure 12. Data Set List Panel After Function Completes
For more information on using DFSMShsm/ISMF line operators, see z/OS DFSMS
Using the Interactive Storage Management Facility or use the online help provided
with ISMF.
Using TSO
Task: Alter the parameters that control the number of backup versions kept and
how frequently they are eligible for creation. This command cannot be used on
SMS-managed data sets, which are controlled by the data sets management class
parameters. If the HALTERDS command is used on SMS-managed data sets, the
command fails and an error message is issued (see Figure 11 on page 48).
To make a change, you specify VERSIONS or SYSVERSIONS, FREQUENCY or
SYSFREQUENCY, or one from each pair of parameters. If you do not specify at
least one with the HALTERDS command, nothing is altered.
RACF authority: To alter the parameters that affect the backup of a
RACF-protected data set, you must have RACF ALTER authority to the data set.
Abbreviation: The minimum abbreviation for the HALTERDS command is HAL.
Syntax
The following diagram presents the syntax of the HALTERDS command. This
command only applies to non-SMS data sets.
,
(1)
►► HALTERDS
(;
▼ dsname
);
►
/password
Chapter 12. HALTERDS: Changing data set parameters
49
HALTERDS
►
►◄
FREQUENCY (;
SYSFREQUENCY
days );
VERSIONS (; limit );
SYSVERSIONS
Notes:
1
Parentheses around data set names are required only when multiple data set
names are specified.
Required parameters
dsname: Specifying the name of the data set being altered
Explanation: (dsname/password ...) is a required positional parameter specifying
the name of the data set or list of names of data sets for which backup attributes
are being changed.
For password, substitute the correct password and include the preceding slash (/).
TSO does not prompt you for the password.
v For password-protected non-VSAM data sets, you must supply the password
that allows you to write to the data set.
v For password-protected VSAM data sets, you must supply the master password
of the base cluster.
Abbreviations: None.
Defaults: None.
Restrictions: Because dsname is a required positional parameter, you must specify
it immediately after HALTERDS.
You cannot use any wild card (%, *, or **) in a data set name.
DFSMShsm does not process individual partitioned data set members. If you
specify a partitioned data set with a member name, DFSMShsm ignores the
member name and alters the backup parameters for the entire data set.
Optional parameters
FREQUENCY and SYSFREQUENCY: Specifying the frequency for
creation of backup versions for changed data sets
Explanation: FREQUENCY(days) | SYSFREQUENCY are mutually exclusive,
optional parameters used to specify the minimum number of days between
consecutive backup versions of changed data sets during incremental backup. If
you have changed a data set since DFSMShsm created the latest backup version
and the specified number of days has elapsed, DFSMShsm creates a new backup
version of the data set during automatic backup. If the specified number of days
has elapsed but you have not changed the data set, DFSMShsm does not create a
new backup version of the data set during automatic backup.
FREQUENCY specifies the minimum number of days that must elapse between
two consecutive backup versions of the data set during incremental backup. For
days, substitute a decimal number from 0 through 999. For example, if you specify
50
z/OS DFSMShsm Managing Your Own Data
HALTERDS
days as 5, DFSMShsm backs up the data set providing you changed the data set
since the last backup and the last backup version is at least five days old. If you
specify 0, DFSMShsm creates a backup version for a changed data set every day in
the backup cycle during automatic backup.
SYSFREQUENCY specifies that you want DFSMShsm to back up the specified data
set at the same frequency that the system programmer specified. Use this
parameter only if you issued a previous HALTERDS command to change the
frequency of backup versions from the frequency specified by the general
DFSMShsm parameter value.
Abbreviations: The TSO abbreviation convention applies for FREQUENCY and
SYSFREQUENCY. There are no additional abbreviations.
Defaults: None.
Restrictions: You can specify FREQUENCY or SYSFREQUENCY, but not both.
VERSIONS and SYSVERSIONS: Specifying the number of backup
versions to maintain
Explanation: VERSIONS(limit) | SYSVERSIONS are mutually exclusive,
optional parameters you can use to specify the maximum number of backup
versions that DFSMShsm is to maintain for the data set.
VERSIONS specifies the number of backup versions that you want DFSMShsm to
maintain for the data set. The maximum number of backup versions is limited to
29 versions or 100 versions based on the BCDS record length.
The following values are the valid maximum allowable number of backup versions
for different BCDS record lengths:
v Record length of 2040 to 6543 — 29 versions maximum
v Record length of 6544 or more — 100 versions maximum
Your computing center can tell you the maximum number of backup versions you
can specify for your installation.
For limit, substitute a decimal number from 0 through 100. If you specify 0,
DFSMShsm does not maintain any backup versions for the data set. If you reduce
the number of backup versions, DFSMShsm does not delete any existing backup
versions when it processes the HALTERDS command. DFSMShsm deletes existing
excess backup versions for a specified reduced limit at the time the data set is
backed up or when an EXPIREBV command is performed.
SYSVERSIONS specifies that you want DFSMShsm to maintain the same number
of backup versions for the data set that the system programmer specified or
defaulted to. Use this parameter only if you issued a previous HALTERDS
command to change the number of backup versions from the number specified by
the system programmer.
Abbreviations: The TSO abbreviation convention applies for VERSIONS and
SYSVERSIONS. There are no additional abbreviations.
Defaults: The maximum number of backup versions you can have is 29 versions
or 100 versions depending on the BCDS record length.
Chapter 12. HALTERDS: Changing data set parameters
51
HALTERDS
Restrictions: You can specify VERSIONS or SYSVERSIONS, but not both.
Examples of different ways to code the HALTERDS command
The examples below present different ways to code the HALTERDS command. The
values are examples only. Do not interpret them as values that you should use for
your system.
Altering data set parameters for maximum backup versions and
minimum frequency when using a BCDS record length of 6544 or
more
In this example, you are issuing the HALTERDS command to change the number
of backup versions for the data set CRPA.PARTSTST.CNTL to the maximum
allowable number of versions (100) for a BCDS record length of 6544 or more, and
the number of days between backup versions to the minimum number of days (0).
You are changing the frequency of creation of backup versions of the data set so
that DFSMShsm creates a backup version every day during automatic backup,
provided you changed the data set.
HALTERDS ’CRPA.PARTSTST.CNTL’ VERSIONS(100) FREQUENCY(0)
Altering data set parameters for maximum backup versions and
minimum frequency when using a BCDS record length of 2040
In this example, you are issuing the HALTERDS command to change the number
of backup versions for the data set CRPA.PARTSTST.CNTL to the maximum
allowable number of versions (29) for a BCDS record length of 2040, and the
number of days between backup versions to the minimum number of days (0). You
are changing the frequency of creation of backup versions of the data set so that
DFSMShsm creates a backup version every day during automatic backup, provided
you changed the data set.
HALTERDS ’CRPA.PARTSTST.CNTL’ VERSIONS(29) FREQUENCY(0)
Altering data set parameters for installation-specified versions
and maximum frequency
In this example, you are issuing the HALTERDS command to change the number
of backup versions of the data set CRPA.COMTEST.CLIST from the number of
versions that was previously specified to the number of versions specified by the
system programmer. You are changing the maximum frequency of creation of
backup versions of the data set so that DFSMShsm creates a backup version every
four days during automatic backup, provided you changed the data set.
HALTERDS ’CRPA.COMTEST.CLIST’ SYSVERSIONS FREQUENCY(4)
Altering data set parameters for specified versions and
frequencies
In this example, you are issuing the HALTERDS command to change the number
of backup versions and the frequency of creation of backup versions of the data set
SMITH.VERSION1.TEXT.
HALTERDS ’SMITH.VERSION1.TEXT’ VERSIONS(7) FREQUENCY(10)
52
z/OS DFSMShsm Managing Your Own Data
HALTERDS
Altering parameters for a list of data sets for installationspecified versions and frequency
In this example, you are issuing the HALTERDS command to change the number
of backup versions for three data sets CRPA.PARTSTST.CNTRL,
CRPA.COMMTEST.CLIST, and CRPA.OUTTESTS.TESTLIST to the number of
backup versions and the frequency of creation specified by the system
programmer.
HALTERDS (’CRPA.PARTSTST.CNTL’,’CRPA.COMMTEST.CLIST’, ’CRPA.OUTTESTS.TESTLIST’) SYSVERSIONS SYSFREQUENCY
Chapter 12. HALTERDS: Changing data set parameters
53
HALTERDS
54
z/OS DFSMShsm Managing Your Own Data
Chapter 13. HBACKDS: Backing up data sets
This topic describes how to back up data sets using ISMF, TSO, or inline backup.
This command applies to both SMS-managed and non-SMS-managed data sets and
is intended to supplement the automatic functions of DFSMShsm.
Using ISMF
The following steps present an example of how to use the HBACKDS line operator
to back up data sets. In our example, we have used USER20.ISMF.JCL as a sample
data set name.
1. Generate a data set list as explained in Chapter 4, “Methods of performing
tasks,” on page 13.
2. Enter the HBACKDS line operator in the line operator column next to
USER20.ISMF.JCL as shown in Figure 13.
Panel List Dataset Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET LIST
Entries 1-1 of 1
Enter Line Operators below:
Data Columns 3-6 of 39
LINE
OPERATOR
---(1)----
HBACKDS
----------
ALLOC
DATA SET NAME
SPACE
------------(2)------------ --(3)-USER20.CLIST.CLIST
46
USER20.DFP220.DGTTLIB
46
USER20.ISMF.DGTLLIB
46
USER20.ISMF.DGTPLIB
46
USER20.ISMF.DUMP
4684
USER20.ISMF.JCL
468
USER20.ISPFILE
46
USER20.ISPPROF
93
USER20.SPFLOG1.LIST
2623
USER20.TEMP.DATASET
4684
------ ----------- BOTTOM OF DATA
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
F3=End
F4=Return
F12=Cursor
ALLOC % NOT COMPRESSED
USED
USED FORMAT
--(4)-- -(5)- ---(6)---46
0 ???
46
0 ???
46
0 ???
46
0 ???
4356
7 ???
46
90 ???
46
0 ???
93
0 ???
1311
50 ???
93
98 ???
----------- ------ ----
F7=Up
Scroll ===> HALF
F8=Down
F9=Swap
Figure 13. Data Set List Panel with HBACKDS Selected
The HBACKDS entry panel appears.
3. Complete the HBACKDS entry panel as shown in Figure 14 on page 56. You
may choose to use a TARGET option or leave the field blank. Likewise, you
may choose to use a concurrent copy option or leave the field blank. Specify Y
in the Wait for Completion field if you want to wait for HBACKDS to complete
before you return to ISMF.
© Copyright IBM Corp. 1984, 2017
55
HBACKDS
Panel Utilities Help
-----------------------------------------------------------------------------HBACKDS ENTRY PANEL
Command ===>
Optionally Specify one or more for
Data Set:
Target . . . . . . . . . . . . .
(D=DASD, T=TAPE or blank)
Concurrent copy . . . . . . . .
For P, R, VP, VR, CP or CR,
enter CC option
(P, R, S, VP, VR, CP, CR or blank)
Wait for Completion . . . . . . N
(Y or N)
Data Set Password . . . . . . .
(if password protected)
Retain Days . . . . . . . . . .
(0 to 50000, or 99999 or blank)
(P=PHYSICAL, L=LOGICAL or blank)
Note: Dataset Password ignored when in ADMIN mode.
Use ENTER to Perform Hbackds;
Use HELP Command for Help; Use END Command to Exit.
Figure 14. HBACKDS Entry Panel
4. Press ENTER to perform the backup and redisplay the list (see Figure 15).
The asterisk next to the HBACKDS in the line operator column indicates that the
backup was successful if you specified wait for completion=Y, or that the backup
task was successfully issued to DFSMShsm if you specified wait for completion=N.
Panel List Dataset Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET LIST
Entries 1-1 of 1
Enter Line Operators below:
Data Columns 3-6 of 39
LINE
OPERATOR
---(1)----
*HBACKDS
----------
ALLOC
DATA SET NAME
SPACE
------------(2)------------ --(3)-USER20.CLIST.CLIST
46
USER20.DFP220.DGTTLIB
46
USER20.ISMF.DGTLLIB
46
USER20.ISMF.DGTPLIB
46
USER20.ISMF.DUMP
4684
USER20.ISMF.JCL
468
USER20.ISPFILE
46
USER20.ISPPROF
93
USER20.SPFLOG1.LIST
2623
USER20.TEMP.DATASET
4684
------ ----------- BOTTOM OF DATA
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
F3=End
F4=Return
F12=Cursor
ALLOC % NOT COMPRESSED
USED
USED FORMAT
--(4)-- -(5)- ---(6)---46
0 ???
46
0 ???
46
0 ???
46
0 ???
4356
7 ???
46
90 ???
46
0 ???
93
0 ???
1311
50 ???
93
98 ???
----------- ------ ----
F7=Up
Scroll ===> HALF
F8=Down
F9=Swap
Figure 15. Data Set List Panel after Function Completes
Using TSO commands
The commands for backing up SMS-managed and non-SMS-managed data sets are
different. When you are backing up SMS-managed data sets, the SMS management
class attributes that are used in your computing center direct whether DFSMShsm
creates your backup version. With the TARGET keyword, you can direct the
56
z/OS DFSMShsm Managing Your Own Data
HBACKDS
backup to a specific device when you are backing up either SMS or non-SMS data
sets. The CC keyword also works for both SMS and non-SMS data sets.
All allocations to a data set are freed before requesting service from DFSMShsm
when HBACKDS is issued from your TSO address space. This includes REXX
programs that invoke the HBACKDS command.
Backing up a data set
Task: Create a backup version for a specific data set, a list of data sets, or a filter
specification. You can back up a data set to either DASD or tape.
Only eligible data sets are backed up. Whether an SMS-managed data set is eligible
to be backed up by command is determined by SMS management class attributes.
For a non-SMS-managed data set, eligibility for backup is determined by the
VERSIONS parameter of the HALTERDS command.
If the data set to be backed up is currently allocated, DFSMShsm attempts to
deallocate it. DFSMShsm does not try to reallocate the data set at the end of
HBACKDS processing.
Note: When you back up a data set to DASD, it must fit on a migration level 1
volume. If it does not, the command fails.
RACF authority: To back up a RACF-protected data set, you must have RACF
UPDATE authority to the data set.
Abbreviation: The minimum abbreviation for the HBACKDS command is HBACK.
Syntax
The following diagram presents the syntax of the HBACKDS command for
SMS-managed data sets:
,
(1)
►► HBACKDS
( ▼ dsname
)
►
WAIT
NOWAIT
EXTENDRC
CHANGEDONLY
►
►
NEWNAME(newdsname)
DATE(yyyy/mm/dd)
TIME(hhmmss)
►
►
SPHERE (
YES
NO
)
GENVSAMCOMPNAMES
GVCN
(
YES
NO
)
Chapter 13. HBACKDS: Backing up data sets
57
HBACKDS
►
►
TARGET
(
DASD
TAPE
)
►
►
CC
STANDARD
PHYSICALEND
PREFERRED
ANYPREFERRED
CACHEPREFERRED
CPREF
VIRTUALPREFERRED
VPREF
REQUIRED
ANYREQUIRED
CACHEREQUIRED
CREQ
VIRTUALREQUIRED
VREQ
LOGICALEND
LE
PHYSICALEND
PE
(
)
►
►◄
RETAINDAYS
RD
( days )
Notes:
1
Parentheses around data set names are required only when multiple data set
names are specified.
The following diagram presents the syntax of the HBACKDS command for
non-SMS-managed data sets:
,
(1)
►► HBACKDS
( ▼ dsname
)
►
/password
►
►
NEWNAME(newdsname)
DATE(yyyy/mm/dd)
TIME(hhmmss)
►
►
SPHERE (
58
YES
NO
z/OS DFSMShsm Managing Your Own Data
)
GENVSAMCOMPNAMES
GVCN
(
YES
NO
)
HBACKDS
►
►
UNIT
( unittype
)
VOLUME
( volser
)
WAIT
NOWAIT
►
►
EXTENDRC
CHANGEDONLY
TARGET
(
DASD
TAPE
)
►
►
CC
STANDARD
PHYSICALEND
PREFERRED
ANYPREFERRED
CACHEPREFERRED
CPREF
VIRTUALPREFERRED
VPREF
REQUIRED
ANYREQUIRED
CACHEREQUIRED
CREQ
VIRTUALREQUIRED
VREQ
LOGICALEND
LE
PHYSICALEND
PE
(
)
►
►◄
RETAINDAYS
RD
( days )
Notes:
1
Parentheses around data set names are required only when multiple data set
names are specified.
Chapter 13. HBACKDS: Backing up data sets
59
HBACKDS
Required parameters
dsname: Specifying the name of one or more data sets to be
copied for backup
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: (dsname) or (dsname/password ...) is a required positional parameter
that specifies the name of the data set or list of data set names that you want to
back up. Passwords are not supported for SMS-managed data sets.
For dsname, substitute the name of the data set or list of data set names you want
to back up. You can use a data set filter for any dsname in a list. For a discussion
of how to specify data set names, see “Specifying data set names” on page 37.
For non-SMS data sets, specifying a filter requests only cataloged, not uncataloged,
data sets. If you want to back up an uncataloged data set, you must specify its
data set name explicitly.
For password, substitute the correct password and include the preceding slash (/).
TSO does not prompt you for the password.
v For password-protected non-VSAM data sets, you must supply the password
that allows you to write to the data set.
v For password-protected VSAM data sets, you must supply the master password
of the base cluster.
Abbreviations: None.
Defaults: None.
Restrictions:
v Because dsname is a required positional parameter, you must specify it
immediately after HBACKDS.
v The volume on which the data set resides must be mounted before you issue the
command.
v DFSMShsm does not process individual partitioned data set members. If you
specify a partitioned data set name with a member name, message ARC1065I is
issued and nothing is backed up.
v If dsname is fully qualified and refers to a VSAM data set, specify the base
cluster name. The entire VSAM data set will be backed up.
v When you specify a password with a filter, all the password-protected data sets
affected must have the same password. Otherwise, DFSMShsm authorization
checking fails the backup of those password-protected data sets that are
protected by some other password.
Optional parameters
CHANGEDONLY: Specifying whether to back up only changed
data sets
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: CHANGEDONLY is an optional parameter that specifies whether
DFSMShsm backs up only those data sets specified (explicitly or by a filter) that
have their change bits on in their data set VTOC entries.
60
z/OS DFSMShsm Managing Your Own Data
HBACKDS
Abbreviations: The TSO abbreviation convention applies for CHANGEDONLY.
There are no additional abbreviations.
Defaults: DFSMShsm backs up all the data sets specified, regardless of the state
of the change bits.
Note: The HBACKDS command will not back up a migrated data set if
CHANGEDONLY is specified.
DATE: Specifying the address of a field containing the date
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: DATE is an optional parameter that can be specified with
NEWNAME. For yyyy/mm/dd, substitute the date to assign to the backup version. If
DATE is specified without the NEWNAME parameter, the HBACKDS command
will fail.
Abbreviations: None.
Defaults: None.
Restrictions: None.
EXTENDRC: Requesting an extended set of return and reason
codes
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: EXTENDRC is an optional parameter that specifies that DFSMShsm
return an extended set of return and reason codes while you are running
DFSMShsm commands in a truly interactive mode (TSO or foreground). This
option returns only the return and reason codes that are mapped into DFSMShsm
messages that are issued to the users terminal. For detailed information on return
codes that DFSMShsm returns for this command, see “Return codes from the
extended set” on page 190.
Abbreviations: The TSO abbreviation convention applies for EXTENDRC.
Defaults: None.
Restrictions: The WAIT option must be specified with the EXTENDRC parameter
when you are running DFSMShsm commands in a truly interactive mode (TSO or
foreground).
GENVSAMCOMPNAMES: Overriding SETSYS
DSBACKUP(GENVSAMCOMPNAMES)
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: The GENVSAMCOMPNAMES specified setting overrides the
SETSYS DSBACKUP(GENVSAMCOMPNAMES) setting. If GVCN=YES is
specified, and newdsname represents a VSAM base cluster that is either migrated or
uncataloged, DFSMShsm will process the request, and default names will be
assigned to the VSAM data and index components (.data and .index). If
GVCN=NO is specified, and newdsname represents a VSAM base cluster that is
either migrated or uncataloged, the HBACKDS command will fail, as DFSMShsm
is unable to assign the proper names to the data and index components. If the
newdsname is uncataloged or has been migrated outside of DFSMShsm, and the
data set to be backed up is VSAM and has an associated AIX/PATH, the
Chapter 13. HBACKDS: Backing up data sets
61
HBACKDS
SPHERE(NO) keyword must be specified on the command. If GVCN is specified
and the data set to back up is non-VSAM or is VSAM and is cataloged and not
migrated, the GVCN keyword will be ignored.
Abbreviations: GVCN
Defaults: None.
Restrictions: None.
NEWNAME: Specifying a backup version of a specified data set
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: NEWNAME is an optional parameter that specifies the data set
name to assign to the new backup version that is created by specifying the
BACKDS command. The NEWNAME parameter must be fully-qualified and in the
standard data set name format.
Abbreviations: None
Defaults: None.
Restrictions: None.
RETAINDAYS: Specifying a number of days to retain a backup
copy
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: RETAINDAYS is an optional parameter specifying a number of
days to retain a specific backup copy of a data set. If you specify RETAINDAYS,
number of retain days is a required parameter that specifies a minimum number of
days (0–50000) that DFSMShsm retains the backup copy. If you specify 99999, the
data set backup version never expires. Any value given on the command line
greater than 50000 (and other than 99999) causes a failure with an ARC1605I error
message. When a value is specified via the ARCBDEXT, any value greater than
50000 is changed to 50000. A decimal value of 99999 indicates that the backup copy
should never expire. Any value less than 0 is changed to 0. A retain days value of
0 indicates that:
v the backup version might expire within the same day that it was created if
EXPIREBV processing takes place,
v the backup version is kept as an active copy before roll-off occurs,
v The backup version is not managed as a retained copy.
SPHERE: Specifying whether components of a VSAM data set
will be backed up with the base cluster
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: SPHERE is an optional parameter that can be specified with
NEWNAME. If YES is specified a backup of the entire VSAM SPHERE will be
performed. If NO is specified, a backup of the base cluster will be performed, and
any associated AIXs and/or PATHs will not be backed up. If SPHERE is specified
without a parameter, or if SPHERE is not specified at all, DFSMShsm will attempt
to back up the entire SPHERE. If SPHERE is specified without NEWNAME, the
HBACKDS command will fail. The default is YES.
Abbreviations: None.
62
z/OS DFSMShsm Managing Your Own Data
HBACKDS
Defaults: SPHERE(YES)
Restrictions: In order to backup the entire sphere, the following restrictions apply:
v No more than one PATH can be defined for the data set to back up, and no
more than one PATH can be defined for the NEWNAME data set.
v No more than one AIX can exist for the data set to back up, and no more than
one AIX can exist for the NEWNAME data set.
If multiple AIXs and/or PATHs exist for one or both of the data sets, specify
SPHERE(NO) to back up the base cluster.
TIME: Specifying the address of a field containing the time
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: TIME is an optional parameter that can be specified with
NEWNAME and DATE keywords. For hhmmss, substitute the time to assign to the
backup version. Specify '00' for ss if the seconds are unknown. If TIME is specified
without DATE, the HBACKDS command will fail. If DATE is specified and TIME
is not specified, DFSMShsm will set a time of 120000 (12 noon).
Abbreviations: None.
Defaults: 120000
Restrictions: None.
UNIT: Specifying the type of device
This parameter applies only to non-SMS-managed data sets.
Explanation: UNIT(unittype) is an optional parameter that specifies the type of
unit on which the volume can be allocated for an uncataloged data set. For
unittype, substitute the type of unit. The valid types of units are 3380, 3390, and
9345.
Abbreviations: The TSO abbreviation convention applies for UNIT. There are no
additional abbreviations.
Defaults: None.
Restrictions: You must specify the UNIT parameter with the VOLUME parameter
if any data set to be backed up is uncataloged. Do not specify the UNIT parameter
if the data set to be backed up is a cataloged data set. If you specify the UNIT
parameter, you must also specify the VOLUME parameter.
NEWNAME cannot be specified with UNIT and VOLUME.
VOLUME: Specifying the volume where the data set resides
This parameter applies only to non-SMS-managed data sets.
Explanation: VOLUME(volser) is an optional parameter used to specify the
volume where the uncataloged data set to be backed up resides. For volser,
substitute the serial number of the volume where the uncataloged data set to be
backed up resides.
Abbreviations: The TSO abbreviation convention applies for VOLUME. There are
no additional abbreviations.
Chapter 13. HBACKDS: Backing up data sets
63
HBACKDS
Defaults: None.
Restrictions: You must specify the VOLUME parameter if any data set to be
backed up is uncataloged. Do not specify the VOLUME parameter if the data set to
be backed up is a cataloged data set. If you specify VOLUME, you must also
specify UNIT and unittype.
WAIT and NOWAIT: Specifying whether to wait for the HBACKDS
command to be completed
These parameters apply to both SMS-managed and non-SMS-managed data sets.
Explanation: WAIT | NOWAIT are mutually exclusive, optional parameters used
to specify whether you want to wait for the HBACKDS command to complete.
WAIT specifies that you want to wait for the HBACKDS command to complete.
When DFSMShsm successfully completes the HBACKDS process, the ARC1000I
message is issued. If the HBACKDS process does not complete successfully, the
ARC1001I message is issued. If you press the TSO Attention key before DFSMShsm
completes the command, DFSMShsm issues the ARC1800I message and does not
issue the ARC1000I message.
NOWAIT specifies that you do not want to wait for the HBACKDS command to
complete. When DFSMShsm successfully receives the request, the ARC1007I
message is issued. After DFSMShsm successfully completes the HBACKDS
command, the ARC1000I message is issued. If the HBACKDS command does not
complete successfully, the ARC1001I message is issued.
Abbreviations: The TSO abbreviation convention applies for WAIT and NOWAIT.
There are no additional abbreviations.
Defaults: The default is NOWAIT.
Restrictions: You can specify WAIT or NOWAIT, but not both.
TARGET: Specifying the media target of the backup data set
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: TARGET is an optional parameter that specifies that you want
backup data sets targeted to either DASD or a backup tape.
DASD indicates that you want the data set initially backed up to ML1 DASD.
TAPE indicates that you want the data set backed up to tape.
Abbreviations: The TSO abbreviation convention applies for TARGET. There is no
additional abbreviation.
Defaults: None. If you do not specify the TARGET keyword, DFSMShsm selects
the output target device type.
Restrictions: You can specify either DASD or TAPE, but not both.
CC: Tailoring concurrent copy backups for SMS and non-SMS
data sets
This parameter applies to both SMS-managed and non-SMS-managed data sets.
64
z/OS DFSMShsm Managing Your Own Data
HBACKDS
Explanation: CC is an optional parameter with which you can tailor concurrent
copy backups. The parameters of CC are:
STANDARD
indicates that you want to use standard backup methods without using
concurrent copy.
REQUIRED
ANYREQUIRED
indicates that you want to use concurrent copy as the backup method. Virtual
concurrent copy is attempted first, if the storage subsystem on which the data
set resides is capable of virtual concurrent copy and working-space data sets
have been defined. Otherwise, cache-based concurrent copy is attempted if the
storage subsystem is capable of it. If both types of concurrent copy are not
possible or fail, the data set backup will fail.
PREFERRED
ANYPREFERRED
indicates that you want to use concurrent copy as the preferred backup
method. Virtual concurrent copy is attempted first, if the storage subsystem on
which the data set resides is capable of virtual concurrent copy and
working-space data sets have been defined. Otherwise, cache-based concurrent
copy is attempted if the storage subsystem is capable of it. If both types of
concurrent copy are not possible or fail, the data set backup continues as if the
CC parameter was not specified. PREFERRED is the default if CONCURRENT
is specified without a parameter.
CACHEPREFERRED
CPREF
indicates that you want to use cache-based concurrent copy as the preferred
backup method. If cache-based concurrent copy is not available, the data set
backup continues as if the CC keyword was not specified.
VIRTUALPREFERRED
VPREF
indicates that you want to use virtual concurrent copy as the preferred backup
method. If virtual concurrent copy is not available the data set backup
continues as if the CC keyword was not specified.
CACHEREQUIRED
CREQ
indicates that you want to use cache-based concurrent copy as the backup
method. The data set backup will fail if cache-based concurrent copy is not
available.
VIRTUALREQUIRED
VREQ
indicates that you want to use virtual concurrent copy as the backup method.
The data set backup will fail if virtual concurrent copy is not available.
PHYSICALEND
PE indicates that you want control returned to the application only after the
backup has physically completed.
LOGICALEND
LE indicates that you want control returned to the application when the
concurrent copy initialization has completed.
Chapter 13. HBACKDS: Backing up data sets
65
HBACKDS
Abbreviations: The TSO abbreviation convention applies for the CC
subparameters CACHEPREFERRED, VIRTUALPREFERRED, CACHEREQUIRED,
VIRTUALREQUIRED, LOGICALEND and PHYSICALEND. There are no
additional abbreviations.
Defaults: If you do not specify any subparameters with the CC parameter, the
defaults are STANDARD and PHYSICALEND.
Restrictions: By default, all users can use the CC options. However, if RACF
indicates a lack of authority, DFSMShsm fails the data set backup request if
concurrent copy is a requirement. If concurrent copy is not required and RACF
indicates a lack of authority, DFSMShsm backs up the data set as if the concurrent
copy keyword were not specified on the backup command.
You cannot use the CC option with the EXTENDRC parameter. EXTENDRC is an
optional parameter that directs DFSMShsm to return an extended set of return and
reason codes. These codes may not be completed until after physical completion of
the backup. The HBACKDS command fails if you use both the CC and
EXTENDRC keywords together.
If you use the CC option with LE or PE, you must also specify the option
WAIT=YES.
The CC keyword applies to all data sets that result from filter resolution.
Examples of different ways to code the HBACKDS command
The following examples present different ways to code the HBACKDS command.
The values are examples only. Do not interpret them as values that you should use
for your system.
Backing up a data set and not waiting for completion
In this example, you are issuing the HBACKDS command to create a backup
version of the cataloged data set PAC1234.LEVELMST.OUTLIST. The NOWAIT
parameter indicates that you do not want to wait for the HBACKDS command to
complete.
HBACKDS ’PAC1234.LEVELMST.OUTLIST’ NOWAIT
Backing Up a Password-Protected Cataloged Data Set and
Waiting for Completion
In this example, you are issuing the HBACKDS command to create a backup
version for the uncataloged data set WIDRR.MSTLEVEL.LINKLIST protected with
the password WRITE. A 3380 is the type of unit that volume GRAVU1 can reside
on. The WAIT parameter indicates that you want to wait for the HBACKDS
command to complete.
HBACKDS ’WIDRR.MSTLEVEL.LINKLIST’/WRITE VOLUME(GRAVU1) UNIT(3380) WAIT
Backing Up Data Sets with the Same User Prefix Using an
Asterisk in the Data Set Name and Not Waiting for Completion
In this example, you are issuing the HBACKDS command to create backup
versions for all cataloged data sets that have the same user prefix and descriptive
qualifier. The NOWAIT parameter indicates that you do not want to wait for the
HBACKDS to complete.
66
z/OS DFSMShsm Managing Your Own Data
HBACKDS
HBACKDS ’RRDIW.*.TEXT’ NOWAIT
Backing Up a Data Set and Requesting the Extended Return and
Reason Codes
In this example, you are issuing the HBACKDS command from a TSO session to
create a backup version of the cataloged data set RPA5678.LEVELMST.OUTLIST.
The WAIT EXTENDRC parameter indicates that you want to see the extended
return and reason codes.
HBACKDS ’RPA5678.LEVELMST.OUTLIST’ WAIT EXTENDRC
Backing up a data set that is targeted to DASD and waiting for
completion
In this example, you are issuing the HBACKDS command to create a backup
version of the cataloged data set PAC5678.LEVELMST.OUTLIST. The WAIT
parameter indicates that you want to wait for the HBACKDS process to complete
before you receive notice of the completion. The TARGET(DASD) parameter
indicates that you want to direct the backup data set to DASD, rather than to tape.
HBACKDS ’PAC5678.LEVELMST.OUTLIST’ WAIT TARGET(DASD)
Backing up a data set that is targeted to tape and that uses
concurrent copy as the preferred backup method
In this example, you are issuing the HBACKDS command to create a backup
version of the cataloged data set PAC1234.LEVELMST.OUTLIST. The
TARGET(TAPE) parameter indicates that you want to direct the backup data set to
tape, rather than to DASD. The CC(PREFERRED) parameter indicates that you
want concurrent copy to be the backup method, if it is available. If concurrent
copy is not available, the data set will be backed up as if this keyword were not
specified. Because the default is PHYSICALEND, control returns to the application
when the data set has completed the backup operation.
HBACKDS ’PAC1234.LEVELMST.OUTLIST’ TARGET(TAPE) CC(PREFERRED)
Backing up a data set with a specified retention period
In this example, you are backing up data sets with a specified retention period by
specifying the RETAINDAYS keyword on the HBACKDS command. RETAINDAYS
controls the minimum number of days that a backup copy of a data set is
maintained. DFSMShsm uses the RETAINDAYS value to determine when a backup
version expires.
HBACKDS (dsname1, dsname2, dsname3,..... dsnamen) RETAINDAYS(days)
Using inline backup
The inline backup function allows you to request a backup of a data set in a batch
environment. Inline backup is a way of overcoming the problems of invoking the
terminal monitor program (TMP) in the background in order to issue HBACKDS
commands.
When you are invoking TMP, the HBACKDS command requires that you specify
the fully qualified data set names or a filter name. In the case of a generation data
Chapter 13. HBACKDS: Backing up data sets
67
HBACKDS
group (GDG), you may not know this fully qualified data set name, and TMP does
not allow you to specify a relative generation number. Also, in executing a batch
job with TMP, if a data set is created (DISP=NEW), an exclusive enqueue is done
on the data set name, and the enqueue is not released until the last job step
referring to that data set has ended. If a job step backward references a newly
created data set after the TMP job step is processed, the HBACKDS command fails.
Inline backup also allows you to back up data sets in the middle of a job. You can
add a new step to a job by specifying the inline backup module as the program to
start. You specify in specially named DD statements the data sets that are being
backed up. Inline backup extracts the data set names associated with these
DDNAMEs and then performs the backup.
The results of each data set backup attempt can be written to a specially named
output data set. SNAP dumps of storage relating to inline backup can be written to
a specially named output data set for certain error conditions.
Uncataloged data sets are not supported for inline backup.
Invoking inline backup
To invoke inline backup, perform the following tasks:
1. Include a step at the correct place in the job to execute a program called
ARCINBAK. The PARM parameter allows you to specify the options TARGET
and CC, from which you can target data set backups and concurrent copy
support, respectively. These TARGET and CC parameter values apply to all
backups in this job step.
2. For each data set to be backed up, specify the name of the data set to be
processed by including a valid DD statement with a DDNAME of BACKxxxx
(where xxxx is 1–4 characters).
Note:
a. Only cataloged data sets and SMS-managed open VSAM data sets are
supported for inline backup. If volume and unit information is specified on
the DD statement, an uncataloged data set is assumed, and the data set is
not processed.
b. ARCINBAK does not support data sets allocated with any of the following
three dynamic allocation options: XTIOT, UCB NOCAPTURE, and DSAB
above the line, except when the calling program supplies an open DCB.
Any form of the data set name is acceptable to ARCINBAK. Specification of a
relative generation number for a GDG or a reference to a DDNAME in a
previous step is acceptable. You can also specify a VSAM cluster, or data or
index components, or both.
3. A DD statement with a DDNAME of ARCPRINT can be optionally included in
the ARCINBAK program job step. This DD statement defines a SYSOUT data
set to contain messages about data sets for which a backup has been attempted.
The possible messages are as follows:
BACKUP
DDNAME
BACKUP
BACKUP
FOR (DSNAME)
(DDNAME) NOT
FOR (DSNAME)
FOR (DSNAME)
SUCCESSFUL
BACKED UP, UNABLE TO GET ASSOCIATED JFCB
FAILED, DATA SET NOT CATALOGED
FAILED, RC = (RETURN CODE), REAS = (REASON CODE)
At the completion of the ARCINBAK module job step, you will receive a return
code as shown in Table 2 on page 69
68
z/OS DFSMShsm Managing Your Own Data
HBACKDS
Table 2. ARCINBAK Return Codes
CC=
Explanation
CC=0
All backups were successful.
CC=4
No DDNAMEs prefixed with BACK were found or the JFCB associated with
a DDNAME could not be found.
CC=8
Backup of an uncataloged data set was attempted. Uncataloged data sets are
not supported by inline backup.
CC=12
Backup of a data set failed. If the return code equals:
RC=0100
DFSMShsm is not active; request rejected.
RC=0001-0099
For message return codes and reason codes, see message ARCnnnnI
using the REAS field, where nnnn is the return code.
For RC=0004, see message ARC13nnI, where nn is the reason code.
CC=16
Parameter error.
CC=806
Link error.
4. You can specify the RETAINDAYS keyword with the ARCINBAK program.
RETAINDAYS specifies a number of days to retain a specific backup copy of a
data set. A single RETAINDAYS value applies to all of the data sets that are
backed up under this job step. RETAINDAYS specifies a minimum number of
days (0–50000) that DFSMShsm retains the backup copy. If you specify 99999,
the data set backup version never expires. Any value greater than 50000 (and
other than 99999) causes failure. A retain days value of 0 indicates, that:
v The backup version might expire within the same day that it was created if
EXPIREBV processing takes place,
v The backup version is kept as an active copy before roll-off occurs,
v The backup version is not managed as a retained copy.
5. A DD statement with a DDNAME of ARCSNAP can be included in the
ARCINBAK program job step. This DD statement defines a SYSOUT data set
for the output from a SNAP macro. The following storage areas are dumped to
the SNAPDCB data set when the inline backup fails for any reason:
v MWE storage can be dumped when an error occurs in issuing the service
call.
v A complete image of the task storage can be dumped when no DDNAMEs or
data sets are processed.
Figure 16 on page 70 shows a job stream example of data sets that can or cannot be
backed up by ARCINBAK in a batch environment. In this example, each data set
backup is targeted to tape, and each data set will be backed up using the specified
concurrent copy and RETAINDAYS options. For a description of the TARGET
options, see “TARGET: Specifying the media target of the backup data set” on page
64. For a description of the CC options, see “CC: Tailoring concurrent copy
backups for SMS and non-SMS data sets” on page 64.
Chapter 13. HBACKDS: Backing up data sets
69
HBACKDS
//JOBNAME JOB . . . ,USER=USERID,PASSWORD=USERPSWD
//STEP1
EXEC PGM=USERPGM
//SYSPRINT DD SYSOUT=A
//DSET1
DD DSN=USERID.N03.GDG(-1),DISP=OLD
//DSET2
DD DSN=USERID.N03.PSFB,DISP=OLD
//DSET3
DD DSN=USERID.N04.PSFB,DISP=OLD
//DSET4
DD DSN=USERID.N03.KSDS,DISP=OLD
/*
//STEP2
EXEC PGM=ARCINBAK,PARM=(’RETAINDAYS(00365),
//
TARGET(TAPE),CC=(PREFERRED,PHYSICALEND)’)
//ARCPRINT DD SYSOUT=A
//ARCSNAP DD SYSOUT=A
//* ---------------------------------------------------------------//*
BACKUP OF GDG DATA SET SHOULD BE SUCCESSFUL.
//* ---------------------------------------------------------------//BACK01
DD DSN=*.STEP1.DSET1,DISP=SHR
//* ---------------------------------------------------------------//*
BACKUP OF NON-VSAM DATA SET SHOULD BE SUCCESSFUL.
//* ---------------------------------------------------------------//BACK02
DD DSN=*.STEP1.DSET2,DISP=SHR
//* ---------------------------------------------------------------//*
BACKUP OF VSAM DATA SET SHOULD BE SUCCESSFUL.
//* ---------------------------------------------------------------//BACK03
DD DSN=*.STEP1.DSET4,DISP=SHR
//* ---------------------------------------------------------------//*
BACKUP OF GDG DATA SET SHOULD BE SUCCESSFUL.
//* ---------------------------------------------------------------//BACK04
DD DSN=USERID.N01.GDG.G0001V00,DISP=SHR
//* ---------------------------------------------------------------//*
BACKUP OF NON-VSAM DATA SET SHOULD BE SUCCESSFUL.
//* ---------------------------------------------------------------//BACK05
DD DSN=USERID.N01.PSFB,DISP=SHR
//* ---------------------------------------------------------------//*
BACKUP OF UNCATALOGED DATA SET SHOULD FAIL.
//* ---------------------------------------------------------------//BACK06
DD DSN=USERID.N02.UNCAT,VOL=SER=VOL003,UNIT=3390,DISP=SHR
//* ---------------------------------------------------------------//*
BACKUP OF VSAM DATA SET SHOULD BE SUCCESSFUL.
//* ---------------------------------------------------------------//BACK07
DD DSN=USERID.N01.KSDS,DISP=SHR
//* ---------------------------------------------------------------//*
BACKUP OF OPEN IN-USE VSAM DATA SET SHOULD FAIL.
//* ---------------------------------------------------------------//BACK08
DD DSN=USERID.N02.KSDS,DISP=SHR
//* ---------------------------------------------------------------//*
BACKUP OF RACF PROTECTED NON-VSAM DATA SET
//*
BY AN UNAUTHORIZED USER SHOULD FAIL.
//* ---------------------------------------------------------------//BACK09
DD DSN=USERXX.N02.PSFB,DISP=SHR
//* ---------------------------------------------------------------//*
DDNAME PREFIX OTHER THAN BACK IS NOT PROCESSED.
//* ---------------------------------------------------------------//BAK01
DD DSN=*.STEP1.DSET3,DISP=SHR
//* ---------------------------------------------------------------//*
DDNAME PREFIX OTHER THAN BACK IS NOT PROCESSED
//* ---------------------------------------------------------------//BAK02
DD DSN=USERID.N02.PSFB,DISP=SHR
/*
Figure 16. Example of Inline Backup Job Stream
The return code from processing the inline backup job stream example of the
ARCINBAK program is 12, and the resulting messages for each DDNAME prefixed
with BACK are described in Figure 17 on page 71.
70
z/OS DFSMShsm Managing Your Own Data
BACKUP
BACKUP
BACKUP
BACKUP
BACKUP
BACKUP
BACKUP
BACKUP
BACKUP
FOR
FOR
FOR
FOR
FOR
FOR
FOR
FOR
FOR
USERID.N03.GDG.G0001V00
USERID.N03.PSFB
USERID.N03.KSDS
USERID.N01.GDG.G0001V00
USERID.N01.PSFB
USERID.N02.UNCAT
USERID.N01.KSDS
USERID.N02.KSDS
USERXX.N02.PSFB
SUCCESSFUL
SUCCESSFUL
SUCCESSFUL
SUCCESSFUL
SUCCESSFUL
FAILED, DATA SET NOT CATALOGED
SUCCESSFUL
FAILED, RC = 056, REAS = 016
FAILED, RC = 039, REAS = 008
Figure 17. Example of Messages Resulting from Inline Backup Job Stream
Chapter 13. HBACKDS: Backing up data sets
71
72
z/OS DFSMShsm Managing Your Own Data
Chapter 14. HBDELETE: Deleting backup versions
This topic describes how to delete backup versions of data sets using ISMF or TSO.
This command applies to both SMS-managed and non-SMS-managed data sets and
is intended to supplement the automatic functions of DFSMShsm.
Using ISMF
The following steps present an example of how to use the HBDELETE line
operator to delete backup versions of a data set. In our example, we have used
USER20.SAMPLE.DATASET as a sample data set name.
1. Generate a list of data sets as explained in Chapter 4, “Methods of performing
tasks,” on page 13.
2. Enter the HBDELETE line operator in the line operator column next to
USER20.SAMPLE.DATASET as described in Figure 18.
Panel List Dataset Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET LIST
Entries 1-1 of 1
Enter Line Operators below:
Data Columns 3-6 of 39
LINE
OPERATOR
---(1)----
HBDELETE
----------
ALLOC
DATA SET NAME
SPACE
------------(2)------------ --(3)-USER20.CLIST.CLIST
46
USER20.DFP220.DGTTLIB
46
USER20.ISMF.DGTLLIB
46
USER20.ISMF.DGTPLIB
46
USER20.ISMF.DUMP
4684
USER20.ISPFILE
46
USER20.ISPPROF
93
USER20.SAMPLE.DATASET
468
USER20.SPFLOG1.LIST
2623
USER20.TEMP.DATASET
4684
------ ----------- BOTTOM OF DATA
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
F3=End
F4=Return
F12=Cursor
ALLOC % NOT COMPRESSED
USED
USED FORMAT
--(4)-- -(5)- ---(6)---46
0 ???
46
0 ???
46
0 ???
46
0 ???
4356
7 ???
46
0 ???
93
0 ???
46
90 ???
1311
50 ???
93
98 ???
----------- ------ ----
F7=Up
Scroll ===> HALF
F8=Down
F9=Swap
Figure 18. Data Set List Panel with HBDELETE Selected
The HBDELETE Entry panel appears.
3. Complete the HBDELETE Entry panel as described in “HBDELETE Entry
Panel” on page 74. Up to five panels can be displayed. In each panel, the
backup version, date, and time of the backup are displayed as two lists with
headers. If Y is entered for the DELETE ALL VERSIONS field, only one
HBDELETE Entry panel is displayed.
Note: Retained backup versions are not displayed on these panels. Entering Y
for the DELETE ALL VERSIONS field will delete all active and retained backup
copies. To delete an individual retained backup copy, use the DFSMShsm
HLIST DSNAME(dsname) BCDS command to obtain a complete list of the
active and retained backup copies of this data set. Then issue the HBDELETE
command with the DATE and TIME keywords.
© Copyright IBM Corp. 1984, 2017
73
HBDELETE
HBDELETE Entry Panel
Panel Utilities Scroll Help
-----------------------------------------------------------------------------HBDELETE ENTRY PANEL
Page 1 of 5
Specify Y to Delete all or individual Backup Versions for
Data Set: USER20.SAMPLE.DATASET
Delete All Versions . . N (Y or N)
Data Set Password . . .
(if password protected)
Version Date
Time
Delete(Y/N) | Version Date
Time
Delete(Y/N)
-------------------------------------|--------------------------------------100
94100 00:58
N
|
099
94099 12:36
N
098
94098 00:58
N
|
097
94097 12:36
N
096
94096 00:58
N
|
095
94095 12:36
N
094
94094 00:58
N
|
093
94093 12:36
N
092
94092 00:58
N
|
091
94091 12:36
N
090
94090 00:58
N
|
089
94089 12:36
N
088
94088 00:58
N
|
087
94087 12:36
N
086
94086 00:58
N
|
085
94085 12:36
N
084
94084 00:58
N
|
083
94083 12:36
N
Command ===>
F1=Help
F2=Split
F10=Left
F11=Right
F3=End
F4=Return
F12=Cursor
F7=Up
F8=Down
F9=Swap
Panel Utilities Scroll Help
-----------------------------------------------------------------------------HBDELETE ENTRY PANEL
Page 2 of 5
Specify Y to Delete individual Backup Versions for
Data Set: USER20.SAMPLE.DATASET
Version Date
Time
Delete(Y/N) | Version Date
Time
Delete(Y/N)
-------------------------------------|--------------------------------------082
94082 00:58
N
|
081
94081 12:36
N
080
94080 00:58
N
|
079
94079 12:36
N
078
94078 00:58
N
|
077
94077 12:36
N
076
94076 00:58
N
|
075
94075 12:36
N
074
94074 00:58
N
|
073
94073 12:36
N
072
94072 00:58
N
|
071
94071 12:36
N
070
94070 00:58
N
|
069
94069 12:36
N
068
94068 00:58
N
|
067
94067 12:36
N
066
94066 00:58
N
|
065
94065 12:36
N
064
94064 00:58
N
|
063
94063 12:36
N
062
94062 00:58
N
|
061
94061 12:36
N
Command ===>
F1=Help
F2=Split
F10=Left
F11=Right
74
z/OS DFSMShsm Managing Your Own Data
F3=End
F4=Return
F12=Cursor
F7=Up
F8=Down
F9=Swap
HBDELETE
Panel Utilities Scroll Help
-----------------------------------------------------------------------------HBDELETE ENTRY PANEL
Page 3 of 5
Specify Y to Delete individual Backup Versions for
Data Set: USER20.SAMPLE.DATASET
Version Date
Time
Delete(Y/N) | Version Date
Time
Delete(Y/N)
-------------------------------------|--------------------------------------060
94060 00:58
N
|
059
94059 12:36
N
058
94058 00:58
N
|
057
94057 12:36
N
056
94056 00:58
N
|
055
94055 12:36
N
054
94054 00:58
N
|
053
94053 12:36
N
052
94052 00:58
N
|
051
94051 12:36
N
050
94050 00:58
N
|
049
94049 12:36
N
048
94048 00:58
N
|
047
94047 12:36
N
046
94046 00:58
N
|
045
94045 12:36
N
044
94044 00:58
N
|
043
94043 12:36
N
042
94042 00:58
N
|
041
94041 12:36
N
Command ===>
F1=Help
F2=Split
F10=Left
F11=Right
F3=End
F4=Return
F12=Cursor
F7=Up
F8=Down
F9=Swap
Panel Utilities Scroll Help
-----------------------------------------------------------------------------HBDELETE ENTRY PANEL
Page 4 of 5
Specify Y to Delete individual Backup Versions for
Data Set: USER20.SAMPLE.DATASET
Version Date
Time
Delete(Y/N) | Version Date
Time
Delete(Y/N)
-------------------------------------|--------------------------------------040
94040 00:58
N
|
039
94039 12:36
N
038
94038 00:58
N
|
037
94037 12:36
N
036
94036 00:58
N
|
035
94035 12:36
N
034
94034 00:58
N
|
033
94033 12:36
N
032
94032 00:58
N
|
031
94031 12:36
N
030
94030 00:58
N
|
029
94029 12:36
N
028
94028 00:58
N
|
027
94027 12:36
N
026
94026 00:58
N
|
025
94025 12:36
N
024
94024 00:58
N
|
023
94023 12:36
N
022
94022 00:58
N
|
021
94021 12:36
N
Command ===>
F1=Help
F2=Split
F10=Left
F11=Right
F3=End
F4=Return
F12=Cursor
F7=Up
F8=Down
F9=Swap
Chapter 14. HBDELETE: Deleting backup versions
75
HBDELETE
Panel Utilities Scroll Help
-----------------------------------------------------------------------------HBDELETE ENTRY PANEL
Page 5 of 5
Specify Y to Delete individual Backup Versions for
Data Set: USER20.SAMPLE.DATASET
Version Date
Time
Delete(Y/N) | Version Date
Time
Delete(Y/N)
-------------------------------------|--------------------------------------020
94020 00:58
N
|
019
94019 12:36
N
018
94018 00:58
N
|
017
94017 12:36
N
016
94016 00:58
N
|
015
94015 12:36
N
014
94014 00:58
N
|
013
94013 12:36
N
012
94012 00:58
N
|
011
94011 12:36
N
010
94010 00:58
N
|
009
94009 12:36
N
008
94008 00:58
N
|
007
94007 12:36
N
006
94006 00:58
N
|
005
94005 12:36
N
004
94004 00:58
N
|
003
94003 12:36
N
002
94002 00:58
N
|
001
94001 12:36
N
Command ===>
F1=Help
F2=Split
F10=Left
F11=Right
F3=End
F4=Return
F12=Cursor
F7=Up
F8=Down
F9=Swap
On the DATA SET LIST panel, the asterisk next to the HBDELETE in the line
operator column (Figure 19) indicates that the deletion was successful.
Panel List Dataset Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET LIST
Entries 1-1 of 1
Enter Line Operators below:
Data Columns 3-6 of 39
LINE
OPERATOR
---(1)----
*HBDELETE
----------
ALLOC
DATA SET NAME
SPACE
------------(2)------------ --(3)-USER20.CLIST.CLIST
46
USER20.DFP220.DGTTLIB
46
USER20.ISMF.DGTLLIB
46
USER20.ISMF.DGTPLIB
46
USER20.ISMF.DUMP
4684
USER20.ISPFILE
46
USER20.ISPPROF
93
USER20.SAMPLE.DATASET
468
USER20.SPFLOG1.LIST
2623
USER20.TEMP.DATASET
4684
------ ----------- BOTTOM OF DATA
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
F3=End
F4=Return
F12=Cursor
ALLOC % NOT COMPRESSED
USED
USED FORMAT
--(4)-- -(5)- ---(6)---46
0 ???
46
0 ???
46
0 ???
46
0 ???
4356
7 ???
46
0 ???
93
0 ???
46
90 ???
1311
50 ???
93
98 ???
----------- ------ ----
F7=Up
Scroll ===> HALF
F8=Down
F9=Swap
Figure 19. Data Set List Panel After Function Completes
For more information on using DFSMShsm/ISMF line operators, see z/OS DFSMS
Using the Interactive Storage Management Facility or use the online help provided
with ISMF.
Using TSO
The commands for deleting backup versions of SMS-managed and
non-SMS-managed data sets are different.
76
z/OS DFSMShsm Managing Your Own Data
HBDELETE
With SMS-managed data sets, you only need to specify the backup version you
want to delete. With non-SMS-managed data sets, you can delete the backup
versions DFSMShsm created from uncataloged data sets.
Deleting backup versions of a data set
Task
Delete all backup versions of a specific cataloged or uncataloged data set, specific
backup versions by version number, or delete backup versions that were created
on a specified date and at a specific time. A retired version is a specially marked
backup version that DFSMShsm created before it deleted the original data set
during the data set retirement space management process. The only way you can
delete a retired version is to specify its version number, or the date and time when
the backup version was created.
RACF authority
To delete specific backup versions of a RACF-protected data set, you must have
RACF ALTER authority to the data set from which the backup version was created.
Abbreviations
The minimum abbreviation for the HBDELETE command is HBDEL.
Syntax
The following diagram presents the syntax of the HBDELETE command for
SMS-managed data sets:
,
(1)
►► HBDELETE
( ▼ dsname
)
ALL
DATE(yyyy/mm/dd)
,
VERSIONS
( ▼ bvn
►◄
TIME(hhmmss)
)
Notes:
1
Parentheses around data set names are required only when multiple data set
names are specified.
The following diagram presents the syntax of the HBDELETE command for
non-SMS-managed data sets:
,
(1)
►► HBDELETE
( ▼ dsname
)
►
/password
Chapter 14. HBDELETE: Deleting backup versions
77
HBDELETE
►
FROMVOLUME
(
volser )
ALL
DATE(yyyy/mm/dd) TIME(hhmmss)
,
VERSIONS
( ▼ bvn
►◄
)
Notes:
1
Parentheses around data set names are required only when multiple data set
names are specified.
Required parameters
The follow parameters are required parameters of the HBDELETE command. If
you do not specify any of these parameters, the HBDELETE fails with a parse
error.
ALL: Deleting all backup versions
ALL specifies that all of the backup copies of a data set are to be deleted, including
active and retained copies. You can specify ALL for one or more data sets. If you
specify ALL for multiple data sets, all backup copies for all specified data sets are
deleted. If you specify a partially qualified data set, all data sets that meet the filter
criteria are deleted. ALL is mutually exclusive with DATE TIME and VERSIONS
Abbreviations
None.
Default
None.
SMS relationship
This parameter applies to SMS-managed and non-SMS-managed data sets.
Restrictions
ALL does not delete retired versions.
DATE TIME: Deleting a backup version that was created on a
specific date and time
DATE(yyyy/mm/dd) and TIME(hhmmss) specify that a backup version that was
created on a specified date and at a specified time is to be deleted.
yyyy/mm/dd
The date when the backup version to be deleted was created.
hhmmss
The time when the backup version to be deleted was created.
You can use DATE and TIME to delete both active and retained backup copies that
match the specified criteria. DATE TIME is mutually exclusive with ALL and
VERSIONS.
78
z/OS DFSMShsm Managing Your Own Data
HBDELETE
Abbreviations
None.
Default
None.
SMS relationship
This parameter applies to SMS-managed and non-SMS-managed data sets.
Restrictions
The following restrictions apply to the DATE TIME parameter:
v You must specify DATE and TIME together, otherwise the HBDELETE command
fails.
v If you specify FROMVOLUME with the DATE and TIME keywords, the
command fails. The command also fails if you specify VERSIONS(0).
VERSIONS: Specifying the number of the backup versions to be
deleted
VERSIONS(bvn ...) specifies that DFSMShsm is to delete specific backup versions of
a data set. You can specify multiple backup version numbers. If you specify
multiple data set names and multiple version numbers, DFSMShsm applies each
number you specified with VERSIONS to each data set name you specified with
dsname.
bvn
The one-to-three digit decimal number of a particular backup version that is to
be deleted. You can obtain backup version numbers by issuing an HLIST
command and specifying the data set name and the
BACKUPCONTROLDATASET parameter.
VERSIONS is mutually exclusive with ALL and DATE TIME.
Abbreviations
The TSO abbreviation convention applies for VERSIONS. There are no additional
abbreviations.
Default
None.
SMS relationship
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Restrictions
You cannot delete retained backup copies with the VERSIONS keyword.
Chapter 14. HBDELETE: Deleting backup versions
79
HBDELETE
dsname: Specifying the name of the data set backup versions to
be deleted
(dsname...) or (dsname/password ...) is a required positional parameter you use to
specify the name of the data set or list of data set names whose backup versions
you want to delete.
dsname
The data set name or list of names of the data set whose backup versions are
to be deleted. The data sets can be either cataloged or uncataloged. To delete
all the backup versions of a cataloged data set, you specify only the data set
name.
/password
The password including the preceding slash (/). TSO does not prompt you for
the password.
v For a password-protected non-VSAM data set, you must supply the
password that allows you to write to the data set.
v For a password-protected VSAM data set, you must supply the master
password of the base cluster.
Abbreviations
None.
Default
None.
SMS relationship
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Restrictions
The following restrictions apply to the dsname parameter:
v Because dsname is a required positional parameter, you must specify it
immediately after HBDELETE.
v DFSMShsm does not process individual partitioned data set members. If you
specify a partitioned data set name with a member name, DFSMShsm rejects the
request.
v You cannot use any wild card (%, *, or **) in a data set name.
Optional parameters
The follow parameters are optional parameters of the HBDELETE command.
FROMVOLUME: Specifying the volume on which the data set
resided when the backup versions were created
FROMVOLUME(volser) is an optional parameter that you should include only if
DFSMShsm created the specified backup versions from an uncataloged data set.
FROMVOLUME specifies the volume on which an uncataloged data set or data
sets resided when DFSMShsm created the backup versions. For volser, substitute
the serial number of the volume where the uncataloged data set resided when
DFSMShsm created the backup versions. To delete all the backup versions of an
uncataloged data set, specify the data set name and the serial number of the
volume from which the data set was backed up.
80
z/OS DFSMShsm Managing Your Own Data
HBDELETE
Abbreviations
The TSO abbreviation convention applies for FROMVOLUME. There are no
additional abbreviations.
Default
None.
SMS relationship
This parameter applies only to non-SMS-managed data sets.
Restrictions
The following restrictions apply to the FROMVOLUME parameter:
v The data sets listed should have been either all cataloged or all uncataloged at
the time DFSMShsm created the specified backup versions. If uncataloged, the
data sets should have been on the same volume.
v If you specify FROMVOLUME, DFSMShsm only deletes backup versions of
uncataloged data sets. If you do not specify FROMVOLUME, DFSMShsm only
deletes backup versions of cataloged data sets.
Examples of different ways to code the HBDELETE command
The examples below present different ways to code the HBDELETE command. The
values are examples only. Do not interpret them as values you should use for your
system.
Deleting all backup versions of a cataloged data set
In this example, you are issuing the HBDELETE command to delete all backup
versions of the cataloged data set USER1.CMD.CLIST.
HBDELETE ’USER1.CMD.CLIST’ ALL
Deleting specific backup versions of an uncataloged data set
In this example, you are issuing the HBDELETE command to delete only backup
versions 2, 3, and 10 of the uncataloged data set userid.MATRIX.TEXT. DFSMShsm
had backed up this data set from volume VOL001.
HBDELETE MATRIX.TEXT FROMVOLUME(VOL001) VERSIONS(2,3,10)
Chapter 14. HBDELETE: Deleting backup versions
81
HBDELETE
82
z/OS DFSMShsm Managing Your Own Data
Chapter 15. HCANCEL: Canceling a queued request
To cancel a queued request, use the HCANCEL command in TSO. The following
discussion applies to both SMS-managed data sets and non-SMS-managed data
sets.
Cancel queued requests
Task: Cancel existing queued DFSMShsm requests.
The HCANCEL command is designed for the TSO user who wants to cancel a data
movement request. The command cannot be used on a request that is already
being processed.
To use the HCANCEL command, your user ID must be DFSMShsm-authorized or
be the same as that of the command to be canceled. Identification of the command
to cancel can be specified by the DFSMShsm request number, user ID, or data set
name. A request number implies that only one request be found, but a user ID or
data set name causes all existing nonprocessing requests that have the same user
ID or data set name to be canceled.
You can determine the request numbers that you have active by using the
HQUERY command with the REQUEST parameter. Two commands cannot be
canceled: HCANCEL and HQUERY.
If no parameters are included in this command, no function results.
Abbreviation: The minimum abbreviation for the HCANCEL command is HCAN.
Syntax
The following diagram presents the syntax of the HCANCEL command for both
SMS-managed and non-SMS-managed data sets:
►► HCANCEL
►◄
REQUEST
( num )
REQ
USERID ( userid )
DATASETNAME
( dsn )
DSNAME
Required parameters
None.
© Copyright IBM Corp. 1984, 2017
83
HCANCEL
Optional parameters
REQUEST: Specifying the DFSMShsm request number to be
canceled
Explanation: REQUEST(num) is a optional parameter you use to specify a single
request by a DFSMShsm request number. For num, substitute the number (issued
by DFSMShsm) of the request to be canceled. You can enter a HQUERY REQUEST
command to determine current requests.
Abbreviations: The TSO abbreviation convention applies for REQUEST. In
addition, you can use the abbreviation REQ.
Defaults: None.
Restrictions: Only one parameter can be specified at a time. REQUEST and
USERID or REQUEST and DATASETNAME cannot be specified together.
USERID: Specifying that all requests submitted by a particular
user be canceled
Explanation: USERID(userid) is an optional parameter you use to specify that all
requests submitted by a particular user be canceled. For userid, substitute the users
identification to be canceled.
Abbreviations: The TSO abbreviation convention applies for USERID.
Defaults: None.
Restrictions: Only one parameter can be specified at a time. USERID and
REQUEST or USERID and DATASETNAME cannot be specified together.
An unauthorized user cannot cancel the requests for another users ID.
DATASETNAME: Specifying that all requests submitted to
process a particular data set be canceled
Explanation: DATASETNAME(dsn) is an optional parameter you use to specify
that all requests submitted to process a particular data set be canceled. For dsn,
substitute the name of the data set to be canceled.
Abbreviations: The TSO abbreviation convention applies for DATASETNAME.
DSNAME can also be used.
Defaults: None.
Restrictions: Only one parameter can be specified at a time. DATASETNAME and
REQUEST or DATASETNAME and USERID cannot be specified together.
You cannot use any wild card (%, *, or **) in a data set name.
Examples of different ways to code the HCANCEL command
The examples below present different ways to code the HCANCEL command. The
values are examples only. Do not interpret them as values you should use for your
system.
84
z/OS DFSMShsm Managing Your Own Data
HCANCEL
Canceling a request number
In this example, you are issuing the HCANCEL command to cancel a single
request by its request number, 0068.
HCANCEL REQUEST(0068)
Canceling all requests submitted by a particular user
In this example, you are issuing the HCANCEL command to cancel all requests
submitted by a particular user with a user ID of B123456.
HCANCEL USERID(B123456)
Canceling all requests submitted to process a particular data set
In this example, you are issuing the HCANCEL command to cancel all requests
submitted to process a particular data set named USER.WXYZ2. The data set name
must be fully qualified.
HCANCEL DSNAME(’USER.WXYZ2’)
Chapter 15. HCANCEL: Canceling a queued request
85
HCANCEL
86
z/OS DFSMShsm Managing Your Own Data
Chapter 16. HDELETE: Deleting migrated data sets
This topic describes how to delete migrated data sets using ISMF or TSO. This
command and its parameters apply to both SMS and non-SMS-managed data sets
and is intended to supplement the automatic functions of DFSMShsm.
Using ISMF
The following steps present an example of how to use the HDELETE line operator
to delete a migrated data set. In our example, we have used USER20.ISMF.JCL as a
sample data set name.
1. Generate a list of data sets as described in Chapter 4, “Methods of performing
tasks,” on page 13.
2. Enter the HDELETE line operator in the line operator column next to
USER20.ISMF.JCL as described in Figure 20.
Panel List Dataset Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET LIST
Entries 1-1 of 1
Enter Line Operators below:
Data Columns 3-6 of 39
LINE
OPERATOR
---(1)----
HDELETE
----------
ALLOC
DATA SET NAME
SPACE
------------(2)------------ --(3)-USER20.CLIST.CLIST
46
USER20.DFP220.DGTTLIB
46
USER20.ISMF.DGTLLIB
46
USER20.ISMF.DGTPLIB
46
USER20.ISMF.DUMP
4684
USER20.ISMF.JCL
468
USER20.ISPFILE
46
USER20.ISPPROF
93
USER20.SPFLOG1.LIST
2623
USER20.TEMP.DATASET
4684
------ ----------- BOTTOM OF DATA
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
F3=End
F4=Return
F12=Cursor
ALLOC % NOT COMPRESSED
USED
USED FORMAT
--(4)-- -(5)- ---(6)---46
0 ???
46
0 ???
46
0 ???
46
0 ???
4356
7 ???
46
90 ???
46
0 ???
93
0 ???
1311
50 ???
93
98 ???
----------- ------ ----
F7=Up
Scroll ===> HALF
F8=Down
F9=Swap
Figure 20. Data Set List Panel with HDELETE Selected
The HDELETE Entry panel appears.
3. Complete the HDELETE Entry panel as described in Figure 21 on page 88.
(Specify Y in the wait for completion field if you want to wait for HDELETE to
complete before returning to ISMF.)
© Copyright IBM Corp. 1984, 2017
87
HDELETE
Panel Utilities Help
-----------------------------------------------------------------------------HDELETE ENTRY PANEL
Optionally Specify One or More for
Data Set: USER20.ISMF.JCL
Delete DFSMShsm Backup Versions
Y
(Y or N)
Wait for Completion . . . . . . N
(Y or N)
Purge Unexpired Data Set . . . . N
(Y or N)
Data Set Password
(if password protected)
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
. . . . . . .
F3=End
F4=Return
F12=Cursor
F7=Up
F8=Down
F9=Swap
Figure 21. HDELETE Entry Panel
The Data Set List panel appears as shown in Figure 22. The asterisk next to the
HDELETE in the line operator column indicates that the deletion was successful if
you specified wait for completion=Y, or that the deletion task was successfully
issued to DFSMShsm if you specified wait for completion=N.
Panel List Dataset Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET LIST
Entries 1-1 of 1
Enter Line Operators below:
Data Columns 3-6 of 39
LINE
OPERATOR
---(1)----
*HDELETE
----------
ALLOC
DATA SET NAME
SPACE
------------(2)------------ --(3)-USER20.CLIST.CLIST
46
USER20.DFP220.DGTTLIB
46
USER20.ISMF.DGTLLIB
46
USER20.ISMF.DGTPLIB
46
USER20.ISMF.DUMP
4684
USER20.ISMF.JCL
468
USER20.ISPFILE
46
USER20.ISPPROF
93
USER20.SPFLOG1.LIST
2623
USER20.TEMP.DATASET
4684
------ ----------- BOTTOM OF DATA
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
F3=End
F4=Return
F12=Cursor
ALLOC % NOT COMPRESSED
USED
USED FORMAT
--(4)-- -(5)- ---(6)---46
0 ???
46
0 ???
46
0 ???
46
0 ???
4356
7 ???
46
90 ???
46
0 ???
93
0 ???
1311
50 ???
93
98 ???
----------- ------ ----
F7=Up
Scroll ===> HALF
F8=Down
F9=Swap
Figure 22. Data Set List Panel after Function Completes
For more information on using DFSMShsm/ISMF line operators, see z/OS DFSMS
Using the Interactive Storage Management Facility or use the online help provided
with ISMF.
88
z/OS DFSMShsm Managing Your Own Data
HDELETE
Using TSO
The following discussion applies to both SMS-managed and non-SMS-managed
data sets.
Task: Delete one or more migrated data sets from migration volumes.
DFSMShsm deletes the data set without recalling it to a DFSMShsm-managed
volume. When DFSMShsm deletes the data set, it maintains any backup versions
of the data set and the information in the BCDS. You cannot delete data sets from
DFSMShsm-managed volumes or backup volumes with this command.
This command deletes both the migrated data set and the data set catalog entry.
RACF authority: To delete a RACF-protected data set, you must have RACF
ALTER authority to the data set.
Abbreviation: The minimum abbreviation for the HDELETE command is HDEL.
Syntax
The following diagram presents the syntax of the HDELETE command for both
SMS-managed and non-SMS-managed data sets:
,
(2)
►► HDELETE ( ▼ dsname
)
(1)
►◄
PURGE
/password
WAIT
NOWAIT
EXTENDRC
Notes:
1
Password does not apply to SMS-managed data sets.
2
Parentheses are required only when multiple data set names are specified.
Required parameters
dsname: Specifying the data set to delete
Explanation: (dsname/password ...) is a required positional parameter that specifies
the name of a migrated data set or list of names of migrated data sets that you
want to delete. For dsname, substitute the name of the migrated data set you want
to delete. You can use a data set filter for any dsname in a list. See “Specifying
data set names” on page 37 for a discussion of how to specify data set names. For
VSAM data sets, only the base cluster name can be specified. For non-VSAM data
sets, only the true name can be specified. Other names, such as migration names,
cannot be specified.
For password, substitute the correct password and include the preceding slash (/).
TSO does not prompt you for the password. Password protection does not apply to
SMS-managed data sets; if a password is specified, it is ignored.
v For a password-protected non-VSAM data set, you must supply the password
that allows you to write to the data set.
v For a password-protected VSAM data set, you must supply the master password
of the base cluster.
Abbreviations: None.
Chapter 16. HDELETE: Deleting migrated data sets
89
HDELETE
Defaults: None.
Restrictions: Because dsname is a required positional parameter, you must specify
it immediately after HDELETE.
When you specify a password with a filter, all the password-protected data sets
affected must have the same password. Otherwise, DFSMShsm rejects the
HDELETE command for those password-protected data sets that are protected by
some other password.
DFSMShsm does not process individual partitioned data set members. If you
specify a partitioned data set name with a member name, DFSMShsm rejects the
request.
Optional parameters
PURGE: Specifies deletion of migrated data sets within their
retention periods
Explanation: PURGE is an optional parameter you use if you want to delete a
migrated data set while it is within its retention period.
Abbreviations: The TSO abbreviation convention applies for PURGE. There are
no additional abbreviations.
Defaults: None.
Restrictions: If the data set has a valid date that has not expired, the PURGE
parameter is required.
WAIT and NOWAIT: Specifying whether to wait for the data set to
be deleted
Explanation: WAIT | NOWAIT are mutually exclusive, optional parameters
specifying whether you want to wait for the HDELETE command to complete.
WAIT specifies that you want to wait for the HDELETE command to complete.
When DFSMShsm successfully completes the HDELETE process, an ARC1000I
message is issued. If the HDELETE process does not complete successfully, an
ARC1001I message is issued. If you press the TSO Attention key before DFSMShsm
completes the command, DFSMShsm issues an ARC1800I message and does not
issue an ARC1000I message.
NOWAIT specifies that you do not want to wait for the HDELETE command to
complete. When DFSMShsm successfully receives the request, an ARC1007I
message is issued. After DFSMShsm successfully completes the HDELETE
command, an ARC1000I message is issued. If the HDELETE command does not
complete successfully, an ARC1001I message is issued.
Abbreviations: The TSO abbreviation convention applies for WAIT and NOWAIT.
There are no additional abbreviations.
Defaults: The default is NOWAIT.
Restrictions: You can specify WAIT or NOWAIT, but not both.
90
z/OS DFSMShsm Managing Your Own Data
HDELETE
EXTENDRC: Requesting an extended set of return and reason
codes
Explanation: EXTENDRC is an optional parameter specifying that DFSMShsm
should return an extended set of return and reason codes while you are running
DFSMShsm commands in a truly interactive mode (TSO or foreground). This
option returns only the return and reason codes that are mapped into DFSMShsm
messages that are issued to the users terminal. For detailed information on return
codes that DFSMShsm returns for this command, see Appendix B, “Return codes
from DFSMShsm commands,” on page 189.
Abbreviations: The TSO abbreviation convention applies for EXTENDRC.
Defaults: None.
Restrictions: The WAIT option must be specified with the EXTENDRC parameter
when you are running DFSMShsm commands in a truly interactive mode (TSO or
foreground).
Examples of different ways to code the HDELETE command
The examples below present different ways to code the HDELETE command. The
values are examples only. Do not interpret them as values that you should use for
your system.
Deleting a migrated data set that is still within its retention
period
In this example, you are issuing the command to delete the migrated data set
KTMM.TEXTVER1.TEXT. The PURGE parameter indicates that you want to delete
the data set before the end of its retention period.
HDELETE ’KTMM.TEXTVER1.TEXT’ PURGE
Deleting a migrated data set and waiting for completion
In this example, you are issuing the command to delete the migrated data set
CLCE.TEXTVER1.TEXT. The WAIT parameter indicates that you want to wait for
DFSMShsm to complete the deletion of the data set.
HDELETE ’CLCE.TEXTVER1.TEXT’ WAIT
Deleting a group of migrated data sets and not waiting for
completion
In this example, you are issuing the HDELETE command to delete all migrated
data sets that have the user prefix and the descriptive qualifier of the specified
data set name CCEL.*.LOADLIST. The NOWAIT parameter indicates that you do
not want to wait for DFSMShsm to complete the deletion of the data sets.
HDELETE ’CCEL.*.LOADLIST’ NOWAIT
Deleting a password-protected migrated data set and not waiting
for completion
In this example, you are issuing the HDELETE command to delete the migrated
data set ELCCA.BASICTST.VSBASIC with the password WRITE. You do not want
to wait for DFSMShsm to complete the deletion of the data set.
Chapter 16. HDELETE: Deleting migrated data sets
91
HDELETE
HDELETE ’ELCCA.BASICTST.VSBASIC’/WRITE NOWAIT
Deleting two migrated data sets and not waiting for completion
In this example, you are issuing the HDELETE command to delete two migrated
data sets, ELCCA.VER1TEXT.LIST and CLCE.BASICTST.VSBASIC. You do not
want to wait for DFSMShsm to complete the deletion of the data sets.
HDELETE (’ELCCA.VER1TEXT.LIST’,’CLCE.BASICTST.VSBASIC’) NOWAIT
Deleting a data set and requesting to see the extended return
and reason codes
In this example, you are issuing the HDELETE command from a TSO session to
delete the migrated data set RPM2345.TEXTVER1.TEXT. You want to see the
extended return and reason codes.
HDELETE ’RPM2345.TEXTVER1.TEXT’ WAIT EXTENDRC
92
z/OS DFSMShsm Managing Your Own Data
Chapter 17. HLIST: Listing information from the BCDS and
MCDS
To list information from the BCDS and MCDS use TSO. This command can only be
issued directly through TSO.
An unauthorized user can use this command to get any of the information that is
offered. The most useful information for unauthorized users is information about
their own data sets.
DFSMShsm maintains information about the volumes and data sets that it manages
and owns and its control data sets. DFSMShsm maintains three control data sets:
backup, migration, and offline. The information for the user comes from only two:
backup and migration.
The HLIST command is a long-running command that can tie up your TSO
terminal if its output is directed to TERM.
Listing information from the BCDS and MCDS in TSO
The following information applies to both SMS and non-SMS-managed data sets.
Task: List selected information from the MCDS and BCDS.
You can issue the HLIST command without specifying any parameters to list all of
your migrated data sets. Or, you can list information from the following categories,
using the HLIST command:
v Backup volume information from the BCDS
v Data set information from the MCDS or BCDS
v Migration and DFSMShsm-managed volume information from the MCDS
v User authorization information
The HLIST command can process only one of the four categories at a time. If you
specify more than one category, the HLIST command processes the category of the
highest order of preference. The following is the order of preference:
v PRIMARYVOLUME, MIGRATIONVOLUME, or VOLUME
v BACKUPVOLUME
v USER
v DATASETNAME or LEVEL
Note: For examples of lists produced by using the HLIST command, see “Sample
lists from the HLIST command” on page 104.
Abbreviation: The minimum abbreviation for the HLIST command is HL.
Syntax
The following diagram presents the syntax of the HLIST command for both
SMS-managed and non-SMS-managed data sets:
© Copyright IBM Corp. 1984, 2017
93
HLIST
►► HLIST
BACKUPVOLUME
fragment A
BVOL
( volser )
DATASETNAME
fragment B
DSNAME
( dsname )
LEVEL
( qualifier
)
MIGRATIONVOLUME
fragment C
MVOL
MIGRATIONLEVEL1
ML1
MIGRATIONLEVEL2
ML2
(
DASD
)
TAPE
PRIMARYVOLUME
PVOL
VOLUME(volser)
USER
fragment A
( userid )
►◄
A: HLIST Optional Parameters
TERMINAL
►►
►◄
OUTDATASET
( dsname
ODS
SYSOUT
( class )
)
B: HLIST Optional Parameters
►►
►
BACKUPCONTROLDATASET
BCDS
BACKUP
MIGRATIONCONTROLDATASET
MCDS
MIGRAT
BOTH
►
INCLUDEPRIMARY
SUMMARY
fragment A
►
SELECT (
)
AGE ( mindays
)
maxdays
MIGRATIONLEVEL1
ML1
MIGRATIONLEVEL2
ML2
VOLUME ( volser )
RETAINDAYS
ACTIVE
94
z/OS DFSMShsm Managing Your Own Data
HLIST
►
►◄
SMALLDATASETPACKING
SDSP
NOSMALLDATASETPACKING
NOSDSP
VSAM
C: HLIST Optional Parameters
►►
►◄
BACKUPCONTROLDATASET
BCDS
BACKUP
MIGRATIONCONTROLDATASET
MCDS
MIGRAT
BOTH
Required parameters
BACKUPVOLUME: Requesting a list of backup volume entries
Explanation: BACKUPVOLUME is the parameter you use to request a list of
selected information from backup volume entries contained in the BCDS. For
volser, substitute the serial number of the backup volume for which you want
listed.
Abbreviations: The TSO abbreviation convention applies for BACKUPVOLUME.
In addition, you can use the abbreviation BVOL for BACKUPVOLUME.
Defaults: If you specify BACKUPVOLUME without volser, DFSMShsm lists all the
backup volume entries from the BCDS.
If you do not specify the parameters MIGRATIONVOLUME, PRIMARYVOLUME,
VOLUME, BACKUPVOLUME, USER, DATASETNAME, or LEVEL, DFSMShsm
lists all the data set entries that have your user identification as the set of initial
characters of the data set name.
Restrictions: None.
DATASETNAME and LEVEL: Requesting a list of data set entries
Explanation: DATASETNAME | LEVEL(qualifier) are the parameters you use to
request a list of data set entries.
DATASETNAME specifies a list of all of your data set entries. For dsname,
substitute the name of the data set for which you want the list. You cannot use any
wild cards (%, *, or **) in the data set name and you can specify a data set name of
up to 44 characters.
LEVEL(qualifier) is specified to request a list of all data set entries that have the
same set of initial characters of the data set name. For qualifier, substitute the set of
initial characters of the data set name for the data sets you want listed. The set of
Chapter 17. HLIST: Listing information from the BCDS and MCDS
95
HLIST
initial characters can contain imbedded periods. The qualifier can end with a period
if LEVEL is the first keyword on the command. You can specify a qualifier of up to
44 characters.
Abbreviations: The TSO abbreviation convention applies for DATASETNAME
and LEVEL. In addition, you can use the abbreviation DSNAME for
DATASETNAME.
Defaults: If you specify DATASETNAME without dsname or specify LEVEL
without a qualifier, DFSMShsm lists all the data set entries that have your user
identification as the set of initial characters of the data set name.
If you do not specify the parameters MIGRATIONVOLUME, PRIMARYVOLUME,
VOLUME, USER, BACKUPVOLUME, DATASETNAME, or LEVEL, DFSMShsm
lists all the data set entries that have your user identification as the set of initial
characters of the data set name.
Restrictions: None.
MIGRATIONVOLUME, MIGRATIONLEVEL1, MIGRATIONLEVEL2,
PRIMARYVOLUME, and VOLUME: Requesting a list of primary
and migration volume entries
Explanation: MIGRATIONVOLUME | MIGRATIONLEVEL1 |
MIGRATIONLEVEL2 | PRIMARYVOLUME | VOLUME are mutually exclusive,
optional parameters you use to request a list of DFSMShsm-managed or migration
volume entries. A list of volume entries does not include information about any
individual data sets that reside on the volumes.
MIGRATIONVOLUME specifies that you want a list of the volume entries for all
migration volumes.
MIGRATIONLEVEL1 specifies that you want a list of the volume entries for all
migration level 1 volumes.
MIGRATIONLEVEL2 specifies that you want a list of the volume entries for all
migration level 2 volumes.
DASD or TAPE are mutually exclusive, optional subparameters of the
MIGRATIONLEVEL2 parameter that specifies whether to list DASD or tape
migration level 2 volumes. DASD specifies that you want a list of the volume
entries for all DASD migration level 2 volumes. TAPE specifies that you want a list
of the volumes entries for all tape migration level 2 volumes.
PRIMARYVOLUME specifies that you want a list of the volume entries for all
DFSMShsm-managed volumes.
VOLUME (volser) specifies a list of all DFSMShsm-managed and migration
volumes. For volser, substitute the serial number of the volume for which you want
the volume entry listed.
Abbreviations: The TSO abbreviation convention applies for PRIMARYVOLUME,
MIGRATIONVOLUME, MIGRATIONLEVEL1, MIGRATIONLEVEL2 and
VOLUME. In addition, you can use the abbreviation PVOL for
PRIMARYVOLUME, the abbreviation MVOL for MIGRATIONVOLUME, the
abbreviation ML1 for MIGRATIONLEVEL1, and the abbreviation ML2 for
MIGRATIONLEVEL2.
96
z/OS DFSMShsm Managing Your Own Data
HLIST
Defaults: If you specify VOLUME without volser, DFSMShsm lists all volume
entries for all the DFSMShsm-managed and migration volumes it owns or
manages.
If you do not specify the parameters MIGRATIONVOLUME, PRIMARYVOLUME,
VOLUME, BACKUPVOLUME, USER, DATASETNAME, or LEVEL, DFSMShsm
lists all the data set entries that have your user identification as the set of initial
characters of the data set name.
Restrictions: You can specify only one of PRIMARYVOLUME,
MIGRATIONVOLUME, MIGRATIONLEVEL1, MIGRATIONLEVEL2, or VOLUME
with each HLIST command.
USER: Requesting a list of user entries
Explanation: USER is the parameter you use to request a list of the authorization
status of users. A list of user entries does not include any information about the
data sets associated with a specified user.
Abbreviations: The TSO abbreviation convention applies for USER. There are no
additional abbreviations.
Defaults: If you specify USER without userid, DFSMShsm lists all
DFSMShsm-authorized users.
If you do not specify the parameters MIGRATIONVOLUME, PRIMARYVOLUME,
VOLUME, BACKUPVOLUME, USER, DATASETNAME, or LEVEL, DFSMShsm
lists all the data set entries that have your user identification as the set of initial
characters of the data set name.
Optional parameters
BACKUPCONTROLDATASET, MIGRATIONCONTROLDATASET,
and BOTH: Controlling the source of information listed
Explanation: BACKUPCONTROLDATASET |
MIGRATIONCONTROLDATASET | BOTH are mutually exclusive, optional
parameters that specify where DFSMShsm should obtain the information for the
list. Specify one or the other when data set or volume information can exist in both
the MCDS and BCDS.
BACKUPCONTROLDATASET specifies a list of selected information from only the
BCDS entries for a specific data set, level, or volume, or for DFSMShsm-managed
volumes. BACKUP is allowed as an alias for BACKUPCONTROLDATASET.
MIGRATIONCONTROLDATASET specifies a list of selected information from the
MCDS entries for a specific data set, level, or volume, or for DFSMShsm-managed
volumes or migration volumes. MIGRAT is allowed as an alias for
MIGRATIONCONTROLDATASET.
BOTH specifies a list of selected information from the MCDS and BCDS entries for
the specified data sets, DFSMShsm-managed volumes, or migration volumes.
Note: Records of the DFSMShsm-managed volumes exist in both the MCDS and
BCDS. Records of the migration volumes exist only in the MCDS. Records of the
backup volumes exist only in the BCDS.
Chapter 17. HLIST: Listing information from the BCDS and MCDS
97
HLIST
Abbreviations: The TSO abbreviation convention applies for BOTH,
MIGRATIONCONTROLDATASET, and BACKUPCONTROLDATASET. In addition,
you can use the abbreviation MCDS for MIGRATIONCONTROLDATASET and the
abbreviation BCDS for BACKUPCONTROLDATASET.
Defaults: The default is MIGRATIONCONTROLDATASET.
Restrictions: You can specify only one of BOTH,
MIGRATIONCONTROLDATASET, or BACKUPCONTROLDATASET when you
specify DATASETNAME, LEVEL, PRIMARYVOLUME, MIGRATIONVOLUME, or
VOLUME. If you do not specify any of these parameters, DFSMShsm ignores the
BOTH, MIGRATIONCONTROLDATASET, and BACKUPCONTROLDATASET
parameters.
INCLUDEPRIMARY: Requesting a list of entries for a data set that
has migrated even though the data set might have been recalled
Explanation: INCLUDEPRIMARY is an optional parameter you use to request a
list of all data set entries including entries of recalled data sets. DFSMShsm retains
data set entries in the MCDS for a limited amount of time even after it recalls the
data set.
Abbreviations: The TSO abbreviation convention applies for INCLUDEPRIMARY.
There are no additional abbreviations.
Defaults: If you do not specify INCLUDEPRIMARY, the list will not include data
set entries for recalled data sets among the data set entries listed.
Restrictions: The INCLUDEPRIMARY parameter applies only to the
DATASETNAME and LEVEL parameters and only when information from the
MCDS is being listed. If you specify INCLUDEPRIMARY when it does not apply,
DFSMShsm ignores it.
OUTDATASET, SYSOUT, and TERMINAL: Specifying the location
of output for the list
Explanation: OUTDATASET(dsname) | SYSOUT | TERMINAL are mutually
exclusive, optional parameters that specify the output location for the list.
OUTDATASET(dsname) specifies the name of the data set where DFSMShsm is to
write the output data. For dsname, substitute the fully-qualified name of the data
set to receive the HLIST command output.
If you specify a data set that does not exist, DFSMShsm dynamically allocates and
catalogs an output data set with the following characteristics:
v Data set name specified (dsname)
v Record format of fixed-blocked with ANSI control characters (FBA)
v Logical record length of 121
v System-reblockable if DFSMShsm is running with DFP 3.1.0 or a subsequent
release; otherwise, block size of 1210
v Primary allocation of 20 tracks
v Secondary allocation of 50 tracks
v Unit of SYSALLDA
If the data set already exists:
v The data set must be cataloged and on DASD.
98
z/OS DFSMShsm Managing Your Own Data
HLIST
v The data set record format must be FBA and the logical record length must be
121.
v The data set is system-reblockable if DFSMShsm is running with DFP 3.1.0 or a
subsequent release and the block size must be 0; otherwise, the block size must
be a multiple of 121 up to a limit of 32K.
v The user can choose the primary space allocation.
v If DFSMShsm needs additional extents after the primary space allocation,
DFSMShsm uses a secondary space allocation of 50 tracks.
v If the data set does not contain data, DFSMShsm starts writing output data at
the beginning of the data set.
v If the data set contains data, DFSMShsm writes the output data after the existing
data.
SYSOUT specifies that the list is to be printed to the specified system output class.
For class, substitute the alphanumeric character for the system output class you
want.
TERMINAL specifies that the list is to be printed at your terminal.
Abbreviations: The TSO abbreviation convention applies for TERMINAL,
SYSOUT, and OUTDATASET. In addition, you can use the abbreviation ODS for
OUTDATASET.
Defaults: The default is TERMINAL. If you specify SYSOUT without class, class
defaults to the type of class specified by the system programmer. If the system
programmer did not specify a type of class, the default is class A.
Restrictions: You can specify only one of TERMINAL, SYSOUT, or OUTDATASET
with each HLIST command.
DFSMShsm does not process partitioned data set members individually. If you
specify a partitioned data set with a member name as the output data set,
DFSMShsm could write the list over existing data.
SELECT: Requesting a list of only those data set entries that
meet selection criteria
Explanation: SELECT is an optional parameter set that you use to request a list
containing only selected data set entries. When the DATASETNAME or LEVEL
parameter identifies multiple data sets, you use the SELECT parameter to select a
subset of data set entries for the list.
Note: Because of the number of subparameters of SELECT, this publication lists
and describes each subparameter separately.
Abbreviations: The TSO abbreviation convention applies for SELECT. There are
no additional abbreviations.
Defaults: None.
Restrictions: The SELECT parameter applies only to the DATASETNAME and
LEVEL parameters. If you do not specify either parameter, DFSMShsm ignores the
SELECT parameter.
The AGE subparameter is the only subparameter that applies to information from
both the MCDS and BCDS. The other subparameters apply only to the MCDS.
Chapter 17. HLIST: Listing information from the BCDS and MCDS
99
HLIST
SELECT(ACTIVE | RETAINDAYS): Selecting entries based on
specification of the RETAINDAYS keyword
ACTIVE specifies that DFSMShsm is to display the information about the active
backup versions only. The information about the retained backup copies is not
included in the output.
RETAINDAYS specifies that DFSMShsm is to display the backup information
about the active and retained backup copies that have RETAINDAYS specified at
the time of backup. Retained backup copies do not have version and generation
numbers, therefore this information is not available in the HLIST command output.
Note: If you specify SELECT without specifying either RETAINDAYS or ACTIVE,
DFSMShsm displays information about both active and retained backup copies.
The output contains "***" for generation and version numbers for retained copies,
and "*****" in the field of the RETAINDAYS value for copies that do not have
RETAINDAYS specified during backup.
SELECT(AGE): Selecting entries based on data set use
Explanation: AGE(mindays maxdays) is an optional subparameter of SELECT that
specifies a list of those entries in the MCDS for only the data sets whose most
recent reference is within the specified range of days, or a list of those entries in
the BCDS for the data sets that were backed up within the specified range of days.
For mindays, substitute a decimal number from 0 to 999999 for the minimum
number of days since you referred to the data sets or since DFSMShsm backed
them up.
For maxdays, substitute a decimal number from 0 to 999999 for the maximum
number of days since you referred to the data sets or since DFSMShsm backed
them up. The maxdays value should be greater than or equal to the mindays value.
If the maxdays value is not greater than the mindays value, DFSMShsm lists only
the data sets whose most recent reference or backup was exactly mindays days ago.
Abbreviations: The TSO abbreviation convention applies for AGE. There are no
additional abbreviations.
Defaults: The default for mindays is 0, and the default for maxdays is 999999. The
default range of days causes entries to be listed for all of the data sets that meet
the data set or volume specification. If maxdays is less than mindays, maxdays
defaults to the same value as mindays.
Restrictions: None.
SELECT(MIGRATIONLEVEL1 | MIGRATIONLEVEL2 |
VOLUME(volser)): Selecting entries based on the volume where
the data set resides
Explanation: MIGRATIONLEVEL1 | MIGRATIONLEVEL2 | VOLUME(volser)
| are mutually exclusive, optional subparameters of SELECT that specify the
volume or migration volumes where the data sets must reside for the data set
entries to be included in the list.
MIGRATIONLEVEL1 specifies a list of the entries for data sets that reside on level
1 migration volumes only.
100
z/OS DFSMShsm Managing Your Own Data
HLIST
MIGRATIONLEVEL2 specifies a list of the entries for data sets that reside on level
2 migration volumes only.
VOLUME (volser) specifies a list of one of the following:
v The entries for data sets that reside on the specified migration volume
v The entries for data sets that reside on the specified level 0 volume
v The entries for only those data sets whose most recent backup version resides on
the specified backup volume
For volser, substitute the serial number of the volume that contains the data sets for
which you want entries listed.
Note: To list data set entries on a specific level 0 volume, you must also specify
INCLUDEPRIMARY.
Abbreviations: The TSO abbreviation convention applies for VOLUME,
MIGRATIONLEVEL1, and MIGRATIONLEVEL2. In addition, you can use the
abbreviation ML1 for MIGRATIONLEVEL1 and the abbreviation ML2 for
MIGRATIONLEVEL2.
Defaults: None.
Restrictions: You can specify only one of VOLUME, MIGRATIONLEVEL1, or
MIGRATIONLEVEL2 with the SELECT parameter for each HLIST command.
SELECT(SMALLDATASETPACKING |
NOSMALLDATASETPACKING): Selecting entries based on
whether the data sets migrated to an SDSP data set
Explanation: SMALLDATASETPACKING | NOSMALLDATASETPACKING are
mutually exclusive, optional subparameters of the SELECT parameter that you use
to request a list of those entries for the data sets that DFSMShsm has migrated to
small-data-set-packing data sets or entries for only the data sets that DFSMShsm
has not migrated to a small-data-set-packing data set. If you do not specify either
subparameter, the list contains entries for data sets that DFSMShsm migrated
regardless of where it migrated them to.
SMALLDATASETPACKING specifies a list of entries for only those data sets that
DFSMShsm has migrated to small-data-set-packing data sets.
NOSMALLDATASETPACKING specifies a list of entries for only those data sets
that DFSMShsm has not migrated to small-data-set-packing data sets.
Small-data-set-packing data sets can exist only on migration level 1 volumes. You
can specify the ML1 subparameter and the SDSP or NOSDSP subparameters of the
SELECT parameter in the same HLIST command.
Abbreviations: The TSO abbreviation convention applies for
SMALLDATASETPACKING and NOSMALLDATASETPACKING. In addition, you
can use the abbreviation SDSP for SMALLDATASETPACKING and the
abbreviation NOSDSP for NOSMALLDATASETPACKING.
Defaults: None.
Restrictions: You can specify either SMALLDATASETPACKING or
NOSMALLDATASETPACKING, but not both. Do not specify ML2 and SDSP in the
Chapter 17. HLIST: Listing information from the BCDS and MCDS
101
HLIST
same HLIST command. In addition, do not specify a particular volume and SDSP
in the same HLIST command if the volume is not a migration level 1 volume.
SELECT(VSAM): Specifying the data set organization
Explanation: VSAM is an optional subparameter of the SELECT parameter that
specifies a list of only migrated VSAM data sets. The list contains standard data set
information for the MCDS data set records and any VSAM object names that you
can use to automatically recall the data set.
The VSAM subparameter applies only to data set information from the MCDS.
Abbreviations: The TSO abbreviation convention applies for VSAM. There are no
additional abbreviations.
Defaults: None.
Restrictions: None.
SUMMARY: Requesting a summary only
Explanation: SUMMARY is an optional parameter that specifies only a count of
data sets, tracks, and bytes of the selected data sets. The SUMMARY parameter
suppresses information about individual data sets. Also, this parameter applies
only to information from the MCDS.
Abbreviations: The TSO abbreviation convention applies for SUMMARY. There
are no additional abbreviations.
Defaults: None.
Restrictions:
v When you specify this parameter, DFSMShsm does not list information about
each data set. Also, this parameter applies only to information from the MCDS.
v The SUMMARY information is issued when you specify the LEVEL parameter
or the DATASETNAME parameter (with no data set name specified) and the
MCDS information is requested and available. The SUMMARY parameter
applies only to the DATASETNAME parameter (with no data set name
specified) and the LEVEL parameter.
Examples of different ways to code the HLIST command
The examples below present different ways to code the HLIST command. The
values are examples only. Do not interpret them as values that you should use for
your system.
Listing the data set entries from the MCDS and printing them at
the terminal
In this example, you are issuing the HLIST command to list all migrated data set
entries in the MCDS with MST7707 as the specified set of initial characters of the
data set name. The list is printed at the terminal from which you issued the
command.
HLIST LEVEL(MST7707) MIGRATIONCONTROLDATASET TERMINAL
102
z/OS DFSMShsm Managing Your Own Data
HLIST
Listing the data set entries for data sets from the BCDS
In this example, you are issuing the HLIST command to list the BCDS entries for
all data sets that have MST7707.A as the set of initial characters of the data set
name. The list is printed at SYSOUT class A.
HLIST LEVEL(MST7707.A) BACKUPCONTROLDATASET SYSOUT(A)
Listing the entry for a backup volume
In this example, you are issuing the HLIST command to list the BCDS volume
entry for backup volume BVL005. The list is printed at the terminal from which
you issued the command.
HLIST BACKUPVOLUME(BVL005)
Listing the entries for data sets of selected age and sending the
output to an output data set
In this example, you are issuing the HLIST command to list all the data sets from
both the MCDS and BCDS whose set of initial characters is the same as your user
identification. The data sets listed from the MCDS will be those that are migrated
and that you have referred to in the last 60 days. The data sets listed from the
BCDS will be those that DFSMShsm last backed up in the last 60 days. The list is
to go to the output data set CECL.OUTTESTS.TESTLIST.
HLIST DATASETNAME BOTH SELECT(AGE(0 60)) OUTDATASET(’CECL.OUTTESTS.TESTLIST’)
Listing all migration volume entries from the MCDS
In this example, you are issuing the HLIST command to list all the migration
volume entries from the MCDS. The list is to go to the output data set
GRPA.COMMTEST.LIST.
HLIST MIGRATIONVOLUME OUTDATASET(’GRPA.COMMTEST.LIST’)
Listing the data set entries for data sets residing in a
small-data-set-packing data set of a specific volume
In this example, you are issuing the HLIST command to list the entries from the
MCDS for all migrated data sets with MST7707 as the specific set of initial
characters of the data set name that are in the small-data-set-packing data set on
migration level 1 volume MVL003. The list is to go to SYSOUT class A.
HLIST LEVEL(MST7707) SELECT(VOLUME(MVL003) SMALLDATASETPACKING) SYSOUT(A)
Listing the data set entries for all level 1 volumes and sending
the output to a terminal
In this example, you are issuing the HLIST command to list the entries for
migrated data sets that have MST7707 as the set of initial characters of the data set
name, are on migration level 1 volumes, but are not in small-data-set-packing data
sets. The list is to be printed at the terminal from which you issued the command.
HLIST LEVEL(MST7707) SELECT(MIGRATIONLEVEL1 NOSMALLDATASETPACKING)
Chapter 17. HLIST: Listing information from the BCDS and MCDS
103
HLIST
Sample lists from the HLIST command
This section contains examples of printer and terminal lists generated by the
HLIST command.
Listing volume entries
Table 3 presents the headings that appear in a list printed at the printer or terminal
when you request information for DFSMShsm-managed or migration volumes and
a description of the information that appears with those headings.
Table 3. Headings of Output When You Request Information from the Migration Control Data Set for
DFSMShsm-Managed or DASD Migration Volume
Printer Output
Heading
Terminal Label
Description
VOLSER
VOL
The number under this heading is the volume serial number of the
DFSMShsm-managed or migration volume.
DEVICE
TYPE
DEVTYP
The name under this heading is the name of the type of unit on which
this volume can reside.
VOL
TYPE
VOLTYPE
The DFSMShsm category assigned to this volume is PRIM, P SMS,
LEV 1, L1-OV, or LEV 2. UN indicates that a DASD migration level 2
volume has not been assigned to a key range and that a tape level 2
migration volume has not been selected for migration by any
processing unit.
THRESHOLD
HI---LO
HI-THRESH
LO-THRESH
This field contains the high and low threshold of occupancy defined
for this volume. The low threshold of occupancy applies only to
DFSMShsm-managed volumes. The values listed for SMS-managed
volumes are those that DFSMShsm last retrieved from SMS and may
not be the most current values. The most current values for
SMS-managed volumes are reflected in the volume’s associated storage
group.
FRAG
INDEX
FRAG
The number under this heading is a qualitative measure of the
scattered free space on the volume. The values of the index can range
from 0 to 1. The higher the value, the more fragmented the free space
on the volume.
HOSTID
AUTO-MIG
The character listed is the processor ID of a processor by which this
volume was assigned the automatic space management attribute. A
NO indicates that the volume has not been assigned the automatic
space management attribute by any processor. This field applies to
DFSMShsm-managed volumes only.
HOSTID
BACK
The character listed is the processor ID of a processor by which this
volume was assigned the automatic backup attribute. A NO indicates
that the volume was not assigned the automatic backup attribute by
any processor. This field applies to DFSMShsm-managed volumes
only.
DUMP
The character listed is the processor ID of a processor by which this
volume was assigned the automatic dump attribute. A NO indicates
that the volume was not assigned the automatic dump attribute by
any processor. This field applies to DFSMShsm-managed volumes
only.
AUTO
RECALL
AUTO-RECALL
YES or Y indicates that the volume with the automatic recall attribute
is eligible to receive recalled data sets. This field applies to
DFSMShsm-managed volumes only.
SDSP
AVAIL
SDSP
YES or Y indicates that a small-data-set-packing data set was created
on this volume. This field applies to migration level 1 volumes only.
104
z/OS DFSMShsm Managing Your Own Data
HLIST
Table 3. Headings of Output When You Request Information from the Migration Control Data Set for
DFSMShsm-Managed or DASD Migration Volume (continued)
Printer Output
Heading
Terminal Label
Description
MIN AGE
MIN-AGE
This is the inactive age of the most recently migrated data set from the
volume that was processed the last time volume space management
ran.
MIGRATED
DS--TRKS
MIG DS
This is the number of data sets that were migrated or deleted from the
volume during the last volume space management.
MIG TRKS
This is the number of tracks of data that were migrated or deleted
from the volume during the last volume space management.
DATE--TIME
LAST MIGRATED
MIGDATE-TIME
This is the date of the last volume space management of this volume.
SPACE-MGMT
TYPE/AGE
SPACE-MGMT
This is the type of space management assigned to this volume. MIG
indicates migration, DBA indicates delete-by-age, and DBU indicates
delete-if-backed-up.
AGE
This is the number of days a data set on this volume must be inactive
before it is eligible for space management. DEFAULT indicates that the
age criteria for the volume or all DFSMShsm-managed volumes is not
specified in the SETSYS command and DFSMShsm determines the age
based on whether DFSMShsm is running in a single processor
environment or multiple processor environment. This field applies
only to DFSMShsm-managed volumes.
BACKDEV
CATEGORY
BACKUP-DEVICE
CATEGORY
This field contains the backup device category assigned to this
volume. If no category was assigned, the field contains ANY. This field
applies only to DFSMShsm-managed volumes.
DUMP CLASS
DUMPCLASS
This field contains the dump class of the DFSMShsm-managed or
migration volume. The values listed for SMS-managed volumes are
those that DFSMShsm last retrieved from SMS and may not be the
most current values. The most current values for SMS-managed
volumes are reflected in the volume’s associated storage group.
Note: A field containing only *** is not applicable to this volume (see individual field descriptions in the sample
lists).
Figure 23 is a sample printer list of a specific migration volume when you specify
the MIGRATIONVOLUME parameter. The printer list format for a specific
migration volume, for all the DFSMShsm-managed and migration volumes, or for
all the DFSMShsm-managed volumes or migration volumes has the same format as
described in Figure 23. If you request information for more than one volume, the
list has multiple entries.
1- DFSMSHSM CONTROL DATASET - MIGRATE VOLUME-MCDS--- LISTING ----- AT 14:09:45 ON 08/12/02 FOR SYSTEM=PCC
VOLSER DEVICE VOLUME THRESH FRAG HOSTID AUTO- AUTO SDSP MIN MIGRATED
TYPE
TYPE HI--LOW INDX MIG--BACK-DUMP RECL ELIG AGE DS-----TRKS
DATE---TIME SPACE-MGMT BUDEV DUMP
LAST MIGRATED TYPE/AGE CATGY CLASS
MIG101
MIG102
MIG103
OVFML1
00/00/00
00/00/00
00/00/00
00/00/00
3390
3390
3390
3390
LEV 1
LEV 1
LEV 1
L1-OV
075
075
075
080
***
***
***
***
.018
.012
.079
.000
****
****
****
****
****
****
****
****
8
8
8
C
***
***
***
***
YES
NO
NO
NO
***
***
***
***
00115
00010
00005
00012
009636
000125
000070
745930
00:00
00:00
00:00
00:00
***
***
***
***
***
***
***
***
****
****
****
****
DUMPCLB
DUMPCLC
DUMPCLC
DUMPCLB
----- END OF - MIGRATE VOLUME - LISTING ----1- DFSMSHSM CONTROL DATASET - MIGRATE VOLUME-MCDS--- LISTING ----- AT 14:09:54 ON 08/12/02 FOR SYSTEM=PCC
Figure 23. Sample Printer List of Migration Volumes from the Migration Control Data Set When You Specify
MIGRATIONVOLUME and MIGRATIONCONTROLDATASET
Chapter 17. HLIST: Listing information from the BCDS and MCDS
105
HLIST
Figure 24 is a sample terminal list for all the DFSMShsm-managed and migration
volumes when you have specified the VOLUME and TERMINAL parameters. The
terminal list format for a specific DFSMShsm-managed volume or migration
volume, or for all the DFSMShsm-managed volumes or migration volumes, has the
same format as described in Figure 24. If you request information for only one
volume, the list has one entry.
VOL=SMS001 DEVTYP=3380
VOLTYPE=P SMS
MIGDS=0001 MIGTRKS=****
MIGDATE-TIME=89/01/28 12:01 FRAG=.069 HI-THRESH=020 LO-THRESH=010
MIN-AGE=*** BACKUP-DEVICE-CATEGORY=**** AUTO-RECALL=*
SDSP=*** SPACE-MGMT=MIG AGE=*** AUTO-HOST MIG=** BACK=** DUMP=**
DUMPCLASS = ********
VOL=M2TP02 DEVTYP=3480
MIGTYP=L2-TP
VOL FULL=Y VOL EMPTY=N DELDS=0000
SP-MGT-DATE=88/01/10 PSWD=Y EXP=N RACF=N AVAIL=Y IN USE=-NO- SELD=N
Figure 24. Sample Terminal List of All Volumes from the Migration Control Data Set When You Specify VOLUME and
TERMINAL
Table 4 presents the headings of the output when DFSMShsm lists information
from the MCDS for tape migration level 2 volumes.
Table 4. Headings of Output When You Request Information from the MCDS for Tape Migration Level 2 Volumes
Printer Output
Heading
Terminal Label
Description
VOLSER
VOL
This field contains the volume serial number of the tape
migration level 2 volume.
DEVTYP
This field contains the name of the unit where this volume can be
allocated.
MIGTYP
L2-TP: The tape volume was added as a tape migration level 2
volume.
VOL FULL
A YES or Y indicates that an end-of-tape marker was reached or a
data movement error occurred while DFSMShsm was writing on
the tape volume.
SP-MGT-DATE
This is the date of the last volume space management of this
volume.
VOL EMPTY
A YES or Y indicates that the volume is empty.
DELDS
This is the number of data sets deleted from the volume during
the last volume space management.
PSWD
PSWD
A YES or Y indicates that the tape volume is password-protected.
EXP
EXP
A YES or Y indicates that this tape volume is protected by an
expiration date.
RACF
RACF
A YES or Y indicates that the tape volume is RACF-protected.
AVAILABLE
AVAIL
A YES or Y indicates that the tape volume is available.
DEVICE
TYPE
MIGRATE
TYPE
VOL
FULL
DATE LAST VOL
SP MANAGEMENT
VOL
EMPTY
DELETED
DS
106
z/OS DFSMShsm Managing Your Own Data
HLIST
Table 4. Headings of Output When You Request Information from the MCDS for Tape Migration Level 2
Volumes (continued)
Printer Output
Heading
Terminal Label
Description
IN USE
IN USE
NO: The tape volume is not being used.
MIGD: Data set migration is using the tape volume.
MIGV: Volume migration is using the tape volume.
RECL: Recall is using the tape volume.
RCYS: The tape volume is a recycle source volume.
RCYT: The tape volume is a recycle target volume.
DBAU: Data set deletion or data set retirement is using the tape
volume.
SELECTED
SELD
A YES or Y indicates that the volume is selected.
IDRC
IDRC
Y = Volume contains data in the Improved Data Recording
Capability format.
N = Volume does not contain data in the Improved Data
Recording Capability format.
** = Volume is empty—not assigned the Improved Data
Recording Capability format.
DUPLEX ALT
DUPLEX ALT
volser indicated the volume serial number of the duplexed
alternate.
*PEND* indicates an exception condition and an internal
TAPECOPY is pending.
*NONE* indicates volume not created in a duplexing
environment.
Figure 25 on page 108 is a sample of the printer list of tape migration level 2
volumes when you specify the MIGRATIONLEVEL2(TAPE) parameter and
MIGRATIONCONTROLDATASET parameter.
Chapter 17. HLIST: Listing information from the BCDS and MCDS
107
HLIST
1- DFSMSHSM CONTROL DATASET - MIGRATE VOLUME-MCDS--- LISTING ----- AT 14:09:45 ON 08/12/02 FOR SYSTEM=PCC
VOLSER DEVICE VOLUME THRESH FRAG HOSTID AUTO- AUTO SDSP MIN MIGRATED
TYPE
TYPE HI--LOW INDX MIG--BACK-DUMP RECL ELIG AGE DS-----TRKS
MIG101
MIG102
MIG103
OVFML1
3390
3390
3390
3390
LEV 1
LEV 1
LEV 1
L1-OV
075
075
075
080
***
***
***
***
.018
.012
.079
.000
****
****
****
****
****
****
****
****
8
8
8
C
***
***
***
***
YES
NO
NO
NO
***
***
***
***
00115
00010
00005
00012
DATE---TIME SPACE-MGMT BUDEV DUMP
LAST MIGRATED TYPE/AGE CATGY CLASS
009636
000125
000070
745930
00/00/00
00/00/00
00/00/00
00/00/00
00:00
00:00
00:00
00:00
***
***
***
***
***
***
***
***
****
****
****
****
DUMPCLB
DUMPCLC
DUMPCLC
DUMPCLB
----- END OF - MIGRATE VOLUME - LISTING ----1- DFSMSHSM CONTROL DATASET - MIGRATE VOLUME-MCDS--- LISTING ----- AT 14:09:54 ON 08/12/02 FOR SYSTEM=PCC
1- DFSMSHSM CONTROL DATASET - MIGRATE VOLUME-MCDS--- LISTING ----- AT 10:44:26 ON 96/11/12 FOR SYSTEM=3090
VOLSER DEVICE MIGRATE VOL DATE VOL LAST VOL DELETED PSWD EX RACF AVAILABLE IN USE SELECTED IDRC DUPLEX
TYPE
TYPE
FULL SP MANAGED
EMPTY
DS
ALT
A16010 3480
L2-TP
NO
A16012 3480
L2-TP
NO
A16014 3480
L2-TP
NO
----- END OF - MIGRATE VOLUME -
00/00/00
NO
00/00/00
NO
00/00/00
NO
LISTING -----
0000
0000
0000
YES
YES
YES
NO
NO
NO
NO
NO
NO
YES
YES
YES
-NO-NO-NO-
NO
NO
NO
N
N
N
A16011
*NONE*
*PEND*
Figure 25. Sample Printer List of Tape Migration Level 2 Volumes When You Specify MIGRATIONLEVEL2(TAPE) and
MIGRATIONCONTROLDATASET parameter.
Table 5 presents the headings that appear when you request a list of
DFSMShsm-managed volume information from the backup control data set.
Table 5. Headings of Output When You Request Information for DFSMShsm-Managed Volumes from the Backup
Control Data Set
Printer Output
Heading
Terminal Label
Description
VOLSER
VOL
The number under this heading is the volume serial number of
the volume.
ICF catalog
VSAM CTLG
ICF catalogs are no longer supported.
CTLG VOL
This field contains the volume serial number of the volume on
which the catalog resides, SYSRES, or blanks.
CATALOG
ON VOLSER
LAST BACKED UP
DATE TIME
LAST BACKED
UP ON
DUMP CLASS
DUMPCLASS
This field contains the date and time of the last volume backup of
this volume.
This field contains the dump class of the DFSMShsm-managed or
migration volume.
Figure 26 is a sample of a printer list of information about DFSMShsm-managed
volumes from the BCDS.
---- DFSMShsm CONTROL DATASET -PRIMARY VOLUME-BCDS--- LISTING ----AT 13:31:36 ON 89/12/31 FOR SYSTEM=SYSA
CATALOG
LAST BACKED UP
VOLSER SMS OWNED BY ICF CATALOG
ON VOLSER
DATE
TIME DUMPCLASS DUMPED
TIME
PRIM01 NO NOT OWNED BY A ICF CATALOG
PRIM01
88/01/15
00:59 DCLASS01 88/01/31 01:59
DCLASS02 88/01/31 01:59
DCLASS03 88/01/31 01:59
DCLASS04 88/01/31 01:59
DCLASS05 88/01/31 01:59
EXP DATE
*NOLIMIT
88/12/31
88/12/31
88/12/31
88/12/31
Figure 26. Sample Printer List from the BCDS When You Specify VOLUME, PRIMARYVOLUME(volser) and
BACKUPCONTROLDATASET
108
z/OS DFSMShsm Managing Your Own Data
HLIST
Listing backup volume entries
You specify the HLIST command with the BACKUPVOLUME parameter to get a
list of the information for all the backup volumes managed by DFSMShsm. The
command lists the volumes in alphanumeric sequence by volume serial number.
You specify HLIST BACKUPVOLUME(volser) to get a list of the information for a
specific backup volume managed by DFSMShsm.
Table 6 presents the information included in the list of all backup volumes or of a
specific backup volume.
Table 6. Headings of Output When You Request Information for Backup Volumes
Printer Output
Heading
Terminal Label
Description
VOLSER
VOL
This field contains the volume serial number of the backup
volume.
DEVICE
TYPE
DEVTYP
This field contains the type of unit on which this volume can be
allocated.
BACKUP
TYPE
BACKTYP
DAILY or SPILL indicates the DFSMShsm volume category of the
backup volume. AVAIL specifies that the backup category was not
assigned and the volume is available to be used as a daily or spill
backup volume when the volume is used for the first time.
VOL
FULL
FULL
For a DASD backup volume, YES indicates that an attempt to
back up a data set to this volume failed because of insufficient
space. For a tape backup volume, YES indicates that in writing to
the tape, an end-of-tape marker was reached or a data movement
error occurred and the volume was marked full to prevent further
use.
TOTAL
TRACKS
TOTAL TRKS
This field contains the total track capacity of the DASD volume. If
this field indicates zero tracks, the backup volume has never been
used. This field does not apply to tape.
FREE
TRACKS
FREE TRKS
This field contains the number of tracks on the DASD volume
available for data sets. This field does not apply to tape.
THRESH
THRESH
This field contains the threshold of occupancy for the DASD
backup volume. This field does not apply to tape.
LAST BACKUP
DATE
LAST BACKUP
DATE
This field contains the date that the volume was most recently
used as a target volume for backup, spill, or recycle processing.
PSWD
PSWD
A YES or Y indicates that the tape volume is password-protected.
This field does not apply to DASD.
EXP
EXP
A YES or Y indicates that the tape volume is protected by an
expiration date. This field does not apply to DASD.
RACF
RACF
A YES or Y indicates that the tape volume is RACF-protected.
This field does not apply to DASD.
EMPTY
EMPTY
A Y indicates that the tape volume is empty. This field does not
apply to DASD.
IDRC
IDRC
Y = Volume contains data in the Improved Data Recording
Capability format.
N = Volume does not contain data in the Improved Data
Recording Capability format.
** = Volume is empty—not assigned the Improved Data Recording
Capability format.
Chapter 17. HLIST: Listing information from the BCDS and MCDS
109
HLIST
Table 6. Headings of Output When You Request Information for Backup Volumes (continued)
Printer Output
Heading
Terminal Label
Description
DUPLEX ALT
DUPLEX ALT
volser indicated the volume serial number of the duplexed
alternate
*PEND* indicates an exception condition and an internal
TAPECOPY is pending
*NONE* indicates volume not created in a duplexing environment
Note: A field containing only *** is not applicable (see individual field descriptions in the sample lists).
Figure 27 is a sample printer list of all the backup volumes when you specify the
BACKUPVOLUME parameter. The printer list format for a specific volume has the
same format as that described in Figure 27. If you request information for only one
volume, the list has one entry.
1- DFSMSHSM CONTROL DATASET - BACKUP VOLUME-- LISTING ----- AT 10:55:46 ON 01/04/03 FOR SYSTEM=3090
VOLSER
DEVICE BACKUP VOL TOTAL
TYPE
TYPE
FULL TRACKS
A00002
3480
DAILY
NO ********
A00017
3480
DAILY
YES ********
A00018
3480
DAILY
NO ********
BACK01
3390
DAILY
NO 00000150
BACK02
3390
DAILY
NO 00000150
BACK03
3390
SPILL
NO 00000150
----- END OF - BACKUP VOLUME - LISTING
FREE THRESH
TRACKS
******** ***
******** ***
******** ***
00000021 090
00000023 090
******** 090
-----
LAST BACKUP
DATE
00/09/05
00/08/25
00/10/31
01/04/02
01/04/03
00/00/00
PSWD EXP
RACF EMPTY
YES
YES
YES
***
***
***
NO
NO
NO
***
***
***
NO
NO
NO
***
***
***
NO
NO
NO
***
***
***
IDRC DUPLEX
ALT
N
*NONE*
N
*NONE*
N
*NONE*
NA
NA
NA
NA
NA
NA
PCT
FULL
****
****
****
NA
NA
NA
Figure 27. Sample Printer List of All the Backup Volumes When You Specify BACKUPVOLUME
Listing data set entries from the migration control data set
Table 7 presents the information you receive when you request information from
the MCDS for data sets.
Table 7. Headings of Output When You Request MCDS Information for Data Sets
Printer Output
Heading
Terminal Label
Description
DATASET NAME
DSN
This field contains the name of the user data set.
MIGRATED ON
VOLUME
MIGVOL
This field contains the volume serial number of the migration
volume the data set is on if the data set is currently migrated. If the
data set is on more than one tape migration level 2 volume, this
field contains the volume serial number of the first volume the data
set is on. The field contains ONLINE if the data set was recalled.
LAST REF DATE
LAST REF
This field contains the date of the most recent reference of the data
set.
MIGRATED DATE
MIG
This field contains the date that the data set was last migrated.
TRKS ALLOC
TRKS
If the data set is currently migrated, this field contains the number
of tracks allocated for the data set on the DFSMShsm-managed
volume from which the data set migrated. If the data set is recalled,
this field is the number of tracks allocated for the recalled data set.
QTY 2K BLKS
2K BLKS
This field contains the size, in 2K blocks, of the data set on the
migration volume. This field does not apply to tape.
110
z/OS DFSMShsm Managing Your Own Data
HLIST
Table 7. Headings of Output When You Request MCDS Information for Data Sets (continued)
Printer Output
Heading
Terminal Label
Description
TIMES MIG
TIMES MIG
This field contains the number of times DFSMShsm migrated the
data set. If migration cleanup has deleted the data set record, this is
the number of times DFSMShsm migrated the data set since the
record was deleted.
DS ORG
DSO
This field contains the type of data set organization:
v PE (partitioned data set extended)
v PS (physical sequential)
v PO (partitioned)
v DA (BDAM)
v VS (VSAM)
v *** if the data set organization is unknown.
SDSP DS
SDSP
A YES under this heading indicates that the data set resides in a
small-data-set-packing data set.
QTY
16K BLOCKS
16K BLOCKS
This field contains the size, in 16K blocks, of the data set on the
tape migration level 2 volume. This field does not apply to DASD
migration volumes.
LAST MIG
VOLUME
LAST MIGVOL
This field contains the volume serial number of the last tape
migration level 2 volume if the data set spans more than one tape
volume. *NONE* indicates that the data set does not span more
than one tape volume. This field does not apply to DASD.
Figure 28 is a sample printer list from the migration control data set for all the data
sets that contain the user’s identification as the specific set of initial characters of
the data set name. If you request information for a specific data set, the list
contains the entry for only that data set.
----DFSMShsm CONTROL DATASET - MIGRATED DATASET--LISTING ----- AT 13:07:20 ON 89/03/23 FOR SYSTEM=381A
DATASET NAME
MIGRATED
LAST REF MIGRATED TRKS QTY TIMES DS SDSP QTY
LAST MIG
ON VOLUME
DATE
DATE
ALLOC 2K BLKS MIG ORG DS 16K BLKS VOLUME
S469193.DAV.N.F40RC034.DSET01
S469193.DAVS.N.F40RC034.DSET01
M2TP10
M2TP10
89/03/23 89/03/01
89/03/23 89/03/01
0589 ****
0001 ****
01
01
DA
DA
NO
NO
0118
0001
M2TP01
*NONE*
Figure 28. Sample Printer List When You Specify DATASETNAME and MIGRATIONCONTROLDATASET
Figure 29 is a sample printer list of data set entries when you specify the LEVEL
parameter.
----DFSMShsm CONTROL DATASET - MIGRATED DATASET--LISTING ----- AT 13:07:20 ON 89/03/23 FOR SYSTEM=381A
DATASET NAME
H952762.PSFB.F40LI404.DSET01
H952762.PSFB.F40LI404.DSET02
MIGRATED
LAST REF MIGRATED TRKS QTY TIMES DS SDSP QTY
LAST MIG
ON VOLUME
DATE
DATE
ALLOC 2K BLKS MIG ORG DS 16K BLKS VOLUME
M2TP01
M2TP01
89/03/23 89/03/23
89/03/23 89/03/23
0006 ****
0006 ****
01
01
PS
PS
NO
NO
0004
0004
*NONE*
*NONE*
Figure 29. Sample Printer List of a Group of Data Sets When You Specify LEVEL
Chapter 17. HLIST: Listing information from the BCDS and MCDS
111
HLIST
Figure 30 is a sample terminal list of data set entries when you specify the LEVEL
and TERMINAL parameters.
DSN=H952762.PSFB.F40LI404.DSET01
MIGVOL=M2TP01 DSO=PS
LAST REF=89/03/23 MIG=89/03/23 TRKS=0006 2K BLKS=**** TIMES MIG=01
16K BLKS=0004 LAST MIGVOL=*NONE*
SDSP=NO
DSN=H952762.PSFB.F40LI404.DSET02
MIGVOL=M2TP01 DSO=PS
LAST REF=89/03/23 MIG=89/03/23 TRKS=0006 2K BLKS=**** TIMES MIG=01
16K BLKS=0004 LAST MIGVOL=*NONE*
SDSP=NO
MIGRATED DATA SETS = 00002
TRACKS = 000012
K-BYTES = 00000104
Figure 30. Sample Terminal List of a Group of Data Sets When You Specify LEVEL and TERMINAL
Listing data set entries from the backup control data set
Table 8 presents the following information from the BCDS for all data sets:
Table 8. Headings of Output for All Data Sets When You Request Information from the Backup Control Data Set
Printer Output
Heading
Terminal Label
Description
DSNAME
DSN
This field contains the data set name of the data set that was
backed up.
BACKUP FREQ
BACK FREQ
This field contains the minimum number of days that must
elapse after a backup of the data set before another backup can
be done during incremental backup processing.
MAX VERS
This field contains the maximum number of versions of the data
set to be kept. More than this number of backup versions may
be listed if backup versions exist of uncataloged data sets with
the same names as cataloged data sets or if you reduced the
limit and no new backup versions were created.
BDSN
This field contains the data set name of the backup version.
BACKVOL
This field contains the volume serial number of the volume on
which the backup version resides. The volume can be a backup
volume or a migration level 1 volume.
FRVOL
This field contains the volume serial number of the user volume
on which the data set resided when the backup version was
made. If the data set was migrated at the time of the backup,
this field contains the volume serial number of the user volume
from which the data set migrated.
BACKDATE
This field contains the date the backup version was created.
BACKTIME
This field contains the time the backup version was created.
CAT
YES indicates that the backup version was made from the
cataloged data set.
MAX BACKUP
VERSIONS
BACKUP VERSION
DATA SET NAME
BACKUP
VOLUME
FROM
VOLUME
BACKUP
DATE
BACKUP
TIME
SYS
CAT
112
z/OS DFSMShsm Managing Your Own Data
HLIST
Table 8. Headings of Output for All Data Sets When You Request Information from the Backup Control Data
Set (continued)
Printer Output
Heading
Terminal Label
Description
GEN
This field contains the relative generation number of the backup
version. The most recent backup version is number 0, the next
most recent backup version is number 1, and so forth.
VER
This field contains the version number of the backup version.
This number is unique to the backup version during its entire
life span. The numbering begins at 1 for the first backup version
of a data set.
UNS/RET
This field indicates special conditions or exceptions. UNS
indicates that the data set was unserialized when backed up.
RET indicates that the version listed is a retired version. U/R
indicates an unserialized, retired version. NO indicates a version
that is neither unserialized nor retired.
RETDAYS
This field contains the RETAINDAYS parameter specified at the
time of backup. The value represents the minimum number of
days that DFSMShsm maintains the backup copy. ***** indicates
that RETAINDAYS is not specified.
RACF IND
YES indicates that the RACF indicator was on at the time of
backup. NO indicates that the RACF indicator was not on at the
time of backup.
BACK PROF
YES indicates that the RACF discrete backup profile exists. NO
indicates that a RACF discrete backup profile does not exist.
GEN
NMBR
VER
NMBR
UNS/
RET
RET DAYS
RACF
IND
BACKUP
PROF
NEWNM
NEWNAME
NOSPH
YES indicates the data set was VSAM with associated
AIX/PATH and SPHERE(NO) was specified. NO indicates the
data set was VSAM with associated AIX/PATH and
SPHERE(NO) was not specified.
GVCN
YES indicates the data set was VSAM and was uncataloged or
migrated and the backup was processed with the GVCN(YES)
option.
SPHERE(NO)
GENVSAMCOMPNAMES
Y as the first character indicates that NEWNAME was specified
at the time of backup. N as the first character indicates that
NEWNAME was not specified at the time of backup. Y as the
second character indicates that the data set was VSAM with
associated AIX/PATH, and SPHERE(NO) was specified. N as
the second character indicates the data set was VSAM with
associated AIX/PATH and SPHERE(NO) was not specified. Y as
the third character indicates the data set was VSAM and was
uncataloged or migrated and the backup was processed with
the GVCN(YES) option. * as the second character indicates the
data set was non-VSAM or VSAM and no AIX/PATH existed. *
as the third character indicates the data set was non-VSAM or
was VSAM and cataloged and not migrated.
Figure 31 on page 114 is a sample printer list of all data sets that contain the user’s
identification as the specific set of initial characters of the data set name when you
have specified the DATASETNAME and BACKUPCONTROLDATASET
parameters. If you request information for a specific data set, the list contains the
Chapter 17. HLIST: Listing information from the BCDS and MCDS
113
HLIST
entries for only that data set.
1- DFSMSHSM CONTROL DATASET - BACKUP DATASET-- LISTING ----- AT 08:55:18 ON 09/03/06 FOR SYSTEM=3090
DSNAME = HSMATH0.SMSDS4.N01.KSDS
BACKUP FREQ = ***, MAX ACTIVE BACKUP VERSIONS = ***
BACKUP VERSION DATA SET NAME
BACKUP FROM BACKUP
VOLUME VOLUME DATE
DFHSM.BACK.T165308.HSMATH0.SMSDS4.J9065
DFHSM.BACK.T445208.HSMATH0.SMSDS4.J9065
A00138 SRC001 09/03/06 08:53:16 YES 000
A00136 SRC001 09/03/06 08:52:44 YES 001
BACKUP
TIME
SYS GEN VER UNS/ RET BACKUP NEW
CAT NMBR NMBR RET DAYS PROF NAME
002
001
NO 00300 NO
NO ***** NO
N**
N**
TOTAL BACKUP VERSIONS = 0000000002
----- END OF - BACKUP DATASET - LISTING -----
Figure 31. Sample Printer List of All Data Sets When You Specify DATASETNAME and BACKUPCONTROLDATASET
Figure 32 is a sample terminal list for all the data sets that contain the user’s
identification as the specific set of initial characters of the data set name when you
have specified the DATASETNAME, BACKUPCONTROLDATASET, and
TERMINAL parameters. If you request information for a specific data set, the list
only contains entries for that data set.
DSN=HSMATH0.SMSDS4.N01.KSDS
BACK FREQ = ***
MAX ACTIVE BACKUP VERSIONS = ***
BDSN=DFHSM.BACK.T371814.HSMATH0.SMSDS4.J9064
BACKVOL=MIG102
FRVOL=SMS001, BACKDATE=09/03/05 BACKTIME=14:18:37 CAT=YES GEN=000 VER=001
UNS/RET= NO RACF IND=NO BACK PROF=NO NEWNM=NO NOSPH=*** GVCN=*** RETDAYS=00002
TOTAL BACKUP VERSIONS = 0000000001
Figure 32. Sample Terminal List of All Data Sets When You Specify DATASETNAME, BACKUPCONTROLDATASET,
and TERMINAL
Listing entries of the latest backup version on backup
volumes
Table 9 presents the following information for data sets whose latest backup
version is contained on the specified backup volume:
Table 9. HLIST--Listing Information from the BCDS and MCDS
Printer Output
Heading
Terminal Label
Description
DATA SET NAME
DSN
This field contains the original data set name of the data set that
was backed up.
FROM
VOLUME
FRVOL
This field contains the volume serial number of the user volume on
which the data set resided when the backup version was made. If
the data set was migrated at the time of the backup, this field
contains the volume serial number of the user volume from which
the data set migrated.
BACKUP
DATE
BACKDATE
This field contains the date the backup version was created.
BACKUP
TIME
BACKTIME
This field contains the time the backup version was created.
114
z/OS DFSMShsm Managing Your Own Data
HLIST
Table 9. HLIST--Listing Information from the BCDS and MCDS (continued)
Printer Output
Heading
Terminal Label
Description
UNS/
RET
UNS/RET
This field indicates special conditions or exceptions. UNS indicates
that the data set was unserialized when backed up. RET indicates
that the version listed is a retired version. U/R indicates an
unserialized, retired version. NO indicates a version that is neither
unserialized nor retired.
RET DAYS
RETDAYS
This field contains the RETAINDAYS parameter specified at the time
of backup. The value represents the minimum number of days that
DFSMShsm maintains the backup copy. ***** indicates that
RETAINDAYS is not specified.
Figure 33 is a sample printer list that you would get if you specified the
DATASETNAME and SELECT(VOLUME(volser)) parameters and the volume
specified was a backup volume.
- DFSMSHSM CONTROL DATASET - LATEST VERSION BACK01-- LISTING ----- AT 12:51:21 ON 09/01/22 FOR SYSTEM=3090
DATA SET NAME
FROM
VOLUME
BACKUP
DATE
BACKUP
TIME
HSMATH0.SMSDS4.N01.KSDS
HSMATH0.SMSDS4.N04.PSFB
SMS001
SMS001
09/01/22
09/01/22
12:49:32
12:49:58
UNS/
RET
NO
NO
RET
DAYS
00999
00034
----- END OF - LATEST VERSION BACK01 - LISTING -----
Figure 33. Sample Printer List When You Specify DATASETNAME and SELECT(VOLUME(volser))
Figure 34 is a sample terminal list that you would get if you specified the
DATASETNAME, SELECT(VOLUME(volser)), and TERMINAL parameters and the
volume specified was a backup volume.
DSN= HSMATH0.SMSDS4.N04.PSFB
BACKVOL=BACK01
FRVOL=SMS001 BACKDATE=09/01/22 BACKTIME=12:49:58 UNS/RET= NO RETDAYS=00034
ARC0140I LIST COMPLETED,4 LINE(S) OF DATA
ARC0140I (CONT.) OUTPUT
Figure 34. Sample Terminal List When You Specify DATASETNAME, SELECT(VOLUME(volser)), and TERMINAL
Listing data set entries from both control data sets
You specify HLIST DATASETNAME BOTH to get a list of both the migration and
backup control data set information for all the data sets that contain the user’s
identification as the specific set of initial characters of the data set name. You
specify HLIST DATASETNAME(dsname) BOTH to get a list of both the migration
and backup control data set information for a specific data set.
The information is provided in separate lists, and the command lists the data sets
in each list in alphanumeric sequence by data set name. If you request information
for a specific data set, the list contains entries only for that data set.
If you specify SYSOUT or OUTDATASET, the lists are in the same format as that
described in Figure 28 on page 111 and Figure 31 on page 114. If you specify
TERMINAL, the lists are in the same format as that described in Figure 32 on page
114.
Chapter 17. HLIST: Listing information from the BCDS and MCDS
115
HLIST
Listing user authorization status entries
Figure 35 is a sample printer list of user entries when you specify the USER (userid)
parameter.
--- DFSMShsm CONTROL DATASET - USER-- LISTING --- AT 15:24:51 ON 89/01/24 FOR SYSTEM=381A
USERID
D324711
G834921
H952762
M059259
M100222
S369193
S469193
TMPUSRI
AUTH
USER
USER
CNTL
USER
CNTL
CNTL
CNTL
USER
-----END OF - USER - LISTING -----
Figure 35. Sample Printer List of User Entries When You Specify USER
Listing a summary of data set entries
Table 10 presents the following information from the MCDS for the specified data
sets:
Table 10. Headings of Output When You Request Summary Information from the MCDS
Printer Output
Heading
Terminal Label
Description
MIGRATED
DATA SETS
MIGRATED
DATA SETS
This field contains the number of data sets listed.
TRACKS
MIGRATED
TRACKS
This field contains the sum of the tracks allocated for all
the data sets listed.
K-BYTES
MIGRATED
K-BYTES
This field contains the sum of the lengths of the data
sets listed in units of 1024 bytes.
Figure 36 is a sample printer list of data sets when you specify DATASETNAME
and SUMMARY.
---- DFSMShsm CONTROL DATASET - SUMMARY-- LISTING ----- AT 13:07:32 ON 89/03/23 FOR
SYSTEM=381A
MIGRATED
DATA SETS
TRACKS
MIGRATED
K-BYTES
MIGRATED
00002
000012
00000104
---- END OF - MIGRATED DATASET - LISTING ----
Figure 36. Sample Printer List When You Specify DATASETNAME and SUMMARY
116
z/OS DFSMShsm Managing Your Own Data
Chapter 18. HMIGRATE: Migrating data sets
This topic describes how to migrate data sets using ISMF or TSO. This command
applies to both SMS-managed and non-SMS-managed data sets and is intended to
supplement the automatic functions of DFSMShsm.
Using ISMF
The following steps present an example of how to use the HMIGRATE line
operator to migrate a data set. In this example, USER20.ISMF.JCL is used as a
sample data set name.
1. Generate a list of data sets as described in Chapter 4, “Methods of performing
tasks,” on page 13.
2. Enter the HMIGRATE line operator in the line operator column next to
USER20.ISMF.JCL as described in Figure 37.
Panel List Dataset Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET LIST
Entries 1-1 of 1
Enter Line Operators below:
Data Columns 3-6 of 39
LINE
OPERATOR
DATA SET NAME
---(1)---- ------------(2)-----------USER20.CLIST.CLIST
USER20.DFP220.DGTTLIB
USER20.ISMF.DGTLLIB
USER20.ISMF.DGTPLIB
USER20.ISMF.DUMP
HMIGRATE
USER20.ISMF.JCL
USER20.ISPFILE
USER20.ISPPROF
USER20.SPFLOG1.LIST
USER20.TEMP.DATASET
---------- ------ ----------- BOTTOM
Command ===>
F1=Help
F2=Split F3=End
F4=Return
F10=Left
F11=Right F12=Cursor
ALLOC
SPACE
--(3)-46
46
46
46
4684
468
46
93
2623
4684
OF DATA
ALLOC % NOT COMPRESSED
USED
USED
FORMAT
--(4)-- -(5)- ---(6)--46
0 ???
46
0 ???
46
0 ???
46
0 ???
4356
7 ???
46
90 ???
46
0 ???
93
0 ???
1311
50 ???
93
98 ???
----------- ------ ---
F7=Up
Scroll ===> HALF
F8=Down
F9=Swap
Figure 37. Data Set List Panel with HMIGRATE Selected
The HMIGRATE Entry panel appears.
3. Complete the HMIGRATE Entry panel as described in Figure 38 on page 118.
(Specify Y in the Wait for Completion field if you want to wait for HMIGRATE to
complete before returning to ISMF.)
© Copyright IBM Corp. 1984, 2017
117
HMIGRATE
Panel Utilities Help
-----------------------------------------------------------------------------HMIGRATE ENTRY PANEL
Optionally Specify One or More for
Data Set: USER20.ISMF.JCL
Current Migration Level : NOT MIGRATED
Desired Migration Level/Transition/Move . . 1
(1, 2, T, M or blank)
Wait for Completion . . . . . . . . . . . . N
(Y or N)
Data Set Password . . . . . . . . . . . . .
(if password protected)
Note: Dataset Password ignored when in ADMIN mode.
Use ENTER to Perform Hmigrate;
Use HELP Command for Help; Use END Command to Exit.
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
F3=End
F4=Return
F12=Cursor
F7=Up
F8=Down
F9=Swap
Figure 38. HMIGRATE Entry Panel
4. Press ENTER to perform the migration and redisplay the list (see Figure 39).
The asterisk next to the HMIGRATE in the line operator column indicates that the
migration was successful if you specified Wait for Completion=Y, or that the
migration task was successfully issued to DFSMShsm if you specified Wait for
Completion=N.
Panel List Dataset Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET LIST
Entries 1-1 of 1
Enter Line Operators below:
Data Columns 3-6 of 39
LINE
OPERATOR
---(1)----
*HMIGRATE
----------
ALLOC
DATA SET NAME
SPACE
------------(2)------------ --(3)-USER20.CLIST.CLIST
46
USER20.DFP220.DGTTLIB
46
USER20.ISMF.DGTLLIB
46
USER20.ISMF.DGTPLIB
46
USER20.ISMF.DUMP
4684
USER20.ISMF.JCL
468
USER20.ISPFILE
46
USER20.ISPPROF
93
USER20.SPFLOG1.LIST
2623
USER20.TEMP.DATASET
4684
------ ----------- BOTTOM OF DATA
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
F3=End
F4=Return
F12=Cursor
ALLOC % NOT COMPRESSED
USED
USED FORMAT
--(4)-- -(5)- ---(6)---46
0 ???
46
0 ???
46
0 ???
46
0 ???
4356
7 ???
46
90 ???
46
0 ???
93
0 ???
1311
50 ???
93
98 ???
----------- ------ ----
F7=Up
Scroll ===> HALF
F8=Down
F9=Swap
Figure 39. Data Set List Panel After Function Completes
For more information on using DFSMShsm/ISMF line operators, see z/OS DFSMS
Using the Interactive Storage Management Facility or use the online help that is
provided with ISMF.
118
z/OS DFSMShsm Managing Your Own Data
HMIGRATE
Using TSO commands
The following information applies to both SMS-managed and non-SMS-managed
data sets.
Task: Migrate one or more data sets to migration volumes. For SMS-managed data
sets only, you can also perform class transition.
The data set migrates to a level 1 migration volume unless you specify the
MIGRATIONLEVEL2 parameter in the command or you are in an environment
that migrates directly to migration level 2 volumes. An SMS-managed data set, for
example, can migrate directly to a level 2 volume if defined to do so by a
management class parameter. You can cause a data set on a level 1 migration
volume to migrate to a level 2 migration volume if you specify a data set that is
already on a level 1 migration volume and you specify the MIGRATIONLEVEL2
parameter.
Command migration or class transition processing of SMS-managed data sets is
available only for eligible data sets. Data set eligibility is determined by an SMS
management class attribute. If you issue HMIGRATE for a data set that is not
eligible for migration, the HMIGRATE operation ends and DFSMShsm issues
message ARC1245I.
If choosing class transition for a data set (SMS-managed only), note that class
transition processing is mutually exclusive with any of the migration-related
options.
RACF Authority: To migrate a RACF-protected data set, you must have RACF
UPDATE authority to the data set.
Abbreviation: The minimum abbreviation for the HMIGRATE command is HMIG.
Syntax
The following diagram presents the syntax of the HMIGRATE command for both
SMS-managed and non-SMS-managed data sets:
,
(1)
►► HMIGRATE
( ▼ dsname
(2)
)
►
/password
|
►
►
MIGRATIONLEVEL2
ML2
MOVE
(3)
TRANSITION
TRANSITION Optional SMS Parameters
TRN
CLOUD(SMScloudname)
WAIT
NOWAIT
Chapter 18. HMIGRATE: Migrating data sets
119
HMIGRATE
►
►◄
EXTENDRC
TRANSITION Optional SMS Parameters:
(
MANAGEMENTCLASS ( mclass1
MC
MCLASS
)
STORAGECLASS ( sclass1
SC
SCLASS
)
►
,
►
STORAGEGROUP
SG
SGROUP
STRGRP
( ▼ sgn
)
)
Notes:
1
Password does not apply to SMS-managed data sets.
2
Parentheses around data set names are required only when multiple data set
names are specified.
3
TRANSITION applies to SMS-managed data sets only.
Required parameters
dsname: Specifying the name of the data set that is to migrate
Explanation: (dsname/password ...) is a required positional parameter specifying
the name of the cataloged data set or list of names of cataloged data sets that are
to migrate. For dsname, substitute the name or list of names of the data sets (in
parentheses) that are to migrate. You can use a data set filter for any dsname in a
list. See “Specifying data set names” on page 37 for a discussion of how to specify
data set names.
For password, substitute the correct password and include the preceding slash (/).
TSO does not prompt you for the password. Password protection does not apply to
SMS-managed data sets; if a password is specified, it is ignored.
v For password-protected non-VSAM data sets, you must supply the password
that allows you to write to the data set.
v For password-protected VSAM data sets, you must supply the master password
of the base cluster.
Abbreviations: None.
Defaults: None.
Restrictions:
v Because dsname is a required positional parameter, you must specify it
immediately after HMIGRATE.
v The volume on which the data set resides must be mounted before you issue the
command.
120
z/OS DFSMShsm Managing Your Own Data
HMIGRATE
v When you specify a password with a filter, all the data sets protected by a
password must have the same password. Otherwise, DFSMShsm authorization
checking fails the migration of those data sets that are protected by a different
password.
v DFSMShsm does not process individual partitioned data set members. If you
specify a partitioned data set name with a member name, DFSMShsm fails the
HMIGRATE command.
v If dsname is fully qualified and refers to a VSAM data set, specify the base
cluster name, or any component name, or any path name. The entire VSAM
sphere will be migrated. If the sphere has more than one alternate index (AIX),
more than one path, or more than one path on the AIX, the data set can be
recalled by the base cluster name only.
v If you migrate a VSAM data set with more than one path per alternate index,
only the last path listed in the catalog is preserved. After the migration, you
must redefine any other paths that are needed.
Optional parameters
MIGRATIONLEVEL2: Specifying migration of a data set directly
to a level 2 volume
Explanation: MIGRATIONLEVEL2 is an optional parameter you use to migrate a
data set from a level 0 volume or a migration level 1 volume to a migration level 2
volume. The MIGRATIONLEVEL2 parameter must be specified if you are
migrating an already migrated data set.
Abbreviations: The TSO abbreviation convention applies for
MIGRATIONLEVEL2. In addition, you can use the abbreviation ML2.
Defaults: None.
Restrictions:
You can specify either MIGRATIONLEVEL2/ML2 or TRANSITION, but not both.
TRANSITION: Specifying whether the data set should go through
transition processing
Explanation: TRANSITION is an optional parameter that you use to specify
whether the data set is to go through transition processing. It is valid only for
SMS-managed data sets.
The optional subparameters of the TRANSITION parameter are:
MANAGEMENTCLASS
Specifies the target management class used for class transition. Aliases: MC,
MCLASS
STORAGECLASS
Specifies the target storage class used for class transition processing. Aliases:
SC, SCLASS
STORAGEGROUP
Specifies the target storage group list used for class transition processing. Up
to 15 storage groups can be specified by this parameter. If STORAGEGROUP is
specified with more than 15 storage groups, only the first 15 are processed.
Aliases: SG, SGROUP, STRGRP
Chapter 18. HMIGRATE: Migrating data sets
121
HMIGRATE
Note: If at least one SMS parameter is specified, then the specified value or values
are used and the ACS routine is not called during class transition processing. The
omitted values of management class, storage class, or storage group are taken from
the data set's SMS construct.
Abbreviations: The TSO abbreviation convention applies for TRANSITION. There
are no additional abbreviations.
Defaults: None.
Restrictions: You can specify either MIGRATIONLEVEL2/ML2 or TRANSITION,
but not both.
|
|
CLOUD: Specifying migration of a data set directly to Cloud
storage
|
|
|
|
|
|
Explanation: CLOUD is an optional parameter specifying that a data set migrates
from an SMS managed volume to the requested Cloud storage. The SMS
cloudname is defined in the SMS Cloud construct. When the cloud name is
specified, the data set is migrated to the requested Cloud storage, regardless of the
data set management class attributes (with the exception of migration, which is not
allowed). It is valid only for SMS-managed data sets.
|
The CLOUD parameter cannot be specified with the following parameters:
|
MIGRATIONLEVEL1, MIGRATIONLEVEL2, and CONVERT.
|
|
Note: When you perform a Migrate to Cloud storage, the following DFSMShsm
SETSYS settings do not apply:
|
|
|
COMPACT, COMPACTPERCENT, COMPACT(ALL)
Because data movement is not performed by the host, there is no opportunity
to perform compression on the backup on Cloud storage.
|
|
|
CONVERSION(REBLOCKTOANY)
Because data movement is not performed by the host, there is no opportunity
to perform re-blocking of a data set.
|
|
|
CONCURRENT
Migrating a data set to Cloud storage ignores any current setting that relates to
concurrent.
|
WAIT and NOWAIT: Specifying whether to wait for data set
migration
Explanation: WAIT | NOWAIT are mutually exclusive, optional parameters that
specify whether you want to wait for the HMIGRATE command to complete.
WAIT specifies that you want to wait for the HMIGRATE command to complete.
When DFSMShsm successfully completes the HMIGRATE process, an ARC1000I
message is issued. If the HMIGRATE process does not complete successfully, an
ARC1001I message is issued. If you press the TSO Attention key before DFSMShsm
completes the command, DFSMShsm issues an ARC1800I message and does not
issue an ARC1000I message.
NOWAIT specifies that you do not want to wait for the HMIGRATE command to
complete. When DFSMShsm successfully receives the request, an ARC1007I
message is issued. After DFSMShsm successfully completes the HMIGRATE
122
z/OS DFSMShsm Managing Your Own Data
HMIGRATE
command, an ARC1000I message is issued. If the HMIGRATE command does not
complete successfully, an ARC1001I message is issued.
Abbreviations: The TSO abbreviation convention applies for WAIT and NOWAIT.
There are no additional abbreviations.
Defaults: The default is NOWAIT.
Restrictions: You can specify either WAIT or NOWAIT, but not both.
MOVE: Specifying that the data set should go through data set
moving processing
Explanation: MOVE is an optional parameter that specifies that the data set
should go through the data set moving processing. MOVE is mutually exclusive
with the migration related parameters.
Abbreviations: The TSO abbreviation convention applies for MOVE.
Defaults: None.
Restrictions: MOVE is mutually exclusive with the migration-related parameters.
EXTENDRC: Requesting an extended set of return and reason
codes
Explanation: MOVE is an optional parameter that specifies that the data set
should go through the data set moving processing. MOVE is mutually exclusive
with the migration related parameters.
Abbreviations: The TSO abbreviation convention applies for EXTENDRC.
Defaults: None.
Restrictions: The WAIT option must be specified with the EXTENDRC parameter
when you are running DFSMShsm commands in a truly interactive mode (TSO or
foreground).
Examples of different ways to code the HMIGRATE command
The examples below present different ways to code the HMIGRATE command. The
values are examples only. Do not interpret them as values that you should use for
your system.
Causing multiple data sets to migrate and not waiting for
completion
In this example, you are issuing the HMIGRATE command to migrate all data sets
that have the same user prefix and descriptive qualifier, GRPA.*.OUTLIST, from
level 0 volumes. The NOWAIT parameter indicates that you do not want to wait
for DFSMShsm to complete the migration of the data sets.
HMIGRATE ’GRPA.*.OUTLIST’ NOWAIT
If your datasetname filter specification includes already-migrated data sets,
DFSMShsm does not attempt to migrate these data sets.
Chapter 18. HMIGRATE: Migrating data sets
123
HMIGRATE
Causing a password-protected data set to migrate
In this example, you are issuing the HMIGRATE command to migrate the data set
CLARK.TEXTVER3.TEXT protected by the password WRITE from a level 0
volume. The WAIT parameter indicates that you want to wait for DFSMShsm to
complete the migration of the data set.
HMIGRATE ’CLARK.TEXTVER3.TEXT’/WRITE WAIT
Causing a password-protected data set to go through transition
processing
In this example, you are issuing the HMIGRATE command to cause the data set
CLARK.TEXTVER3.TEXT, protected by the password WRITE, to go through
transition processing. The WAIT parameter indicates that you want to wait for the
transition processing to complete.
HMIGRATE ’CLARK.TEXTVER3.TEXT’/WRITE WAIT TRANSITION
Causing data sets to migrate to level 2 volumes and not waiting
for completion
In this example, you are issuing the HMIGRATE command to migrate all data sets
that have the same user prefix and descriptive qualifier, GRPA.*.OUTLIST, from
level 0 volumes or migration level 1 volumes (ML1) to migration level 2 volumes
(ML2). The NOWAIT parameter indicates that you do not want to wait for
DFSMShsm to complete the migration of the data sets.
HMIGRATE ’GRPA.*.OUTLIST’ MIGRATIONLEVEL2 NOWAIT
Causing multiple data sets to migrate to level 2 volumes and not
waiting for completion
In this example you are issuing the HMIGRATE command to migrate two data
sets, USER01.TEXTVER3.TEXT and USER01.APGOUT.LOADLIST, which are both
protected by the password WRITE from level 0 volumes directly to migration level
2 volumes. Your user ID prefix is USER01. The NOWAIT parameter indicates that
you do not want to wait for DFSMShsm to complete the migration of the data sets.
HMIGRATE (TEXTVER3.TEXT/WRITE APGOUT.LOADLIST/WRITE) MIGRATIONLEVEL2 NOWAIT
Migrating a data set and requesting to see the return codes and
reason codes
In this example, you are issuing the HMIGRATE command from a TSO session to
migrate the data set VOLUN.TEXTVER2.TEXT from a level 0 volume to a
migration volume. The WAIT EXTENDRC parameter indicates that you want to
see the extended return and reason codes.
HMIGRATE ’VOLUN.TEXTVER2.TEXT’ WAIT EXTENDRC
124
z/OS DFSMShsm Managing Your Own Data
Chapter 19. HQUERY: Listing pending requests
To list pending requests, use the HQUERY command in TSO. The following
discussion applies to both SMS-managed data sets and non-SMS-managed data
sets.
Using TSO commands
Task: Display pending DFSMShsm requests associated with your user
identification.
You can display specific requests by request number or you can display all of the
requests for a specific data set name. To display all pending requests associated
with your user identification, issue the HQUERY command without parameters.
For an example of the messages displayed in response to an HQUERY command,
see “Messages from the HQUERY command” on page 127.
Abbreviation: The minimum abbreviation for the HQUERY command is HQ.
Syntax
The following diagram presents the syntax of the HQUERY command for both
SMS-managed and non-SMS-managed data sets:
►► HQUERY
►◄
,
DATASETNAME ( ▼ dsname
,
)
REQUEST
( ▼ reqnum
)
Required parameters
None.
Optional parameters
DATASETNAME: Specifying a list of requests by data set name
Explanation: DATASETNAME(dsname ...) is an optional parameter you use to
display pending requests associated with one or more specified data set names.
For dsname, substitute the name or names of the data sets for which you want the
list of requests. You cannot use any wild cards (%, *, or **) in a data set name.
Abbreviations: The TSO abbreviation convention applies for DATASETNAME.
There are no additional abbreviations.
Defaults: If you do not specify HQUERY with either DATASETNAME(dsname) or
REQUEST(reqnum), the list contains all pending requests associated with your user
identification.
© Copyright IBM Corp. 1984, 2017
125
HQUERY
Restrictions: DFSMShsm does not process individual partitioned data set
members. If you specify a partitioned data set name with a member name,
DFSMShsm ignores the member name and lists the requests for the entire
partitioned data set.
REQUEST: Specifying a list of requests by request number
Explanation: REQUEST(reqnum ...) is an optional parameter you can use to
display specific pending requests for your user identification. For reqnum,
substitute the DFSMShsm request number. A request number is given when a
DFSMShsm command is accepted and you specify that you do not want to wait
for completion of the command.
To display all of the pending requests associated with your user identification,
issue the HQUERY command by itself.
Abbreviations: The TSO abbreviation convention applies for REQUEST. There are
no additional abbreviations.
Defaults: If you do not specify HQUERY with either DATASETNAME(dsname) or
REQUEST(reqnum), the list contains all pending requests associated with your user
identification.
Restrictions: None.
Examples of different ways to code the HQUERY command
The examples below present different ways to code the HQUERY command. The
values are examples only. Do not interpret them as values that you should use for
your system.
Listing pending requests for a data set
In this example, you are issuing the HQUERY command to list the pending
DFSMShsm requests for the data set ELPA.OUTTESTS.TESTLIST and request
number 104.
HQUERY DATASETNAME(’ELPA.OUTTESTS.TESTLIST’) REQUEST(104)
Listing all pending requests for your user identification
In this example, you are issuing the HQUERY command to list all pending
DFSMShsm requests that are associated with your user identification.
HQUERY
Listing pending requests by request number
In this example, you are issuing the HQUERY command to list three pending
DFSMShsm requests, 25, 27, and 28.
HQUERY REQUEST(25,27,28)
126
z/OS DFSMShsm Managing Your Own Data
HQUERY
Messages from the HQUERY command
When you issue the HQUERY command, the information appears as a message at
your terminal as well as on the DFSMShsm log. Table 11 presents the messages
associated with the HQUERY command.
Table 11. Messages Associated with the QUERY Command by Parameter Name
Parameter name
Message
DATASETNAME
(dsname)
ARC0101I QUERY {ACTIVE | ABARS | ARPOOL | AUTOPROGRESS | BACKUP |
CDSVERSIONBACKUP | CONTROLDATASETS | CSALIMITS | DATASETNAME |
MIGRATIONLEVEL2 | POOL/VOLUMEPOOL | REQUEST | RETAIN | SETSYS | SPACE
| STARTUP | STATISTICS | TRAPS | USER | WAITING} COMMAND {STARTING |
COMPLETED | IGNORED} ON HOST=x
ARC0161I {MIGRATING | MIGRATION PREPROCESSING | FREEVOL PROCESSING |
DBA/DBU PROCESSING | BACKING UP | RECOVERING | RECYCLING | AUDITING
| {DUMPING | FRBACKUP DUMP OF | FRBACKUP DUMPONLY OF} | MOUNTING
INITIAL TAPE FOR DS BACKUP,| RESTORING} VOLUME {volser | volser, SGROUP=sg |
volser, COPY POOL = cpname} FOR USER {userid | **AUTO** | *} REQUEST {request-number
| NONE | *} [, TCB=X'tcbaddress'| TCB2=X'tcbaddress' | TCB=X'****?***']
ARC0162I {MIGRATING | BACKING UP | RECALLING | RECOVERING | DELETING |
RESTORING | FRRECOV OF} DATA SET dsname FOR USER userid, REQUEST request ON
HOST hostid [,TCB=X'tcbaddress']
ARC0165I USER NOT AUTHORIZED TO QUERY REQUESTS FOR OTHER USERIDS OR
REQNUM MISSING
ARC0166I NO DFSMSHSM REQUEST FOUND FOR QUERY
ARC0167I type MWE FOR {VOLUME | DATA SET | COMMAND | AGGREGATE GROUP
| CONTROL FILE DATA SET | COPY POOL} {name |name, SGROUP = sg | name, COPY
POOL = cpname} FOR USER userid, REQUEST request, WAITING TO BE PROCESSED, nmwe
MWE(S) AHEAD OF THIS ONE
ARC1543I type MWE FOR DATA SET name, FOR USER userid, REQUEST request_number,
WAITING TO BE PROCESSED ON A COMMON QUEUE, nmwe MWES AHEAD OF THIS
ONE{, REQUEST ORIGINATED ON HOST hostid}
Chapter 19. HQUERY: Listing pending requests
127
HQUERY
Table 11. Messages Associated with the QUERY Command by Parameter Name (continued)
Parameter name
Message
REQUEST
ARC0101I QUERY {ACTIVE | ABARS | ARPOOL | AUTOPROGRESS | BACKUP |
CDSVERSIONBACKUP | CONTROLDATASETS | CSALIMITS | DATASETNAME |
MIGRATIONLEVEL2 | POOL/VOLUMEPOOL | REQUEST | RETAIN | SETSYS | SPACE
| STARTUP | STATISTICS | TRAPS | USER | WAITING} COMMAND {STARTING |
COMPLETED | IGNORED} ON HOST=x
ARC0161I {MIGRATING | MIGRATION PREPROCESSING | FREEVOL PROCESSING |
DBA/DBU PROCESSING | BACKING UP | RECOVERING | RECYCLING | AUDITING
| {DUMPING | FRBACKUP DUMP OF | FRBACKUP DUMPONLY OF} | MOUNTING
INITIAL TAPE FOR DS BACKUP,| RESTORING} VOLUME {volser | volser, SGROUP=sg |
volser, COPY POOL = cpname} FOR USER {userid | **AUTO** | *} REQUEST {request-number
| NONE | *} [, TCB=X'tcbaddress'| TCB2=X'tcbaddress' | TCB=X'****?***']
ARC0162I {MIGRATING | BACKING UP | RECALLING | RECOVERING | DELETING |
RESTORING | FRRECOV OF} DATA SET dsname FOR USER userid, REQUEST request ON
HOST hostid [,TCB=X'tcbaddress']
ARC0165I USER NOT AUTHORIZED TO QUERY REQUESTS FOR OTHER USERIDS OR
REQNUM MISSING
ARC0166I NO DFSMSHSM REQUEST FOUND FOR QUERY
ARC0167I type MWE FOR {VOLUME | DATA SET | COMMAND | AGGREGATE GROUP
| CONTROL FILE DATA SET | COPY POOL} {name |name, SGROUP = sg | name, COPY
POOL = cpname} FOR USER userid, REQUEST request, WAITING TO BE PROCESSED, nmwe
MWE(S) AHEAD OF THIS ONE
ARC1543I type MWE FOR DATA SET name, FOR USER userid, REQUEST request_number,
WAITING TO BE PROCESSED ON A COMMON QUEUE, nmwe MWES AHEAD OF THIS
ONE{, REQUEST ORIGINATED ON HOST hostid}
ARC1822I {FRBACKUP | FRRECOV | FRBACKUP DUMP OR DUMPONLY | FRRECOV
FROMDUMP} OF COPY POOL cpname FOR USER userid, REQUEST request-number ON
HOST host_id IS IN PROGRESS: NOT PROCESSED = xx, TOTAL = yy
128
z/OS DFSMShsm Managing Your Own Data
Chapter 20. HRECALL: Recalling data sets
This topic describes how to recall one or more data sets using ISMF or TSO. This
command applies to both SMS-managed and non-SMS-managed data sets and is
intended to supplement the automatic functions of DFSMShsm.
Using ISMF
The following steps present an example of how to use the HRECALL line operator
to recall one or more data sets. In our example, we have used USER20.ISMF.JCL as
a sample data set name.
1. Generate a list of data sets as described in Chapter 4, “Methods of performing
tasks,” on page 13.
2. Enter the HRECALL line operator in the line operator column next to
USER20.ISMF.JCL as described in Figure 40.
Panel List Dataset Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET LIST
Entries 1-1 of 1
Enter Line Operators below:
Data Columns 3-6 of 39
LINE
OPERATOR
---(1)----
HRECALL
----------
ALLOC
DATA SET NAME
SPACE
------------(2)------------ --(3)-USER20.CLIST.CLIST
46
USER20.DFP220.DGTTLIB
46
USER20.ISMF.DGTLLIB
46
USER20.ISMF.DGTPLIB
46
USER20.ISMF.DUMP
4684
USER20.ISMF.JCL
468
USER20.ISPFILE
46
USER20.ISPPROF
93
USER20.SPFLOG1.LIST
2623
USER20.TEMP.DATASET
4684
------ ----------- BOTTOM OF DATA
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
F3=End
F4=Return
F12=Cursor
ALLOC % NOT COMPRESSED
USED
USED FORMAT
--(4)-- -(5)- ---(6)---46
0 ???
46
0 ???
46
0 ???
46
0 ???
4356
7 ???
46
90 ???
46
0 ???
93
0 ???
1311
50 ???
93
98 ???
----------- ------ ----
F7=Up
Scroll ===> HALF
F8=Down
F9=Swap
Figure 40. Data Set List Panel with HRECALL Selected
The HRECALL Entry panel appears.
3. Complete the HRECALL Entry panel as described in Figure 41 on page 130.
(Specify Y in the wait for completion field if you want to wait for HRECALL to
complete before returning to ISMF. Specify N in the wait for completion field if
you do not want to wait for HRECALL to complete before returning to ISMF.)
© Copyright IBM Corp. 1984, 2017
129
HRECALL
Panel Utilities Help
-----------------------------------------------------------------------------HRECALL ENTRY PANEL
Optionally Specify One or More for
Data Set: USER20.ISMF.JCL
To Recall to a Specific Volume, Specify:
Volume Serial Number . .
(target volume)
Device Type . . . . . . .
(target device type)
DA Access Option
. . . . .
(SAMETRK, RELTRK OR RELBLK)
Wait for Completion . . . . N
(Y or N)
Data Set Password . . . . .
(if password protected)
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
F3=End
F4=Return
F12=Cursor
F7=Up
F8=Down
F9=Swap
Figure 41. HRECALL Entry Panel
4. Press ENTER to perform the recall and redisplay the list (see Figure 42).
The asterisk next to HRECALL in the line operator column indicates that the recall
was successful if you specified wait for completion=Y, or that the HRECALL task
was successfully issued to DFSMShsm if you specified wait for completion=N.
Panel List Dataset Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET LIST
Entries 1-1 of 1
Enter Line Operators below:
Data Columns 3-6 of 39
LINE
OPERATOR
---(1)----
*HRECALL
----------
ALLOC
DATA SET NAME
SPACE
------------(2)------------ --(3)-USER20.CLIST.CLIST
46
USER20.DFP220.DGTTLIB
46
USER20.ISMF.DGTLLIB
46
USER20.ISMF.DGTPLIB
46
USER20.ISMF.DUMP
4684
USER20.ISMF.JCL
468
USER20.ISPFILE
46
USER20.ISPPROF
93
USER20.SPFLOG1.LIST
2623
USER20.TEMP.DATASET
4684
------ ----------- BOTTOM OF DATA
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
F3=End
F4=Return
F12=Cursor
ALLOC % NOT COMPRESSED
USED
USED FORMAT
--(4)-- -(5)- ---(6)---46
0 ???
46
0 ???
46
0 ???
46
0 ???
4356
7 ???
46
90 ???
46
0 ???
93
0 ???
1311
50 ???
93
98 ???
----------- ------ ----
F7=Up
Scroll ===> HALF
F8=Down
F9=Swap
Figure 42. Data Set List Panel After Function Completes
For more information on using DFSMShsm/ISMF line operators, see z/OS DFSMS
Using the Interactive Storage Management Facility or use the online help provided
with ISMF.
130
z/OS DFSMShsm Managing Your Own Data
HRECALL
Using TSO commands
The commands for recalling SMS-managed and non-SMS-managed data sets are
different.
When you are recalling SMS-managed data sets, the SMS allocation services used
in your computing center directs the return of your data set. When you are
recalling non-SMS-managed data sets or uncataloged data sets, you can direct the
return of your data set to a specific volume.
Recalling one or more data sets with TSO
Task: Recall one or more migrated data sets.
When you are recalling an SMS-managed data set, the automatic class selection
(ACS) routines determine whether a data set should be SMS-managed or not. If a
data set is going to be SMS-managed, the ACS routines select a target storage
group and from the volumes that belong to that storage group, a target volume is
chosen on which to place the data set.
When you are recalling non-SMS-managed data sets, you can specify to which
volume you want DFSMShsm to recall the data sets. If you do not specify the
volume, DFSMShsm selects the volume.
It is not considered an error when you are recalling a data set that is not cataloged
to the volume MIGRAT. If this occurs, the informational message ARC1102I will be
issued and a zero will be returned in register 15.
RACF authority: To recall a RACF-protected data set, you must have RACF
EXECUTE authority to the data set.
Abbreviation: The minimum abbreviation for the HRECALL command is HRECA.
Syntax
The following diagram presents the syntax of the HRECALL command for
SMS-managed data sets:
,
(1)
►► HRECALL
( ▼ dsname
)
►◄
WAIT
NOWAIT
EXTENDRC
Notes:
1
Parentheses around data set names are required only when multiple data set
names are specified.
The following diagram presents the syntax of the HRECALL command for
non-SMS-managed data sets:
,
(1)
►► HRECALL
( ▼ dsname
)
/password
►
UNIT
( unittype
)
Chapter 20. HRECALL: Recalling data sets
131
HRECALL
►
►
VOLUME
( volser
)
WAIT
NOWAIT
EXTENDRC
►
►◄
DAOPTION
(
SAMETRK
RELTRK
RELBLK
)
Notes:
1
Parentheses around data set names are required only when multiple data set
names are specified.
Required parameters
dsname: Specifying the name of the data set to be recalled
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: (dsname...) or (dsname/password ...) is a required positional parameter
you use to specify the name of the data set or list of data set names that you want
to recall. For dsname, substitute the name of the data set or list of data set names
that you want to recall. You can use a data set filter for any data set name in a list.
See “Specifying data set names” on page 37 for a discussion of how to specify data
set names.
For password, substitute the correct password and include the preceding slash (/).
TSO does not prompt you for the password.
v For a password-protected non-VSAM data set, you must supply the password
that allows you to read the data set.
v For a password-protected VSAM data set, you must supply the master password
of the base cluster.
Abbreviations: None.
Defaults: None.
Restrictions:
v Because dsname is a required positional parameter, you must specify it
immediately after HRECALL.
v DFSMShsm does not process individual members of partitioned data sets. If you
specify a partitioned data set name with a member name, message ARC1065I is
issued and nothing is recalled.
v If dsname is fully qualified and refers to a VSAM data set, specify the base
cluster name, or any component name, or any path name.
v If you recall a VSAM data set with more than one path per alternate index, only
the last path listed in the catalog is preserved. After the migration, you must
redefine any other paths that are needed.
132
z/OS DFSMShsm Managing Your Own Data
HRECALL
v When you specify a password with a filter, all the affected data sets protected by
a password must have the same password. Otherwise, DFSMShsm authorization
checking fails the recall of those password-protected data sets that are protected
by some other password.
Optional parameters
DAOPTION: Selecting target volume track length
This parameter applies only to data that will be returned to a non-SMS-managed
DASD volume.
Explanation: DAOPTION(SAMETRK | RELTRK | RELBLK) are mutually
exclusive, optional parameters specifying the type of data set accessing required
(relative track or relative block) upon recall of a direct access data set. This, in turn,
will imply the allowable target volume device types.
SAMETRK specifies that if DFSMShsm is not directed to a volume by the
VOLUME parameter, it will select a target volume with the same track length as
the last L0 volume from which the data set was migrated. If DFSMShsm is directed
to a specific volume by the VOLUME parameter, this volume must have the same
track length as the last L0 volume from which the data set was migrated.
Data will be moved as a track-to-track image, accessible for both relative track and
relative block processing.
RELTRK specifies that if DFSMShsm is not directed to a volume by the VOLUME
parameter, it will attempt to select a target volume with the same track length as
the last L0 volume from which the data set was migrated. If no volume with equal
track length is available, then the target volume selected may have a larger track
length than the last L0 volume. If DFSMShsm is directed to a specific volume by
the VOLUME parameter, this volume must have the same or greater track length
than the last L0 volume from which the data set was migrated.
Data will be moved as a track-to-track image, accessible by relative track
addressing.
RELBLK specifies that if DFSMShsm is not directed to a volume by the VOLUME
parameter, it will attempt to select a target volume with the same track length as
the last L0 volume from which the data set was migrated. If no volume with equal
track length is available, then the target volume selected may have a larger or
smaller track length than the last L0 volume. If DFSMShsm is directed to a specific
volume by the VOLUME parameter, this volume can have any track length.
Data will be moved to fill out the track, accessible by relative block addressing.
Abbreviations: TSO abbreviation convention applies for this parameter. There are
no additional abbreviations.
Defaults: If DAOPTION is not specified, the target volume selection is unchanged
and data is moved as a track image, allowing for relative track accessing.
Note: Only direct access (BDAM) data sets are supported by this option. Using
DAOPTION to recall a data set as SMS-managed is not supported. If a data set
would be SMS-managed after the recall, the FORCENONSMS parameter of the
RECALL command must be used to force it to be non-SMS-managed.
Chapter 20. HRECALL: Recalling data sets
133
HRECALL
EXTENDRC: Requesting an extended set of return and reason
codes
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: EXTENDRC is an optional parameter you use to specify that
DFSMShsm should return an extended set of return and reason codes while you
are running DFSMShsm commands in a truly interactive mode (TSO or
foreground). This option returns only the return and reason codes that are mapped
into DFSMShsm messages that are issued to the user’s terminal. For detailed
information on return codes that DFSMShsm returns for this command, see
Appendix B, “Return codes from DFSMShsm commands,” on page 189.
Abbreviations: The TSO abbreviation convention applies for EXTENDRC.
Defaults: None.
Restrictions: The WAIT option must be specified with the EXTENDRC parameter
when you run DFSMShsm commands in a truly interactive mode (TSO or
foreground).
UNIT: Specifying the type of unit for the receiving volume
This parameter applies only to data that will be returned to a non-SMS-managed
DASD volume.
Explanation: UNIT(unittype) is an optional parameter you use to specify the type
of unit where the receiving volume can be allocated. For unittype, substitute the
type of unit where the volume that is to receive the recalled data set can be
allocated. The valid types of units are 3380, 3390, and 9345.
Abbreviations: The TSO abbreviation convention applies for UNIT. There are no
additional abbreviations.
Defaults: None.
Restrictions:
v If you specify UNIT, you must also specify VOLUME.
v If the block size of the data set is greater than the track capacity of the target
volume, track overflow must be supported in both the software and the
hardware. This applies to devices whose track size is less than 32K.
VOLUME: Specifying the volume to receive the recalled data set
This parameter applies only to data that will be returned to a non-SMS-managed
DASD volume.
Explanation: VOLUME(volser) is an optional parameter you use to specify the
volume that is to receive the recalled data set. The volume does not have to be
managed by DFSMShsm. For volser, substitute the serial number of the volume that
is to receive the recalled data set.
The volume specified with the HRECALL command can be a DFSMShsm-managed
volume or a volume not managed by DFSMShsm. If you do not specify the
VOLUME parameter on the HRECALL command, DFSMShsm uses its defaults for
volume selection.
Abbreviations: The TSO abbreviation convention applies for VOLUME. There are
no additional abbreviations.
134
z/OS DFSMShsm Managing Your Own Data
HRECALL
Defaults: If you do not specify VOLUME, DFSMShsm recalls the data set to the
DFSMShsm-managed storage volume that has the most space available, unless the
data set is associated with a recall pool.
Restrictions:
v If you specify VOLUME, you must also specify UNIT and unittype. The volume
cannot be SMS-managed.
v If you specify the VOLUME parameter on the HRECALL command, enough
available space must exist on the specified volume for the data set recall.
Otherwise, the recall fails.
WAIT and NOWAIT: Specifying whether to wait for the data set to
be recalled
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: WAIT | NOWAIT are mutually exclusive, optional parameters you
use to specify whether to wait for the HRECALL command to complete.
WAIT specifies that you want to wait for the HRECALL command to complete. If
you are recalling data sets from tape, we recommend that you specify the
NOWAIT parameter because the operator must mount the tape before the recall
can complete.
When DFSMShsm successfully completes the HRECALL process, an ARC1000I
message is issued. If the HRECALL process does not complete successfully, an
ARC1001I message is issued. If you press the TSO Attention key before DFSMShsm
completes the command, DFSMShsm issues an ARC1800I message and does not
issue an ARC1000I message.
NOWAIT specifies that you do not want to wait for the HRECALL command to
complete. When DFSMShsm successfully receives the request, an ARC1007I
message is issued. If you are recalling data sets from tape, a volume mount request
message (ARC0612I) is issued. After DFSMShsm successfully completes the
HRECALL command, an ARC1000I message is issued. If the HRECALL command
does not complete successfully, an ARC1001I message is issued.
Abbreviations: The TSO abbreviation convention applies for WAIT and NOWAIT.
There are no additional abbreviations.
Defaults: The default is NOWAIT.
Restrictions: You can specify either WAIT or NOWAIT, but not both.
Examples of different ways to code the HRECALL command
The examples below present different ways to code the HRECALL command. The
values are examples only. Do not interpret them as values that you should use for
your system.
Recalling two SMS-managed data sets and not waiting for
completion
In this example, you are issuing the HRECALL command to recall two
SMS-managed data sets, ELMST.TEXTVER3.TEXT and ELMST.VER1TEXT.LIST.
Because the data are SMS-managed, SMS directs the return of the data sets. The
NOWAIT parameter indicates that you do not want to wait for DFSMShsm to
complete the recall of the data sets.
Chapter 20. HRECALL: Recalling data sets
135
HRECALL
HRECALL (’ELMST.TEXTVER3.TEXT’,’ELMST.VER1TEXT.LIST’) NOWAIT
Recalling a group of data sets and not waiting for completion
In this example, you are issuing the HRECALL command to recall all data sets that
have ELMST.*.TEXT as the user prefix and descriptive qualifier. The NOWAIT
parameter indicates that you do not want to wait for DFSMShsm to complete the
recall of the data sets.
HRECALL ’ELMST.*.TEXT’ NOWAIT
Recalling a data set and requesting to see the return code and
reason code
In this example, you are issuing the HRECALL command from a TSO session to
recall the data set BROWN.TEXTVER6.TEXT to a DFSMShsm-managed volume.
The WAIT EXTENDRC parameter indicates that you want to see the extended
return and reason codes.
HRECALL ’BROWN.TEXTVER6.TEXT’ WAIT EXTENDRC
Recalling a password-protected data set to a specific volume
and waiting for completion
In this example, you are issuing the HRECALL command to recall the data set
CRPA.COMMTEST.CLIST protected with password LOCK1 to volume VOL005. A
3380 is the type of unit where volume VOL005 can be allocated. The WAIT
parameter indicates that you want to wait for DFSMShsm to complete the recall of
the data set.
HRECALL ’CRPA.COMMTEST.CLIST’/LOCK1 VOLUME(VOL005) UNIT(3390) WAIT
Recalling two non-SMS-managed data sets to a
DFSMShsm-managed volume and not waiting for completion
In this example, you are issuing the HRECALL command to recall two
non-SMS-managed data sets, ELMST.TEXTVER3.TEXT and
ELMST.VER1TEXT.LIST, to a DFSMShsm-managed volume. Because you did not
specify a specific volume, DFSMShsm directs the return of the data set. The
NOWAIT parameter indicates that you do not want to wait for DFSMShsm to
complete the recall of the data sets.
HRECALL (’ELMST.TEXTVER3.TEXT’,’ELMST.VER1TEXT.LIST’) NOWAIT
Recalling a non-SMS-managed DA (BDAM) data set to a volume
with a different track length than that of the last level 0 volume
In this example, a non-SMS-managed direct access (DA) data set is recalled to a
target volume that, if no volume with equal track length is available, will have a
track length either larger or smaller than the last L0 volume from which the data
set was migrated. The data will be moved to fill out the track, allowing for relative
block accessing.
HRECALL TKS1975.SERVICE.DATA DAOPTION(RELBLK)
136
z/OS DFSMShsm Managing Your Own Data
Chapter 21. HRECOVER: Recovering data sets
This topic describes how to recover a backup version or a dump copy of a data set
using ISMF or TSO. This command applies to both SMS-managed and
non-SMS-managed data sets.
Using ISMF
The following steps present an example of how to use the HRECOVER line
operator to recover a cataloged data set. In our ISMF panel example, we have used
USER20.SAMPLE.DATASET as a sample data set name.
1. Generate a list of data sets as described in Chapter 4, “Methods of performing
tasks,” on page 13.
2. Enter the HRECOVER line operator in the line operator column next to
USER20.SAMPLE.DATASET as described in Figure 43.
Panel List Dataset Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET LIST
Entries 1-1 of 1
Enter Line Operators below:
Data Columns 3-6 of 39
LINE
OPERATOR
---(1)----
HRECOVER
----------
ALLOC
DATA SET NAME
SPACE
------------(2)------------ --(3)-USER20.CLIST.CLIST
46
USER20.DFP220.DGTTLIB
46
USER20.ISMF.DGTLLIB
46
USER20.ISMF.DGTPLIB
46
USER20.ISMF.DUMP
4684
USER20.ISPFILE
46
USER20.ISPPROF
93
USER20.SAMPLE.DATASET
468
USER20.SPFLOG1.LIST
2623
USER20.TEMP.DATASET
4684
------ ----------- BOTTOM OF DATA
Command ===>
F1=Help
F2=Split
F10=Left F11=Right
F3=End
F4=Return
F12=Cursor
ALLOC % NOT COMPRESSED
USED
USED FORMAT
--(4)-- -(5)- ---(6)---46
0 ???
46
0 ???
46
0 ???
46
0 ???
4356
7 ???
46
0 ???
93
0 ???
46
90 ???
1311
50 ???
93
98 ???
----------- ------ ----
F7=Up
Scroll ===> HALF
F8=Down
F9=Swap
Figure 43. Data Set List Panel with HRECOVER Selected
The HRECOVER entry panel appears.
3. Complete the HRECOVER entry panel as described in Figure 44 on page 138
through Figure 49 on page 140. Up to six panels can be displayed. In each
panel, the backup version, date and time of the backup are displayed as two
lists with headers.
Note: Retained backup versions are not displayed on these panels. Use the
DFSMShsm HLIST DSNAME (dsname) BCDS command to obtain a complete
list of the active and retained backup copies of this data set. To recover a
retained backup copy, specify the creation date and time of the copy to recover
on page 6 of the ISMF HRECOVER panel, or issue the HRECOVER command
with the DATE and TIME keywords.
© Copyright IBM Corp. 1984, 2017
137
HRECOVER
Panel Utilities Scroll Help
-----------------------------------------------------------------------------HRECOVER ENTRY PANEL
Page 1 of 6
Command ===>
Specify Y to recover a Backup Version for
Data Set:
Recover
Recover
Version Date
TIME Gen# (Y/N) | Version Date
TIME
Gen# (Y/N)
--------------------------------------|--------------------------------------100
2008100 162511 00
N
| 099
2008099 163501 01
N
098
2008098 162926 02
N
| 097
2008097 162551 03
N
096
2008096 162704 04
N
| 095
2008095 162905 05
N
094
2008094 162851 06
N
| 093
2008093 163301 07
N
092
2008092 162956 08
N
| 091
2008091 162918 09
N
090
2008090 162604 10
N
| 089
2008089 162945 11
N
088
2008088 162936 12
N
| 087
2008087 162651 13
N
086
2008086 162724 14
N
| 085
2008085 162705 15
N
084
2008084 162801 16
N
| 083
2008083 163103 17
N
082
2008082 162916 18
N
| 081
2008081 162938 19
N
Use ENTER to Continue; Use DOWN to select other versions;
Use HELP Command for Help; Use END Command to Cancel the HRecover.
Figure 44. HRECOVER Entry Panel (Part 1 of 6)
Panel Utilities Scroll Help
-----------------------------------------------------------------------------Panel Utilities Scroll Help
-----------------------------------------------------------------------------HRECOVER ENTRY PANEL
Page 2 of 6
Command ===>
Specify Y to recover a Backup Version for
Data Set:
Recover
Recover
Version Date
TIME Gen# (Y/N) | Version Date
TIME
Gen# (Y/N)
--------------------------------------|--------------------------------------080
2008080 162634 20
N
| 079
2008079 162935 21
N
078
2008078 162936 22
N
| 077
2008077 162531 23
N
076
2008076 162744 24
N
| 075
2008075 162805 25
N
074
2008074 162951 26
N
| 073
2008073 163101 27
N
072
2008072 162556 28
N
| 071
2008071 162718 29
N
070
2008070 162624 30
N
| 069
2008069 162925 31
N
068
2008068 162836 32
N
| 067
2008067 162611 33
N
066
2008066 162734 34
N
| 065
2008065 162805 35
N
064
2008064 162841 36
N
| 063
2008063 163133 37
N
062
2008062 162916 38
N
| 061
2008061 162918 39
N
Use ENTER to Continue; Use UP/DOWN to select other versions;
Use HELP Command for Help; Use END Command to Cancel the HRecover.
Figure 45. HRECOVER Entry Panel (Part 2 of 6)
138
z/OS DFSMShsm Managing Your Own Data
HRECOVER
Panel Utilities Scroll Help
-----------------------------------------------------------------------------HRECOVER ENTRY PANEL
Page 3 of 6
Command ===>
Specify Y to recover a Backup Version for
Data Set:
Recover
Recover
Version Date
TIME Gen# (Y/N) | Version Date
TIME
Gen# (Y/N)
--------------------------------------|--------------------------------------060
2008060 162534 40
N
| 059
2008059 163421 41
N
058
2008058 162936 42
N
| 057
2008057 162631 43
N
056
2008056 162738 44
N
| 055
2008055 162815 45
N
054
2008054 162827 46
N
| 053
2008053 163331 47
N
052
2008052 162929 48
N
| 051
2008051 162948 49
N
050
2008050 162631 50
N
| 049
2008049 162825 51
N
048
2008048 162736 52
N
| 047
2008047 162751 53
N
046
2008046 162924 54
N
| 045
2008045 162545 55
N
044
2008044 163001 56
N
| 043
2008043 163213 57
N
042
2008042 162956 58
N
| 041
2008041 162848 59
N
Use ENTER to Continue; Use UP/DOWN to select other versions;
Use HELP Command for Help; Use END Command to Cancel the HRecover.
Figure 46. HRECOVER Entry Panel (Part 3 of 6)
Panel Utilities Scroll Help
-----------------------------------------------------------------------------HRECOVER ENTRY PANEL
Page 4 of 6
Command ===>
Specify Y to recover a Backup Version for
Data Set:
Recover
Recover
Version Date
TIME Gen# (Y/N) | Version Date
TIME
Gen# (Y/N)
--------------------------------------|--------------------------------------040
2008040 162924 60
N
| 039
2008039 162835 61
N
038
2008038 162636 62
N
| 037
2008037 162921 63
N
036
2008036 162724 64
N
| 035
2008035 162635 65
N
034
2008034 162911 66
N
| 033
2008033 163201 67
N
032
2008032 162756 68
N
| 031
2008031 162748 69
N
030
2008030 162724 70
N
| 029
2008029 162825 71
N
028
2008028 162936 72
N
| 027
2008027 162711 73
N
026
2008026 162734 74
N
| 025
2008025 162705 75
N
024
2008024 162821 76
N
| 023
2008023 163233 77
N
022
2008022 162936 78
N
| 021
2008021 162958 79
N
Use ENTER to Continue; Use UP/DOWN to select other versions;
Use HELP Command for Help; Use END Command to Cancel the HRecover.
Figure 47. HRECOVER Entry Panel (Part 4 of 6)
Chapter 21. HRECOVER: Recovering data sets
139
HRECOVER
Panel Utilities Scroll Help
-----------------------------------------------------------------------------HRECOVER ENTRY PANEL
Page 5 of 6
Command ===>
Specify Y to recover a Backup Version for
Data Set:
Recover
Recover
Version Date
TIME Gen# (Y/N) | Version Date
TIME
Gen# (Y/N)
--------------------------------------|--------------------------------------020
2008020 162544 80
N
| 019
2008019 163411 81
N
018
2008018 162726 82
N
| 017
2008017 162831 83
N
016
2008016 162908 84
N
| 015
2008015 162515 85
N
014
2008014 162623 86
N
| 013
2008013 163131 87
N
012
2008012 162826 88
N
| 011
2008011 162908 89
N
010
2008010 163039 90
N
| 009
2008009 162625 91
N
008
2008008 162706 92
N
| 007
2008007 162721 93
N
006
2008006 162524 94
N
| 005
2008005 162845 95
N
004
2008004 163201 96
N
| 003
2008003 163113 97
N
002
2008002 162856 98
N
| 001
2008001 162808 99
N
Use ENTER to Continue; Use UP to select other versions;
Use HELP Command for Help; Use END Command to Cancel the HRecover.
Figure 48. HRECOVER Entry Panel (Part 5 of 6)
Panel Utilities Help
-----------------------------------------------------------------------------HRECOVER ENTRY PANEL
Page 6 of 6
Command ===>
Optionally specify one or more for
Data Set:
For the Backup Data Set, Specify:
Backup Generation Number . __
(0 to 99)
Backup Date . . . . . . . . __________ (yyyy/mm/dd)
Backup Time . . . . . . . . ______
(hhmmss)
Data Set Password . . . . .
(if password protected)
Note: Dataset Password ignored when in ADMIN mode.
To Recover to a specific volume, Specify:
Volume Serial Number . . . . ______
(target volume)
Device Type . . . . . . . . ______
(target device type)
To rename recovered Data Set, Specify:
New Data Set Name . . . . . ______________________________________________
Password of New Data Set . .
(if password protected)
Replace existing Data Set . . _
(Y or N)
DA Access Option . . . . . . . _
(1-SAMETRK, 2-RELTRK or 3-RELBLK)
Wait for completion . . . . . N
(Y or N)
Use ENTER to perform HRecover;
Use HELP Command for Help; Use END Command to Exit.
Figure 49. HRECOVER Entry Panel (Part 6 of 6)
4. Press ENTER to perform the recover and redisplay the list (see Figure 50 on
page 141).
The asterisk next to the HRECOVER in the line operator column indicates that the
recovery was successful.
140
z/OS DFSMShsm Managing Your Own Data
HRECOVER
Panel List Dataset Utilities Scroll Help
-----------------------------------------------------------------------------DATA SET LIST
Entries 1-1 of 1
Enter Line Operators below:
Data Columns 3-6 of 39
LINE
OPERATOR
DATA SET NAME
---(1)---- ------------(2)-----------USER20.CLIST.CLIST
USER20.DFP220.DGTTLIB
USER20.ISMF.DGTLLIB
USER20.ISMF.DGTPLIB
USER20.ISMF.DUMP
USER20.ISPFILE
USER20.ISPPROF
*HRECOVER USER20.SAMPLE.DATASET
USER20.SPFLOG1.LIST
USER20.TEMP.DATASET
---------- ------ ----------- BOTTOM
Command ===>
F1=Help
F2=Split F3=End
F4=Return
F10=Left
F11=Right F12=Cursor
ALLOC
SPACE
--(3)-46
46
46
46
4684
46
93
468
2623
4684
OF DATA
ALLOC % NOT COMPRESSED
USED
USED
FORMAT
--(4)-- -(5)- ---(6)--46
0 ???
46
0 ???
46
0 ???
46
0 ???
4356
7 ???
46
0 ???
93
0 ???
46
90 ???
1311
50 ???
93
98 ???
----------- ------ ---
F7=Up
Scroll ===> HALF
F8=Down
F9=Swap
Figure 50. Data Set List Panel After Function Completes
For more information on using DFSMShsm/ISMF line operators, see z/OS DFSMS
Using the Interactive Storage Management Facility or use the online help provided
with ISMF.
Using TSO
The commands for recovering an SMS-managed or a non-SMS-managed data set
are different.
When recovering SMS-managed data sets, the SMS allocation services used in your
computing center directs the return of your data set. When recovering non-SMS
data sets or uncataloged data sets, you can direct the return of your data sets to a
specific volume.
Recovering a backup version or a dump copy of a data set
Task: Recover a backup version or a dump copy of one or more data sets.
When recovering SMS-managed or non-SMS-managed data sets, you can do any of
the following tasks:
v Replace an existing version or damaged data set with the recovered version of
the data set.
v Recover the backup version of a cataloged non-VSAM data set that is currently
migrated, as specified in the computing system catalog or the MCDS, if the
HRECOVER command is issued with NEWNAME specified, and the
NEWNAME data set is not a migrated data set.
v Rename the recovered version of the data set and have two versions of the same
data set on DFSMShsm-managed volumes.
You cannot recover the backup version of a cataloged VSAM data set that is
currently migrated, as specified in the computing system catalog or the MCDS,
until DFSMShsm recalls or deletes the migrated VSAM data set.
Chapter 21. HRECOVER: Recovering data sets
141
HRECOVER
The copy of a data set to be recovered can be either a backup version or a dump
copy created by DFSMSdss. If your installation uses both incremental backup and
the DFSMSdss dump function, an HRECOVER command may result in
DFSMShsm invoking DFSMSdss to do a restore of the data set. You can read about
the decisions that DFSMShsm makes to select the DFSMSdss copy in z/OS
DFSMShsm Storage Administration. In most cases, it will be transparent to you
whether the HRECOVER command results in using a backup version or a dump
copy. Usually, the most recent copy of your data set will be made available based
on the DFSMShsm options set by your installation’s system programmer and on
the optional parameters that you specify on the HRECOVER command.
RACF authority: To recover a RACF-protected data set and you issue the
HRECOVER command:
v Without the NEWNAME parameter, you must have RACF ALTER authority to
the data set.
v With the NEWNAME parameter:
– You must have RACF READ authority to the data set being recovered.
– In addition, if the newname data set exists and is RACF-protected and you
specify REPLACE, you must have RACF ALTER authority to the newname
data set.
RACF profile requirements: The following are RACF profile requirements when
you issue the HRECOVER command with the NEWNAME parameter:
v A RACF profile must exist for the original data set if the original data set was
RACF-indicated at the time of backup or recovery.
v A RACF profile must exist for the newname data set if the newname data set
exists and is RACF indicated.
Note: In either case, it does not matter if the original data set exists as long as the
profile exists.
Abbreviation: The minimum abbreviation for the HRECOVER command is
HRECOV.
Syntax
The following diagram presents the syntax of the HRECOVER command for
SMS-managed data sets:
,
(1)
►► HRECOVER
( ▼ dsname
)
►
GENERATION ( gennum )
DATE ( date )
TIME(hhmmss)
VERSION ( vernum )
►
►◄
NEWNAME
( newdsname
)
REPLACE
142
z/OS DFSMShsm Managing Your Own Data
WAIT
NOWAIT
EXTENDRC
HRECOVER
Notes:
1
Parentheses around data set names are required only when multiple data set
are specified.
The following diagram presents the syntax of the HRECOVER command for
non-SMS-managed data sets:
,
(1)
( ▼ dsname
►► HRECOVER
)
►
/password
►
►
FROMVOLUME
(
volser )
GENERATION ( gennum )
DATE ( date )
TIME(hhmmss)
VERSION ( vernum )
►
►
NEWNAME
( newdsname
)
REPLACE
/password
►
►
TOVOLUME
( volser
)
UNIT ( unittype
)
WAIT
NOWAIT
►
►◄
EXTENDRC
DAOPTION (
SAMETRK
RELTRK
RELBLK
)
Notes:
1
Parentheses around data set names are required only when multiple data set
are specified.
Required parameters
dsname: Specifying the name of the data set to be recovered
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: (dsname...) or (dsname/password ...) is a required positional parameter
used to specify the name of the data set or list of data set names to be recovered.
For dsname, substitute the name of the data set or list of data set names that you
want to recover. You can use a data set filter for any dsname in a list. If you
specify a list of data sets or one or more filters, each data set is associated with the
other parameters specified with the command. Thus a filter and the NEWNAME
parameter are not compatible since a filter implies more than one data set to
recover.
Chapter 21. HRECOVER: Recovering data sets
143
HRECOVER
If you want to recover an uncataloged data set, you must specify its data set name
explicitly. For a discussion of how to specify data set names, see “Specifying data
set names” on page 37.
For password, substitute the correct password and include the preceding slash (/).
TSO does not prompt you for the password.
v For a password-protected non-VSAM data set, supply the password that allows
you to write to the data set.
v For a password-protected VSAM data set:
– If the data set exists, you must supply the current master password of the
base cluster.
– If the data set does not exist, you must supply the master password of the
base cluster that existed when DFSMShsm backed up the data set.
Abbreviations: None.
Defaults: None.
Restrictions:
v Because dsname is a required positional parameter, you must specify it
immediately after HRECOVER.
v Individual partitioned data set members are not processed by DFSMShsm. If you
specify a partitioned data set with a member name, message ARC1065I is issued
and nothing is recovered.
v If dsname is fully qualified and refers to a VSAM data set, specify the base
cluster name. The entire VSAM data set will be recovered.
v When you specify a password with a filter, all the affected data sets protected by
a password must have the same password. Otherwise, DFSMShsm authorization
checking fails the recovery of those password-protected data sets that are
protected by a different password.
v If an alias is substituted for the data set name of an ICF catalog, the command
fails, even if the user is DFSMShsm-authorized.
Optional parameters
DAOPTION: Selecting target volume track length
This parameter applies only to data that will be returned to a non-SMS-managed
DASD volume.
Explanation: DAOPTION(SAMETRK | RELTRK | RELBLK) are mutually
exclusive, optional parameters specifying the type of data set accessing required
(relative track or relative block) upon recovery of a direct access data set. This, in
turn, implies the allowable target volume device types.
SAMETRK specifies that data is to be moved as a track-to-track image and that the
target volume track size must be the same as the L0 volume from which the data
set was backed up. If DFSMShsm is directed to a specific volume by the
TOVOLUME parameter, this volume must have the same track length as the L0
volume from which the data set was backed up.
Data can be accessed for both relative track and relative block processing.
RELTRK specifies that data is to be moved as a track-to-track image and that the
target volume track size must be the same or greater than the L0 volume from
144
z/OS DFSMShsm Managing Your Own Data
HRECOVER
which the data set was backed up. If DFSMShsm is directed to a specific volume
by the TOVOLUME parameter, this volume must have the same or greater track
length as the L0 volume from which the data set was backed up.
Data can be accessed for relative track processing.
RELBLK specifies that data is to be moved to fill out the track and that the target
volume track size can be the same, greater, or smaller than the L0 volume from
which the data set was backed up.
Data can be accessed for relative block processing.
Abbreviations: The TSO abbreviation convention applies to this parameter. There
are no additional abbreviations.
Defaults: If you do not specify DAOPTION, the data is moved as a track image,
allowing for relative track accessing.
Note: Only direct access (BDAM) data sets are supported by this option. Using
DAOPTION to recover a data set as SMS-managed is not supported. If a data set
would be SMS-managed after the recover, the FORCENONSMS parameter of
RECOVER must be used to force it to be non-SMS-managed.
EXTENDRC: Requesting an extended set of return and reason
codes
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: EXTENDRC is an optional parameter that specifies that DFSMShsm
return an extended set of return and reason codes while you are running
DFSMShsm commands in a truly interactive mode (TSO or foreground). This
option returns only the return and reason codes that are mapped into DFSMShsm
messages that are issued to the user’s terminal. For detailed information on return
codes that DFSMShsm returns for this command, see Appendix B, “Return codes
from DFSMShsm commands,” on page 189.
Abbreviations: The TSO abbreviation convention applies for EXTENDRC.
Defaults: None.
Restrictions: The WAIT option must be specified with the EXTENDRC parameter
when you are running DFSMShsm commands in a truly interactive mode (TSO or
foreground).
FROMVOLUME: Specifying the volume from which the backup
version or dump copy of a data set was created
This parameter applies only to non-SMS-managed data sets.
Explanation: FROMVOLUME(volser) is an optional parameter that specifies that
the data set was uncataloged and that it resided on the volume specified by the
volser when DFSMShsm created the backup version. For volser, substitute the serial
number of the volume where the uncataloged data set resided when DFSMShsm
created the backup version.
If FROMVOLUME is used to direct DFSMShsm to restore a data set from a dump
copy, the dump copy made from the specified volume will be used regardless of
the catalog status of the data set when the dump copy was made. The data set will
be restored to the FROMVOLUME specified and left uncataloged.
Chapter 21. HRECOVER: Recovering data sets
145
HRECOVER
If the FROMVOLUME is not specified, the volume on which the data set is
currently cataloged, or where an incremental backup version was found, is used to
locate an eligible dump copy.
Abbreviations: The TSO abbreviation convention applies for FROMVOLUME.
There are no additional abbreviations.
Defaults: None.
Restrictions:
v You must use the FROMVOLUME parameter to recover a data set if the data set
was uncataloged at the time DFSMShsm backed it up.
v You cannot use the FROMVOLUME parameter for cataloged data sets.
v When you specify the FROMVOLUME parameter, DFSMShsm does not catalog
the recovered backup version or dump copy.
v The FROMVOLUME parameter does not apply to VSAM data sets.
GENERATION, DATE, and VERSION: Specifying the particular
data set backup version to recover
These parameters apply to both SMS-managed and non-SMS-managed data sets.
Explanation: GENERATION(gennum) | DATE(date) | VERSION(vernum) are
mutually exclusive, optional parameters used to identify the backup version of the
data set or data sets that you want to recover.
GENERATION specifies that you want to recover a particular backup version of a
specific data set. For gennum, substitute the relative generation number of the
backup version of the data set that you want to recover. Zero is the latest created
backup version, one is the next to the latest created version, and so forth, up to the
maximum number of versions existing for the data set. You cannot specify
GENERATION with retained backup copies.
DATE specifies that you want to recover the latest backup version or dump copy
created on or before a particular date. For date, substitute the date in the following
format for the backup or dump copy of the data set that you want to recover:
v yy/mm/dd or mm/dd/yy, if you issue the command before 1 January 2000
v yyyy/mm/dd, if you issue the command after 31 December 1999
The backup or dump copy to be recovered is the newest one created on or before
the date specified. A leading zero is not required for a one-digit month or day.
TIME is an optional parameter that specifies the exact time in hours, minutes, and
seconds (hhmmss) when the backup version was created. The valid range for
hours is 00–23, and for minutes and seconds is 00–59. If you specify TIME, you
must also specify DATE, otherwise the HRECOVER command fails. If you specify
a partially qualified data set, the DATE and TIME are applied to all of the data sets
that meet the filter criteria. If you specify DATE and TIME, DFSMShsm recovers
the exact backup copy that was created at the specified date and time. If you
specify DATE and do not specify TIME, DFSMShsm recovers the most recent
backup copy created on or before the specified date. You can use the LIST
command to determine the creation DATE and TIME of the data sets that you
want to recover. If a copy with specified DATE and TIME does not exist, the
HRECOVER command fails. You cannot specify TIME on a volume recovery
request.
146
z/OS DFSMShsm Managing Your Own Data
HRECOVER
VERSION(vernum) specifies that you want to recover a particular unique version
of a specific data set. For vernum, substitute a decimal number from 1 to 999 for
the particular backup version you would like to recover. If DFSMShsm is unable to
find the specified backup version, the recover fails and message ARC1128I is
issued. You cannot specify VERSION with retained backup copies.
Abbreviations: The TSO abbreviation convention applies for GENERATION,
DATE, and VERSION. There are no additional abbreviations.
Defaults: If you do not specify GENERATION, DATE, or VERSION, DFSMShsm
recovers the latest created backup version or dump copy of the data set. If you
issue the command before 1 January 2000 and specify the date in the form mm/dd,
the year (yy) defaults to the current year.
Restrictions: If either the GENERATION or VERSION parameters are specified,
DFSMShsm will select only from incremental backups and will not recover from
physical dump copies, even if the physical dump is more recent.
NEWNAME: Specifying a new data set name for the recovered
data set
This parameter applies to both SMS-managed and non-SMS-managed data sets.
Explanation: NEWNAME(newdsname) is an optional parameter used to specify a
new data set name for the recovered backup version or dump copy of the data set.
For newdsname, substitute the name to be given to the recovered data set. If a data
set already exists with the same name as the new name you are specifying, you
must specify the REPLACE parameter to replace the existing data set.
For password, substitute the correct password and include the preceding slash (/).
TSO does not prompt you for the password.
v If a password-protected non-VSAM data set currently exists with the name
specified by NEWNAME, you must supply the password that allows you to
write to the data set.
v If a password-protected VSAM data set currently exists with the name specified
by NEWNAME, you must supply the master password of the base cluster.
Abbreviations: The TSO abbreviation convention applies for NEWNAME. There
are no additional abbreviations.
Defaults: None.
Restrictions:
v If you want to keep both versions of the data set, you must specify NEWNAME
when a data set exists with the same name as the data set you are recovering.
v It is inconsistent to specify the NEWNAME parameter when you are recovering
more than one data set with each HRECOVER command.
v When you specify NEWNAME, you may have to consider the following
conditions:
Chapter 21. HRECOVER: Recovering data sets
147
HRECOVER
If
Then
You are recovering a VSAM data set and
you specify NEWNAME,
The new data set name and the original data
set name must be cataloged in the same
catalog. Additionally, the catalog entry for
the original data set name must exist so that
the original data and index component
names can be found. The base cluster data
component name and the base cluster index
component name of the data set being
recovered must be the same as the base
cluster data component name and the base
cluster index name exported.
You specify TOVOLUME with NEWNAME
and the VSAM data set is cataloged in a
non-ICF catalog,
The volume must be owned by the catalog
where the VSAM data set being recovered
will be cataloged.
The newname data set is an already existing DFSMShsm uses the base cluster data
VSAM data set,
component and base cluster index
component name when creating the
newname data set.
The newname data set does not exist,
DFSMShsm generates a name for the base
cluster data component and the base index
component.
There is a path defined on the base cluster
of a VSAM data set,
You cannot rename the VSAM data set.
If you are recovering a VSAM data set and
the original data set exists, but no backup
copy exists (only a dump copy exists), and
you specify NEWNAME,
The recover command fails. DFSMSdss does
not support the NEWNAME parameter for
VSAM data sets, so the restore function
must use the original data set name.
If you are recovering a non-VSAM data set
and you specify NEWNAME,
The new data set name should be cataloged
and must have the same data set
organization as the backup version.
v DFSMShsm does not process individual partitioned data set members. If you
specify a partitioned data set with a member name, DFSMShsm fails the
HRECOVER request.
Note: When you issue the following command:
HRECOVER dsname NEWNAME (newdsname) REPLACE
consider the following:
v If the original data set and newname data set are both VSAM data sets,
password-protected, RACF-protected, and you have the proper RACF authority
to the data sets, this HRECOVER command will delete the newname data set
(including the catalog entry and the RACF profile of the newname data set) and
rename the recovered version to the newname data set.
v If the original data set and the newname data set are both non-VSAM data sets,
this HRECOVER command will not change the protection of the original data
set. The data set VTOC entry of the newname data set indicates that the
newname data set now has the combined protection of the original data set and
the newname data set.
REPLACE: Specifying that the recovered data set version is to
replace any existing data set of the same name
This parameter applies to both SMS-managed and non-SMS-managed data sets.
148
z/OS DFSMShsm Managing Your Own Data
HRECOVER
Explanation: REPLACE is an optional parameter used to specify that the
recovered backup version or dump copy of the data set replaces any existing data
set with the same data set name on the receiving volume or on any volume if the
data set is cataloged. If you specify NEWNAME and the new name is the same as
the name of an existing data set, you must specify the REPLACE parameter or
DFSMShsm does not process the HRECOVER command for that data set. The data
set being replaced is uncataloged (if it was cataloged) and scratched.
Abbreviations: The TSO abbreviation convention applies for REPLACE. There are
no additional abbreviations.
Defaults: None.
Restrictions:
v When a data set with the specified name already exists on the receiving volume
or on any volume if the data set is cataloged and if you do not specify the
REPLACE or NEWNAME parameters, DFSMShsm does not process the
HRECOVER command for that data set.
v The data set to be replaced must have the same data set organization as the data
set from which the backup version was created. For example, a sequential data
set can not be recovered into a partitioned data set member.
v If the backup version is being recovered and both the backup version and the
target data set are cataloged, then DFSMShsm will fail the HRECOVER request
when the data set organizations do not match.
TOVOLUME: Specifying the volume to receive the recovered data
set
This parameter applies only to data that will be returned to a non-SMS-managed
DASD volume.
Explanation: TOVOLUME(volser) is an optional parameter used to specify the
volume that is to receive the recovered data set. For volser, substitute the serial
number of the volume that you want to receive the recovered data set.
Abbreviations: The TSO abbreviation convention applies for TOVOLUME. There
are no additional abbreviations.
Defaults: If you do not specify TOVOLUME, DFSMShsm recovers the data set:
v To the volume where the catalog entry that specifies the data set currently exists;
v If no catalog entry exists, to the volume where it resided at the time DFSMShsm
backed it up unless DFSMShsm created the backup version from a migrated
data set;
v If DFSMShsm backed up a data set while it was migrated, to the volume from
which the data set last migrated.
Restrictions:
v If you specify TOVOLUME, you must also specify UNIT and unittype. If you are
recovering a VSAM data set cataloged in a non-ICF catalog, you can only specify
with the TOVOLUME parameter a volume owned by the catalog where the
VSAM data set being recovered is cataloged or will be cataloged.
v The volume you specify for TOVOLUME cannot be a migration volume.
UNIT: Specifying the type of unit for the receiving volume
This parameter applies only to data that will be returned to a non-SMS-managed
DASD volume.
Chapter 21. HRECOVER: Recovering data sets
149
HRECOVER
Explanation: UNIT(unittype) is an optional parameter used to specify the type of
unit where the receiving volume can be allocated. For unittype, substitute the type
of unit where the volume that is to receive the recovered data set can be allocated.
The valid types of units are: 3380, 3390, and 9345.
Abbreviations: The TSO abbreviation convention applies for UNIT. There are no
additional abbreviations.
Defaults: None.
Restrictions:
v If you specify TOVOLUME, you must also specify UNIT and unittype. If you
specify UNIT, you must also specify TOVOLUME.
v If the device to which you are recovering the backup version has a smaller track
capacity than the block size of the users data set, the track overflow feature must
be on in both the software and hardware.
WAIT and NOWAIT: Specifying whether to wait for the data set to
be recovered
These parameters apply to both SMS-managed and non-SMS-managed data sets.
Explanation: WAIT | NOWAIT are mutually exclusive, optional parameters used
to specify whether to wait for the HRECOVER command to complete.
WAIT specifies that you want to wait for the HRECOVER command to complete.
When DFSMShsm successfully completes the HRECOVER process, the ARC1000I
message is issued. If the HRECOVER process does not complete successfully, the
ARC1001I message is issued. If you press the TSO Attention key before DFSMShsm
completes the command, DFSMShsm issues the ARC1800I message and does not
issue the ARC1000I message.
NOWAIT specifies that you do not want to wait for the HRECOVER command to
complete. When DFSMShsm successfully receives the request, the ARC1007I
message is issued. If you are recovering data sets from tape, a volume mount
request message (ARC0612I) is issued. After DFSMShsm successfully completes the
HRECOVER command, the ARC1000I message is issued. If the HRECOVER
command does not complete successfully, the ARC1001I message is issued.
Abbreviations: The TSO abbreviation convention applies for WAIT and NOWAIT.
There are no additional abbreviations.
Defaults: The default is NOWAIT.
Restrictions: You can specify either WAIT or NOWAIT, but not both.
Examples of different ways to code the HRECOVER command
The examples below present different ways to code the HRECOVER command.
The values are examples only. Do not interpret them as values that you should use
for your system.
Recovering a specific data set by generation number and waiting
for completion
In this example, you are issuing the HRECOVER command to recover the third
latest backup version of the cataloged data set GRPA.OUTTESTS.TESTLIST.
Because you are not specifying the REPLACE option in the command, a data set
150
z/OS DFSMShsm Managing Your Own Data
HRECOVER
with this name does not currently exist. The WAIT parameter indicates that you
want to wait for DFSMShsm to complete the recovery of the data set.
HRECOVER ’GRPA.OUTTESTS.TESTLIST’ GENERATION(2) WAIT
Recovering a data set and requesting to see the return code and
reason code
In this example, you are issuing the HRECOVER command from a TSO session to
recover the latest version of the data set TESTS.TEXTVER4.TEXT. The WAIT
EXTENDRC parameter indicates that you want to see the extended return and
reason codes.
HRECOVER ’TESTS.TEXTVER4.TEXT’ WAIT EXTENDRC
Recovering a non-SMS password-protected data set, renaming it,
and waiting for completion
In this example, you are issuing the HRECOVER command to recover the latest
backup version of the uncataloged data set CLCE.TEXTVER1.TEXT created on or
before 1/05/89 and protected by the password WRITE. You are naming the
recovered version CLCE.VER1TEXT.TEXT and placing it on volume VOL001,
specifying 3380 as the type of unit. VOL003 is the volume where the uncataloged
data set resided when DFSMShsm backed it up. The WAIT parameter indicates
that you want to wait for DFSMShsm to complete the recovery of the data set.
HRECOVER ’CLCE.TEXTVER1.TEXT’/WRITE FROMVOLUME(VOL003) DATE(1/05/89) NEWNAME(’CLCE.VER1TEXT.TEXT’) TOVOLUME(VOL001) UNIT(3380) WAIT
Recovering a non-SMS data set to replace an existing data set
and not waiting for completion
In this example, you are issuing the HRECOVER command to recover the latest
version of the data set USER01.PARTSTST.CNTL to volume VOL007 to replace an
existing cataloged data set of the same name. A 3390 is the type of unit that
volume VOL007 can reside on. Your user ID prefix is USER01. The NOWAIT
parameter indicates that you do not want to wait for DFSMShsm to complete the
recovery and replacement of the data set.
In this example, the original data set is uncataloged and scratched.
HRECOVER PARTSTST.CNTL TOVOLUME(VOL007) UNIT(3390) REPLACE NOWAIT
Recovering a DA (BDAM) data set to a volume with a different
track length than the last L0 volume from which the backup
version was created
In this example, a non-SMS-managed direct access (DA) data set is to be recovered
for relative block accessing to a target volume with a smaller track size than the L0
volume from which the backup version was created.
HRECOVER PMJS73.SERVICE.DATA TOVOLUME(VOL001) UNIT(3380) DAOPTION(RELBLK)
Chapter 21. HRECOVER: Recovering data sets
151
HRECOVER
152
z/OS DFSMShsm Managing Your Own Data
Part 3. DFSMShsm application programming interface
This topic describes the user macros you can use from application programs to
issue DFSMShsm.
© Copyright IBM Corp. 1984, 2017
153
154
z/OS DFSMShsm Managing Your Own Data
Chapter 22. Using DFSMShsm user macros
This topic contains general-use programming interface and associated guidance
information that allow the customer to write programs that use the services of
DFSMShsm.
DFSMShsm has macros available that allow you to request DFSMShsm service
from your application programs. When you provide information to the macro and
process it from your application program, the macro builds the required
DFSMShsm control information and issues the request for DFSMShsm service. The
macros are in execute form only. There is no list form provided.
The following user macros are currently supported in DFSMShsm:
v ARCFMWE frees up storage in common storage area (CSA)
v ARCHBACK backs up a specific data set
v ARCHBDEL deletes backed up versions of a data set
v ARCHDEL deletes a migrated data set
v ARCHMIG migrates a specific data set
v ARCHRCAL recalls a data set
v ARCHRCOV recovers a data set
v ARCHSEND sends a command to DFSMShsm
v ARCXTRCT extracts data from DFSMShsm
Note: When these macros are invoked from a application program that runs APF
Authorized, in System Key (0 or 7), or Supervisor State, then DFSMShsm bypasses
SAF calls for the data sets that are processed. The application owner must ensure
that their application program does not introduce a security exposure by enabling
unauthorized users access to data via these DFSMShsm macros.
© Copyright IBM Corp. 1984, 2017
155
Register usage for return codes
Use the parameters of the macro to specify an explicit value or an address of a
data field. They can be specified in any order. When the address of a data field is
specified, registers 2 through 12 can be used. For example, SNAPDCB=(3) or a
symbol, SNAPDCB=DCBAREA, can be used.
The application program must ensure that register 13 contains the address of a
standard 18-word save area. The following return codes are placed in register 15
upon completion of the invocation:
Return code
Description
0
Function is successful
100
DFSMShsm is not running or the request could not be communicated to
DFSMShsm
400
Invalid request ID
401
Attempt to free a MWE for an incomplete function (applies to ARCFMWE
only)
402
Data set locate failure (applies to ARCHRCAL and ARCHMIG only)
403
Data set name specified was * or blank
404
The date specified with ARCHRCOV has format yyddd, but the system date
is later than 1999.
806
Link error
Any other nonzero
Function fails
See “Individual macros and their messages” on page 194.
Supported unit types and their UCBs
When working with uncataloged data sets, the UNIT and VOLUME parameters
must be specified. The unit address is a four-byte field that contains the UCB
device type. Table 12 presents the unit types and their UCBs that are supported by
the user macros in this section.
Table 12. Supported Unit Types and Their UCBs
Unit Type
UCB
3380
X'3010200E'
3390
X'3010200F'
9345
X'00002004'
Asynchronous processing with DFSMShsm
Asynchronous processing of the ARCHRCAL and ARCHBACK macros is provided
by the ASYNC parameter. This parameter is to be used in conjunction with a
no-wait or wait request:
no-wait
Sends a request to DFSMShsm and returns control to the user as soon as
156
z/OS DFSMShsm Managing Your Own Data
the request is queued. The user is not notified of the request processing
other than a completion message, if the user is logged onto TSO at the
time the request ends.
wait
Sends a request to DFSMShsm and does not receive control back until the
request has completed. In the return notification, a return code and reason
code indicate whether the processing was successful.
The ASYNC=YES parameter allows you, as a program submitter, a way to send
requests to DFSMShsm and immediately receive control back so that you can do
other things while DFSMShsm is processing your request. DFSMShsm notifies you
when the request is complete and returns a return code and reason code.
Before ASYNC=YES will successfully run in your requesting user program, you, as
a program submitter, must perform the following tasks:
v Ensure that the requesting user program is an authorized program because
protected CSA storage is used to communicate the request.
v Specify the ASYNC=YES option and the WAIT=YES option when you code the
requested user macro.
v Save the ECB address that is returned in register 1 and do not free this area until
the ECB is posted. When the request is queued in CSA, control is returned to the
requester. Register 1 contains the address of an ECB that is posted when the
request is finished. For certain errors during an asynchronous request, register 1
contains zero indicating that an ECB is not passed. Check the return and reason
codes under these conditions.
v After the ECB has been posted, issue the ARCFMWE user macro to free the CSA
storage used in this method by specifying the saved ECB address. Upon return
from the ARCFMWE macro, the return code is in register 15 and a reason code
is in register 0.
Chapter 22. Using DFSMShsm user macros
157
ARCFMWE
ARCFMWE: Freeing up storage in common storage area
The ARCFMWE macro allows you to free up storage space for management work
elements and is used only when the ASYNC=YES option is specified with the
ARCHRCAL or ARCHBACK user macros.
Syntax
The following diagram presents the syntax of the ARCFMWE macro:
►► ARCFMWE
ECBADDR=ecbaddr,
WKAREA=waaddr
►◄
,SNAPDCB=dcbaddr
,TEST=
NO
YES
Required parameters
The following are the required parameters of the ARCFMWE macro:
ECBADDR
specifies the address of the ECB in a work area (management work element)
that is obtained when the ASYNC=YES is specified for an ARCHRCAL or
ARCHBACK request. The requesting application must be authorized program
facility (APF) authorized. For ecbaddr, substitute the address that has returned
in register 1 from the ARCHRCAL or ARCHBACK request.
Note: The ASYNC request must have been completed (ECB posted), before
issuing the macro.
WKAREA
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 should be below the 16MB line. The work area serves as a
temporary storage area for the macro processing.
Optional parameters
The following are the optional parameters of the ARCFMWE macro:
SNAPDCB
specifies the address of an open DCB that can be used for SNAP macro
processing. This feature is intended for problem determination. If you specify
this parameter, review “Usage notes.” For dcbaddr, specify the address of an
open DCB.
TEST
specifies whether to refrain from sending a request for service to DFSMShsm.
If YES is specified the service request is not sent. If NO is specified, a service
request is sent to DFSMShsm. In both cases the parameters are checked for
correctness. A 4xx return code will result for invalid parameters. The default is
NO.
Usage notes
1. If a return code of 4xx is returned and SNAPDCB is specified, a SNAP macro is
issued and the request made to DFSMShsm is dumped. The dumped storage
area will include the data set name, volume serial number, and function
requested.
2. If SNAPDCB and TEST=YES were specified, and there was an error flagged in
the MWERC, then a SNAP macro is issued and the MWE is dumped.
158
z/OS DFSMShsm Managing Your Own Data
ARCHBACK
ARCHBACK: Backing up a specific data set
The ARCHBACK macro allows you to create a backup version of a specific data
set. This macro can handle only one data set at a time. Consequently, the macro
must be invoked for each data set processed.
Note: All memory areas passed to DFSMShsm through the macro must be in
24-bit addressing mode and below the 16MB line.
Syntax
The following diagram presents the syntax of the ARCHBACK macro for both
SMS-managed and non-SMS-managed data sets:
►► ARCHBACK
DSN=dsnaddr, WKAREA=waaddr
►
,NEWNAME=newdsnaddr
,DATE=dateaddr
,TIME=timeaddr
►
►
,SPHERE=
YES
NO
,TARGET=
DASD
TAPE
,
YES
NO
GENVSAMCOMPNAMES=
GVCN
NO
YES
,ASYNC=
►
►
,WAIT=
NO
YES
,TARGET=
DASD
TAPE
STANDARD
CC(
PHYSICALEND
,
ANYPREFERRED
PREFERRED
PREFER
CACHEPREFERRED
CPREF
VIRTUALPREFERRED
VPREF
REQUIRED
ANYREQUIRED
CACHEREQUIRED
CREQ
VIRTUALREQUIRED
VREQ
)
PHYSICALEND
PE
LOGICALEND
LE
►
►
,DSNENQ=
YES
NO
,VOLUME=volseraddr
,UNIT=unitaddr
,SNAPDCB=dcbaddr
,TEST=
NO
YES
►
►◄
,RETAINDAYS=rdaddr
Required parameters
The following are the required parameters of the ARCHBACK macro:
DSN
specifies the address of a field that contains the fully qualified name of the
data set to be processed. For dsnaddr, use the address of the 44-byte data area
that contains the 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.
WKAREA
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
Chapter 22. Using DFSMShsm user macros
159
ARCHBACK
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 to your program.
Optional parameters
The following are the optional parameters of the ARCHBACK macro:
DATE
specifies the address of a field which contains the backup date to assign to the
new backup version that will be created via the ARCHBACK macro. DATE can
ONLY be specified with NEWNAME or the invocation will fail. For dateaddr,
substitute the address of a data area that contains the backup date. The field
referenced by dateaddr must contain 7 characters in the form of yyyyddd. This
parameter applies to both SMS-managed and non-SMS-managed data sets.
NEWNAME
specifies the data set name to assign to the new backup version that is created
by specifying the BACKDS command. The NEWNAME parameter must be
fully-qualified and in the standard data set name format.
RETAINDAYS
specifies the number of days to retain a specific backup copy of a data set. For
rdaddr substitute the address of the 5–byte data area that contains the
RETAINDAYS value. RETAINDAYS specifies the minimum number of days
(0–50000) that DFSMShsm retains the backup copy. If you specify 99999, the
data set backup version never expires. Any value greater than 50000 (and other
than 99999) causes a failure with an ARC1605I error message. A retain days
value of 0 indicates that:
v the backup version might expire within the same day that it was created if
EXPIREBV processing takes place,
v the backup version is kept as an active copy before roll-off occurs,
v the backup version is not managed as a retained copy.
SPHERE
specifies whether the AIX and PATH components of a VSAM data set will be
backed up with the base cluster. SPHERE can ONLY be specified with
NEWNAME or the invocation will fail. If NO is specified, a backup of the base
cluster will be performed, but backup for any associated AIXs and/or PATHs
will not be performed. If YES, the default, is specified, a backup of the entire
VSAM SPHERE will be performed. The following restrictions apply when
using the SPHERE parameter:
v No more than one PATH can be defined for the data set to back up, and no
more than one PATH can be defined for the NEWNAME data set.
v No more than one AIX can exist for the data set to back up, and no more
than one AIX can exist for the NEWNAME data set.
This parameter applies to both SMS-managed and non-SMS-managed data sets.
TIME
specifies the address of a field which contains the backup time to assign to the
new backup version that will be created via the ARCHBACK macro. TIME can
ONLY be specified when NEWNAME AND DATE are also specified. For
timeaddr, substitute the address of a data area that contains the backup time.
The field referenced by timeaddr must contain 6 characters in the form of
hhmmss. For hhmmss, substitute the time to assign to the backup version. If the
seconds are unknown, specify '00' for ss. If TIME is not specified, DFSMShsm
will set a time of 120000. This parameter applies to both SMS-managed and
non-SMS-managed data sets.
160
z/OS DFSMShsm Managing Your Own Data
ARCHBACK
GVCN
overrides the SETSYS DSBACKUP(GENVSAMCOMPNAMES) setting. If
GVCN=YES is specified, and the NEWNAME data set represents a VSAM base
cluster that is either migrated or uncataloged, DFSMShsm will process the
request, and default names will be assigned to the VSAM data and index
components. If GVCN=NO is specified, and the NEWNAME data set
represents a VSAM base cluster that is either migrated or uncataloged, the data
set backup command will fail. DFSMShsm ignores the GVCN specification
when the NEWNAME data set is cataloged to a volser other than MIGRAT.
This parameter applies to both SMS-managed and non-SMS-managed data sets.
If the old component's name is equal to the old cluster name (plus any suffix),
then the new component name will equal the new cluster name, plus the same
suffix of the old component. For more information on how component
(default) names are derived during rename processing see z/OS DFSMSdss
Storage Administration.
ASYNC
specifies whether the special asynchronous backup processing is requested. The
requesting application must be authorized by the authorized program facility
(APF) to request the ASYNC option. If ASYNC=YES is specified, the WAIT
parameter must also be specified as YES to allow the ECB to be posted back to
the user when DFSMShsm completes the function. The default is NO. This
parameter applies to both SMS-managed and non-SMS-managed data sets.
If YES is specified, storage for the generated MWE is obtained in the
requester's private storage, and an event control block (ECB) address is
returned in register 1 when control is returned to the requester. The application
program is responsible for freeing this storage area; however, do not free it
until the ECB is posted. You must use the ARCFMWE macro to free the storage
area by supplying the ECB address. In cases where a zero value is returned for
the ECB address, the request has failed and storage is not obtained for the
MWE. Upon return from the ARCFMWE macro, the return code is in register
15 and a reason code is in register 0. If register 15 contains a return code of
400, 401, or 806, this error is from the completion of the ARCFMWE macro. All
other return codes contained in register 15 are from the completion of the
ARCHBACK macro. The last reported, nonzero return code is in register 15.
For example:
If the return code from
ARCHBACK is:
And the return code
from ARCFMWE is:
Then the return code placed in
register 15 is from:
Zero
Nonzero
ARCFMWE
Nonzero
Zero
ARCHBACK
Nonzero
Nonzero
ARCFMWE
WAIT
specifies whether you want the application to wait until DFSMShsm has
processed this request. If you specify YES without ASYNC=YES, the
application does not receive control back until DFSMShsm completes
processing of the request. The default is NO. This parameter applies to both
SMS-managed and non-SMS-managed data sets.
TARGET
specifies whether tape or DASD will be the target of the backup output data
set. If you specify TAPE, the backup data set goes to tape. If you specify
DASD, the backup data set goes to DASD. If you specify neither, DFSMShsm
decides the target for this data set.
Chapter 22. Using DFSMShsm user macros
161
ARCHBACK
CC specifies whether you want to use concurrent copy and which notification
options that you want. If you specify PREFERRED, CACHEPREFERRED or
VIRTUALPREFERRED, you have indicated that you want to use concurrent
copy, if it is available. However, processing continues even if concurrent copy
is not available. If you specify REQUIRED, CACHEREQUIRED or
VIRTUALREQUIRED then a form of concurrent copy is a requirement, and the
command fails if that form of concurrent copy is not available. If you specify
STANDARD, you do not want to use concurrent copy. The default is
STANDARD.
If you specify PHYSICALEND, you will receive notice when the physical end
of the backup has completed. If you specify LOGICALEND, you will receive
notice when the concurrent copy initialization has completed. The default is
PHYSICALEND.
Note:
1. If you use the CC option with LE or PE, you must also specify the option
WAIT=YES.
2. You can abbreviate PHYSICALEND and LOGICALEND as PE and LE,
respectively. You can abbreviate PREFERRED as PREFER. You can
abbreviate CACHEPREFERRED as CPREF, VIRTUALPREFERRED as
VPREF, CACHEREQUIRED as CREQ, and VIRTUALREQUIRED as VREQ.
DSNENQ
specifies whether the data set is serialized by DFSMShsm during backup
processing. If NO is used, the data set is not enqueued during backup
processing, and the application program is responsible for data set
serialization. The data set is not allocated and the SYSDSN resource is not
obtained if NO is chosen. If YES is chosen, normal serialization occurs. The
default is YES.
VOLUME
specifies the address of a field that contains the volume serial number of a
volume that contains the requested uncataloged data set. For volseraddr, use the
address of the six-character field that contains the volume serial number. The
volume serial number must be left-justified and padded with blanks. This
parameter applies only to non-SMS-managed data sets.
Note: Do not specify the VOLUME parameter if the data set to be backed up
is a cataloged data set. If you specify the VOLUME parameter, you must also
specify the UNIT parameter.
UNIT
specifies the address of a field that contains the unit type of the
non-DFSMShsm-managed volume that contains the uncataloged data set. For
unitaddr, use the address of the four-byte field that contains the UCB device
type. For example, X'3010200E' is the UCB unit type for a 3380 device. For a
table showing the supported unit types and UCBs, see Table 12 on page 156.
This parameter applies only to non-SMS-managed data sets.
Note: Do not specify the UNIT parameter if the data set to be backed up is a
cataloged data set. If you specify the UNIT parameter, you must also specify
the VOLUME parameter.
SNAPDCB
specifies the address of an open DCB that can be used for SNAP macro
162
z/OS DFSMShsm Managing Your Own Data
ARCHBACK
processing. This feature is intended for problem determination. If you specify
this parameter, review “Usage notes.” For dcbaddr, specify the address of an
open DCB.
TEST
specifies whether to refrain from sending a request for service to DFSMShsm.
If YES is specified, the service request is not sent. If NO is specified, a service
request is sent to DFSMShsm. In both cases the parameters specified to the
macro are checked for correctness. A 4xx return code results for invalid
parameters. The default is NO.
Usage notes
1. If you issue ARCHBACK on a system prior to the current release, where new
parameters were added to current release, a warning message is issued that
informs you that DFSMShsm is processing the backup request, but ignoring all
new parameters.
2. If a return code of 4xx is returned and SNAPDCB is specified, a SNAP macro is
issued and the request made to DFSMShsm is dumped. The dumped storage
area will include the data set name, volume serial number, and function
requested.
3. If SNAPDCB and TEST=YES were specified, and there was an error flagged in
the MWERC, then a SNAP macro is issued and the MWE is dumped.
Chapter 22. Using DFSMShsm user macros
163
ARCHBDEL
ARCHBDEL: Deleting a backed up version of data sets
The ARCHBDEL macro allows you to delete a backup version of a data set. This
macro can handle only one data set at a time. Consequently, the macro must be
invoked for each data set processed.
Note: All memory areas passed to DFSMShsm through the macro must be in
24-bit addressing mode and below the 16MB line.
Syntax
The following diagram presents the syntax of the ARCHBDEL macro for both
SMS-managed and non-SMS-managed data sets:
►► ARCHBDEL
DSN=dsnaddr, WKAREA=waaddr
►
,FROMVOL=volseraddr
,SNAPDCB=dcbaddr
,TEST=
►
,ALL=YES
,VERS=versaddr
,DATE=dateaddr
NO
YES
►◄
,TIME=timeaddr
Required parameters
The following are the required parameters of the ARCHBDEL macro:
ALL
DATE
TIME
VERS
are mutually exclusive required parameters.
ALL
specifies that all backup versions are to be deleted, including both active
and retained backup versions. ALL does not delete retired versions.
DATE
specifies the address of a field that contains the date when the backup
version to be deleted was created. For dateaddr, specify the address of a
data area that contains the backup date. The field referenced by dateaddr
must contain 7 digits in the form of yyyyddd.
TIME
specifies the address of the field that contains the time when the backup
version to be deleted was created. For timeaddr, specify the address of the
data area that contains the backup time. The field referenced by timeaddr
must contain 6 digits in the form of hhmmss.
VERS
specifies a list of versions to delete. Specify the address of a structure that
contains a 2-byte number of entries on the list, followed by entries (2-bytes
each) containing the version number (001–999) that you want to delete. You
can use the ARCXTRCT macro to extract data for version numbers that
currently exist. For more information on this macro, see “ARCXTRCT:
Extracting data from DFSMShsm” on page 180. You cannot use the VERS
keyword to delete retained backup copies.
DSN
specifies the address of a field that contains the fully qualified name of the
data set to be processed. For dsnaddr, use the address of the 44-byte data area
164
z/OS DFSMShsm Managing Your Own Data
ARCHBDEL
that contains the 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.
WKAREA
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 that is available to you as soon as the
macro returns control to your program.
Optional parameters
The following are the optional parameters of the ARCHBDEL macro:
FROMVOL
specifies the address of a field that contains the volume from which
uncataloged data sets were backed up. For volseraddr, substitute the address of
the six-character field that contains the volume serial number. The volume
serial number must be left-justified and padded with blanks. FROMVOL
applies only to non-SMS-managed data sets that were uncataloged at the time
they were backed up.
SNAPDCB
specifies the address of an open DCB that can be used for SNAP macro
processing. This feature is intended for problem determination. If you specify
this parameter, review “Usage notes.” For dcbaddr, specify the address of an
open DCB.
TEST
specifies whether to refrain from sending a request for service to DFSMShsm.
If YES is specified, the service request is not sent. If NO is specified, a service
request is sent to DFSMShsm. In both cases, the parameters specified to the
macro are checked for correctness. A 4xx return code results for invalid
parameters. The default is NO.
Usage notes
1. You can use the DATE and TIME parameters to delete active and retained
backup copies.
2. You can use the LIST command or ARCXTRCT macro to extract data from
DFSMShsm to obtain the creation date and time for available backup versions.
3. If a return code of 4xx is returned and SNAPDCB is specified, a SNAP macro is
issued and the request made to DFSMShsm is dumped. The dumped storage
area will include the data set name, volume serial number, and function
requested.
4. If SNAPDCB and TEST=YES were specified, and there was an error flagged in
the MWERC, then a SNAP macro is issued and the MWE is dumped.
Chapter 22. Using DFSMShsm user macros
165
ARCHDEL
ARCHDEL: Deleting migrated data sets
The ARCHDEL macro allows you to delete a migrated data set. This macro can
handle only one data set at a time. Consequently, the macro must be invoked for
each data set processed.
Note: All memory areas passed to DFSMShsm through the macro must be in
24-bit addressing mode and below the 16MB line.
Syntax
The following diagram presents the syntax of the ARCHDEL macro for both
SMS-managed and non-SMS-managed data sets:
►► ARCHDEL
DSN=dsnaddr,
WKAREA=waaddr
►
,WAIT=
NO
YES
,PURGE=
NO
YES
,SNAPDCB=dcbaddr
►
►◄
,TEST=
NO
YES
Required parameters
The following are the required parameters of the ARCHDEL macro:
DSN
specifies the address of a field that contains the fully qualified name of the
data set to be processed. For dsnaddr, use the address of the 44-byte data area
that contains the 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.
WKAREA
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 that becomes available to you as soon as
DFSMShsm returns control to your program.
Optional parameters
The following are the optional parameters of the ARCHDEL macro:
WAIT
specifies whether you want the application to wait until DFSMShsm has
processed this request. If YES is specified, the application waits until
DFSMShsm completes processing of the request. The default is NO. This
parameter applies to both SMS-managed and non-SMS-managed data sets.
PURGE
specifies whether or not the data set is to be deleted even though the
expiration date has not been reached. If YES is specified, the data set is
deleted. The default is NO. This parameter applies to both SMS-managed and
non-SMS-managed data sets.
SNAPDCB
specifies the address of an open DCB that can be used for SNAP macro
166
z/OS DFSMShsm Managing Your Own Data
ARCHDEL
processing. This feature is intended for problem determination. If you specify
this parameter, review “Usage notes.” For dcbaddr, specify the address of an
open DCB.
TEST
specifies whether to refrain from sending a request for service to DFSMShsm.
If YES is specified, the service request is not sent. If NO is specified, a service
request is sent to DFSMShsm. In both cases the parameters of the macro are
checked for correctness. A 4xx return code results for invalid parameters. The
default is NO.
Usage notes
1. If a return code of 4xx is returned and SNAPDCB is specified, a SNAP macro is
issued and the request made to DFSMShsm is dumped. The dumped storage
area will include the data set name, volume serial number, and function
requested.
2. If SNAPDCB and TEST=YES were specified, and there was an error flagged in
the MWERC, then a SNAP macro is issued and the MWE is dumped.
Chapter 22. Using DFSMShsm user macros
167
ARCHMIG
ARCHMIG: Migrating data sets
The ARCHMIG macro allows you to migrate a data set, and in the case of an
SMS-managed data set:
v perform class transition and optionally specify the address of a data area
containing SMS parameters for class transition processing
v or specify that the data set that is to go through moving processing.
This macro can handle only one data set at a time. Therefore, the macro must be
invoked for each data set processed.
Note: All memory areas that are passed to DFSMShsm through the macro must be
in 24-bit addressing mode and below the 16MB line.
Syntax
The following diagram presents the syntax of the ARCHMIG macro for both
SMS-managed and non-SMS-managed data sets:
►► ARCHMIG
DSN=dsnaddr,
WKAREA=waaddr
►
,FORCML1=
NO
YES
,MIGLVL=
ML1
ML2
(1)
,MOVE=
NO
YES
►
►
(1)
,SNAPDCB=dcbaddr
,SMSAREA=smsaddr
|
,TEST=
NO
YES
,TRANSITION=
NO
YES
(1)
►
►◄
,CLOUD=cloudnameaddr
,WAIT=
NO
YES
Notes:
1
MOVE, SMSAREA, and TRANSITION apply only to SMS-managed data sets.
Required parameters
The following are the required parameters of the ARCHMIG macro:
DSN
specifies the address of a field containing the fully qualified name of the data
set to be processed. For dsnaddr, use the address of the 44-byte data area that
contains the 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.
WKAREA
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.
Optional parameters
The following are the optional parameters of the ARCHMIG macro:
CLOUD
specifies the address of a 30-byte area containing the name of an SMS cloud
|
|
168
z/OS DFSMShsm Managing Your Own Data
ARCHMIG
|
|
|
|
|
construct. The data is migrated to the cloud storage defined in the SMS cloud
construct, and overrides any other specification in the management class of the
data set, other than eligibility for migration. Non-SMS managed data sets are
not eligible for migration to cloud storage. The name must be left-aligned and
padded with blanks. The CLOUD keyword cannot be specified with MIGLVL.
FORCML1
specifies whether to override the management class parameter of ML1DAYS(0)
and force this data set to migrate to ML1. If YES is specified, the data set is
migrated to ML1 without compaction. If NO is specified, the management class
criteria are used to determine whether the data set is to migrate to ML1 or
ML2. The default is NO.
MIGLVL
specifies the migration level, ML1 or ML2, to which you want to migrate the
data set. The default is ML1. This parameter applies to both SMS-managed and
non-SMS-managed data sets.
MOVE
specifies that the data set is to go through moving processing. MOVE is
mutually exclusive with the migration-related parameters (FORCML1,
MIGLVL, and TRANSITION) and processed only for the SMS-managed data
sets. The default value is NO.
SMSAREA
specifies the address of data area containing the optional SMS parameters for
class transition processing. If at least one SMS parameter is specified, then the
specified value or values are used and the ACS routines are not called during
class transition processing. The omitted values of management class, storage
class, or storage group are taken from the data set's SMS construct.
The format of SMS area:
MCLENGTH
MCNAME
SCLENGTH
SCNAME
STGLCNT
DS
DS
DS
DS
DS
DS
SGDEF
DS
SGLENGTH DS
SGNAME
DS
H
CL30
H
CL30
AL1
CL3
0H
H
CL30
MGMT Class name length
MGMT Class name
STRG Class name length
STRG Class name
Number of storage group list
Reserved
Storage group definition
Length of storage group name
Name of storage group
Notes:
v If the management class or storage class is not specified, the name length
must be zero.
v If the storage group list is not specified, the number of storage group lists
must be zero.
SNAPDCB
specifies the address of an open DCB that can be used for SNAP macro
processing. This feature is intended for problem determination. If you specify
this parameter, review “Usage notes” on page 170. For dcbaddr, specify the
address of an open DCB.
TEST
specifies whether to refrain from sending a request for service to DFSMShsm.
If YES is specified, the service request is not sent. If NO is specified, a service
request is sent to DFSMShsm. In both cases, the parameters that are specified
on the macro are checked for correctness. A 4xx return code results for invalid
parameters. The default is NO.
Chapter 22. Using DFSMShsm user macros
169
ARCHMIG
TRANSITION
specifies whether the data set is to go through transition processing.
TRANSITION is mutually exclusive with the migration-related parameters
(FORCML1=YES and MIGLVL=ML2) and is valid only for SMS-managed data
sets. The default value is NO.
WAIT
specifies whether you want the application to wait until DFSMShsm has
processed this request. If YES is specified, the application waits until
DFSMShsm completes processing of the request. The default is NO. This
parameter applies to both SMS-managed and non-SMS-managed data sets.
Usage notes
1. If a return code of 4xx is returned and SNAPDCB is specified, a SNAP macro is
issued and the request made to DFSMShsm is dumped. The dumped storage
area will include the data set name, volume serial number, and function
requested.
2. If SNAPDCB and TEST=YES were specified, and there was an error flagged in
the MWERC, then a SNAP macro is issued and the MWE is dumped.
170
z/OS DFSMShsm Managing Your Own Data
ARCHRCAL
ARCHRCAL: Recalling a data set
The ARCHRCAL macro allows you to recall a migrated data set. This macro can
handle only one data set at a time. Consequently, the macro must be invoked for
each data set processed.
Note: All memory areas passed to DFSMShsm through the macro must be in
24-bit addressing mode and below the 16MB line.
Syntax
The following diagram presents the syntax of the ARCHRCAL command for both
SMS-managed and non-SMS-managed data sets:
►► ARCHRCAL
DSN=dsnaddr, WKAREA=waaddr
►
,ASYNC=
NO
YES
,TEST=
NO
YES
,WAIT=
NO
YES
,TOVOL=volseraddr
►
►
,UNIT=unitaddr
,SNAPDCB=dcbaddr
,DAOPT(
SAMETRK
RELTRK
RELBLK
)
,TCBTOKEN=CURRENT
►
►◄
,DLRKEEP=
NO
YES
Required parameters
The following are the required parameters of the ARCHRCAL macro:
DSN
specifies the address of a field containing the fully qualified name of the data
set to be processed. For dsnaddr, use the address of the 44-byte data area that
contains the 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.
WKAREA
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.
Optional parameters
The following are the optional parameters of the ARCHRCAL macro:
ASYNC
specifies whether the special asynchronous recall processing is requested. The
requesting application must be authorized by the authorized program facility
(APF) to request the ASYNC option. If ASYNC=YES is specified, the WAIT
parameter must also be specified as YES to allow the ECB to be posted back to
the user when DFSMShsm completes the function. The default is NO. This
parameter applies to both SMS-managed and non-SMS-managed data sets.
If YES is specified, storage for the generated MWE is obtained in the
requester's private storage, and an event control block (ECB) address is
returned in register 1 when control is returned to the requester. The application
Chapter 22. Using DFSMShsm user macros
171
ARCHRCAL
program is responsible for freeing this storage area; however, it must not be
freed until the ECB is posted. The ARCFMWE macro must be used to free the
storage area by supplying the ECB address. In cases where a zero value is
returned for the ECB address, the request has failed and storage is not
obtained for the MWE. Upon return from the ARCFMWE macro, the return
code is in register 15 and a reason code is in register 0. If register 15 contains a
return code of 400, 401, or 806, this error is reported from the completion of
the ARCFMWE macro. All other return codes contained in register 15 are from
the completion of the ARCHRCAL macro. The last reported, nonzero return
code is placed in register 15. For example:
If the return code from
ARCHRCAL is:
And the return code
from ARCFMWE is:
Then the return code placed in
register 15 is from:
Zero
Nonzero
ARCFMWE
Nonzero
Zero
ARCHRCAL
Nonzero
Nonzero
ARCFMWE
DLRKEEP
specifies whether or not to keep the date-last-referenced (DLR) after recall of
the data set. If YES is specified, the DLR after the recall remains the same and
the date is not updated to the current recall date. If NO is specified, the DLR
after recall is equal to the recall date. The default is NO.
WAIT
specifies whether you want the application to wait until DFSMShsm has
processed this request. If YES is specified, the application waits until
DFSMShsm completes processing of the request. The default is NO. This
parameter applies to both SMS-managed and non-SMS-managed data sets.
TOVOL
specifies the address of a field containing the volume serial number of the
volume to which the data set is recalled. For volseraddr, substitute the address
of the six-byte area that contains the specified volume serial number. The
volume serial number must be left-justified and padded with blanks.
SMS-managed data sets are recalled to the volume determined by SMS.
Note: When the TOVOL parameter is used, the UNIT parameter must also be
used.
UNIT
specifies the address of a field containing the unit type of the volume to which
the data set is to be recalled. For unitaddr, use the address of the four-byte field
that contains the UCB device type. For example, X'3010200F' is the UCB unit
type for a 3390 device. For a table presenting the supported unit type and
UCBs, see Table 12 on page 156. If the data set is SMS-managed, SMS
determines the unit type.
Note: When the UNIT parameter is used, the TOVOL parameter must also be
used.
SNAPDCB
specifies the address of an open DCB that can be used for SNAP macro
processing. This feature is intended for problem determination. If you specify
this parameter, review “Usage notes” on page 173. For dcbaddr, specify the
address of an open DCB.
172
z/OS DFSMShsm Managing Your Own Data
ARCHRCAL
TEST
specifies whether to refrain from sending a request for service to DFSMShsm.
If YES is specified the service request is not sent. If NO is specified, a service
request is sent to DFSMShsm. In both cases the parameters specified to the
macro are checked for correctness. A 4xx return code results for invalid
parameters. The default is NO.
DAOPT
specifies the type of data set accessing required after the recall of a direct
access data set. This, in turn, implies the allowable target volume DASD types.
The recalled data set must be non-SMS-managed. For details on DAOPT see
“DAOPTION: Selecting target volume track length” on page 133.
TCBTOKEN=CURRENT
specifies that the current TCB TOKEN will be used to validate the ECB on
POST. If not specified, the JOBSTEP TCB TOKEN will be used.
Note: When the TCBTOKEN=CURRENT parameter is used, both the
ASYNC=YES and WAIT=YES parameters must also be used.
Usage notes
1. If a return code of 4xx is returned and SNAPDCB is specified, a SNAP macro is
issued and the request made to DFSMShsm is dumped. The dumped storage
area will include the data set name, volume serial number, and function
requested.
2. If SNAPDCB and TEST=YES were specified, and there was an error flagged in
the MWERC, then a SNAP macro is issued and the MWE is dumped.
Chapter 22. Using DFSMShsm user macros
173
ARCHRCOV
ARCHRCOV: Recovering a data set
The ARCHRCOV macro allows you to recover a backup version or a dump copy
of a data set. This macro can handle only one data set at a time. Consequently, the
macro must be invoked for each data set processed.
Note: All memory areas passed to DFSMShsm through the macro must be in
24-bit addressing mode and below the 16MB line.
Syntax
The following diagram presents the syntax of the ARCHRCOV macro for both
SMS-managed and non-SMS-managed data sets:
►► ARCHRCOV
DSN=dsnaddr, WKAREA=waaddr
►
,WAIT=
NO
YES
,FROMVOL=volseraddr
,GEN=gennumaddr
►
►
,DATE=dateaddr
,VER=vernumaddr
,NEWNAME=dsnaddr
,TIME=timeaddr
,REPLACE=
NO
YES
►
►
,TOVOL=volseraddr
,UNIT=unitaddr
,SNAPDCB=dcbaddr
,TEST=
NO
YES
,DAOPT(
SAMETRK
RELTRK
RELBLK
)
►
►◄
,RCVRQD=
NO
YES
Required parameters
The following are the required parameters of the ARCHRCOV macro:
DSN
specifies the address of a field containing the fully qualified name of the data
set to be processed. For dsnaddr, use the address of the 44-byte data area that
contains the 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.
WKAREA
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.
Optional parameters
The following are the optional parameters of the ARCHRCOV macro:
DAOPT
specifies the type of data set accessing required after the recover of a direct
access data set. This, in turn, implies the allowable target volume DASD types.
The recovered data set must be non-SMS-managed. For details on DAOPT, see
“DAOPTION: Selecting target volume track length” on page 144.
DATE
specifies the address of a field containing the date of creation of a backup
174
z/OS DFSMShsm Managing Your Own Data
ARCHRCOV
version number that you wish to recover. For dateaddr, substitute the address of
a field containing the date of the backup version you wish to recover in one of
the following forms:
v If the system date is after 1999, that field must contain 7 digits in the format
yyyyddd.
v If the system date is before 1 January 2000, that field may contain either (a)
7 digits in the format yyyyddd, where the first two digits are 19, 20, or 21; or
(b) 5 digits in the format yyddd, where the first two digits (prefixed by 19 to
form year 19yy) must be greater than 21.
The backup version that is recovered is the newest one created on or before the
specified date. GEN and DATE are mutually exclusive parameters. You can use
the ARCXTRCT macro in “ARCXTRCT: Extracting data from DFSMShsm” on
page 180 to obtain this backup version number creation date for backup
versions that exist. This parameter applies to both SMS-managed and
non-SMS-managed data sets.
FROMVOL
specifies the address of a field containing the volume serial number of the
volume from which uncataloged data sets were backed up. For volseraddr,
substitute the address of the six-character field that contains the volume serial
number. The volume serial number must be left-justified and padded with
blanks. FROMVOL applies only to non-SMS-managed data sets that were
uncataloged at the time they were backed up.
GEN
specifies the address of a field containing the relative generation number that
you wish to recover. For gennumaddr, substitute the address of a four-byte field
that contains the fullword (binary) generation number to be recovered. You can
use the ARCXTRCT macro in “ARCXTRCT: Extracting data from DFSMShsm”
on page 180 to extract data for the generation numbers that currently exist.
This parameter applies to both SMS-managed and non-SMS-managed data sets.
GEN applies only to active backup copies. You cannot use GEN with retained
copies.
NEWNAME
specifies the address of a field containing a new name for the recovered data
set. For dsnaddr, substitute the address of the 44-byte area that contains the
data set name. The data set name must be left-justified and padded with
blanks. This parameter applies to both SMS-managed and non-SMS-managed
data sets.
RCVRQD
specifies whether to set the recovery required indicator on in the target data
set. This parameter should only be used by forward recovery applications. The
default is NO. This parameter applies to both SMS-managed and
non-SMS-managed data sets.
REPLACE
specifies whether an existing data set with the same name is to be replaced.
The default is NO. This parameter applies to both SMS-managed and
non-SMS-managed data sets.
SNAPDCB
specifies the address of an open DCB that can be used for SNAP macro
processing. This feature is intended for problem determination. If you specify
this parameter, review “Usage notes” on page 177. For dcbaddr, specify the
address of an open DCB.
Chapter 22. Using DFSMShsm user macros
175
ARCHRCOV
TEST
specifies whether to refrain from sending a request for service to DFSMShsm.
If YES is specified, the service request is not sent. If NO is specified, a service
request is sent to DFSMShsm. In both cases the parameters specified for the
macro are checked for correctness. A 4xx return code results for invalid
parameters. The default is NO.
TIME
specifies the address of the field containing the creation time of the backup
version that you want to recover. For timeaddr, substitute the address of the
field that contains the time that the backup version was created in following
form: hhmmss, where the first two digits are hours, the next two digits are
minutes, and the last two digits are seconds. The range for hours is 00–23 and
the range for minutes and seconds is 00–59. If a backup copy with the
specified data and time does not exist, the request fails. You can use the
ARCXTRCT macro to obtain the creation date and time of the backup version
of an existing data set. TIME applies to both SMS-managed and
non-SMS-managed data sets.
Note: If you specify TIME, you must specify DATE. If you specify TIME
without DATE, the ARCHRCOV macro fails.
TOVOL
specifies the address of a field containing the volume serial number of the
volume to which the data set is recovered. For volseraddr, substitute the address
of the six-byte area that contains the specified volume serial number. The
volume serial number must be left-justified and padded with blanks. This
parameter only applies to non-SMS-managed data sets.
Note: When the TOVOL parameter is specified, the UNIT parameter must also
be specified.
UNIT
specifies the address of a field containing the unit type of the volume to which
the data set is to be recovered. For unitaddr, use the address of the four-byte
field that contains the UCB device type. For example, X'3010200F' is the UCB
unit type for a 3390 device. For a table presenting the supported unit types
and UCBs, see Table 12 on page 156. This parameter only applies to
non-SMS-managed data sets.
Note: When the UNIT parameter is specified, the TOVOL parameter must also
be specified.
VER
specifies the address of a field containing the unique version number of the
particular active backed up data set that you would like to recover. For
vernumaddr, substitute the address of a four-byte field that contains the
fullword (binary) version number for the specified backup version. If
DFSMShsm is unable to find the specified backup version, the recover fails and
message ARC1128I is issued. This parameter applies to both SMS-managed and
non-SMS-managed data sets. VER applies only to active backup copies. You
cannot use VER with retained copies.
WAIT
specifies whether you want the application to wait until DFSMShsm has
processed this request. If YES is specified, the application waits until
DFSMShsm completes processing of the request. The default is NO. This
parameter applies to both SMS-managed and non-SMS-managed data sets.
176
z/OS DFSMShsm Managing Your Own Data
ARCHRCOV
Usage notes
1. If a return code of 4xx is returned and SNAPDCB is specified, a SNAP macro is
issued and the request made to DFSMShsm is dumped. The dumped storage
area will include the data set name, volume serial number, and function
requested.
2. If SNAPDCB and TEST=YES were specified, and there was an error flagged in
the MWERC, then a SNAP macro is issued and the MWE is dumped.
Chapter 22. Using DFSMShsm user macros
177
ARCHSEND
ARCHSEND: Sending a command to DFSMShsm
The ARCHSEND macro allows you to send authorized user commands to
DFSMShsm. You must be a DFSMShsm-authorized user to use this macro.
Note: All memory areas passed to DFSMShsm through the macro must be in
24-bit addressing mode and below the 16MB line.
Syntax
The following diagram presents the syntax of the ARCHSEND macro:
►► ARCHSEND
TEXT=textaddr, WKAREA=waaddr
►
,WAIT=
NO
YES
,HOSTID=hostid
,PRIV=
NO
YES
►
►◄
,SNAPDCB=dcbaddr
,TEST=
NO
YES
Required parameters
The following are the required parameters of the ARCHSEND macro:
TEXT
specifies the address of a field containing the command text that is to be
passed to DFSMShsm by the HSENDCMD command. For textaddr, substitute
the address of a variable length area (on a halfword boundary) that contains a
halfword of the length of the text string (including the halfword length field),
followed by the text string of the command to be passed to DFSMShsm.
WKAREA
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.
Optional parameters
The following are the optional parameters of the ARCHSEND macro:
WAIT
specifies whether you want the application to wait until DFSMShsm has
processed this request. If YES is specified, the application waits until
DFSMShsm completes processing of the request. The default is NO.
HOSTID
is a one-character host identifier that is used to distinguish which active
DFSMShsm (main or auxiliary) host is to receive the command. The specified
host ID must match one of the currently active DFSMShsm host IDs. For
requirements of the hostid value, see the topic about startup procedure
keywords in z/OS DFSMShsm Implementation and Customization Guide.
SNAPDCB
specifies the address of an open DCB that can be used for SNAP macro
processing. This feature is intended for problem determination. If you specify
this parameter, review “Usage notes” on page 179. For dcbaddr, specify the
address of an open DCB.
TEST
specifies whether to refrain from sending a request for service to DFSMShsm.
If YES is specified the service request is not sent. If NO is specified, a service
178
z/OS DFSMShsm Managing Your Own Data
ARCHSEND
request is sent to DFSMShsm. In both cases the parameters are checked for
correctness. A 4xx return code will result for invalid parameters. The default is
NO.
PRIV
specifies a reserved keyword for the internal interface from the CATALOG
function to DFSMShsm. If YES is specified, the interface is used. If NO is
specified, the interface is not used. The default is NO.
Usage notes
1. If a return code of 4xx is returned and SNAPDCB is specified, a SNAP macro is
issued and the request made to DFSMShsm is dumped. The dumped storage
area will include the data set name, volume serial number, and function
requested.
2. If SNAPDCB and TEST=YES were specified, and there was an error flagged in
the MWERC, then a SNAP macro is issued and the MWE is dumped.
Chapter 22. Using DFSMShsm user macros
179
ARCXTRCT
ARCXTRCT: Extracting data from DFSMShsm
The ARCXTRCT macro allows you to extract DFSMShsm data within a program.
The data can be used to issue other DFSMShsm user macros.
Note: All memory areas passed to DFSMShsm through the macro must be in
24-bit addressing mode and below the 16MB line.
Syntax
The following diagram presents the syntax of the ARCXTRCT macro.
►► ARCXTRCT
DATA=type,
NO
DEFINE=
YES
FREE=bufarea,
COPYPOOL=cpnameaddr,
DSN=dsnaddr,
WKAREA=waaddr
►
,SNAPDCB=dcbaddr
,
►
►◄
,TEST=
NO
YES
,DATE=dateaddr
,TIME=timeaddr
Required parameters
There are three usage forms for ARCXTRCT, specified by DATA=type,
DEFINE=YES, and FREE=bufarea, respectively. These are mutually exclusive
keywords; only one can be specified per invocation. The three usage forms are
described as follows:
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.
v 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 13 shows the layout for the extract header.
Table 13. Extract Header Layout
Offsets
Dec
180
Type
Bytes
Name
Description
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.
z/OS DFSMShsm Managing Your Own Data
ARCXTRCT
Table 14 shows the layout of each DATA=COPYPOOL backup version entry.
Table 14. Entry for DATA=COPYPOOL backup version
Offsets
Dec
Type
Bytes
Name
Description
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.
....
...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
58
(3A) Character
9(5) CPDINFO
58
(3A) Character
8 CPDCNAME
Dump class name.
66
(42) Bitstring
1 CPDFLAGS
Flags for this dump class.
103
Token.
Array containing dump class info.
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.
5 *
Reserved.
(67) Character
Chapter 22. Using DFSMShsm user macros
181
ARCXTRCT
v 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 13 on page 180 shows the layout of the DATA=BUVERS extract header and
Table 15 shows the layout of each DATA=BUVERS backup version entry.
Table 15. Entry for DATA=BUVERS backup version
Offsets
Dec
182
Type
Bytes
Name
Description
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
32
(20) Character
8 BUVEDATA
Resource data.
40
(28) Bitstring
4 BUVEFLAG
Status flags.
Resource owner.
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.
z/OS DFSMShsm Managing Your Own Data
ARCXTRCT
Table 15. Entry for DATA=BUVERS backup version (continued)
Offsets
Dec
Type
Bytes
Name
Description
.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.
Hex
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.
DEFINE: Defining a DSECT for the data returned
The extract buffer address contains an area with a header, followed by a list of
entries. Both the header and entry definitions are generated. DEFINE=YES specifies
that a DSECT is to be generated. DEFINE=NO is the default. Table 13 on page 180
and Table 14 on page 181 show the layouts of the data buffer that is returned.
FREE: Free the extract buffer
The FREE keyword specifies the address of the extract buffer that was returned by
a previous extract request. If the extract request did not obtain storage, register 1
would be zero. If register 1 is not zero, it is the caller’s responsibility to free the
storage as described by its first four bytes of the extract header layout (shown in
Table 13 on page 180).
Optional parameters
The following are the optional parameters of the ARCXTRCT macro:
DATE
specifies the date and time that the backup version to be extracted was created.
Chapter 22. Using DFSMShsm user macros
183
ARCXTRCT
For dateaddr, specify the address of a data area that contains the backup date.
The field referenced by dateaddr must contain 7 digits in the form of yyyyddd.
The default value for date is 0.
TIME
specifies the time that the backup version to be extracted was created. For
timeaddr, specify the address of the data area that contains the backup time.
The field referenced by timeaddr must contain 6 digits in the form of hhmmss.
The default value for time is 0.
SNAPDCB
specifies the address of an open DCB that can be used for SNAP macro
processing. This feature is intended for problem determination. If you specify
this parameter, review “Usage notes.” For dcbaddr, specify the address of an
open DCB.
TEST
specifies whether to refrain from sending a request for service to DFSMShsm.
If YES is specified the service request is not sent. If NO is specified, a service
request is sent to DFSMShsm. In both cases the parameters are checked for
correctness. A 4xx return code will result for invalid parameters. The default is
NO.
Usage notes
1. You must specify DATE and TIME together and they are valid only with the
DATA=BUVERS form of the macro. Otherwise, the macro fails.
2. The ARCXTRCT DATA=BUVERS output can contain information for up to 100
backup versions. If there are more than 100 backup copies of the specified data
set, DFSMShsm sets the BUVEFMAS flag in the last entry of the output. To
obtain information on the additional backup copies, issue the request again and
specify the DATE and TIME parameters. DFSMShsm returns up to 100 versions
created before the specified date and time.
3. If a return code of 4xx is returned and SNAPDCB is specified, a SNAP macro is
issued and the request made to DFSMShsm is dumped. The dumped storage
area will include the data set name, volume serial number, and function
requested. DFSMShsm also dumps the extract buffer.
4. If SNAPDCB and TEST=YES were specified, and there was an error flagged in
the MWERC, then a SNAP macro is issued and the MWE is dumped.
184
z/OS DFSMShsm Managing Your Own Data
Part 4. Appendixes
© Copyright IBM Corp. 1984, 2017
185
186
z/OS DFSMShsm Managing Your Own Data
Appendix A. DFSMShsm and ISMF line operator reference
summary
Table 16 presents the DFSMShsm/ISMF line operators, summarizes their functions,
and gives the minimum abbreviation that you can use when entering them in the
foreground.
Table 16. DFSMShsm/ISMF Line Operators
Line Operator
Minimum
Abbreviation
CONDENSE
CON
Frees unused space at the end of a partitioned or
sequential data set; compresses a PDS.
DELETE
DE
Deletes a DFSMShsm-migrated data set or an
online data set.
HALTERDS
HA
Changes the maximum number of backup
versions of a data set; changes the minimum
frequency of incremental backup. Cannot be used
on SMS-managed data sets, which are controlled
by the data sets management class parameters. If
used on SMS-managed data sets, the command
fails and an error message is issued.
HBACKDS
HBA
Creates a backup version of a data set.
HBDELETE
HBD
Deletes backup versions of a data set.
HMIGRATE
HMI
Migrates a data set to a DFSMShsm level one or
level two volume.
HRECALL
HRECA
Recalls a data set that has been migrated by
DFSMShsm.
HRECOVER
HRECO
Recovers a backup version of a data set.
© Copyright IBM Corp. 1984, 2017
Description
187
188
z/OS DFSMShsm Managing Your Own Data
Appendix B. Return codes from DFSMShsm commands
The following DFSMShsm commands issue return codes to indicate the success or
failure of their operation:
v HBACKDS
v HDELETE
v HMIGRATE
v HRECALL
v HRECOVER
Return codes are assigned in register 15. This allows the success or failure of the
commands to be tested in a CLIST or batch job. Return codes come from one of
two sets: default and extended.
The default set of return codes appear during normal DFSMShsm operations and
provides a return code that indicates success or one of several errors.
The extended set of return codes is functional only when DFSMShsm commands
are running in a truly interactive mode (TSO or foreground). This extended set of
return codes, which appear when the EXTENDRC and the WAIT parameters are
specified, provides a more detailed indication of processing results by returning
both a return code and a reason code. The EXTENDRC parameter does not apply
when it is used by a terminal monitor program (TMP) or when DFSMShsm
commands are issued from a batch job; although DFSMShsm does not fail the
command, the parameter is ignored. Because the extended set of return and reason
codes may not be completed until after physical completion of backup processing,
the HBACKDS command fails if you use both the CC and EXTENDRC keywords
together.
© Copyright IBM Corp. 1984, 2017
189
Return codes from the default set
Table 17 lists the return codes (retcode) that belong to the default set.
Table 17. Default Set Return Codes
Retcode
Meaning
0
No errors are detected.
Note: It is not considered an error when an HRECALL command finds that
the data set is not cataloged to volume MIGRAT. The informational message
ARC1102I will be issued and zero will be returned in register 15.
12
DFSMShsm functional failure has occurred or more than one type of error
was detected as a multiple data set request was processed. DFSMShsm
received the request and tried to process it, but was unsuccessful.
DFSMShsm issued an error message between messages: ARC1101I and
ARC1900I.
To obtain this return code, the WAIT option must be specified on the
command. Otherwise, only the success or failure of communication with
DFSMShsm is reported.
14
Data set error has occurred and the request was not communicated to
DFSMShsm. A data set error occurs when the data set is not cataloged for a
command that requires a cataloged data set or if the data set name syntax is
incorrect.
16
DFSMShsm SVC path error has occurred. An error has occurred in
attempting to communicate with DFSMShsm. DFSMShsm has not received
the request.
18
A command syntax error was detected.
The default set of return codes is returned in register 15. The following JCL is an
example of using a DFSMShsm command and testing the return code while
running in a batch job:
//LISTDS
JOB...
//*RECOVER DATA SET
//RECOVER EXEC PGM=IKJEFT01
//SYSIN
DD DUMMY
//SYSPRINT DD SYSOUT=A
//SYSTSPRT DD SYSOUT=A
//SYSTSIN DD *
HRECOVER DATA.SET.NAME REPLACE WAIT
/*
//*PRINT DATA SET IF RECOVERY IS SUCCESSFUL
//PRINT EXEC PGM=IDCAMS,COND=(0,NE)
//SYSPRINT DD SYSOUT=A
//SYSIN
DD *
PRINT INDATASET(DATA.SET.NAME)
/*
Return codes from the extended set
When the EXTENDRC parameter is specified on the HBACKDS, HDELETE,
HRECALL, HRECOVER or HMIGRATE commands, DFSMShsm assigns both a
return code and a reason code in register 15 that provides a more detailed
indication of the results from processing the request. In most cases, the return
codes correspond to the message number that DFSMShsm issues to provide an
explanation when the request fails. If there is a reason code associated with the
failure, it is also returned.
190
z/OS DFSMShsm Managing Your Own Data
Important: The return code is returned in the high-order two bytes of register 15.
The reason code is returned in the low-order two bytes of register 15.
To obtain the corresponding message number from the contents of register 15, the
following algorithms are used:
For return code: HSMRC = (contents of register 15 / 65536)
For reason code: HSMREAS = (contents of register 15 - (HSMRC × 65536))
The following example shows how to obtain the return code, the corresponding
message number, and any associated reason code from the contents of register 15.
For this example, when we tried to migrate a data set that was not eligible for
migration, we received the following values:
Table 18. Return codes from the extended set example: register 15 values
Decimal Value
HEX Value
1310724
00140004
v Return code:
HSMRC = (1310724 / 65536)
HSMRC = 20.000061
HSMRC = 20
The HSMRC variable contains the return code value of 20. The return code (or
nn) can be used to locate the corresponding message number; in our migration
example, ARC12nn or ARC1220.
v Reason code:
HSMRC = 20 (return code must be obtained before reason code)
HSMREAS = (1310724 - (20 × 65536))
HSMREAS = (1310724 - 1310720)
HSMREAS = 4
The HSMREAS variable contains the reason code value of 4. Look for this reason
code under the corresponding message number; in our migration example,
message ARC1220 and reason code of 4.
When you are using a TSO CLIST, the return and reason codes are both provided
in register 15 for access as the CLIST variables: &LASTCC or &MAXCC; The
CLIST example (see below) shows how to separate the return and reason codes set
by DFSMShsm from the &LASTCC variable.
When you are using ISPF, the return and reason codes are both provided in
register 15 and can be obtained by using the HELP function. Use the given
algorithms to obtain the return code, the corresponding message number, and any
associated reason code.
The EXTENDRC parameter is best used when single data set requests are issued.
When a multiple data set request is issued, multiple failures are reported with a
single, generic return code of 112.
Table 19 on page 192 lists the return codes that belong to the extended set. These
return codes are returned in the high-order two bytes of register 15 with the
exception of return code 18, which is returned in the low-order two bytes of
register 15.
Appendix B. Return codes from DFSMShsm commands
191
Table 19. Extended set return codes
Retcode
Meaning
0
No errors are detected.
18
A command syntax error is detected. The return code is reported in the
low-order two bytes of register 15.
112
For a multiple data set request, more than one type of error was detected,
or more than one functional failure has occurred.
114
A data set error has occurred. A data set error occurs when the data set is
not cataloged for a command that requires a cataloged data set or if the
data set name syntax is incorrect. DFSMShsm did not receive the request.
116
A DFSMShsm SVC path error has occurred. An error has occurred in
communicating with DFSMShsm. DFSMShsm did not receive the request.
120
An ABEND occurred.
nn
A DFSMShsm functional failure occurred (the WAIT option was specified)
and the MWE return code of the functional failure coincides with ARCxxnn
messages as follows:
v Failing recall/recovery/delete messages ARC1101 to ARC1199 have
return codes 1 to 99.
Note: It is not considered an error when an HRECALL command finds
that the data set is not cataloged to volume MIGRAT. The informational
message ARC1102I will be issued and zero will be returned in register 15.
v Failing migration messages ARC1201 to ARC1299 have return codes 1 to
99.
v Failing backup messages ARC1301 to ARC1399 have return codes 1 to 99.
v Failing DFSMShsm command messages ARC1601 to ARC1699 have
return codes 1 to 99.
v Attention message ARC1800 has return code 100. This return code is
returned when the request is interrupted with a TSO attention request.
v Abnormal ending message ARC1900 of the preceding function has a
return code of 120.
These reason codes have meaning only with specific return codes. Reason codes
are described with the corresponding messages. See z/OS MVS System Messages, Vol
2 (ARC-ASA).
The following fragment is an example of checking return codes when issuing
DFSMShsm commands from a CLIST running in the foreground:
192
z/OS DFSMShsm Managing Your Own Data
/*ERROR EXIT TO GET RETURN AND REASON CODES FROM REGISTER 15*/
ERROR DO
SET
HSMRC = &EVAL(&LASTCC; / 65536)
SET
HSMREAS = &EVAL(&LASTCC - &EVAL(&HSMRC * 65536))
RETURN
END
/*RECOVER THE DATA SET */
HRECOVER DATA.SET.NAME REPLACE WAIT EXTENDRC
IF &HSMRC = 45 THEN /*IF DATA SET IS MIGRATED, RECALL THE DATA SET */
DO
SET HSMRC = 0
SET HSMREAS = 0
HRECALL DATA.SET.NAME WAIT EXTENDRC
IF &HSMRC = 0 THEN /*IF RECALL IS SUCCESSFUL, ATTEMPT DATA SET RECOVER
HRECOVER DATA.SET.NAME REPLACE WAIT EXTENDRC
ELSE /*IF RECALL IS NOT SUCCESSFUL, ISSUE MESSAGE */
DO
WRITE RECALL NOT SUCCESSFUL
EXIT
END
END
ELSE /*IF DATA SET IS NOT MIGRATED OR RECOVERY NOT SUCCESSFUL
/*ISSUE MESSAGE */
DO
WRITE RECOVERY NOT SUCCESSFUL
EXIT
END
EXIT
Return codes from user macros
Programming Interface Information
When using the user macros, DFSMShsm sets a return code in register 15 that
indicates the result of processing the request. In most cases, the return codes
correspond to the message number that DFSMShsm issues to provide an
explanation when the request fails. If there is a reason code associated with the
failure, it is returned in register 0.
Table 20 lists the return codes that are placed in register 15 upon completion of the
invocation of the macro.
Table 20. User Macros Return Codes
Retcode
0
Meaning
Function is successful
100
DFSMShsm is not running or the request could not be communicated to
DFSMShsm
400
Invalid request ID
401
Attempt to free a MWE for an incomplete function (applies to ARCFMWE
only)
402
Data set locate failure (applies to ARCHRCAL and ARCHMIG only)
403
Data set name specified was * or blank
404
The date specified with ARCHRCOV has format yyddd, but the system date
is later than 1999
407
An internal error occurs with the ARCHBACK command.
Appendix B. Return codes from DFSMShsm commands
193
Table 20. User Macros Return Codes (continued)
Retcode
806
Any other
nonzero
Meaning
Link error
Function fails
End Programming Interface Information
Individual macros and their messages
Programming Interface Information
Table 21 lists individual macros and their related messages. xx is the nonzero value
returned in register 15. This hexadecimal value must be converted to decimal
before the corresponding message number can be obtained. For most of the
macros, WAIT must be coded in the macro to get an “any other nonzero” return
code.
Table 21. Messages from Individual Macros
Macro
Message
ARCFMWE
None.
ARCHBACK
See ARC13xx for return codes (use WAIT to get a retcode).
ARCHBDEL
See messages ARC0182 and ARC0183.
ARCHDEL
See message ARC11xx for return codes (use WAIT to get a retcode).
ARCHMIG
See message ARC12xx for return codes (use WAIT to get a retcode).
ARCHRCAL
See message ARC11xx for return codes (use WAIT to get a retcode).
ARCHRCOV
See message ARC11xx for return codes (use WAIT to get a retcode).
ARCHSEND
Dependent on the text sent. For instance, if the text indicated
MIGRATE, then see message ARC12xx (use WAIT to get a retcode).
ARCXTRCT
See message ARC0184I.
End Programming Interface Information
194
z/OS DFSMShsm Managing Your Own Data
Appendix C. Accessibility
Accessible publications for this product are offered through IBM Knowledge
Center (www.ibm.com/support/knowledgecenter/SSLTBW/welcome).
If you experience difficulty with the accessibility of any z/OS information, send a
detailed message to the Contact z/OS web page (www.ibm.com/systems/z/os/
zos/webqs.html) or use the following mailing address.
IBM Corporation
Attention: MHVRCFS Reader Comments
Department H6MA, Building 707
2455 South Road
Poughkeepsie, NY 12601-5400
United States
Accessibility features
Accessibility features help users who have physical disabilities such as restricted
mobility or limited vision use software products successfully. The accessibility
features in z/OS can help users do the following tasks:
v Run assistive technology such as screen readers and screen magnifier software.
v Operate specific or equivalent features by using the keyboard.
v Customize display attributes such as color, contrast, and font size.
Consult assistive technologies
Assistive technology products such as screen readers function with the user
interfaces found in z/OS. Consult the product information for the specific assistive
technology product that is used to access z/OS interfaces.
Keyboard navigation of the user interface
You can access z/OS user interfaces with TSO/E or ISPF. The following
information describes how to use TSO/E and ISPF, including the use of keyboard
shortcuts and function keys (PF keys). Each guide includes the default settings for
the PF keys.
v z/OS TSO/E Primer
v z/OS TSO/E User's Guide
v z/OS ISPF User's Guide Vol I
Dotted decimal syntax diagrams
Syntax diagrams are provided in dotted decimal format for users who access IBM
Knowledge Center with a screen reader. In dotted decimal format, each syntax
element is written on a separate line. If two or more syntax elements are always
present together (or always absent together), they can appear on the same line
because they are considered a single compound syntax element.
Each line starts with a dotted decimal number; for example, 3 or 3.1 or 3.1.1. To
hear these numbers correctly, make sure that the screen reader is set to read out
© Copyright IBM Corp. 1984, 2017
195
punctuation. All the syntax elements that have the same dotted decimal number
(for example, all the syntax elements that have the number 3.1) are mutually
exclusive alternatives. If you hear the lines 3.1 USERID and 3.1 SYSTEMID, your
syntax can include either USERID or SYSTEMID, but not both.
The dotted decimal numbering level denotes the level of nesting. For example, if a
syntax element with dotted decimal number 3 is followed by a series of syntax
elements with dotted decimal number 3.1, all the syntax elements numbered 3.1
are subordinate to the syntax element numbered 3.
Certain words and symbols are used next to the dotted decimal numbers to add
information about the syntax elements. Occasionally, these words and symbols
might occur at the beginning of the element itself. For ease of identification, if the
word or symbol is a part of the syntax element, it is preceded by the backslash (\)
character. The * symbol is placed next to a dotted decimal number to indicate that
the syntax element repeats. For example, syntax element *FILE with dotted decimal
number 3 is given the format 3 \* FILE. Format 3* FILE indicates that syntax
element FILE repeats. Format 3* \* FILE indicates that syntax element * FILE
repeats.
Characters such as commas, which are used to separate a string of syntax
elements, are shown in the syntax just before the items they separate. These
characters can appear on the same line as each item, or on a separate line with the
same dotted decimal number as the relevant items. The line can also show another
symbol to provide information about the syntax elements. For example, the lines
5.1*, 5.1 LASTRUN, and 5.1 DELETE mean that if you use more than one of the
LASTRUN and DELETE syntax elements, the elements must be separated by a comma.
If no separator is given, assume that you use a blank to separate each syntax
element.
If a syntax element is preceded by the % symbol, it indicates a reference that is
defined elsewhere. The string that follows the % symbol is the name of a syntax
fragment rather than a literal. For example, the line 2.1 %OP1 means that you must
refer to separate syntax fragment OP1.
The following symbols are used next to the dotted decimal numbers.
? indicates an optional syntax element
The question mark (?) symbol indicates an optional syntax element. A dotted
decimal number followed by the question mark symbol (?) indicates that all
the syntax elements with a corresponding dotted decimal number, and any
subordinate syntax elements, are optional. If there is only one syntax element
with a dotted decimal number, the ? symbol is displayed on the same line as
the syntax element, (for example 5? NOTIFY). If there is more than one syntax
element with a dotted decimal number, the ? symbol is displayed on a line by
itself, followed by the syntax elements that are optional. For example, if you
hear the lines 5 ?, 5 NOTIFY, and 5 UPDATE, you know that the syntax elements
NOTIFY and UPDATE are optional. That is, you can choose one or none of them.
The ? symbol is equivalent to a bypass line in a railroad diagram.
! indicates a default syntax element
The exclamation mark (!) symbol indicates a default syntax element. A dotted
decimal number followed by the ! symbol and a syntax element indicate that
the syntax element is the default option for all syntax elements that share the
same dotted decimal number. Only one of the syntax elements that share the
dotted decimal number can specify the ! symbol. For example, if you hear the
lines 2? FILE, 2.1! (KEEP), and 2.1 (DELETE), you know that (KEEP) is the
196
z/OS DFSMShsm Managing Your Own Data
default option for the FILE keyword. In the example, if you include the FILE
keyword, but do not specify an option, the default option KEEP is applied. A
default option also applies to the next higher dotted decimal number. In this
example, if the FILE keyword is omitted, the default FILE(KEEP) is used.
However, if you hear the lines 2? FILE, 2.1, 2.1.1! (KEEP), and 2.1.1
(DELETE), the default option KEEP applies only to the next higher dotted
decimal number, 2.1 (which does not have an associated keyword), and does
not apply to 2? FILE. Nothing is used if the keyword FILE is omitted.
* indicates an optional syntax element that is repeatable
The asterisk or glyph (*) symbol indicates a syntax element that can be
repeated zero or more times. A dotted decimal number followed by the *
symbol indicates that this syntax element can be used zero or more times; that
is, it is optional and can be repeated. For example, if you hear the line 5.1*
data area, you know that you can include one data area, more than one data
area, or no data area. If you hear the lines 3* , 3 HOST, 3 STATE, you know
that you can include HOST, STATE, both together, or nothing.
Notes:
1. If a dotted decimal number has an asterisk (*) next to it and there is only
one item with that dotted decimal number, you can repeat that same item
more than once.
2. If a dotted decimal number has an asterisk next to it and several items
have that dotted decimal number, you can use more than one item from the
list, but you cannot use the items more than once each. In the previous
example, you can write HOST STATE, but you cannot write HOST HOST.
3. The * symbol is equivalent to a loopback line in a railroad syntax diagram.
+ indicates a syntax element that must be included
The plus (+) symbol indicates a syntax element that must be included at least
once. A dotted decimal number followed by the + symbol indicates that the
syntax element must be included one or more times. That is, it must be
included at least once and can be repeated. For example, if you hear the line
6.1+ data area, you must include at least one data area. If you hear the lines
2+, 2 HOST, and 2 STATE, you know that you must include HOST, STATE, or
both. Similar to the * symbol, the + symbol can repeat a particular item if it is
the only item with that dotted decimal number. The + symbol, like the *
symbol, is equivalent to a loopback line in a railroad syntax diagram.
Appendix C. Accessibility
197
198
z/OS DFSMShsm Managing Your Own Data
Notices
This information was developed for products and services that are offered in the
USA or elsewhere.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive, MD-NC119
Armonk, NY 10504-1785
United States of America
For license inquiries regarding double-byte character set (DBCS) information,
contact the IBM Intellectual Property Department in your country or send
inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
© Copyright IBM Corp. 1984, 2017
199
This information could include missing, incorrect, or broken hyperlinks.
Hyperlinks are maintained in only the HTML plug-in output for the Knowledge
Centers. Use of hyperlinks in other output formats of this information is at your
own risk.
Any references in this information to non-IBM websites are provided for
convenience only and do not in any manner serve as an endorsement of those
websites. The materials at those websites are not part of the materials for this IBM
product and use of those websites is at your own risk.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
Site Counsel
2455 South Road
Poughkeepsie, NY 12601-5400
USA
Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
200
z/OS DFSMShsm Managing Your Own Data
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which
illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. The sample
programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.
Terms and conditions for product documentation
Permissions for the use of these publications are granted subject to the following
terms and conditions.
Applicability
These terms and conditions are in addition to any terms of use for the IBM
website.
Personal use
You may reproduce these publications for your personal, noncommercial use
provided that all proprietary notices are preserved. You may not distribute, display
or make derivative work of these publications, or any portion thereof, without the
express consent of IBM.
Commercial use
You may reproduce, distribute and display these publications solely within your
enterprise provided that all proprietary notices are preserved. You may not make
derivative works of these publications, or reproduce, distribute or display these
publications or any portion thereof outside your enterprise, without the express
consent of IBM.
Rights
Except as expressly granted in this permission, no other permissions, licenses or
rights are granted, either express or implied, to the publications or any
information, data, software or other intellectual property contained therein.
IBM reserves the right to withdraw the permissions granted herein whenever, in its
discretion, the use of the publications is detrimental to its interest or, as
determined by IBM, the above instructions are not being properly followed.
You may not download, export or re-export this information except in full
compliance with all applicable laws and regulations, including all United States
export laws and regulations.
IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE
PUBLICATIONS. THE PUBLICATIONS ARE PROVIDED "AS-IS" AND WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING
BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY,
Notices
201
NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.
IBM Online Privacy Statement
IBM Software products, including software as a service solutions, (“Software
Offerings”) may use cookies or other technologies to collect product usage
information, to help improve the end user experience, to tailor interactions with
the end user, or for other purposes. In many cases no personally identifiable
information is collected by the Software Offerings. Some of our Software Offerings
can help enable you to collect personally identifiable information. If this Software
Offering uses cookies to collect personally identifiable information, specific
information about this offering’s use of cookies is set forth below.
Depending upon the configurations deployed, this Software Offering may use
session cookies that collect each user’s name, email address, phone number, or
other personally identifiable information for purposes of enhanced user usability
and single sign-on configuration. These cookies can be disabled, but disabling
them will also eliminate the functionality they enable.
If the configurations deployed for this Software Offering provide you as customer
the ability to collect personally identifiable information from end users via cookies
and other technologies, you should seek your own legal advice about any laws
applicable to such data collection, including any requirements for notice and
consent.
For more information about the use of various technologies, including cookies, for
these purposes, see IBM’s Privacy Policy at ibm.com/privacy and IBM’s Online
Privacy Statement at ibm.com/privacy/details in the section entitled “Cookies,
Web Beacons and Other Technologies,” and the “IBM Software Products and
Software-as-a-Service Privacy Statement” at ibm.com/software/info/productprivacy.
Policy for unsupported hardware
Various z/OS elements, such as DFSMS, JES2, JES3, and MVS, contain code that
supports specific hardware servers or devices. In some cases, this device-related
element support remains in the product even after the hardware devices pass their
announced End of Service date. z/OS may continue to service element code;
however, it will not provide service related to unsupported hardware devices.
Software problems related to these devices will not be accepted for service, and
current service activity will cease if a problem is determined to be associated with
out-of-support devices. In such cases, fixes will not be issued.
Minimum supported hardware
The minimum supported hardware for z/OS releases identified in z/OS
announcements can subsequently change when service for particular servers or
devices is withdrawn. Likewise, the levels of other software products supported on
a particular release of z/OS are subject to the service support lifecycle of those
products. Therefore, z/OS and its product publications (for example, panels,
samples, messages, and product documentation) can include references to
hardware and software that is no longer supported.
v For information about software support lifecycle, see: IBM Lifecycle Support for
z/OS (www.ibm.com/software/support/systemsz/lifecycle)
202
z/OS DFSMShsm Managing Your Own Data
v For information about currently-supported IBM hardware, contact your IBM
representative.
Programming interface information
This document primarily documents information that is not intended to be used as
a programming interface of DFSMShsm.
This document also documents intended programming interfaces that allow the
customer to write programs to obtain the services of DFSMShsm. This information
is identified where it occurs, either by an introductory statement or by the
following marking:
Programming Interface Information
Programming interface information.
End Programming Interface Information
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
A current list of IBM trademarks is available at Copyright and Trademark
information (www.ibm.com/legal/copytrade.shtml).
Notices
203
204
z/OS DFSMShsm Managing Your Own Data
Index
A
abbreviating commands and
parameters 36
accessibility 195
contact IBM 195
features 195
active backup copies 62
AGE subparameter, HLIST SELECT
command 95, 100
ARCFMWE user macro 158
ARCHBACK user macro 159
ARCHBDEL user macro 164
ARCHDEL user macro 166
ARCHMIG user macro
optional parameters 168
overview 168
required parameters 168
ARCHRCAL user macro 171
ARCHRCOV user macro 174
ARCHSEND user macro 178
ARCINBAK program 68
ARCXTRCT user macro 180
assistive technologies 195
ASYNC parameter,
ARCHBACK user macro 159, 161
ARCHRCAL user macro 171
attention key, TSO 39
automatic
backup 23
interval migration 17
on-demand migration 17
primary space management 17
recall 18
secondary space management 17
space management 17
volume space management 17
availability management 4, 23
B
backup
and recovery 23
automatic 23
changed data sets 23
command 24
control data set 31
data sets to DASD or tape 57
function 23, 24
inline, description 24, 67
inline, invoking 68
profile, discrete RACF 9
version to recover, HRECOVER 146
versions
altering data set for
installation-specified number,
example 52
altering data set for maximum
versions, example 52
altering data set for minimum
frequency, example 52
© Copyright IBM Corp. 1984, 2017
backup (continued)
versions (continued)
deleting all, example 81
deleting specific versions 81
frequency of creation,
HALTERDS 50
number to delete, HBDELETE 79
number to keep, HALTERDS 51
number to maintain,
HALTERDS 51
recover, HRECOVER 146
volume 23
backup data set deletion, expired 30
BACKUPCONTROLDATASET parameter,
HLIST command 95, 97
BACKUPVOLUME parameter, HLIST
command 95
batch mode processing 40
batch mode processing, example of
JCL 40
BOTH parameter, HLIST command 95,
97
building a data set list 14
C
cancel
backup version, HCANCEL 84
request numbers, example 85
requests submitted by a particular
user, example 85
requests submitted to process a
particular data set, example 85
CC parameter
ARCHBACK user macro 64, 159
HBACKDS command 64
changed data set, backup 23
CHANGEDONLY parameter,
HBACKDS command (non-SMS) 57,
60
HBACKDS command (SMS) 57, 60
CLOUD parameter
HMIGRATE command 122
CLOUD parameter, ARCHMIG user
macro 168
command
syntax diagrams 33
command backup 24
command migration 119
commands
abbreviating commands and
parameters 36
authorization 11, 43
comments 36
conventions used 36
delimiters 36
HALTERDS 49
HBACKDS 57
HBDELETE 77
HCANCEL 83
HDELETE 89
commands (continued)
HELP 39
HLIST 93
HMIGRATE 119
HQUERY command 125
HRECALL 131
HRECOVER 141
keyword parameters 35
line continuations 36
positional parameters 35
space maintenance 21
syntax 38
TSO terminal users 21, 31
TSO/E terminal users 21, 31
comments, using commands 36
compression
partitioned data set 29
contact
z/OS 195
control data sets
backup 31
migration 31
offline 31
controlling the source of information
listed, HLIST command 97
conventions, using commands 36
COPYPOOL parameter
ARCXTRCT user macro 180
D
daily backup volume definition 5
DAOPT parameter
ARCHRCAL user macro 171, 173
ARCHRCOV user macro 174
DAOPTION parameter
HRECALL command (non-SMS) 131,
133
HRECOVER command
(non-SMS) 142, 144
DASD (direct access storage device)
backup 23
recovery 24
DATA parameter, ARCXTRCT user
macro 180, 183
data set
altering 53
installation-specified versions and
maximum frequency,
example 52
list of versions and frequency,
example 53
maximum backup versions and
minimum frequency,
example 52
using HALTERDS 50
backup
control 31
not waiting, example 66
delete, HDELETE 89
deleting partitioned data sets 90
205
data set (continued)
deletion
of expired 29
of expired backup 30
extent reduction 30
journal 31
listing entries, HLIST 98
listing, HLIST 93, 104
migration control 31
name
cancelling queued requests
HCANCEL 83, 84
cancelling requests 85
cancelling, HCANCEL 87
copied for backup, HBACKDS 60
deleting backup versions,
HBDELETE 77, 83
filter 37
listing request, HQUERY 125, 127
recovered data set,
HRECOVER 147, 148
offline control 31
partitioned, compression 29
password protected 10
recalling 131
recover from backup,
HRECOVER 143
recovery 141
recovery, by generation number,
example 150
return codes and reason codes
HBACKDS example 67, 156
HDELETE example 92
HMIGRATE example 124
HRECALL example 136
HRECOVER example 151
space overallocation, release 29
temporary, deleting 29
with same user prefix using asterisk
in data set name, not waiting
example 66
data set list, building 14
data set not waiting, example 66
DATASETNAME parameter,
HCANCEL command 83, 84
HLIST command 95
HQUERY command 125
DATE parameter,
ARCHRCOV user macro 174
HRECOVER command
(non-SMS) 142, 146
HRECOVER command (SMS) 142,
146
DEFINE parameter, ARCXTRCT user
macro 180, 183
delete
all backup versions of a cataloged
data set, example 81
backup version HBDELETE 77
group of data sets, HDELETE 89
group of data sets, not waiting,
example 91
inactive 17
migrated data set HDELETE 89
migrated data set, waiting,
example 91
partitioned data set 90
206
delete (continued)
password-protected data set, not
waiting, example 91
specific backup versions of an
uncataloged data set, example 81
two data sets, not waiting,
example 92
deletion
expired backup data sets 30
expired data sets 29
temporary data sets 29
delimiters, using commands 36
device type for receiving volume
specifying HRECALL 134
specifying HRECOVER 149
device type for the volume,
HBACKDS 63
DFSMShsm
HALTERDS command 47
HBACKDS command 55
HBDELETE command 73
HCANCEL command 83
HDELETE command 87
HLIST command 93
HMIGRATE command 117
HQUERY command 125
HRECALL command 129
HRECOVER command 137
incompatibilities 39
introduction 3
line operator reference summary 187
line operators 15
storage device support 5
using with ISMF 13
DFSMShsm-managed
volume entries, listing, HLIST 96
volumes 5
discrete
RACF backup profile 9
RACF profiles 9
DLRKEEP parameter,
ARCHRCAL user macro 172
DSN parameter,
ARCHBACK user macro 159
ARCHBDEL user macro 164
ARCHDEL user macro 166
ARCHMIG user macro 168
ARCHRCAL user macro 171
ARCHRCOV user macro 174
ARCXTRCT user macro 180, 182
dsname parameter
(non-SMS)
HBACKDS command 57
HBDELETE command 77, 80
HRECALL command 131, 132
HRECOVER command 142, 143
(SMS)
HBACKDS command 57
HBDELETE command 77, 80
HRECALL command 131, 132
HRECOVER command 142, 143
HALTERDS command 49, 50
HDELETE command 89
HMIGRATE command 119, 120
DSNENQ parameter, ARCHBACK user
macro 159, 162
z/OS DFSMShsm Managing Your Own Data
E
ECBADDR parameter, ARCFMWE user
macro 158
entering
the HALTERDS command 47
the HDELETE command 87
the HMIGRATE command 117
the HRECALL command 129
the HRECOVER command 137
examples
coding commands
HALTERDS 52
HBACKDS 66
HBDELETE 81
HCANCEL 84
HDELETE 91
HLIST 102
HMIGRATE 123
HQUERY 126
HRECALL 135
HRECOVER 150
expired backup data set deletion 30
expired data set deletion 29
extended return codes 191
EXTENDRC parameter,
(non-SMS)
HBACKDS command 57, 61
HRECALL command 131, 134
HRECOVER command 142, 145
(SMS)
HBACKDS command 57, 61
HRECALL command 131, 134
HRECOVER command 142, 145
HDELETE command 89, 91
HMIGRATE command 119, 123
EXTENDRC, using commands 189
extent reduction 30
F
filter, data set name 37
FORCML1 parameter, ARCHMIG user
macro 169
FREE parameter, ARCXTRCT user
macro 180, 183
frequency of creating backup versions,
HALTERDS 50
FREQUENCY parameter, HALTERDS
command 49, 50
FROMVOL parameter,
ARCHBDEL user macro 164, 165
ARCHRCOV user macro 174, 175
FROMVOLUME parameter
HBDELETE command (non-SMS) 77,
80
HRECOVER command 142, 145
function
availability management 23
space management 17
G
GEN parameter, ARCHRCOV user
macro 174, 175
GENERATION parameter,
HRECOVER 142, 146
K
generic RACF profiles 9
group of data sets
deleting, example 91
recalling, example 136
keyboard
navigation 195
PF keys 195
shortcut keys 195
keyword, parameters using
commands 35
H
HALTERDS command
description 49
line operator, example
HBACKDS command
description 57
line operator, example
HBDELETE command
description 77
line operator, example
HCANCEL command 83
HDELETE command
description 89
line operator, example
HLIST command
description 93
sample lists from 104
HMIGRATE command
description 119
line operator, example
HQUERY command
description 125
example 126
HRECALL command
description 131
line operator, example
HRECOVER command
description 141
line operator, example
47
55
73
87
117
129
137
I
IDCAMS considerations 40
INCLUDEPRIMARY parameter, HLIST
command 95, 98
incompatibilities caused by DFSMShsm
IDCAMS 40
IEHMOVE utility 40
inline backup
data set eligibility 67
description 24, 67
example JCL 69
invoking 68
return codes 68
introduction to DFSMShsm 3
ISMF (interactive storage management
facility)
invoking 13, 14
line operator reference summary 187
line operators, using 15
using with DFSMShsm 13
J
JCL
batch processing example 40
inline backup example 69
journal data set 31
L
last-use mode 16
level 1 volumes, migration 5
level 2 volumes, migration 5
LEVEL parameter, HLIST command 95
line continuations using commands 36
line operator
data set list, building 14
feedback for successful completion or
submission 16
HALTERDS command 47
HDELETE example 87
HMIGRATE example 117
HRECALL example 129
HRECOVER example 137
mode 16
reference summary 187
using to perform DFSMShsm
tasks 15
list of pending DFSMShsm requests
HQUERY command 125
list pending requests
by request number, example 126
data set, example 126
for your user identification,
example 126
listing
all migration volume entries from
migration control data set,
example 103
all pending requests for your user
identification, example 126
by request number, HQUERY 126
data set entries
for level 1 volume and sending to
terminal, example 103
from migration control data set
and printing at the terminal,
example 102
DFSMShsm-managed and migration
volume entries, HLIST 96
entries for a backup volume,
HLIST 95
entries for a data set, HLIST 95
entries for a user, HLIST 97
entries for data sets of selected age
and sending to output data set,
example 103
entries for data sets on level 2
volumes from backup control data
set, example 103
entries for data sets residing in a
small-data-set-packing data set of a
specific volume, example 103
entry for backup volume,
example 103
listing (continued)
migrated data set entries even though
data sets may have been recalled,
HLIST 98
migration and backup control data set
entries, HLIST 93, 104
only data sets that meet selection
criteria, HLIST 99
requesting a summary 102
requests by data set name,
HQUERY 125
specifying data set organization 102
lists produced by HLIST, samples 104
location of output for the listing 98
logging onto ISMF
master application menu 13
primary option menu 13
M
macro
ARCFMWE 158, 194
ARCHBACK 159, 194
ARCHBDEL 164, 194
ARCHDEL 166, 194
ARCHMIG 168, 194
ARCHRCAL 171, 194
ARCHRCOV 174, 194
ARCHSEND 178, 194
ARCXTRCT 180, 194
management, automatic space 17
maximum concurrent recall tasks 18
MIGLVL parameter, ARCHMIG user
macro 168, 169
migrate a data set with HMIGRATE 119
migrated data sets
deleting 89
deleting, example 91
purging, example 91
migration
command 119
control data set 31
data sets to level 2 volume, not
waiting, example 124
directly to Cloud storage
specifying HMIGRATE 122
directly to level 2 volume
example 124
specifying HMIGRATE 121
level 1 volumes 4, 5
level 2 volumes 4, 5
multiple data sets to level 2 volume,
not waiting, example 124
password-protected data set to a level
1 volume, example 124
volume entries, listing using
HLIST 96
MIGRATIONCONTROLDATASET
parameter, HLIST command 95, 97
MIGRATIONLEVEL1 parameter, HLIST
command 95, 96
MIGRATIONLEVEL1 subparameter,
HLIST SELECT command 95, 100
MIGRATIONLEVEL2 parameter
HLIST command 95, 96
HMIGRATE command 119, 121
Index
207
MIGRATIONLEVEL2 subparameter,
HLIST SELECT command 95, 100
MIGRATIONVOLUME parameter, HLIST
command 95, 96
MOVE parameter,
HMIGRATE command 119, 123
MOVE parameter, ARCHMIG user
macro 169
moving processing
extended set
HMIGRATE 123
N
name of data set
being altered, HALTERDS 50
being deleted, HDELETE 89
being migrated, HMIGRATE 120
being recalled, HRECALL 131
being recovered, HRECOVER 143
navigation
keyboard 195
new data set name for recovered data set,
HRECOVER 147
NEWNAME parameter
ARCHRCOV user macro 174, 175
HRECOVER command
(non-SMS) 142, 147
HRECOVER command (SMS) 142,
147
NOSMALLDATASETPACKING
subparameter, HLIST SELECT
command 95, 101
NOWAIT parameter,
(non-SMS)
HBACKDS command 57, 64
HRECALL command 131, 135
HRECOVER command 142, 150
(SMS)
HBACKDS command 57, 64
HRECALL command 131, 135
HRECOVER command 142, 150
HDELETE command 89, 90
HMIGRATE command 119, 122
number of backup versions to maintain,
HALTERDS 51
O
offline control data set 31
OUTDATASET parameter, HLIST
command 95, 98
output for the listing, HLIST
command 98
overallocated space, release 29
P
parameters
abbreviating commands 36
keyword, using commands 35
positional, using commands 35
password protection data set 10
password-protected data set
backing up, example 66
deleting, example 91
208
password-protected data set (continued)
migration, example 124
recalling, example 136
recovering and renaming,
example 151
renaming during recovery 147
transition processing, example 124
waiting, example 66
password, specifying data set 38
PDS (partitioned data set)
compression, space management 29
deleting 90
performing DFSMShsm tasks with line
operators 15
positional parameters using
commands 35
PRIMARYVOLUME parameter,
HLIST 95, 96
PRIV parameter, ARCHSEND user
macro 179
processing, batch mode 40
profile
discrete RACF 9
generic RACF 9
programming interface information 203
protection
password 10
RACF 9
PURGE parameter
ARCHDEL user macro 166
HDELETE command 89, 90
Q
query pending requests
example 126
HQUERY command 125
R
RACF (resource access control facility)
authority 9
command 11, 43
data set 10
password 10
profile 9
protection 9
RCVRQD parameter, ARCHRCOV user
macro 174, 176
reason codes
extended set
HBACKDS 61
HDELETE 91
HMIGRATE 123
HRECALL 134
HRECOVER 145
recall
data sets 18
definition 18
description 18
recalling
group of data sets, not waiting,
example 136
migrated data set, HRECALL 131
z/OS DFSMShsm Managing Your Own Data
recalling (continued)
password-protected data set to
specific volume, waiting,
example 136
two data sets to a volume, not
waiting, example 135, 136
receiving volume
for recalled data set, HRECALL 134
recovered data set, HRECOVER 149
recover tape takeaway 23, 68
recovering
backup version of a data set
HRECOVER 141
backup version to replace a data set,
not waiting, example 151
password-protected data set, renaming
it, waiting, example 151
specific backup version by generation
number, waiting, example 150
recovery
and backup 23
description 24
recovery of a data set 141
reference summary, line operators 187
releasing overallocated space 29
renaming recovered password-protected
data set, example 151
REPLACE parameter,
ARCHRCOV user macro 174, 175
HRECOVER command
(non-SMS) 142, 148
HRECOVER command (SMS) 142,
148
replacing data set
example 151
specifying HQUERY 143
request number
cancelling HCANCEL 85
cancelling queued requests
HCANCEL 83
cancelling, example 85
listing HQUERY 125
REQUEST parameter,
HCANCEL command 83, 84
HQUERY command 125, 126
restore 24, 142, 145, 146, 148
RETAINDAYS parameter, HBACKDS
command 62
retained backup copies 62
return codes
extended set
HBACKDS 61
HDELETE 91
HMIGRATE 123
HRECALL 134
HRECOVER 145
from default set 190
from extended set 190
from user macros 193
S
sample lists from HLIST 104
SELECT parameter, HLIST
command 95, 99
selected data sets, HLIST 99
selecting entries
data set in use, HLIST 100
migrated to small-data-set-packing
data set, HLIST 101
volume, HLIST 100
sending comments to IBM xiii
shortcut keys 195
SMALLDATASETPACKING
subparameter, HLIST SELECT
command 95, 101
SMS (Storage Management Subsystem)
storage class 6
storage tasks 6
SMSAREA parameter,
ARCHMIG user macro 169
SNAPDCB parameter,
ARCFMWE user macro 158
ARCHBACK user macro 159, 162
ARCHBDEL user macro 164, 165
ARCHDEL user macro 166
ARCHMIG user macro 168, 169
ARCHRCAL user macro 171, 172
ARCHRCOV user macro 174, 175
ARCHSEND user macro 178
ARCXTRCT user macro 180, 184
source volume
for recovered data set 145
specifying the HRECOVER 145
space management
automatic 17
expired backup data set deletion 30
expired data set deletion 29
extent reduction 30
partitioned data set compression 29
purpose 17
release of overallocated space 29
temporary data set deletion 29
space, release of overallocated 29
specifying
data set names 37
volume data set resided,
HBDELETE 80
spill backup volume 5
storage device support 5
Summary of changes xv
SUMMARY parameter, HLIST
command 95, 102
support, storage device 5
syntax diagrams
how to read 33
syntax of DFSMShsm user
commands 33
SYSFREQUENCY parameter, HALTERDS
command 49, 50
SYSOUT parameter, HLIST
command 95, 98
SYSVERSIONS parameter, HALTERDS
command 49, 51
T
TARGET parameter
ARCHBACK user macro 162
HBACKDS command 64
target volume
for recalled data set 134
recovered data set, HRECOVER
149
tasks, maximum number of recall 18
TCBTOKEN=CURRENT parameter
ARCHRCAL user macro 173
temporary data set
deletion 29
TERMINAL parameter, HLIST
command 95, 98
TEST parameter,
ARCFMWE user macro 158
ARCHBACK user macro 159, 163
ARCHBDEL user macro 164, 165
ARCHDEL user macro 166, 167
ARCHMIG user macro 168, 169
ARCHRCAL user macro 171, 173
ARCHRCOV user macro 174, 176
ARCHSEND user macro 178
ARCXTRCT user macro 180, 184
TEXT parameter, ARCHSEND user
macro 178
TOVOL parameter,
ARCHRCAL user macro 171, 172
ARCHRCOV user macro 174, 176
TOVOLUME parameter, HRECOVER
command 142, 149
trademarks 203
transition
processing, example 124
TRANSITION parameter,
HMIGRATE command 119
TRANSITION parameter, ARCHMIG user
macro 170
TSO attention key 39
type of device
HBACKDS 63
specifying HRECALL 134
specifying HRECOVER 149
U
UNIT parameter,
ARCHBACK user macro 159, 162
ARCHRCAL user macro 171, 172
ARCHRCOV user macro 174, 176
HBACKDS command (non-SMS) 57,
63
HRECALL command (non-SMS) 131,
134
HRECOVER command
(non-SMS) 142, 149
user
commands 21, 31
listing entries for, HLIST 97
user commands, using 43
user interface
ISPF 195
TSO/E 195
user macros
ARCFMWE 158, 194
ARCHBACK 159, 194
ARCHBDEL 164, 194
ARCHDEL 166, 194
ARCHMIG 168, 194
ARCHRCAL 171, 194
ARCHRCOV 174, 194
ARCHSEND 178, 194
ARCXTRCT 180, 194
USER parameter, HLIST command 95,
97
userid
cancelling HCANCEL 87
cancelling queued requests
HCANCEL 83
cancelling requests 85
USERID parameter, HCANCEL
command 83, 84
using
abbreviating commands and
parameters 36
asterisks in data set name,
example 66
comments 36
conventions used 36
delimiters 36
keyword parameters 35
line continuations 36
line operators to perform DFSMShsm
tasks 15
positional parameters 35
using commands
DFSMShsm user commands 43
DFSMShsm with the MVS/XA
Interactive Storage Management
Facility 13
EXTENDRC, HBACKDS example 67
EXTENDRC, HDELETE example 92
EXTENDRC, HMIGRATE
example 124
EXTENDRC, HRECALL example 136
EXTENDRC, HRECOVER
example 151
Using DFSMShsm User Macros 16
V
VER parameter, ARCHRCOV user
macro 174
VERS parameter, ARCHBDEL user
macro 164
VERSION parameter,
(non-SMS)
HBDELETE command
(non-SMS) 77, 79
HRECOVER command
(non-SMS) 142, 146
(SMS)
HBDELETE command (SMS) 77,
79
HRECOVER command
(SMS) 142, 146
HALTERDS command 49, 51
volume
daily backup 5
deleting backup versions,
HBDELETE 80
DFSMShsm-managed 5
dump 5
listing
backup volume entries, HLIST 95
DFSMShsm-managed volume
entries, HLIST 96
migration volume entries,
HLIST 96
migration level 1 5
Index
209
volume (continued)
migration level 2 5
receive recalled data set,
HRECALL 134
receive recovered data set,
HRECOVER 149
spill backup 5
where data set resides,
HBACKDS 63
VOLUME parameter,
ARCHBACK user macro 159, 162
HBACKDS command (non-SMS) 57,
63
HLIST command 95, 96
HRECALL command (non-SMS) 131,
134
VOLUME subparameter, HLIST SELECT
command 95, 100
VSAM subparameter, HLIST SELECT
command 95, 102
W
WAIT parameter
(non-SMS)
HBACKDS command 57, 64
HRECALL command 131, 135
HRECOVER command 142, 150
(SMS)
HBACKDS command 57, 64
HRECALL command 131, 135
HRECOVER command 142, 150
ARCHBACK user macro 159, 161
ARCHDEL user macro 166
ARCHMIG user macro 168, 170
ARCHRCAL user macro 171, 172
ARCHRCOV user macro 174, 176
ARCHSEND user macro 178
HDELETE command 89, 90
HMIGRATE command 119, 122
WKAREA parameter
ARCFMWE user macro 158
ARCHBACK user macro 159
ARCHBDEL user macro 164, 165
ARCHDEL user macro 166
ARCHMIG user macro 168
ARCHRCAL user macro 171
ARCHRCOV user macro 174
ARCHSEND user macro 178
ARCXTRCT user macro 180, 183
210
z/OS DFSMShsm Managing Your Own Data
IBM®
Product Number: 5650-ZOS
Printed in USA
SC23-6870-30
Download PDF
Similar pages