z/OS


DFSMS: Using Data Sets

SC26-7410-05
z/OS


DFSMS: Using Data Sets

SC26-7410-05
 Note
Before using this information and the product it supports, be sure to read the general information under “Notices” on page
645.

Sixth Edition, September 2005

This edition applies to Version 1 Release 7 of z/OS® (5694-A01), Version 1 Release 7 of z/OS.e (5655-G52), and to all
subsequent releases and modifications until otherwise indicated in new editions.
This edition replaces SC26-7410-04.
IBM® welcomes your comments. A form for readers’ comments may be provided at the back of this publication, or
you may address your comments to the following address:
International Business Machines Corporation
Department 55JA, Mail Station P384
2455 South Road
Poughkeepsie, NY 12601-5400
United States of America

FAX (United States & Canada): 1+845+432-9405

FAX (Other Countries):
Your International Access Code +1+845+432-9405

IBMLink™ (United States customers only): IBMUSM10(MHVRCFS)

Internet e-mail: mhvrcfs@[Link]
World Wide Web: [Link]
If you would like a reply, be sure to include your name, address, telephone number, or FAX number.
Make sure to include the following in your comment or note:
v Title and order number of this document
v Page number or topic related to your comment
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 1987, 2005. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . xiii Actual and Relative Addressing with Non-VSAM
Access Methods . . . . . . . . . . . . 10
Tables . . . . . . . . . . . . . . . xv Magnetic Tape Volumes . . . . . . . . . . 11
Using Magnetic Tape Labels . . . . . . . . 12
Specifying the File Sequence Number . . . . . 12
About This Document . . . . . . . . xvii Identifying Unlabeled Tapes . . . . . . . . 14
Major Divisions of This Document . . . . . . xvii Using Tape Marks . . . . . . . . . . . 15
Required product knowledge . . . . . . . . xvii Data Management Macros . . . . . . . . . 15
Referenced documents . . . . . . . . . . xviii Data Set Processing . . . . . . . . . . . . 16
Accessing z/OS DFSMS documents on the Allocating Data Sets . . . . . . . . . . 16
Internet . . . . . . . . . . . . . . . xviii Processing Data Sets through Programs . . . . 17
Using LookAt to look up message explanations xviii Using Access Methods . . . . . . . . . . 17
Using Addressing Modes . . . . . . . . . 17
Summary of Changes . . . . . . . . xxi Using Hiperspace and Hiperbatch . . . . . . 18
Summary of Changes for SC26-7410-05 z/OS Processing VSAM Data Sets . . . . . . . . 18
Version 1 Release 7 . . . . . . . . . . . xxi Processing PDSs, PDSEs, and UNIX Directories 18
New Information . . . . . . . . . . . xxi Processing Sequential Data Sets and Members of
Changed Information . . . . . . . . . . xxi PDSEs and PDSs . . . . . . . . . . . 19
Deleted Information . . . . . . . . . . xxi Processing UNIX Files with an Access Method . 20
Summary of Changes for SC26-7410-04 z/OS Processing EXCP, EXCPVR, and XDAP Macros 21
Version 1 Release 6 . . . . . . . . . . . xxii Distributed Data Management (DDM) Attributes . . 21
New Information . . . . . . . . . . . xxii Virtual I/O for Temporary Data Sets . . . . . . 21
Changed Information . . . . . . . . . xxii Data Set Names . . . . . . . . . . . . . 22
Summary of Changes for SC26-7410-03 z/OS Catalogs and Volume Table of Contents . . . . . 23
Version 1 Release 5 . . . . . . . . . . . xxii VTOC . . . . . . . . . . . . . . . 23
New Information . . . . . . . . . . . xxii Catalogs . . . . . . . . . . . . . . 23
Changed Information . . . . . . . . . xxiii Data Set Names and Metadata . . . . . . . 24
Moved Information . . . . . . . . . . xxiii Security of Data Set Names . . . . . . . . 25
Summary of Changes for SC26-7410-02 z/OS
Version 1 Release 3 . . . . . . . . . . . xxiii Chapter 2. Using the Storage
New Information . . . . . . . . . . . xxiii Management Subsystem . . . . . . . 27
Changed Information . . . . . . . . . xxiii
Using Automatic Class Selection Routines . . . . 29
Allocating Data Sets . . . . . . . . . . . 30
Part 1. All Data Sets . . . . . . . . . 1 Allocating Data Sets with JCL . . . . . . . 30
Allocating System-Managed Data Sets with the
Chapter 1. Working with Data Sets . . . 3 Access Method Services ALLOCATE Command . 32
Data Storage and Management . . . . . . . . 3 Allocating Data Sets with the TSO ALLOCATE
System-Managed Data Sets . . . . . . . . 4 Command . . . . . . . . . . . . . . 34
Distributed File Manager . . . . . . . . . 4 Allocating Data Sets with Dynamic Allocation . . 34
Access Methods . . . . . . . . . . . . . 4
Basic Direct Access Method . . . . . . . . 4 Chapter 3. Allocating Space on Direct
Basic Partitioned Access Method . . . . . . . 5 Access Volumes . . . . . . . . . . 35
Basic Sequential Access Method . . . . . . . 5 Specification of Space Requirements . . . . . . 35
Data-in-Virtual (DIV) . . . . . . . . . . 5 Blocks . . . . . . . . . . . . . . . 35
Indexed Sequential Access Method . . . . . . 5 Average Record Length . . . . . . . . . 36
Object Access Method . . . . . . . . . . 6 Tracks or Cylinders . . . . . . . . . . . 36
Queued Sequential Access Method . . . . . . 6 Absolute Track . . . . . . . . . . . . 37
Virtual Storage Access Method . . . . . . . 6 Additional Space-Allocation Options . . . . . 37
Access to z/OS UNIX Files . . . . . . . . 7 Maximum Data Set Size . . . . . . . . . . 37
Selection of an Access Method . . . . . . . 7 Maximum Size on One Volume . . . . . . . 37
Direct Access Storage Device (DASD) Volumes . . . 8 Maximum Number of Volumes . . . . . . . 37
DASD Labels . . . . . . . . . . . . . 8 Maximum VSAM Data Set Size . . . . . . . 38
Track Format . . . . . . . . . . . . . 8 | Minimum data set size . . . . . . . . . . 38
Track Overflow . . . . . . . . . . . . 9 Primary and Secondary Space Allocation without
VSAM Record Addressing . . . . . . . . . 9 the Guaranteed Space Attribute . . . . . . . . 38

© Copyright IBM Corp. 1987, 2005 iii

 Multivolume VSAM Data Sets . . . . . . . 39 Chapter 6. Organizing VSAM Data Sets 73
Multivolume Non-VSAM Data Sets . . . . . 39 VSAM Data Formats . . . . . . . . . . . 73
Extended-Format Data Sets . . . . . . . . 39 Data Set Size . . . . . . . . . . . . . 73
Allocation of Data Sets with the Guaranteed Space Control Intervals . . . . . . . . . . . 74
Attribute . . . . . . . . . . . . . . . 40 Control Information Fields . . . . . . . . 74
Guaranteed Space with DISP=NEW or MOD . . 40 Compressed Control Information Field . . . . 76
Guaranteed Space for VSAM . . . . . . . 40 Control Areas. . . . . . . . . . . . . 77
Guaranteed Space with DISP=OLD or SHR . . . 40 Spanned Records . . . . . . . . . . . 77
Guaranteed Space with Extended-Format Data Selection of VSAM Data Set Types . . . . . . . 78
Sets . . . . . . . . . . . . . . . . 41 Entry-Sequenced Data Sets . . . . . . . . 79
Guaranteed Space Example . . . . . . . . 41 Simulated VSAM Access to UNIX files . . . . 81
Allocation of Data Sets with the Space Constraint Key-Sequenced Data Sets . . . . . . . . . 82
Relief Attributes . . . . . . . . . . . . . 41 Linear Data Sets . . . . . . . . . . . . 85
Extension to Another DASD Volume . . . . . . 42 Fixed-Length Relative-Record Data Sets . . . . 86
Examples of Dynamic Volume Count When Variable-Length Relative-Record Data Sets . . . 87
Defining a Data Set . . . . . . . . . . . 43 Summary of VSAM Data Set Types . . . . . 87
Examples of Dynamic Volume Count When Extended-Format VSAM Data Sets. . . . . . . 88
Allocating an Existing Data Set . . . . . . . 43 Restrictions on Defining Extended-Format Data
Multiple Volume Considerations for Sequential Data Sets . . . . . . . . . . . . . . . . 89
Sets . . . . . . . . . . . . . . . . . 44 VSAM Data Striping . . . . . . . . . . 89
Additional Information on Space Allocation . . . 44 Compressed Data . . . . . . . . . . . 93
Access to Records in a VSAM Data Set . . . . . 94
Chapter 4. Backing Up and Recovering Access to Entry-Sequenced Data Sets . . . . . 95
Data Sets . . . . . . . . . . . . . 45 Access to Key-Sequenced Data Sets . . . . . 95
Using REPRO for Backup and Recovery . . . . . 46 Access to Linear Data Sets . . . . . . . . 96
Using EXPORT and IMPORT for Backup and Access to Fixed-Length Relative-Record Data Sets 96
Recovery of VSAM Data Sets . . . . . . . . 47 Access to Variable-Length Relative-Record Data
Structure of an Exported Data Set . . . . . . 48 Sets . . . . . . . . . . . . . . . . 97
EXPORT and IMPORT Commands . . . . . 48 Access to Records through Alternate Indexes . . . 97
Writing a Program for Backup and Recovery . . . 48 Alternate Index Structure for a Key-Sequenced
Using Concurrent Copy for Backup and Recovery 49 Data Set . . . . . . . . . . . . . . 98
Updating a Data Set After Recovery . . . . . . 49 Alternate Index Structure for an Entry-Sequenced
Synchronizing Catalog and VSAM Data Set Data Set . . . . . . . . . . . . . . 99
Information During Recovery . . . . . . . . 49 Building of an Alternate Index . . . . . . 100
Handling an Abnormal Termination . . . . . 50 Automatic Upgrade of Alternate Indexes . . . 100
Using VERIFY to Process Improperly Closed Data Compression . . . . . . . . . . . . 100
Data Sets . . . . . . . . . . . . . . 50
CICS VSAM Recovery . . . . . . . . . . . 52 Chapter 7. Defining VSAM Data Sets 103
Using Cluster Names for Data and Index
Chapter 5. Protecting Data Sets . . . . 53 Components . . . . . . . . . . . . . . 104
z/OS Security Server (RACF) . . . . . . . . 53 Defining a Data Set with Access Method Services 104
RACF Protection for VSAM Data Sets . . . . 53 Naming a Cluster . . . . . . . . . . . 104
Generic and Discrete Profiles for VSAM Data Sets 54 Specifying Cluster Information . . . . . . 106
RACF Protection for Non-VSAM Data Sets . . . 54 Using Access Method Services Parameters . . . 106
Hiding Data Set Names . . . . . . . . . 55 Allocating Space for VSAM Data Sets . . . . 108
Data Set Password Protection . . . . . . . . 55 Calculating Space for the Data Component of a
Passwords for VSAM Data Sets . . . . . . . 56 KSDS . . . . . . . . . . . . . . . 111
Passwords for Non-VSAM Data Sets . . . . . 59 Calculating Space for the Index Component . . 112
User-Security-Verification Routine . . . . . . . 60 Using ALTER to Modify Attributes of a
Erasure of Residual Data . . . . . . . . . . 60 Component . . . . . . . . . . . . . 112
Erasing DASD Data . . . . . . . . . . 60 Using ALTER to Rename Data Sets . . . . . 112
Erasing Tape Data . . . . . . . . . . . 62 Defining a Data Set with JCL . . . . . . . . 113
Authorized Program Facility and Access Method Loading a VSAM Data Set . . . . . . . . . 113
Services . . . . . . . . . . . . . . . 62 Using REPRO to Copy a VSAM Data Set . . . 114
Access Method Services Cryptographic Option . . 63 Using a Program to Load a Data Set . . . . . 115
Data Enciphering and Deciphering . . . . . 64 Reusing a VSAM Data Set as a Work File . . . 116
REPRO ENCIPHER and DECIPHER on ICSF . . 66 Copying and Merging Data Sets . . . . . . . 117
Defining Alternate Indexes . . . . . . . . . 119
Naming an Alternate Index . . . . . . . . 119
Part 2. VSAM Access to Data Sets Specifying Alternate Index Information . . . . 119
and UNIX Files . . . . . . . . . . 69 Building an Alternate Index . . . . . . . 121

iv z/OS V1R7.0 DFSMS Using Data Sets

 Maintaining Alternate Indexes . . . . . . . 121 Optimizing Free Space Distribution . . . . . . 162
Defining a Path. . . . . . . . . . . . 122 Selecting the Optimal Percentage of Free Space 164
Defining a Page Space . . . . . . . . . . 123 Altering the Free Space Specification When
Checking for Problems in Catalogs and Data Sets 124 Loading a Data Set . . . . . . . . . . 165
Listing Catalog Entries . . . . . . . . . 124 Determining I/O Buffer Space for Nonshared
Printing the Contents of Data Sets . . . . . 125 Resource . . . . . . . . . . . . . . . 166
Deleting Data Sets . . . . . . . . . . . . 125 Obtaining Buffers Above 16 MB . . . . . . 166
Tuning for System-Managed Buffering . . . . 167
Chapter 8. Defining and Manipulating Allocating Buffers for Concurrent Data Set
VSAM Data Sets: Examples . . . . . 127 Positioning . . . . . . . . . . . . . 173
Allocating Buffers for Direct Access . . . . . 173
Example of Defining a VSAM Data Set . . . . . 128
Allocating Buffers for Sequential Access . . . 175
Examples of Defining Temporary VSAM Data Sets 130
Allocating Buffers for a Path . . . . . . . 176
Example 1: Defining a Temporary VSAM Data
Acquiring Buffers . . . . . . . . . . . 176
Set Using ALLOCATE . . . . . . . . . 130
Using Index Options . . . . . . . . . . . 177
Example 2: Creating a Temporary Data Set with
Increasing Virtual Storage for Index Set Records 177
Default Parameter Values . . . . . . . . 131
Avoiding Control Area Splits . . . . . . . 177
Examples of Defining Alternate Indexes and Paths 131
Putting the Index and Data on Separate
JCL Statements . . . . . . . . . . . . 131
Volumes . . . . . . . . . . . . . . 178
Commands . . . . . . . . . . . . . 132
Obtaining Diagnostic Information . . . . . . 178
Migrating from the Mass Storage System . . . . 178
Chapter 9. Processing VSAM Data Using Hiperbatch . . . . . . . . . . . . 178
Sets . . . . . . . . . . . . . . . 135
Creating an Access Method Control Block . . . . 136 Chapter 11. Processing Control
Creating an Exit List . . . . . . . . . . . 136
Intervals . . . . . . . . . . . . . 179
Opening a Data Set . . . . . . . . . . . 137
Access to a Control Interval . . . . . . . . 180
Creating a Request Parameter List . . . . . . 138
Structure of Control Information . . . . . . . 181
Manipulating the Contents of Control Blocks . . . 140
CIDF—Control Interval Definition Field . . . 182
Generating a Control Block . . . . . . . . 140
RDF—Record Definition Field . . . . . . . 182
Testing the Contents of ACB, EXLST, and RPL
User Buffering . . . . . . . . . . . . . 186
Fields . . . . . . . . . . . . . . . 140
Improved Control Interval Access . . . . . . 187
Modifying the Contents of an ACB, EXLST, or
Opening an Object for Improved Control
RPL . . . . . . . . . . . . . . . 141
Interval Access . . . . . . . . . . . . 187
Displaying the Contents of ACB, EXLST, and
Processing a Data Set with Improved Control
RPL Fields . . . . . . . . . . . . . 141
Interval Access . . . . . . . . . . . . 187
Requesting Access to a Data Set . . . . . . . 141
Fixing Control Blocks and Buffers in Real
Inserting and Adding Records . . . . . . . 142
Storage . . . . . . . . . . . . . . 188
Retrieving Records . . . . . . . . . . 144
Control Blocks in Common (CBIC) Option . . . 188
Updating Records . . . . . . . . . . . 146
Deleting Records . . . . . . . . . . . 147
Deferring and Forcing Buffer Writing . . . . 147 Chapter 12. Sharing VSAM Data Sets 191
Retaining and Positioning Data Buffers . . . . 147 Subtask Sharing . . . . . . . . . . . . 192
Processing Multiple Strings . . . . . . . . 148 Building a Single Control Block Structure . . . 192
Making Concurrent Requests . . . . . . . 149 Resolving Exclusive Control Conflicts . . . . 193
Using a Path to Access Records . . . . . . 149 Preventing Deadlock in Exclusive Control of
Making Asynchronous Requests . . . . . . 150 Shared Resources . . . . . . . . . . . 195
Ending a Request . . . . . . . . . . . 151 Cross-Region Sharing . . . . . . . . . . . 197
Closing Data Sets . . . . . . . . . . . . 151 Cross-Region Share Options . . . . . . . 197
Operating in SRB or Cross-Memory Mode . . . . 152 Read Integrity During Cross-Region Sharing . . 198
Using VSAM Macros in Programs . . . . . . 153 Write Integrity During Cross-Region Sharing 199
Cross-System Sharing . . . . . . . . . . 200
Chapter 10. Optimizing VSAM Control Block Update Facility (CBUF) . . . . . 201
Considerations for CBUF Processing . . . . . 202
Performance . . . . . . . . . . . . 157 Checkpoints for Shared Data Sets. . . . . . 203
Optimizing Control Interval Size . . . . . . . 157 Techniques of Data Sharing . . . . . . . . . 203
Control Interval Size Limitations . . . . . . 157 Cross-Region Sharing . . . . . . . . . . 203
Data Control Interval Size . . . . . . . . 159 Cross-System Sharing . . . . . . . . . 205
Index Control Interval Size . . . . . . . . 160 User Access to VSAM Shared Information . . . 206
How VSAM Adjusts Control Interval Size . . . 160
Optimizing Control Area Size . . . . . . . . 161
Advantages of a Large Control Area Size . . . 162
Chapter 13. Sharing Resources
Disadvantages of a Large Control Area Size . . 162 Among VSAM Data Sets . . . . . . . 207

Contents v
 Provision of a Resource Pool . . . . . . . . 207 Chapter 16. Coding VSAM
Building a Resource Pool: BLDVRP . . . . . 207 User-Written Exit Routines. . . . . . 241
Connecting a Data Set to a Resource Pool: Guidelines for Coding Exit Routines . . . . . . 241
OPEN . . . . . . . . . . . . . . . 211 Programming Guidelines . . . . . . . . . 242
Deleting a Resource Pool Using the DLVRP Multiple Request Parameter Lists or Data Sets 243
Macro . . . . . . . . . . . . . . . 211 Return to a Main Program . . . . . . . . 243
Management of I/O Buffers for Shared Resources 212 IGW8PNRU Routine for Batch Override . . . . 244
Deferring Write Requests . . . . . . . . 212 Register Contents . . . . . . . . . . . 244
Relating Deferred Requests by Transaction ID 213 Programming Considerations . . . . . . . 244
Writing Buffers Whose Writing is Deferred: EODAD Exit Routine to Process End of Data . . . 245
WRTBFR . . . . . . . . . . . . . . 213 Register Contents . . . . . . . . . . . 245
Accessing a Control Interval with Shared Programming Considerations . . . . . . . 246
Resources . . . . . . . . . . . . . 215 EXCEPTIONEXIT Exit Routine . . . . . . . 246
Restrictions and Guidelines for Shared Resources 216 Register Contents . . . . . . . . . . . 246
Programming Considerations . . . . . . . 246
Chapter 14. Using VSAM Record-Level JRNAD Exit Routine to Journalize Transactions . . 247
Sharing . . . . . . . . . . . . . . 219 Register Contents . . . . . . . . . . . 247
Controlling Access to VSAM Data Sets . . . . . 219 Programming Considerations . . . . . . . 247
Accessing Data Sets Using DFSMStvs and VSAM LERAD Exit Routine to Analyze Logical Errors . . 253
Record-Level Sharing . . . . . . . . . . . 219 Register Contents . . . . . . . . . . . 254
Record-Level Sharing CF Caching . . . . . 220 Programming Considerations . . . . . . . 254
Using VSAM RLS with CICS . . . . . . . 222 RLSWAIT Exit Routine . . . . . . . . . . 254
Non-CICS Use of VSAM RLS . . . . . . . 225 Register Contents . . . . . . . . . . . 255
| Using 64-Bit Addressable Data Buffers . . . . 225 Request Environment . . . . . . . . . . 255
Read Sharing of Recoverable Data Sets . . . . 226 SYNAD Exit Routine to Analyze Physical Errors 256
Read-Sharing Integrity across KSDS CI and CA Register Contents . . . . . . . . . . . 256
Splits . . . . . . . . . . . . . . . 227 Programming Considerations . . . . . . . 256
Read and Write Sharing of Nonrecoverable Data Example of a SYNAD User-Written Exit Routine 257
Sets . . . . . . . . . . . . . . . 227 UPAD Exit Routine for User Processing . . . . 258
Using Non-RLS Access to VSAM Data Sets . . 227 Register Contents . . . . . . . . . . . 259
| RLS Access Rules . . . . . . . . . . . 228 Programming Considerations . . . . . . . 260
Comparing RLS Access and Non-RLS Access 228 User-Security-Verification Routine . . . . . . 261
Requesting VSAM RLS Run-Mode . . . . . 231
Using VSAM RLS Read Integrity Options . . . 231 Chapter 17. Using 31-Bit Addressing
Using VSAM RLS with ESDS . . . . . . . . 232 Mode with VSAM . . . . . . . . . . 263
Specifying Read Integrity . . . . . . . . . 233 VSAM Options . . . . . . . . . . . . . 263
Specifying a Timeout Value for Lock Requests . . 233
| Index Trap . . . . . . . . . . . . . . 234
Chapter 18. Using Job Control
Chapter 15. Checking VSAM Language for VSAM . . . . . . . . 265
Using JCL Statements and Keywords . . . . . 265
Key-Sequenced Data Set Clusters for Data Set Name . . . . . . . . . . . . 265
Structural Errors . . . . . . . . . . 235 Disposition . . . . . . . . . . . . . 265
EXAMINE Command . . . . . . . . . . 235 Creating VSAM Data Sets with JCL . . . . . . 266
Types of Data Sets . . . . . . . . . . . 235 Temporary VSAM Data Sets . . . . . . . 269
EXAMINE Users . . . . . . . . . . . 235 Examples Using JCL to Allocate VSAM Data
How to Run EXAMINE . . . . . . . . . . 236 Sets . . . . . . . . . . . . . . . 270
Deciding to Run INDEXTEST, DATATEST, or Retrieving an Existing VSAM Data Set . . . . . 273
Both Tests . . . . . . . . . . . . . 236 Migration Consideration . . . . . . . . . 273
Skipping DATATEST on Major INDEXTEST Keywords Used to Process VSAM Data Sets . . 273
Errors . . . . . . . . . . . . . . . 236
Examining a User Catalog . . . . . . . . 236 Chapter 19. Processing Indexes of
Understanding Message Hierarchy . . . . . 237
Controlling Message Printout . . . . . . . 237
Key-Sequenced Data Sets . . . . . . 275
Samples of Output from EXAMINE Runs . . . . 238 Access to a Key-Sequenced Data Set Index . . . 275
INDEXTEST and DATATEST Tests of an Access to an Index with GETIX and PUTIX . . 275
Error-Free Data Set . . . . . . . . . . 238 Access to the Index Component Alone . . . . 275
INDEXTEST and DATATEST Tests of a Data Set Prime Index . . . . . . . . . . . . . 276
with a Structural Error . . . . . . . . . 238 Index Levels . . . . . . . . . . . . . 277
INDEXTEST and DATATEST Tests of a Data Set Format of an Index Record . . . . . . . . . 279
with a Duplicate Key Error . . . . . . . . 239 Header Portion . . . . . . . . . . . . 279

vi z/OS V1R7.0 DFSMS Using Data Sets

 Free Control Interval Entry Portion . . . . . 281 Using CLOSE TYPE=T with Sequential Data
Index Entry Portion . . . . . . . . . . 281 Sets . . . . . . . . . . . . . . . 339
Key Compression . . . . . . . . . . . . 282 Releasing Space . . . . . . . . . . . 340
Index Update Following a Control Interval Split 285 Managing Buffer Pools When Closing Data Sets 341
Index Entries for a Spanned Record . . . . . 286 Opening and Closing Data Sets: Considerations 341
Parameter Lists with 31-Bit Addresses . . . . 341
Open and Close of Multiple Data Sets at the
Part 3. Non-VSAM Access to Data
Same Time . . . . . . . . . . . . . 341
Sets and UNIX Files . . . . . . . 287 Factors to Consider When Allocating Direct
Access Data Sets . . . . . . . . . . . 342
Chapter 20. Selecting Record Formats Guidelines for Opening and Closing Data Sets 342
for Non-VSAM Data Sets . . . . . . 293 Open/Close/EOV Errors . . . . . . . . 342
Format Selection . . . . . . . . . . . . 293 Installation Exits . . . . . . . . . . . 343
Fixed-Length Record Formats . . . . . . . . 294 Positioning Volumes . . . . . . . . . . . 344
Standard Format . . . . . . . . . . . 295 Releasing Data Sets and Volumes . . . . . . 344
Restrictions . . . . . . . . . . . . . 295 Processing End-of-Volume . . . . . . . . 344
Variable-Length Record Formats . . . . . . . 296 Positioning During End-of-Volume . . . . . 345
Format-V Records . . . . . . . . . . . 296 Forcing End-of-Volume . . . . . . . . . 346
Spanned Format-VS Records (Sequential Access Managing SAM Buffer Space . . . . . . . . 347
Method) . . . . . . . . . . . . . . 298 Constructing a Buffer Pool . . . . . . . . . 348
Spanned Format-V Records (Basic Direct Access Building a Buffer Pool . . . . . . . . . 349
Method) . . . . . . . . . . . . . . 300 Building a Buffer Pool and a Record Area . . . 349
Undefined-Length Record Format . . . . . . 302 Getting a Buffer Pool . . . . . . . . . . 349
ISO/ANSI Tapes . . . . . . . . . . . . 303 Constructing a Buffer Pool Automatically . . . 350
Character Data Conversion . . . . . . . . 303 Freeing a Buffer Pool . . . . . . . . . . 350
Format-F Records . . . . . . . . . . . 304 Constructing a Buffer Pool: Examples . . . . 351
Format-D Records . . . . . . . . . . . 306 Controlling Buffers . . . . . . . . . . . 352
ISO/ANSI Format-DS and Format-DBS Records 308 Queued Access Method . . . . . . . . . 352
Format-U Records . . . . . . . . . . . 311 Basic Access Method . . . . . . . . . . 352
Record Format—Device Type Considerations . . . 311 QSAM in an Application . . . . . . . . 352
Using Optional Control Characters . . . . . 312 Exchange Buffering . . . . . . . . . . 355
Using Direct Access Storage Devices (DASD) 313 Choosing Buffering Techniques and GET/PUT
Using Magnetic Tape . . . . . . . . . . 313 Processing Modes . . . . . . . . . . . . 355
Using a Printer . . . . . . . . . . . . 314 Using Buffering Macros with Queued Access
Using a Card Reader and Punch . . . . . . 315 Method . . . . . . . . . . . . . . . 356
Using a Paper Tape Reader . . . . . . . . 316 RELSE—Release an Input Buffer . . . . . . 356
TRUNC—Truncate an Output Buffer . . . . 356
Using Buffering Macros with Basic Access Method 356
Chapter 21. Specifying and Initializing
GETBUF—Get a Buffer from a Pool . . . . . 356
Data Control Blocks . . . . . . . . 317 FREEBUF—Return a Buffer to a Pool . . . . 357
Processing Sequential and Partitioned Data Sets 318
Using OPEN to Prepare a Data Set for Processing 323
Chapter 22. Accessing Records . . . 359
Filling in the DCB . . . . . . . . . . . 324
Accessing Data with READ and WRITE . . . . 359
Specifying the Forms of Macros, Buffering
Using the Data Event Control Block (DECB) . . 359
Requirements, and Addresses . . . . . . . 326
Grouping Related Control Blocks in a Paging
Coding Processing Methods . . . . . . . 326
Environment . . . . . . . . . . . . 359
Selecting Data Set Options . . . . . . . . . 327
Using Overlapped I/O with BSAM . . . . . 359
Block Size (BLKSIZE) . . . . . . . . . . 327
Reading a Block . . . . . . . . . . . 361
Data Set Organization (DSORG) . . . . . . 333
Writing a Block . . . . . . . . . . . . 361
Key Length (KEYLEN) . . . . . . . . . 334
Ensuring I/O Initiation with the TRUNC Macro 362
Record Length (LRECL) . . . . . . . . . 334
Testing Completion of a Read or Write
Record Format (RECFM) . . . . . . . . 334
Operation . . . . . . . . . . . . . 362
Write Validity Check Option (OPTCD=W) . . . 335
Waiting for Completion of a Read or Write
DD Statement Parameters . . . . . . . . 335
Operation . . . . . . . . . . . . . 363
Changing and Testing the DCB and DCBE . . . 336
Handling Exceptional Conditions on Tape . . . 363
Using the DCBD Macro . . . . . . . . . 337
Accessing Data with GET and PUT . . . . . . 364
Changing an Address in the DCB . . . . . 337
GET—Retrieve a Record . . . . . . . . . 364
Using the IHADCBE Macro . . . . . . . 338
PUT—Write a Record . . . . . . . . . . 365
Using CLOSE to End the Processing of a Data Set 338
PUTX—Write an Updated Record . . . . . 365
Issuing the CHECK Macro . . . . . . . . 338
PDAB—Parallel Input Processing (QSAM Only) 365
Closing a Data Set Temporarily . . . . . . 338
Analyzing I/O Errors . . . . . . . . . . 368

Contents vii
 SYNADAF—Perform SYNAD Analysis Function 368 Allocating Extended-Format Data Sets . . . . 407
SYNADRLS—Release SYNADAF Message and Allocating Compressed-Format Data Sets . . . 408
Save Areas . . . . . . . . . . . . . 369 Opening and Closing Extended-Format Data
Device Support Facilities (ICKDSF): Diagnosing Sets . . . . . . . . . . . . . . . 409
I/O Problems . . . . . . . . . . . . 369 Reading, Writing, and Updating
Limitations with Using SRB or Cross-Memory Extended-Format Data Sets Using BSAM and
Mode . . . . . . . . . . . . . . . . 369 QSAM . . . . . . . . . . . . . . . 410
Concatenating Extended-Format Data Sets with
Chapter 23. Sharing Non-VSAM Data Other Data Sets . . . . . . . . . . . 410
Sets . . . . . . . . . . . . . . . 371 Extending Striped Sequential Data Sets . . . . 410
Migrating to Extended-Format Data Sets . . . 410
Enhanced Data Integrity for Shared Sequential
Data Sets . . . . . . . . . . . . . . . 374
| Processing Large Format Data Sets . . . . . . 411
Setting Up the Enhanced Data Integrity
| Characteristics of Large Format Data Sets . . . 412
Function . . . . . . . . . . . . . . 374
| Allocating Large Format Data Sets . . . . . 412
Synchronizing the Enhanced Data Integrity
| Opening and Closing Large Format Data Sets 413
Function on Multiple Systems . . . . . . . 376
| Migrating to Large Format Data Sets . . . . 413
Using the START IFGEDI Command . . . . 376
Bypassing the Enhanced Data Integrity Function Chapter 26. Processing a Partitioned
for Applications . . . . . . . . . . . 376 Data Set (PDS) . . . . . . . . . . . 415
Diagnosing Data Integrity Warnings and Structure of a PDS . . . . . . . . . . . . 415
Violations . . . . . . . . . . . . . 377 PDS Directory . . . . . . . . . . . . . 416
PDSEs . . . . . . . . . . . . . . . . 379 Allocating Space for a PDS . . . . . . . . . 419
Direct Data Sets (BDAM) . . . . . . . . . 380 Calculating Space . . . . . . . . . . . 419
Factors to Consider When Opening and Closing Allocating Space with SPACE and AVGREC . . 420
Data Sets . . . . . . . . . . . . . . . 381 Creating a PDS . . . . . . . . . . . . . 420
Control of Checkpoint Data Sets on Shared DASD Creating a PDS Member with BSAM or QSAM 421
Volumes . . . . . . . . . . . . . . . 381 Converting PDSs . . . . . . . . . . . 421
System Use of Search Direct for Input Operations 383 Copying a PDS or Member to Another Data Set 421
Adding Members . . . . . . . . . . . 422
Chapter 24. Spooling and Scheduling Processing a Member of a PDS . . . . . . . 424
Data Sets . . . . . . . . . . . . . 385 BLDL—Construct a Directory Entry List . . . 424
DESERV . . . . . . . . . . . . . . 425
Job Entry Subsystem . . . . . . . . . . . 385
FIND—Position to the Starting Address of a
SYSIN Data Set . . . . . . . . . . . . . 386
Member . . . . . . . . . . . . . . 428
SYSOUT Data Set . . . . . . . . . . . . 386
STOW—Update the Directory . . . . . . . 429
Retrieving a Member of a PDS . . . . . . . 430
Chapter 25. Processing Sequential Modifying a PDS . . . . . . . . . . . . 434
Data Sets . . . . . . . . . . . . . 389 Updating in Place . . . . . . . . . . . 434
Creating a Sequential Data Set . . . . . . . . 389 Rewriting a Member . . . . . . . . . . 437
Retrieving a Sequential Data Set . . . . . . . 390 Concatenating PDSs . . . . . . . . . . . 437
Concatenating Data Sets Sequentially . . . . . 391 Sequential Concatenation . . . . . . . . 437
Concatenating Like Data Sets . . . . . . . 392 Partitioned Concatenation . . . . . . . . 437
Concatenating Unlike Data Sets . . . . . . 396 Reading a PDS Directory Sequentially . . . . . 438
Modifying Sequential Data Sets . . . . . . . 398
Updating in Place . . . . . . . . . . . 398 Chapter 27. Processing a Partitioned
Using Overlapped Operations . . . . . . . 398
Data Set Extended (PDSE) . . . . . . 439
Extending a Data Set . . . . . . . . . . 399
Advantages of PDSEs . . . . . . . . . . 439
Achieving Device Independence . . . . . . . 399
PDSE and PDS Similarities . . . . . . . . 441
Device-Dependent Macros . . . . . . . . 400
PDSE and PDS Differences . . . . . . . . 441
DCB and DCBE Subparameters . . . . . . 401
Structure of a PDSE . . . . . . . . . . . 441
Improving Performance for Sequential Data Sets 401
PDSE Logical Block Size . . . . . . . . . 442
Limitations on Using Chained Scheduling with
Reuse of Space . . . . . . . . . . . . 442
Non-DASD Data Sets . . . . . . . . . . 402
Directory Structure . . . . . . . . . . 443
DASD and Tape Performance . . . . . . . 403
Relative Track Addresses (TTR) . . . . . . 443
Determining the Length of a Block when Reading
Processing PDSE Records . . . . . . . . . 444
with BSAM, BPAM, or BDAM . . . . . . . . 403
Using BLKSIZE with PDSEs . . . . . . . 445
Writing a Short Format-FB Block with BSAM or
Using KEYLEN with PDSEs . . . . . . . 445
BPAM . . . . . . . . . . . . . . . . 405
Reblocking PDSE Records . . . . . . . . 445
Using Hiperbatch . . . . . . . . . . . . 406
Processing Short Blocks . . . . . . . . . 446
Processing Extended-Format Sequential Data Sets 406
Processing SAM Null Segments . . . . . . 447
Characteristics of Extended-Format Data Sets 406

viii z/OS V1R7.0 DFSMS Using Data Sets

Allocating Space for a PDSE . . . . . . . . 447 Creating a Macro Library in a UNIX Directory 489
PDSE Space Considerations . . . . . . . 447 Managing UNIX Files and Directories . . . . . 490
Summary of PDSE Storage Requirements . . . 450 Specifying Security Settings for UNIX Files and
Defining a PDSE . . . . . . . . . . . . 450 Directories . . . . . . . . . . . . . 491
Creating a PDSE Member . . . . . . . . . 451 Editing UNIX Files . . . . . . . . . . 492
Creating a PDSE Member with BSAM or QSAM 451 Using ISHELL to Manage UNIX Files and
Adding or Replacing PDSE Members Serially 452 Directories . . . . . . . . . . . . . 492
Adding or Replacing Multiple PDSE Members Copying UNIX Files or Directories . . . . . 493
Concurrently . . . . . . . . . . . . 453 Services and Utilities for UNIX Files . . . . . . 495
Copying a PDSE or Member to Another Data Services and Utilities Cannot be Used with
Set . . . . . . . . . . . . . . . . 454 UNIX Files . . . . . . . . . . . . . 495
Processing a Member of a PDSE . . . . . . . 454 z/OS UNIX Signals . . . . . . . . . . 496
Establishing Connections to Members . . . . 454 z/OS UNIX Fork Service . . . . . . . . 496
Using the BLDL Macro to Construct a Directory SMF Records . . . . . . . . . . . . 496
Entry List . . . . . . . . . . . . . 455 Reading UNIX Files Using BPAM . . . . . . 496
Using the BSP Macro to Backspace a Physical Using Macros for UNIX Files . . . . . . . 496
Record . . . . . . . . . . . . . . 456 BLDL—Constructing a Directory Entry List . . 497
Using the Directory Entry Services . . . . . 456 CHECK—Checking for I/O Completion . . . 497
Using the FIND Macro to Position to the CLOSE—to Close the DCB . . . . . . . . 497
Beginning of a Member . . . . . . . . . 463 FIND—Positioning to the Starting Address of a
Using ISITMGD to Determine Whether the Data File . . . . . . . . . . . . . . . . 497
Set Is System Managed . . . . . . . . . 464 READ—Reading a UNIX File . . . . . . . 498
Using the NOTE Macro to Provide Relative STOW DISC—Closing a UNIX File . . . . . 498
Position . . . . . . . . . . . . . . 465 Concatenating UNIX Files and Directories . . . . 499
Using the POINT Macro to Position to a Block 465 Sequential Concatenation . . . . . . . . 499
Switching between Members . . . . . . . 466 Partitioned Concatenation . . . . . . . . 499
Using the STOW Macro to Update the Directory 467
Retrieving a Member of a PDSE . . . . . . . 468 Chapter 29. Processing Generation
Sharing PDSEs . . . . . . . . . . . . . 470 Data Groups . . . . . . . . . . . . 501
Sharing within a Computer System . . . . . 470
Data Set Organization of Generation Data Sets . . 502
Sharing Violations . . . . . . . . . . . 470
Absolute Generation and Version Numbers . . . 502
Multiple System Sharing of PDSEs . . . . . 471
Relative Generation Number . . . . . . . . 503
Normal or Extended PDSE Sharing . . . . . 473
Programming Considerations for Multiple-Step
Modifying a Member of a PDSE . . . . . . . 474
Jobs . . . . . . . . . . . . . . . . 503
Updating in Place . . . . . . . . . . . 474
Cataloging Generation Data Groups . . . . . 504
Extending a PDSE Member . . . . . . . . 475
Submitting Multiple Jobs to Update a
Deleting a PDSE Member . . . . . . . . 475
Generation Data Group . . . . . . . . . 504
Renaming a PDSE Member . . . . . . . . 476
Naming Generation Data Groups for ISO/ANSI
Reading a PDSE Directory . . . . . . . . . 476
Version 3 or Version 4 Labels . . . . . . . . 505
Concatenating PDSEs . . . . . . . . . . . 477
Creating a New Generation. . . . . . . . . 506
Sequential Concatenation . . . . . . . . 477
Allocating a Generation Data Set . . . . . . 506
Partitioned Concatenation . . . . . . . . 477
Passing a Generation Data Set . . . . . . . 509
Converting PDSs to PDSEs and Back . . . . . 478
Rolling In a Generation Data Set . . . . . . 509
PDSE to PDS Conversion . . . . . . . . 478
Controlling Expiration of a Rolled-Off
Restrictions on Converting PDSEs . . . . . 479
Generation Data Set . . . . . . . . . . 510
Improving Performance . . . . . . . . . . 479
Retrieving a Generation Data Set . . . . . . . 510
Recovering Space in Fragmented PDSEs . . . . 479
Reclaiming Generation Data Sets . . . . . . . 510
PDSE Address Spaces . . . . . . . . . . 479
Turning on GDS Reclaim Processing . . . . . 511
Turning off GDS Reclaim Processing . . . . . 511
Chapter 28. Processing z/OS UNIX Building a Generation Data Group Index . . . . 511
Files . . . . . . . . . . . . . . . 481
Accessing the z/OS UNIX File System . . . . . 481 Chapter 30. Using I/O Device Control
Characteristics of UNIX Directories and Files 482 Macros . . . . . . . . . . . . . . 513
Access Methods Used . . . . . . . . . 482
Using the CNTRL Macro to Control an I/O Device 513
Using HFS Data Sets . . . . . . . . . . . 483
Using the PRTOV Macro to Test for Printer
Creating HFS Data Sets . . . . . . . . . 483
Overflow . . . . . . . . . . . . . . . 514
Creating Additional Directories . . . . . . 484
Using the SETPRT Macro to Set Up the Printer . . 514
Creating z/OS UNIX Files . . . . . . . . . 485
Using the BSP Macro to Backspace a Magnetic
Creating a UNIX File with BSAM or QSAM . . 485
Tape or Direct Access Volume . . . . . . . . 515
Creating a UNIX File Using JCL . . . . . . 487
JCL Parameters for UNIX Files . . . . . . 488

Contents ix
Using the NOTE Macro to Return the Relative Using the Basic Direct Access Method (BDAM) . . 569
Address of a Block . . . . . . . . . . . 515 Processing a Direct Data Set Sequentially . . . . 570
Using the POINT Macro to Position to a Block . . 516 Organizing a Direct Data Set . . . . . . . . 570
Using the SYNCDEV Macro to Synchronize Data 517 By Range of Keys . . . . . . . . . . . 570
By Number of Records . . . . . . . . . 570
Chapter 31. Using Non-VSAM With Indirect Addressing . . . . . . . . 571
User-Written Exit Routines. . . . . . 519 Creating a Direct Data Set . . . . . . . . . 571
Restrictions in Creating a Direct Data Set Using
General Guidance . . . . . . . . . . . . 519
QSAM . . . . . . . . . . . . . . . 571
Programming Considerations . . . . . . . 520
With Direct Addressing with Keys . . . . . 571
Status Information Following an Input/Output
With BDAM to Allocate a VIO Data Set . . . 572
Operation . . . . . . . . . . . . . 520
Referring to a Record . . . . . . . . . . . 573
EODAD End-of-Data-Set Exit Routine . . . . . 527
Record Addressing . . . . . . . . . . 573
Register Contents . . . . . . . . . . . 527
Extended Search . . . . . . . . . . . 573
Programming Considerations . . . . . . . 527
Exclusive Control for Updating . . . . . . 574
SYNAD Synchronous Error Routine Exit . . . . 528
Feedback Option . . . . . . . . . . . 574
Register Contents . . . . . . . . . . . 531
Adding or Updating Records . . . . . . . . 574
Programming Considerations . . . . . . . 533
Format-F with Keys . . . . . . . . . . 574
DCB Exit List . . . . . . . . . . . . . 535
Format-F without Keys . . . . . . . . . 575
Register Contents for Exits from EXLST . . . 537
Format-V or Format-U with Keys. . . . . . 575
Serialization . . . . . . . . . . . . . 538
Format-V or Format-U without Keys . . . . 575
Allocation Retrieval List . . . . . . . . . . 538
Tape-to-Disk Add—Direct Data Set . . . . . 576
Programming Conventions . . . . . . . . 538
Tape-to-Disk Update—Direct Data Set . . . . 577
Restrictions . . . . . . . . . . . . . 538
With User Labels . . . . . . . . . . . 577
DCB ABEND Exit . . . . . . . . . . . . 539
Sharing DCBs . . . . . . . . . . . . . 578
Recovery Requirements . . . . . . . . . 541
DCB Abend Installation Exit . . . . . . . 543
DCB OPEN Exit . . . . . . . . . . . . 543 | Appendix D. Using the Indexed
Calls to DCB OPEN Exit for Sequential | Sequential Access Method . . . . . . 579
Concatenation . . . . . . . . . . . . 543 Using the Basic Indexed Sequential Access Method
Installation DCB OPEN Exit . . . . . . . 544 (BISAM) . . . . . . . . . . . . . . . 579
Defer Nonstandard Input Trailer Label Exit List Using the Queued Indexed Sequential Access
Entry . . . . . . . . . . . . . . . . 544 Method (QISAM) . . . . . . . . . . . . 579
Block Count Unequal Exit . . . . . . . . . 544 Processing ISAM Data Sets . . . . . . . . . 580
EOV Exit for Sequential Data Sets . . . . . . 545 Organizing Data Sets . . . . . . . . . . . 580
FCB Image Exit . . . . . . . . . . . . . 546 Prime Area . . . . . . . . . . . . . 582
JFCB Exit . . . . . . . . . . . . . . . 547 Index Areas . . . . . . . . . . . . . 582
JFCBE Exit . . . . . . . . . . . . . . 548 Overflow Areas. . . . . . . . . . . . 584
Open/Close/EOV Standard User Label Exit . . . 549 Creating an ISAM Data Set . . . . . . . . . 584
Open/EOV Nonspecific Tape Volume Mount Exit 553 One-Step Method . . . . . . . . . . . 584
Open/EOV Volume Security and Verification Exit 556 Full-Track-Index Write Option . . . . . . . 585
QSAM Parallel Input Exit . . . . . . . . . 558 Multiple-Step Method . . . . . . . . . 586
User Totaling for BSAM and QSAM . . . . . . 558 Resume Load . . . . . . . . . . . . 587
Allocating Space . . . . . . . . . . . . 587
Appendix A. Using Direct Access Prime Data Area . . . . . . . . . . . 589
Labels . . . . . . . . . . . . . . 561 Specifying a Separate Index Area . . . . . . 590
Specifying an Independent Overflow Area. . . 590
Direct Access Storage Device Architecture . . . . 561
Specifying a Prime Area and Overflow Area . . 590
Volume Label Group . . . . . . . . . . . 562
Calculating Space Requirements . . . . . . . 590
Data Set Control Block (DSCB) . . . . . . . 564
Step 1. Number of Tracks Required . . . . . 590
User Label Groups . . . . . . . . . . . 564
Step 2. Overflow Tracks Required . . . . . 591
Step 3. Index Entries Per Track . . . . . . 591
Appendix B. Using the Double-Byte Step 4. Determine Unused Space . . . . . . 592
Character Set (DBCS) . . . . . . . . 567 Step 5. Calculate Tracks for Prime Data Records 592
DBCS Character Support . . . . . . . . . 567 Step 6. Cylinders Required . . . . . . . . 593
Record Length When Using DBCS Characters . . 567 Step 7. Space for Cylinder Indexes and Track
Fixed-Length Records . . . . . . . . . 567 Indexes . . . . . . . . . . . . . . 593
Variable-Length Records . . . . . . . . . 568 Step 8. Space for Master Indexes . . . . . . 593
Summary of Indexed Sequential Space
Appendix C. Processing Direct Data Requirements Calculations . . . . . . . . 594
Sets . . . . . . . . . . . . . . . 569 Retrieving and Updating . . . . . . . . . 595
Sequential Retrieval and Update . . . . . . 595

x z/OS V1R7.0 DFSMS Using Data Sets

 Direct Retrieval and Update . . . . . . . 596 Coded Character Sets Sorted by CCSID. . . . . 625
Adding Records . . . . . . . . . . . . 600 Coded Character Sets Sorted by Default
Inserting New Records . . . . . . . . . 601 LOCALNAME . . . . . . . . . . . . . 628
Adding New Records to the End of a Data Set 602 CCSID Conversion Groups . . . . . . . . . 634
Maintaining an Indexed Sequential Data Set . . . 603 CCSID Decision Tables . . . . . . . . . . 637
Buffer Requirements . . . . . . . . . . 605 Tables for Default Conversion Codes . . . . . 642
Work Area Requirements . . . . . . . . 606 Converting from EBCDIC to ASCII . . . . . 642
Space for the Highest-Level Index . . . . . 607 Converting from ASCII to EBCDIC . . . . . 642
Device Control . . . . . . . . . . . . 608
SETL—Specifying Start of Sequential Retrieval 608 Appendix G. Accessibility . . . . . . 643
ESETL—Ending Sequential Retrieval . . . . 609 Using assistive technologies . . . . . . . . 643
Keyboard navigation of the user interface . . . . 643
Appendix E. Using ISAM Programs z/OS information . . . . . . . . . . . . 643
with VSAM Data Sets . . . . . . . . 611
Upgrading ISAM Applications to VSAM . . . . 612 Notices . . . . . . . . . . . . . . 645
How an ISAM Program Can Process a VSAM Data Programming interface information . . . . . . 646
Set . . . . . . . . . . . . . . . . . 613 Trademarks . . . . . . . . . . . . . . 646
Conversion of an Indexed Sequential Data Set . . 617
JCL for Processing with the ISAM Interface . . . 618 Glossary . . . . . . . . . . . . . 647
Restrictions on the Use of the ISAM Interface . . 620
Example: Converting a Data Set . . . . . . 622
Example: Issuing a SYNADAF Macro . . . . 623
Index . . . . . . . . . . . . . . . 661

Appendix F. Converting Character

Sets . . . . . . . . . . . . . . . 625

Contents xi
xii z/OS V1R7.0 DFSMS Using Data Sets
Figures
1. DASD Volume Track Formats . . . . . . . 9 44. Nonspanned, Format-V Records . . . . . 296
2. REPRO Encipher and Decipher Operations 65 45. Spanned Format-VS Records (Sequential
3. VSAM Logical Record Retrieval . . . . . . 73 Access Method) . . . . . . . . . . . 298
4. Control Interval Format . . . . . . . . 75 46. Spanned Format-V Records for Direct Data
5. Record Definition Fields of Control Intervals 76 Sets . . . . . . . . . . . . . . . 301
6. Data Set with Nonspanned Records . . . . 77 47. Undefined-Length Records . . . . . . . 302
7. Data Set with Spanned Records . . . . . . 78 48. Fixed-Length Records for ISO/ANSI Tapes 305
8. Entry-Sequenced Data Set . . . . . . . . 80 49. Nonspanned Format-D Records for
9. Example of RBAs of an Entry-Sequenced Data ISO/ANSI Tapes As Seen by the Program . . 308
Set . . . . . . . . . . . . . . . 80 50. Spanned Variable-Length (Format-DS)
10. Record of a Key-Sequenced Data Set . . . . 82 Records for ISO/ANSI Tapes As Seen by the
11. Inserting Records into a Key-Sequenced Data Program . . . . . . . . . . . . . 309
Set . . . . . . . . . . . . . . . 83 51. Reading a Sequential Data Set . . . . . . 321
12. Inserting a Logical Record into a CI . . . . 84 52. Reentrant—Above the 16 MB Line . . . . 322
13. Fixed-length Relative-Record Data Set . . . . 86 53. Sources and Sequence of Operations for
14. Control Interval Size . . . . . . . . . 89 Completing the DCB . . . . . . . . . 324
15. Primary and Secondary Space Allocations for 54. Opening Three Data Sets at the Same Time 327
Striped Data Sets . . . . . . . . . . . 90 55. Changing a Field in the DCB . . . . . . 337
16. Control Interval in a Control Area . . . . . 91 56. Closing Three Data Sets at the Same Time 338
17. Layering (Four-Stripe Data Set) . . . . . . 92 57. Record Processed when LEAVE or REREAD
18. Alternate Index Structure for a Key-Sequenced is Specified for CLOSE TYPE=T . . . . . 339
Data Set . . . . . . . . . . . . . . 98 58. Constructing a Buffer Pool from a Static
19. Alternate Index Structure for an Storage Area . . . . . . . . . . . . 351
Entry-Sequenced Data Set . . . . . . . . 99 59. Constructing a Buffer Pool Using GETPOOL
20. VSAM Macro Relationships . . . . . . . 154 and FREEPOOL . . . . . . . . . . . 351
21. Skeleton VSAM Program. . . . . . . . 155 60. Simple Buffering with MACRF=GL and
22. Control Interval Size, Physical Track Size, and MACRF=PM . . . . . . . . . . . . 353
Track Capacity . . . . . . . . . . . 159 61. Simple Buffering with MACRF=GM and
23. Determining Free Space . . . . . . . . 164 MACRF=PM . . . . . . . . . . . . 354
24. Scheduling Buffers for Direct Access . . . . 174 62. Simple Buffering with MACRF=GL and
25. General Format of a Control Interval 181 MACRF=PL . . . . . . . . . . . . 354
26. Format of Control Information for 63. Simple Buffering with MACRF=GL and
Nonspanned Records . . . . . . . . . 184 MACRF=PM-UPDAT Mode . . . . . . . 355
27. Format of Control Information for Spanned 64. Parallel Processing of Three Data Sets 367
Records . . . . . . . . . . . . . 185 65. JCL, Macros, and Procedures Required to
28. Exclusive Control Conflict Resolution 194 Share a Data Set Using Multiple DCBs . . . 372
29. Relationship Between the Base Cluster and 66. Macros and Procedures Required to Share a
the Alternate Index . . . . . . . . . 196 Data Set Using a Single DCB . . . . . . 373
30. VSAM RLS address and data spaces and 67. Creating a Sequential Data Set—Move Mode,
requestor address spaces . . . . . . . . 220 Simple Buffering . . . . . . . . . . 390
31. CICS VSAM non-RLS access . . . . . . 223 68. Retrieving a Sequential Data Set—Locate
32. CICS VSAM RLS . . . . . . . . . . 223 Mode, Simple Buffering . . . . . . . . 391
33. Example of a JRNAD exit . . . . . . . 249 69. Like Concatenation Read through BSAM 396
34. Example of a SYNAD exit routine . . . . 258 70. Reissuing a READ or GET for Unlike
35. Relation of Index Entry to Data Control Concatenated Data Sets . . . . . . . . 397
Interval . . . . . . . . . . . . . 276 71. One Method of Determining the Length of a
36. Relation of Index Entry to Data Control Record when Using BSAM to Read
Interval . . . . . . . . . . . . . 277 Undefined-Length or Blocked Records . . . 405
37. Levels of a Prime Index . . . . . . . . 278 72. A Partitioned Data Set (PDS) . . . . . . 416
38. General Format of an Index Record . . . . 279 73. A PDS Directory Block . . . . . . . . 416
39. Format of the Index Entry Portion of an 74. A PDS Directory Entry . . . . . . . . 417
Index Record . . . . . . . . . . . 282 75. Creating One Member of a PDS . . . . . 421
40. Format of an Index Record . . . . . . . 282 76. Creating Members of a PDS Using STOW 423
41. Example of Key Compression . . . . . . 285 77. BLDL List Format . . . . . . . . . . 425
42. Control Interval Split and Index Update 286 78. DESERV GET by NAME_LIST Control Block
43. Fixed-Length Records . . . . . . . . . 294 Structure . . . . . . . . . . . . . 426

© Copyright IBM Corp. 1987, 2005 xiii

 79. DESERV GET by PDSDE Control Block 107. Creating a UNIX File with QSAM. . . . . 486
Structure . . . . . . . . . . . . . 427 108. Edit-Entry Panel . . . . . . . . . . 492
80. DESERV GET_ALL Control Block Structure 428 109. ISPF Shell Panel . . . . . . . . . . 493
81. Retrieving One Member of a PDS . . . . . 430 110. Using OPUT to Copy Members of a PDS or
82. Retrieving Several Members and Subgroups PDSE to a UNIX File . . . . . . . . . 494
of a PDS without Overlapping I/O Time and 111. A Partitioned Concatenation of PDS extents,
CPU Time. . . . . . . . . . . . . 432 PDSEs, and UNIX directories . . . . . . 500
83. Reading a Member of a PDS or PDSE using 112. Status Indicators—BDAM, BPAM, BSAM, and
Asynchronous BPAM . . . . . . . . . 433 QSAM . . . . . . . . . . . . . . 526
84. Updating a Member of a PDS . . . . . . 436 113. Parameter List Passed to DCB Abend Exit
85. A Partitioned Data Set Extended (PDSE) 440 Routine . . . . . . . . . . . . . 539
86. TTRs for a PDSE Member (Unblocked 114. Recovery Work Area . . . . . . . . . 542
Records) . . . . . . . . . . . . . 443 115. Defining an FCB Image for a 3211 . . . . 547
87. TTRs for Two PDSE Members (LRECL=80, 116. Parameter List Passed to User Label Exit
BLKSIZE=800) . . . . . . . . . . . 444 Routine . . . . . . . . . . . . . 549
88. Example of How PDSE Records Are 117. IECOENTE Macro Parameter List . . . . . 554
Reblocked. . . . . . . . . . . . . 446 118. IECOEVSE Macro Parameter List . . . . . 557
89. Example of Reblocking When the Block Size 119. Direct Access Labeling . . . . . . . . 562
Has Been Changed . . . . . . . . . . 446 120. Initial Volume Label Format . . . . . . 563
90. Creating One Member of a PDSE . . . . . 451 121. User Header and Trailer Labels on DASD or
91. Adding PDSE Members Serially . . . . . 453 Tape . . . . . . . . . . . . . . 564
92. Replacing Multiple PDSE Members 122. Creating a Direct Data Set (Tape-to-Disk) 572
Concurrently . . . . . . . . . . . . 453 123. Adding Records to a Direct Data Set 576
93. DESERV GET by NAME_LIST Control Block 124. Updating a Direct Data Set . . . . . . . 577
Structure . . . . . . . . . . . . . 458 125. Indexed Sequential Data Set Organization 582
94. DESERV GET by PDSDE Control Block 126. Format of Track Index Entries . . . . . . 583
Structure . . . . . . . . . . . . . 459 127. Creating an Indexed Sequential Data Set 586
95. DESERV GET_ALL Control Block Structure 460 128. Sequentially Updating an Indexed Sequential
96. DESERV GET_NAMES Control Block Data Set . . . . . . . . . . . . . 596
Structure . . . . . . . . . . . . . 461 129. Directly Updating an Indexed Sequential Data
97. DESERV RELEASE Input Control Block Set . . . . . . . . . . . . . . . 599
Structure . . . . . . . . . . . . . 462 130. Directly Updating an Indexed Sequential Data
98. DESERV UPDATE . . . . . . . . . . 463 Set with Variable-Length Records . . . . . 601
99. ISITMGD Example . . . . . . . . . . 464 131. Adding Records to an Indexed Sequential
100. Using NOTE and FIND to Switch Between Data Set . . . . . . . . . . . . . 603
Members of a Concatenated PDSE . . . . 467 132. Deleting Records from an Indexed Sequential
101. STOW INITIALIZE Example . . . . . . 468 Data Set . . . . . . . . . . . . . 604
102. Retrieving One Member of a PDSE . . . . 468 133. Use of ISAM Processing Programs . . . . 612
103. Retrieving Several Members of a PDSE or 134. CCSID Conversion Group 1 . . . . . . . 635
PDS . . . . . . . . . . . . . . . 469 135. CCSID Conversion Group 2 . . . . . . . 635
104. OPEN Success/Failure . . . . . . . . 471 136. CCSID Conversion Group 3 . . . . . . . 635
105. OPEN for UPDAT and Positioning to a 137. CCSID Conversion Group 4 . . . . . . . 635
Member Decision Table . . . . . . . . 472 138. CCSID Conversion Group 5 . . . . . . . 636
106. UNIX Directories and Files in a File System 482

xiv z/OS V1R7.0 DFSMS Using Data Sets

 Tables
1. Data Management Access Methods. . . . . 15 32. Optimum and Maximum Block Size
2. Access Method Services Commands . . . . 16 Supported . . . . . . . . . . . . 330
3. Data Set Activity for Non-System-Managed 33. Rules for Setting Block Sizes for Tape Data
and System-Managed Data Sets . . . . . . 28 Sets or Compressed Format Data Sets . . . 333
4. Differences Between Stripes in Sequential and 34. Buffering Technique and GET/PUT
VSAM Data Sets . . . . . . . . . . . 39 Processing Modes . . . . . . . . . . 355
5. Entry-Sequenced Data Set Processing . . . . 80 35. Messages for Data Integrity Processing 378
6. Key-Sequenced Data Set Processing . . . . 83 36. Different Conditions for Data Integrity
7. RRDS Processing . . . . . . . . . . . 86 Violations . . . . . . . . . . . . . 379
8. Variable-Length RRDS Processing . . . . . 87 37. PDSE and PDS Differences . . . . . . . 441
9. Comparison of ESDS, KSDS, Fixed-Length 38. DE Services Function Summary . . . . . 457
RRDS, Variable-Length RRDS, and Linear Data 39. Access Methods That UNIX Files Use 482
Sets . . . . . . . . . . . . . . . 88 40. Access Permissions for UNIX Files and
10. Adding Data to Various Types of Output Data Directories . . . . . . . . . . . . 491
Sets . . . . . . . . . . . . . . . 118 41. DCB Exit Routines . . . . . . . . . . 520
11. Effect of RPL Options on Data Buffers and 42. Data Event Control Block . . . . . . . 521
Positioning . . . . . . . . . . . . 147 43. Exception Code Bits—BISAM . . . . . . 522
| 12. SMB access bias guidelines . . . . . . . 169 44. Event Control Block . . . . . . . . . 523
13. Relationship between SHAREOPTIONS and 45. Exception Code Bits—BDAM . . . . . . 525
VSAM Functions . . . . . . . . . . 202 46. Contents of Registers at Entry to EODAD Exit
| 14. RLS Open Rules, for Recoverable or Routine . . . . . . . . . . . . . 527
| Non-recoverable Data Sets . . . . . . . 228 47. Exception Code Bits—QISAM . . . . . . 529
15. VSAM user-written exit routines . . . . . 242 48. Register Contents on Entry to SYNAD
16. Contents of registers at entry to IGW8PNRU Routine—BDAM, BPAM, BSAM, and QSAM . 531
exit routine . . . . . . . . . . . . 244 49. Register Contents on Entry to SYNAD
17. Contents of registers at entry to EODAD exit Routine—BISAM . . . . . . . . . . 532
routine . . . . . . . . . . . . . . 245 50. Register Contents on Entry to SYNAD
18. Contents of registers at entry to Routine—QISAM . . . . . . . . . . 532
EXCEPTIONEXIT routine . . . . . . . 246 | 51. DCB Exit List Format and Contents . . . . 536
19. Contents of registers at entry to JRNAD exit 52. Option Mask Byte Settings . . . . . . . 540
routine . . . . . . . . . . . . . . 247 53. Conditions for Which Recovery Can Be
20. Contents of parameter list built by VSAM for Attempted . . . . . . . . . . . . 541
the JRNAD exit . . . . . . . . . . . 251 54. System Response to Block Count Exit Return
21. Contents of registers at entry to LERAD exit Code . . . . . . . . . . . . . . 545
routine . . . . . . . . . . . . . . 254 55. System Response to a User Label Exit Routine
22. Contents of registers for RLSWAIT exit Return Code . . . . . . . . . . . . 551
routine . . . . . . . . . . . . . . 255 56. Saving and Restoring General Registers 555
23. Contents of registers at entry to SYNAD exit 57. Requests for Indexed Sequential Data Sets 588
routine . . . . . . . . . . . . . . 256 58. QISAM Error Conditions . . . . . . . . 613
24. Conditions when exits to UPAD routines are 59. BISAM Error Conditions . . . . . . . . 614
taken . . . . . . . . . . . . . . 259 60. Register Contents for DCB-Specified ISAM
25. Contents of registers at entry to UPAD exit SYNAD Routine . . . . . . . . . . 615
routine . . . . . . . . . . . . . . 259 61. Register Contents for AMP-Specified ISAM
26. Parameter list passed to UPAD routine 260 SYNAD Routine . . . . . . . . . . 615
27. Communication with user-security- 62. ABEND Codes Issued by the ISAM Interface 616
verification routine . . . . . . . . . . 262 63. DEB Fields Supported by ISAM Interface 616
28. 31-Bit Address Keyword Parameters . . . . 264 64. DCB Fields Supported by ISAM Interface 618
29. Format of the Header of an Index Record 279 65. Output DISP=NEW,OLD . . . . . . . . 638
30. Segment Control Codes . . . . . . . . 299 66. Output DISP=MOD (IBM V4 tapes only) 638
31. Tape Density (DEN) Values . . . . . . . 313 67. Input . . . . . . . . . . . . . . 640

© Copyright IBM Corp. 1987, 2005 xv

xvi z/OS V1R7.0 DFSMS Using Data Sets
About This Document
This document is intended for system and application programmers. This
document is intended to help you use access methods to process virtual storage
access method (VSAM) data sets, sequential data sets, partitioned data sets (PDSs),
partitioned data sets extended (PDSEs), z/OS UNIX files, and generation data sets
in the DFSMS environment. This document also explains how to use access
method services commands, macro instructions, and JCL to process data sets.

For information about the accessibility features of z/OS, for users who have a
physical disability, see Appendix G, “Accessibility,” on page 643.

Major Divisions of This Document

This document is divided into these major parts:
v Part 1 covers general topics for all data sets.
v Part 2 covers the processing of VSAM data sets.
v Part 3 covers the processing of non-VSAM data sets and UNIX files.
v Appendixes cover the following topics:
– Using direct access labels.
– Copying and printing Kanji characters using the double-byte character set.
– Processing direct data sets.
– Processing indexed sequential data sets.
– Using ISAM programs with VSAM data sets.
– Converting character sets.

Required product knowledge

To use this document effectively, you should be familiar with the following
information:
v IBM® support and how it is structured
v Assembler language
v Job control language (JCL)
v Diagnostic techniques

You should also understand how to use access method services commands,
catalogs, and storage administration, which the following documents describe.

Topic Document
Access method z/OS DFSMS Access Method Services for Catalogs describes the access
services commands method services commands used to process virtual storage access
method (VSAM) data sets.
Catalogs z/OS DFSMS Managing Catalogs describes how to create master and
user catalogs.
Storage administration z/OS DFSMSdfp Storage Administration Reference and z/OS DFSMS
Implementing System-Managed Storage describe storage
administration.
Macros z/OS DFSMS Macro Instructions for Data Sets describes the macros
used to process VSAM and non-VSAM data sets.

© Copyright IBM Corp. 1987, 2005 xvii

 Topic Document
® ®
z/OS UNIX System z/OS UNIX System Services User’s Guide describes how to process
Services z/OS UNIX files.

Referenced documents
For a complete list of DFSMS documents and related z/OS documents referenced
by this document, see the z/OS Information Roadmap. You can obtain a softcopy
version of this document and other DFSMS documents from sources listed here.

This document refers to the following documents:

Document Title Description

z/OS Collection, SK2T-6700 CD-ROM that includes the DFSMS library
and other z/OS element libraries.
[Link] z/OS web site that includes the unlicensed
/zseries/zos documents from DFSMS library and other
z/OS element libraries.
Character Data Representation Architecture Document that includes information about
Reference and Registry coded character set identifiers in the
character data representation architecture
repository.

Accessing z/OS DFSMS documents on the Internet

In addition to making softcopy documents available on CD-ROM, IBM provides
access to unlicensed z/OS softcopy documents on the Internet. To view, search,
and print z/OS documents, go to the z/OS Internet Library:
[Link]/servers/eserver/zseries/zos/bkserv/

Using LookAt to look up message explanations

LookAt is an online facility that lets you look up explanations for most of the IBM
messages you encounter, as well as for some system abends and codes. Using
LookAt to find information is faster than a conventional search because in most
cases LookAt goes directly to the message explanation.

You can use LookAt from the following locations to find IBM message
explanations for z/OS elements and features, z/VM®, and VSE:
v The Internet. You can access IBM message explanations directly from the LookAt
Web site at [Link]
v Your z/OS TSO/E host system. You can install code on your z/OS or z/OS.e
systems to access IBM message explanations, using LookAt from a TSO/E
command line (for example, TSO/E prompt, ISPF, or z/OS UNIX System
Services running OMVS).
v Your Windows® workstation. You can install code to access IBM message
explanations on the z/OS Collection (SK3T-4269), using LookAt from a Windows
DOS command line.
v Your wireless handheld device. You can use the LookAt Mobile Edition with a
handheld device that has wireless access and an Internet browser (for example,

xviii z/OS V1R7.0 DFSMS Using Data Sets

 Internet Explorer for Pocket PCs, Blazer, or Eudora for Palm OS, or Opera for
Linux handheld devices). Link to the LookAt Mobile Edition from the LookAt
Web site.

You can obtain code to install LookAt on your host system or Windows
workstation from a disk on your z/OS Collection (SK3T-4269), or from the LookAt
Web site (click Download, and select the platform, release, collection, and location
that suit your needs). More information is available in the [Link] files
available during the download process.

About This Document xix

xx z/OS V1R7.0 DFSMS Using Data Sets
Summary of Changes
This document contains terminology, maintenance, and editorial changes. Technical
changes or additions to the text and illustrations are indicated by a vertical line to
the left of each change.

You might notice changes in the style and structure of some content in this
document—for example, more specific headings for notes, such as Tip and
Requirement. The changes are ongoing improvements to the consistency and
retrievability of information in DFSMS documents.

Summary of Changes for SC26-7410-05 z/OS Version 1 Release 7

This document contains information that was previously presented in z/OS DFSMS
Using Data Sets, SC26-7410-04.

The following sections summarize the changes to that information.

New Information
This edition includes the following new enhancements:
v Large format sequential data sets. For more information, see “Processing Large
Format Data Sets” on page 411.
v Basic format data sets (sequential data sets which are neither large format nor
extended format).
v VSAM extent constraint relief. For more information, see “Data Set Size” on
page 73 and “Using VSAM Extents” on page 110.
v VSAM RLS 64-bit addressing for data buffers. For more information, see “Using
64-Bit Addressable Data Buffers” on page 225.
v Information about the IHAEXLST mapping macro has been added to “DCB Exit
List” on page 535.
v Information about how VSAM RLS OPENs are allowed has been added to “RLS
Access Rules” on page 228, and information about index record checks has been
added to “Index Trap” on page 234.

Changed Information
The following information changed in this edition:
v Volume assignment considerations for PDSEs in a sysplex. See “Choosing
Volumes for PDSEs in a Sysplex” on page 473for more information.
v Information about ISAM has been changed to indicate that ISAM is no longer
supported, and programs and data sets must be converted to VSAM or use the
ISAM interface to VSAM. For more information, see “Indexed Sequential Access
Method” on page 5, Appendix D, “Using the Indexed Sequential Access
Method,” on page 579, and Appendix E, “Using ISAM Programs with VSAM
Data Sets,” on page 611.
v Recommendations on using IEBCOPY to copy between PDSEs and PDS data sets
have been added to “Copying a PDSE or Member to Another Data Set” on page
454.

Deleted Information
Most information about ISAM data sets has been deleted from this edition.

© Copyright IBM Corp. 1987, 2005 xxi

Summary of Changes for SC26-7410-04 z/OS Version 1 Release 6
This document contains information that was previously presented in z/OS DFSMS
Using Data Sets, SC26-7410-03.

The following sections summarize the changes to that information.

New Information
This edition includes the following new enhancements:
v Restartable PDSE address space. For more information, see “PDSE Address
Spaces” on page 479.

Changed Information
The following information changed in this edition:
v Corrected information about allocating space for a linear data set in “Linear
Data Sets” on page 110.
v Added information about using entry-sequenced data sets (ESDSs) with VSAM
record-level sharing to “Using VSAM RLS with ESDS” on page 232.
v Added information about using 64-bit real storage to “Constructing a Buffer
Pool” on page 348.
v Added information about using partitioned data sets (PDSs) as generation data
sets (GDS) to “Data Set Organization of Generation Data Sets” on page 502.
v Updated information about coded character set identifiers (CCSID) in
Appendix F, “Converting Character Sets,” on page 625.
v This book has been enabled for z/OS LibraryCenter advanced searches by
command name.

Summary of Changes for SC26-7410-03 z/OS Version 1 Release 5

This document contains information that was previously presented in z/OS DFSMS
Using Data Sets, SC26-7410-02.

The following sections summarize the changes to that information.

New Information
This edition includes the following new enhancements:
v You can specify a maximum file sequence number up to 65 535 for a data set on
a tape volume.
v The JOBCAT and STEPCAT DD statements are now disabled by default.
v When the name-hiding function is in effect, you can retrieve the names of data
sets only if you have read access to the data sets or VTOC.
v VSAM automatically determines the resources required to upgrade VSAM
alternate indexes.
v Unrelated messages do not appear between the lines of a multiple-line VSAM
message, so that the operator can interpret the information more easily.
v The system consolidates adjacent extents for VSAM data sets when extending
data on the same volume.
v You can activate the enhanced data integrity function to prevent users from
concurrently opening a shared sequential data set for output or update
processing.
v You can use extended-format sequential data sets with a maximum of 59 stripes.
v You can use the basic partitioned access method (BPAM) to read z/OS UNIX
files.
v Users can specify whether to reclaim generation data sets (GDSs) automatically.

xxii z/OS V1R7.0 DFSMS Using Data Sets

 Changed Information
The following information changed in this edition:
v You must specify the directory block size when allocating of PDSE and PDS data
sets.
v The page space size limit is now 4 GB.
v You can use Integrated Cryptographic Service Facility (ICSF) with the access
method services REPRO ENCIPHER command.
v End-of-volume processing extends to the same volume or to a new volume.
v The large block interface (LBI) section has new information on writing format-U
or format-D blocks without BUFOFF=L.
v You can define a VSAM striped data set as reusable.
v The system affixes a 32-byte suffix to each block for compressed extended-format
data sets.
v Additional information on specifying normal or extended sharing for PDSEs is
provided.
v Recommendations for updating generation data groups with concurrent jobs
have been improved.

Moved Information
The following information has moved to a new location in this document:
v The information on using magnetic tape volumes is in “Magnetic Tape Volumes”
on page 11.
v The information on hierarchical file system (HFS) data sets is now in Chapter 28,
“Processing z/OS UNIX Files,” on page 481.

Summary of Changes for SC26-7410-02 z/OS Version 1 Release 3

This document contains information that was previously presented in z/OS
Version 1 Release 1 DFSMS: Using Data Sets (SC26-7410-01).

The following sections summarize the changes to that information.

New Information
This edition includes the following new information:
v Data set naming conventions
v Virtual input/output (VIO) limit
v Real addresses greater than 2 GB available for all VSAM data sets
v Caching all or some of the VSAM record level sharing (RLS) data in a coupling
facility (CF) cache structure
v VSAM RLS system-managed duplexing rebuild process, and validity checking
for a user-managed rebuild or alter process
v Dynamic volume count for space constraint relief when you store data sets on
DASD volumes
v A summary of the effects of specifying all extents (ALX) or maximum
contiguous extents (MXIG) for virtual input/output (VIO) data sets

Changed Information
The following information changed in this edition:
v Allocation of HFS data sets requiring directory block size
v Requirements for the ENCIPHER and DECIPHER functions of the REPRO
command
v Relative byte address (RBA) in an entry-sequenced data set
v Processing techniques for VSAM system-managed buffering

Summary of Changes xxiii

 v Calculating the index control interval size for a key-sequenced data set
v Extensions of VSAM data sets when you specify zero as a secondary allocation
quantity
v Sharing of non-VSAM data sets
v Use of the BYPASSLLA option with the BLDL list
v Partitioned concatenation of PDSs and PDSEs
v Processing restrictions for PDSEs
v Rules for updating a data set in place
v Conversion of the exclamation point character between EBCDIC and ASCII
v Direct insertion of records into a key-sequenced data set
v Addition of QSAM LRECL value
v Sharing of PDSEs by multiple systems in a sysplex

xxiv z/OS V1R7.0 DFSMS Using Data Sets

Part 1. All Data Sets
Chapter 1. Working with Data Sets . . . . . . 3 Catalogs and Volume Table of Contents . . . . . 23
Data Storage and Management . . . . . . . . 3 VTOC . . . . . . . . . . . . . . . 23
System-Managed Data Sets . . . . . . . . 4 Catalogs . . . . . . . . . . . . . . 23
Distributed File Manager . . . . . . . . . 4 Data Set Names and Metadata . . . . . . . 24
Access Methods . . . . . . . . . . . . . 4 Security of Data Set Names . . . . . . . . 25
Basic Direct Access Method . . . . . . . . 4
Basic Partitioned Access Method . . . . . . . 5 Chapter 2. Using the Storage Management
Basic Sequential Access Method . . . . . . . 5 Subsystem . . . . . . . . . . . . . . 27
Data-in-Virtual (DIV) . . . . . . . . . . 5 Using Automatic Class Selection Routines . . . . 29
Indexed Sequential Access Method . . . . . . 5 Allocating Data Sets . . . . . . . . . . . 30
Object Access Method . . . . . . . . . . 6 Allocating Data Sets with JCL . . . . . . . 30
Queued Sequential Access Method . . . . . . 6 Allocating an HFS Data Set . . . . . . . 31
Virtual Storage Access Method . . . . . . . 6 Allocating System-Managed Data Sets . . . 31
Access to z/OS UNIX Files . . . . . . . . 7 Allocating Non-System-Managed Data Sets . . 32
Selection of an Access Method . . . . . . . 7 Allocating System-Managed Data Sets with the
Direct Access Storage Device (DASD) Volumes . . . 8 Access Method Services ALLOCATE Command . 32
DASD Labels . . . . . . . . . . . . . 8 Allocating a Data Set Using Class
Track Format . . . . . . . . . . . . . 8 Specifications . . . . . . . . . . . . 32
Track Overflow . . . . . . . . . . . . 9 Allocating a VSAM Data Set Using Class
VSAM Record Addressing . . . . . . . . . 9 Specifications . . . . . . . . . . . . 33
Actual and Relative Addressing with Non-VSAM Allocating a System-Managed Non-VSAM
Access Methods . . . . . . . . . . . . 10 Data Set . . . . . . . . . . . . . 33
Actual Addresses . . . . . . . . . . 10 Allocating a PDSE . . . . . . . . . . 33
Relative Addresses . . . . . . . . . . 10 Allocating a New Non-System-Managed Data
Magnetic Tape Volumes . . . . . . . . . . 11 Set . . . . . . . . . . . . . . . 33
Using Magnetic Tape Labels . . . . . . . . 12 Allocating Data Sets with the TSO ALLOCATE
Specifying the File Sequence Number . . . . . 12 Command . . . . . . . . . . . . . . 34
Example of Creating a Tape Data Set with a Allocating Data Sets with Dynamic Allocation . . 34
File Sequence Number Greater than 9999 . . 13
Example of Creating a Tape Data Set Using Chapter 3. Allocating Space on Direct Access
Any File Sequence Number . . . . . . . 13 Volumes . . . . . . . . . . . . . . . 35
Identifying Unlabeled Tapes . . . . . . . . 14 Specification of Space Requirements . . . . . . 35
Using Tape Marks . . . . . . . . . . . 15 Blocks . . . . . . . . . . . . . . . 35
Data Management Macros . . . . . . . . . 15 Average Record Length . . . . . . . . . 36
Data Set Processing . . . . . . . . . . . . 16 Tracks or Cylinders . . . . . . . . . . . 36
Allocating Data Sets . . . . . . . . . . 16 Absolute Track . . . . . . . . . . . . 37
Access Method Services . . . . . . . . 16 Additional Space-Allocation Options . . . . . 37
ALLOCATE Command . . . . . . . . 16 Maximum Data Set Size . . . . . . . . . . 37
JCL . . . . . . . . . . . . . . . 16 Maximum Size on One Volume . . . . . . . 37
Processing Data Sets through Programs . . . . 17 Maximum Number of Volumes . . . . . . . 37
Using Access Methods . . . . . . . . . . 17 Maximum VSAM Data Set Size . . . . . . . 38
Using Addressing Modes . . . . . . . . . 17 | Minimum data set size . . . . . . . . . . 38
VSAM Addressing Modes . . . . . . . 17 Primary and Secondary Space Allocation without
Non-VSAM Addressing Modes . . . . . . 18 the Guaranteed Space Attribute . . . . . . . . 38
Using Hiperspace and Hiperbatch . . . . . . 18 Multivolume VSAM Data Sets . . . . . . . 39
Processing VSAM Data Sets . . . . . . . . 18 Multivolume Non-VSAM Data Sets . . . . . 39
Processing PDSs, PDSEs, and UNIX Directories 18 Extended-Format Data Sets . . . . . . . . 39
Processing Sequential Data Sets and Members of Allocation of Data Sets with the Guaranteed Space
PDSEs and PDSs . . . . . . . . . . . 19 Attribute . . . . . . . . . . . . . . . 40
BSAM Processing . . . . . . . . . . 19 Guaranteed Space with DISP=NEW or MOD . . 40
QSAM Processing . . . . . . . . . . 20 Guaranteed Space for VSAM . . . . . . . 40
Processing UNIX Files with an Access Method . 20 Guaranteed Space with DISP=OLD or SHR . . . 40
Processing EXCP, EXCPVR, and XDAP Macros 21 Guaranteed Space with Extended-Format Data
Distributed Data Management (DDM) Attributes . . 21 Sets . . . . . . . . . . . . . . . . 41
Virtual I/O for Temporary Data Sets . . . . . . 21 Guaranteed Space Example . . . . . . . . 41
Data Set Names . . . . . . . . . . . . . 22

© Copyright IBM Corp. 1987, 2005 1

Allocation of Data Sets with the Space Constraint REPRO ENCIPHER and DECIPHER on ICSF . . 66
Relief Attributes . . . . . . . . . . . . . 41
Extension to Another DASD Volume . . . . . . 42
Examples of Dynamic Volume Count When
Defining a Data Set . . . . . . . . . . . 43
Examples of Dynamic Volume Count When
Allocating an Existing Data Set . . . . . . . 43
Multiple Volume Considerations for Sequential Data
Sets . . . . . . . . . . . . . . . . . 44
Additional Information on Space Allocation . . . 44

Chapter 4. Backing Up and Recovering Data Sets 45

Using REPRO for Backup and Recovery . . . . . 46
Using EXPORT and IMPORT for Backup and
Recovery of VSAM Data Sets . . . . . . . . 47
Structure of an Exported Data Set . . . . . . 48
EXPORT and IMPORT Commands . . . . . 48
Writing a Program for Backup and Recovery . . . 48
Using Concurrent Copy for Backup and Recovery 49
Updating a Data Set After Recovery . . . . . . 49
Synchronizing Catalog and VSAM Data Set
Information During Recovery . . . . . . . . 49
Handling an Abnormal Termination . . . . . 50
Using VERIFY to Process Improperly Closed
Data Sets . . . . . . . . . . . . . . 50
Recovering from Errors Due to an Improperly
Closed VSAM Data Set . . . . . . . . 51
Using VERIFY with Catalogs . . . . . . 51
CICS VSAM Recovery . . . . . . . . . . . 52

Chapter 5. Protecting Data Sets . . . . . . . 53

z/OS Security Server (RACF) . . . . . . . . 53
RACF Protection for VSAM Data Sets . . . . 53
Generic and Discrete Profiles for VSAM Data Sets 54
RACF Protection for Non-VSAM Data Sets . . . 54
Hiding Data Set Names . . . . . . . . . 55
Data Set Password Protection . . . . . . . . 55
Passwords for VSAM Data Sets . . . . . . . 56
Passwords to Authorize Access . . . . . . 56
Password-Protection Precautions . . . . . 57
Data Set and Catalog Protection . . . . . 58
Password Prompting . . . . . . . . . 58
Passwords for Non-VSAM Data Sets . . . . . 59
Assigning a Password . . . . . . . . . 59
Protecting a Data Set When You Define It . . 59
Supplying a Password for a Catalog . . . . 59
Handling Incorrect Passwords . . . . . . 60
Entering a Record in the PASSWORD Data Set 60
User-Security-Verification Routine . . . . . . . 60
Erasure of Residual Data . . . . . . . . . . 60
Erasing DASD Data . . . . . . . . . . 60
System Erasure of Data . . . . . . . . 61
RAMAC Virtual Array . . . . . . . . . 61
Erasing Tape Data . . . . . . . . . . . 62
Authorized Program Facility and Access Method
Services . . . . . . . . . . . . . . . 62
Access Method Services Cryptographic Option . . 63
Data Enciphering and Deciphering . . . . . 64
Encryption of VSAM Data Sets . . . . . . 65
Data Encryption Keys . . . . . . . . . 66
Secondary Key-Encrypting Keys . . . . . 66

2 z/OS V1R7.0 DFSMS Using Data Sets

Chapter 1. Working with Data Sets
This chapter covers the following topics.

Topic Location
Data Storage and Management 3
Access Methods 4
Direct Access Storage Device (DASD) Volumes 8
Magnetic Tape Volumes 11
Data Management Macros 15
Data Set Processing 16
Distributed Data Management (DDM) Attributes 21
Virtual I/O for Temporary Data Sets 21
Data Set Names 22
Catalogs and Volume Table of Contents 23

A data set is a collection of logically related data and can be a source program, a
library of macros, or a file of data records used by a processing program. Data
records are the basic unit of information used by a processing program. By placing
your data into volumes of organized data sets, you can save and process the data.
You can also print the contents of a data set or display the contents on a terminal.

Exception: z/OS UNIX files are different from the typical data set because they are
byte oriented rather than record oriented.

Data Storage and Management

You can store data on secondary storage devices, such as a direct access storage
device (DASD) or magnetic tape volume. The term DASD applies to disks or to a
mass storage medium on which a computer stores data. A volume is a standard
unit of secondary storage. You can store all types of data sets on DASD but only
sequential data sets on magnetic tape. Mountable tape volumes can reside in an
automated tape library. For information about magnetic tape volumes, see z/OS
DFSMS Using Magnetic Tapes. You can also direct a sequential data set to or from
spool, a UNIX file, a TSO/E terminal, a unit record device, virtual I/O (VIO), or a
dummy data set.

Each block of data on a DASD volume has a distinct location and a unique
address, making it possible to find any record without extensive searching. You can
store and retrieve records either directly or sequentially. Use DASD volumes for
storing data and executable programs, including the operating system itself, and
for temporary working storage. You can use one DASD volume for many different
data sets, and reallocate or reuse space on the volume.

Data management is the part of the operating system that organizes, identifies,
stores, catalogs, and retrieves all the information (including programs) that your
installation uses. Data management does these main tasks:
v Sets aside (allocates) space on DASD volumes.
v Automatically retrieves cataloged data sets by name.

© Copyright IBM Corp. 1987, 2005 3

Working with Data Sets

v Mounts magnetic tape volumes in the drive.

v Establishes a logical connection between the application program and the
medium.
v Controls access to data.
v Transfers data between the application program and the medium.

System-Managed Data Sets

The Storage Management Subsystem (SMS) is an operating environment that
automates the management of storage. Storage management uses the values
provided at allocation time to determine, for example, on which volume to place
your data set, and how many tracks to allocate for it. Storage management also
manages tape data sets on mountable volumes that reside in an automated tape
library. With SMS, users can allocate data sets more easily.

The data sets allocated through SMS are called system-managed data sets or
SMS-managed data sets. For information about allocating system-managed data
sets, see Chapter 2, “Using the Storage Management Subsystem,” on page 27. If
you are a storage administrator, also see z/OS DFSMSdfp Storage Administration
Reference for information about using SMS.

Distributed File Manager

With distributed file manager (DFM) target server, applications running on a
processor with the DFM source server can create or access certain types of
SMS-managed data sets. They can also access certain types of non-SMS-managed
data sets on an System/390 processor running DFSMS, with the DFM target server.
See z/OS DFSMS DFM Guide and Reference for details about the supported data set
types and a discussion of considerations in making them available for remote
access. Also see “Distributed Data Management (DDM) Attributes” on page 21.

Access Methods
An access method defines the technique that is used to store and retrieve data.
Access methods have their own data set structures to organize data, macros to
define and process data sets, and utility programs to process data sets.

Access methods are identified primarily by the data set organization. For example,
use the basic sequential access method (BSAM) or queued sequential access
method (QSAM) with sequential data sets. However, there are times when an
access method identified with one organization can be used to process a data set
organized in a different manner. For example, a sequential data set (not
extended-format data set) created using BSAM can be processed by the basic direct
access method (BDAM), and vice versa. Another example is UNIX files, which you
can process using BSAM, QSAM, basic partitioned access method (BPAM), or
virtual storage access method (VSAM).

Basic Direct Access Method

BDAM arranges records in any sequence your program indicates, and retrieves
records by actual or relative address. If you do not know the exact location of a
record, you can specify a point in the data set where a search for the record is to
begin. Data sets organized this way are called direct data sets.

Optionally, BDAM uses hardware keys. Hardware keys are less efficient than the
optional software keys in virtual sequential access method (VSAM).

4 z/OS V1R7.0 DFSMS Using Data Sets

 Working with Data Sets

Related reading: See the following material:

v “Track Format” on page 8
v Appendix C, “Processing Direct Data Sets,” on page 569

Basic Partitioned Access Method

Basic partitioned access method (BPAM) arranges records as members of a
partitioned data set (PDS) or a partitioned data set extended (PDSE) on DASD. You
can use BPAM to view a UNIX directory and its files as if it were a PDS. You can
view each PDS, PDSE, or UNIX member sequentially with BSAM or QSAM. A PDS
or PDSE includes a directory that relates member names to locations within the
data set. Use the PDS, PDSE, or UNIX directory to retrieve individual members.
For program libraries (load modules and program objects), the directory contains
program attributes that are required to load and rebind the member. Although
UNIX files can contain program objects, program management does not access
UNIX files through BPAM.

The following describes some of the characteristics of PDSs, PDSEs, and UNIX
files:
Partitioned data set
PDSs can have any type of sequential records.
Partitioned data set extended
A PDSE has a different internal storage format than a PDS, which
gives PDSEs improved usability characteristics. You can use a
PDSE in place of most PDSs, but you cannot use a PDSE for
certain system data sets.
z/OS UNIX files
UNIX files are byte streams and do not contain records. BPAM
converts the bytes in UNIX files to records. You can use BPAM to
read but not write to UNIX files. BPAM access is like BSAM access.

Basic Sequential Access Method

BSAM arranges records sequentially in the order in which they are entered. A data
set that has this organization is a sequential data set. The user organizes records
with other records into blocks. This is basic access. You can use BSAM with the
following data types:
| v basic format sequential data sets (before z/OS 1.7 these were known as sequential
| data sets or more accurately as non-extended-format sequential data sets
| v large format sequential data sets
v extended-format data sets
v z/OS UNIX files

Data-in-Virtual (DIV)
| The data-in-virtual (DIV) macro provides access to VSAM linear data sets. For
| more information, see z/OS MVS Programming: Assembler Services Guide. You can
| also use window services to access linear data sets, as described in that book.

Indexed Sequential Access Method

| ISAM refers to two access methods: basic indexed sequential access method
| (BISAM) and queued indexed sequential access method (QISAM). Data sets
| processed by ISAM are called indexed sequential data sets. Starting in z/OS V1R7,

Chapter 1. Working with Data Sets 5

 Working with Data Sets

| you cannot create, open, copy, convert, or dump indexed sequential (ISAM) data
| sets. You can delete or rename them. You can use an earlier release of z/OS to
| convert them to VSAM data sets.

| Important: Do not use ISAM. You should convert all indexed sequential data sets
| to VSAM data sets. See Appendix D, “Using the Indexed Sequential Access
| Method,” on page 579.

Object Access Method

Object access method (OAM) processes very large, named byte streams (objects)
that have no record boundary or other internal orientation. These objects can be
recorded in a DB2 database or on an optical storage volume. For information about
OAM, see z/OS DFSMS OAM Application Programmer’s Reference and z/OS DFSMS
OAM Planning, Installation, and Storage Administration Guide for Object Support.

Queued Sequential Access Method

QSAM arranges records sequentially in the order that they are entered to form
sequential data sets, which are the same as those data sets that BSAM creates. The
system organizes records with other records. QSAM anticipates the need for
records based on their order. To improve performance, QSAM reads these records
into storage before they are requested. This is called queued access. You can use
QSAM with the following data types:
v sequential data sets
| v basic format sequential data sets (before z/OS 1.7 these were known as sequential
| data sets or more accurately as non-extended-format sequential data sets
| v large format sequential data sets
v extended-format data sets
v z/OS UNIX files

Virtual Storage Access Method

VSAM arranges records by an index key, relative record number, or relative byte
addressing. VSAM is used for direct or sequential processing of fixed-length and
variable-length records on DASD. Data that is organized by VSAM is cataloged for
easy retrieval and is stored in one of five types of data sets.
v Entry-sequenced data set (ESDS). Contains records in the order in which they
were entered. Records are added to the end of the data set and can be accessed.
v Key-sequenced data set (KSDS). Contains records in ascending collating
sequence. Records can be accessed by a field, called a key, or by a relative byte
address.
v Linear data set (LDS). Contains data that has no record boundaries. Linear data
sets contain none of the control information that other VSAM data sets do.
Linear data sets must be cataloged in a catalog.
v Relative record data set (RRDS). Contains records in relative record number
order, and the records can be accessed only by this number. There are two types
of relative record data sets.
– Fixed-length RRDS: The records must be of fixed length.
– Variable-length RRDS: The records can vary in length.
Throughout this document, the term RRDS refers to both types of relative record
data sets, unless they need to be differentiated.
v z/OS UNIX files. A UNIX file can be accessed as if it were a VSAM
entry-sequenced data set (ESDS). Although UNIX files are not actually stored as

6 z/OS V1R7.0 DFSMS Using Data Sets

 Working with Data Sets

entry-sequenced data sets, the system attempts to simulate the characteristics of

such a data set. To identify or access a UNIX file, specify the path that leads to
it.

Any type of VSAM data set can be in extended format. Extended-format data sets
have a different internal storage format than data sets that are not extended. This
storage format gives extended-format data sets additional usability characteristics
and possibly better performance due to striping. You can choose for an
extended-format key-sequenced data set to be in the compressed format.
Extended-format data sets must be SMS managed. You cannot use an
extended-format data set for certain system data sets.

| Requirement: Do not use BISAM or QISAM. Use VSAM instead.

Access to z/OS UNIX Files

Programs can access the information in UNIX files through z/OS UNIX System
Services (z/OS UNIX) calls, such as open(pathname), read(file descriptor), and
write(file descriptor). Programs can also access the information in UNIX files
through the BSAM, BPAM, QSAM, and VSAM access methods. When you use
BSAM or QSAM, a UNIX file is simulated as a single-volume sequential data set.
When you use VSAM, a UNIX file is simulated as an ESDS. When you use BPAM,
a UNIX directory and its files are simulated as a partitioned data set directory and
its members.

You can use the following types of UNIX files with the access methods:
v Regular files, including files accessed through Network File System (NFS),
temporary file system (TFS), HFS, or zSeries file system (zFS)
v Character special files
v First-in-first-out (FIFO) special files
v Symbolic links

Restriction: You cannot use the following types of UNIX files with the access
methods:
v UNIX directories, except indirectly through BPAM
v External links

Files can reside on other systems. The access method user can use NFS to access
them.

Selection of an Access Method

In selecting an access method for a data set, consider the organization of the data
set, what you need to specify through macros, and the device type:
v VSAM data sets, PDSEs, PDSs, extended-format data sets, direct data sets, and
UNIX files must be stored on DASD volumes.
v Sequential data sets can be on DASD or tape volumes, or these data sets can be
read from or written to a unit record device or TSO/E terminal. They can be
spooled data sets. Spooled data sets named SYSOUT can be directed over a
network. Sequential data sets also can be dummy data sets.

In addition, you should select a data organization according to the type of

processing you want to do: sequential or direct. For example, RRDSs or
key-sequenced data sets are best for applications that use only direct access, or
both direct and sequential access. Sequential or VSAM entry-sequenced data sets
are best for batch processing applications and for sequential access.

Chapter 1. Working with Data Sets 7

Working with Data Sets

Restriction: You cannot process VSAM data sets with non-VSAM access methods,
although you can use DIV macros to access linear data sets. You cannot process
non-VSAM data sets except for UNIX files with VSAM.

See z/OS TSO/E Command Reference for information about using BSAM and QSAM
to read from and write to a TSO/E terminal in line mode.

Direct Access Storage Device (DASD) Volumes

Although DASD volumes differ in physical appearance, capacity, and speed, they
are similar in data recording, data checking, data format, and programming. The
recording surface of each volume is divided into many concentric tracks. The
number of tracks and their capacity vary with the device. Each device has an
access mechanism that contains read/write heads to transfer data as the recording
surface rotates past them.

DASD Labels
The operating system uses groups of labels to identify DASD volumes and the
data sets they contain. Application programs generally do not use these labels
directly. DASD volumes must use standard labels. Standard labels include a
volume label, a data set label for each data set, and optional user labels. A volume
label, stored at track 0 of cylinder 0, identifies each DASD volume.

A utility program initializes each DASD volume before it is used on the system.
The initialization program generates the volume label and builds the volume table
of contents (VTOC). The VTOC is a structure that contains the data set labels.

See Appendix A, “Using Direct Access Labels,” on page 561 for information about
direct access labels.

Track Format
Information is recorded on all DASD volumes in a standard format. This format is
called count-key data (CKD) or extended count-key data (ECKD).

Each track contains a record 0 (also called track descriptor record or capacity
record) and data records. Historically, S/390 hardware manuals and software
manuals have used inconsistent terminology to refer to units of data written on
DASD volumes. Hardware manuals call them records. Software manuals call them
blocks and use “record” for something else. The DASD sections of this document
use both terms as appropriate. Software records are described in Chapter 6,
“Organizing VSAM Data Sets,” on page 73 and Chapter 20, “Selecting Record
Formats for Non-VSAM Data Sets,” on page 293.

For these data formats, one or more of the following is true:

v Each VSAM control interval consists of one or more contiguous blocks. Control
intervals are grouped into control areas.
v Each non-VSAM block contains part of a record or one or more records.
Examples of these programming interfaces are BSAM, BDAM, and EXCP.
v Each VSAM record occupies multiple control intervals or all or part of a control
interval. Each non-VSAM record occupies multiple blocks or all or part of a
block. An example is QSAM.
v The application program might regard byte streams as being grouped in records.
The program does not see blocks. Examples of such programs include UNIX
files and OAM objects.

8 z/OS V1R7.0 DFSMS Using Data Sets

 Working with Data Sets

The process of grouping records into blocks is called blocking. The extraction of
records from blocks is called unblocking. Blocking or unblocking might be done by
the application program or the operating system. In z/OS UNIX, blocking means
suspension of program execution.

| Under certain conditions, BDAM uses the data area of record zero to contain
| information about the number of empty bytes following the last user record on the
| track. This is called the track descriptor record.

Figure 1 shows the two different data formats, count-data and count-key-data, only
one of which can be used for a particular data set. An exception is PDSs that are
not PDSEs. The directory blocks are in count-key-data format, and the member
blocks normally are in count-data format.

Count-Data Format

Count Data Count Data ... Count Data

Track Descriptor Block (R1) Block (Rn)

Record (RO)

Count-Key-Data Format

Count Data Count Key Data ... Count Key Data

Track Descriptor Block (R1) Block (Rn)

Record (RO)

Figure 1. DASD Volume Track Formats

Count-Data Format: Records are formatted without keys. The key length is 0. The
count area contains 8-bytes that identify the location of the block by cylinder, head,
and record numbers, and its data length.

Count-Key-Data Format: The blocks are written with hardware keys. The key area
(1 - 255 bytes) contains a record key that specifies the data record, such as the part
number, account number, sequence number, or some other identifier.

In data sets, only BDAM, BSAM, EXCP, and PDS directories use blocks with
hardware keys. Outside data sets, the VTOC and the volume label contain
hardware keys.

Tip: The use of hardware keys is less efficient than the use of software keys (which
VSAM uses).

Track Overflow
The operating system no longer supports the track overflow feature. The system
ignores any request for it.

VSAM Record Addressing

You identify VSAM records by their key, record number, or relative byte address in
the data set. See “Selection of VSAM Data Set Types” on page 78.

Chapter 1. Working with Data Sets 9

 Working with Data Sets

Actual and Relative Addressing with Non-VSAM Access

Methods
With certain access methods, you can access data non-sequentially. You can use
addresses to identify block locations. Use two types of addresses to store and
retrieve data on DASD volumes: actual addresses and relative addresses. When
sequentially processing a multiple volume data set with a BSAM DCB, except for
extended-format data sets, you can refer to only records of the current volume.

Actual Addresses
When the system returns the actual address of a block on a direct access volume to
your program, it is in the form MBBCCHHR, in which the characters represent the
following values:

M 1-byte binary number specifying the relative extent number. Each extent is a set
of consecutive tracks allocated for the data set.
BBCCHH Three 2-byte binary numbers specifying the cell (bin), cylinder, and head
number for the block (its track address). The cylinder and head numbers are
recorded in the count area for each block. All DASDs require that the bin
number (BB) be zero.
R 1-byte binary number specifying the relative block number on the track. The
block number is also recorded in the count area.
If your program stores actual addresses in your data set, and you refer to those
addresses, the data set must be treated as unmovable. Data sets that are
unmovable cannot reside on system-managed volumes.

If you store actual addresses in another data set, those addresses become nonvalid
if the first data set is moved or migrated. Although you can mark the data set with
the unmovable attribute in DSORG, that prevents the data set from being SMS
managed.

Relative Addresses
| BDAM, BSAM and BPAM optionally use relative addresses to identify blocks in
| the data set.

BSAM and BPAM relative addresses are relative to the data set on the current
volume. BDAM relative addresses are relative to the data set and go across all
volumes.

| BDAM relative block addresses. The relative block address is a 3-byte binary
| number that shows the position of the block, starting from the first block of the
| data set. Allocation of noncontiguous sets of blocks does not affect the number. The
| first block of a data set always has a relative block address of 0.

| BDAM, BSAM, and BPAM Relative Track Addresses. With BSAM you can use
| relative track addresses in basic or large format data sets. With BPAM you can use
| relative track addresses in PDSs. The relative track address has the form TTR or
| TTTR:
|| TT or TTT An unsigned two-byte or three-byte binary number specifying the position of the
| track starting from the first track allocated for the data set. It always is two bytes
| with BDAM and it is two bytes with BSAM and BPAM when you do not specify
| the BLOCKTOKENSIZE=LARGE parameter on the DCBE macro. It is three bytes
| with BSAM and BPAM when you specify the BLOCKTOKENSIZE=LARGE
| parameter on the DCBE macro. The value for the first track is 0. Allocation of
| noncontiguous sets of tracks does not affect the relative track number.

10 z/OS V1R7.0 DFSMS Using Data Sets

 Working with Data Sets

| R 1-byte binary number specifying the number of the block starting from the first
| block on the track TT or TTT. The R value for the first block of data on a track is
| 1.
|

| With some devices, such as the IBM 3380 Model K, a data set can contain more
than 32 767 tracks. Therefore, assembler halfword instructions could result in
non-valid data being processed.

Relative Block Addresses for Extended-Format Data Sets. For extended-format

data sets, block locator tokens (BLTs) provide addressing capability. You can use a
| BLT transparently, as if it were a relative track record (TTR). The NOTE macro
| returns a 4-byte value. If you do not code BLOCKTOKENSIZE=LARGE on the
| DCBE macro, then the three high-order bytes are the BLT value and the fourth byte
| is a zero. If you code BLOCKTOKENSIZE=LARGE on the DCBE macro, then the
| four bytes are the BLT value. Your program uses the value from the NOTE macro
as input to the POINT macro, which provides positioning within a sequential data
set through BSAM. The BLT is essentially the relative block number (RBN) within
each logical volume of the data set (where the first block has an RBN of 1). For
compressed format data sets, the relative block numbers represent uncompressed
simulated blocks, not the real compressed blocks.

A multistriped data appears to the user as a single logical volume. Therefore, for a
multistriped data set, the RBN is relative to the beginning of the data set and
incorporates all stripes.

Relative Track Addresses for PDSEs. For PDSEs, the relative track addresses
(TTRs) do not represent the actual track and record location. Instead, the TTRs are
tokens that define the record’s position within the data set. See “Relative Track
Addresses (TTR)” on page 443 for a description of TTRs for PDSE members and
| blocks. Whether the value is three bytes or four bytes depends on whether you
| specify BLOCKTOKENSIZE=LARGE on the DCBE macro.

Relative Track Addresses for UNIX files. For UNIX files, the relative track
addresses (TTRs) do not represent the actual track and record location. Instead, the
TTRs are tokens that define a BPAM logical connection to a UNIX member or the
| record’s position within the file. Whether the value is three bytes or four bytes
| depends on whether you specify BLOCKTOKENSIZE=LARGE on the DCBE
| macro.

Magnetic Tape Volumes

This section discusses using tape labels and specifying the file sequence number
for data sets that are stored on magnetic tape volumes.

Because data sets on magnetic tape devices must be organized sequentially, the
procedure for allocating space is different from allocating space on DASD. All data
sets that are stored on a given magnetic tape volume must be recorded in the same
density. See z/OS DFSMS Using Magnetic Tapes for information about magnetic tape
volume labels and tape processing.

Related reading: For information about nonstandard label processing routines, see
z/OS DFSMS Installation Exits.

Chapter 1. Working with Data Sets 11

Working with Data Sets

Using Magnetic Tape Labels

The operating system uses groups of labels to identify magnetic tape volumes and
the data sets that they contain. Application programs generally do not use these
labels directly. Magnetic tape volumes can have standard or nonstandard labels, or
they can be unlabeled. DASD volumes must use standard labels. Standard labels
include a volume label, a data set label for each data set, and optional user labels.
A volume label, stored at track 0 of cylinder 0, identifies each DASD volume.

International Organization for Standardization (ISO) and the American National

Standards Institute (ANSI) tape labels are similar to IBM standard labels. ASCII
permits data on magnetic tape to be transferred from one computer to another,
even though the two computers can be products of different manufacturers. IBM
standard labels are coded in the extended binary-coded-decimal interchange code
(EBCDIC). ISO/ANSI labels are coded in the American National Standard Code for
Information Interchange (ASCII).

Specifying the File Sequence Number

When a new data set is to be placed on a magnetic tape volume, you must specify
the file sequence number if the data set is not the first one on the reel or cartridge.
The maximum value of the file sequence number of a data set on a tape volume is
65 535 for the following tapes:
v Standard label (SL) tapes
v Standard user label (SUL) tapes
v Leading tape mark (LTM) tapes
v Unlabeled (NL) tapes
v Bypass label processing (BLP) tapes

Restriction: The ISO/ANSI (AL) labeled tapes do not allow a file sequence
number greater than 9999.

Related reading: For additional information about using file sequence numbers,
see z/OS DFSMS Using the New Functions and z/OS DFSMS Using Magnetic Tapes.

You can specify the file sequence number in one of the following ways:
v Code the file sequence number as the first value of the LABEL keyword on the
DD statement or using the DYNALLOC, macro for dynamic allocation.
v Catalog each data set using the appropriate file sequence number and volume
serial number. Issue the OPEN macro because the catalog provides the file
sequence number.
OPEN uses the file sequence number from the catalog if you do not specify it on
the DD statement or dynamic allocation.
v You can use the RDJFCB macro to read the job file control block (JFCB), set the
file sequence number in the JFCB, and issue the OPEN, TYPE=J macro for a new
or uncataloged data set. The maximum file sequence number is 65 535. This
method overrides other sources of the file sequence number.

Related reading: For more information on the OPEN macro, see z/OS DFSMS
Macro Instructions for Data Sets. For more information on the RDJFCB and OPEN,
TYPE=J macros, see z/OS DFSMSdfp Advanced Services. For more information on
IEHPROGM, see z/OS DFSMSdfp Utilities.

12 z/OS V1R7.0 DFSMS Using Data Sets

 Working with Data Sets

Example of Creating a Tape Data Set with a File Sequence

Number Greater than 9999
The following example shows how to use the OPEN,TYPE=J and RDJFCB macros
to create a cataloged tape data set with a file sequence number of 10 011. The file
sequence number is stored in the JFCB. In the JCL statement, specify the
LABEL=(1,labeltype) parameter, where labeltype is the type of tape label such as SL
or NL. This example works with any file sequence number from 1 to 65 535 if the
previous file exists on the specified tape or on a volume that is named in the JFCB
or JFCB extension. When the system unallocates the data set, it creates an entry for
the data set in the catalog.

Example:
//* STEP05
//* Create a tape data set with a file sequence number of 10 011.
//* Update the file sequence number (FSN) in JFCB using OPEN TYPE=J macro.
//*--------------------------------------------------------------------
//STEP05 EXEC ASMHCLG
//[Link] DD *
. . .
L 6,=F’10011’ CREATE FSN 10011
RDJFCB (DCBAD) READ JFCB
STCM 6,B’0011’,JFCBFLSQ STORE NEW FSN IN JFCB
OPEN (DCBAD,(OUTPUT)),TYPE=J CREATE FILE
PUT DCBAD,RECORD WRITE RECORD
CLOSE DCBAD CLOSE FILE
. . .
DCBAD DCB DDNAME=DD1,DSORG=PS,EXLST=LSTA,MACRF=PM,LRECL=80,RECFM=FB
LSTA DS 0F RJFCB EXIT LIST
DC X'87’ CODE FOR JFCB
DC AL3(JFCBAREA) POINTER TO JFCB AREA
JFCBAREA DS XL176 JFCB AREA
IEFJFCBN DEFINE THE JFCB FIELDS
RECORD DC CL80’RECORD10011’ RECORD AREA
END
//* JCL FOR ALLOCATING TAPE DATA SET
//DD1 DD DSN=DATASET1,UNIT=TAPE,VOL=SER=TAPE01,DISP=(NEW,CATLG),
// LABEL=(1,SL)

Result: The output displays information about the new tape data set with a file
sequence number of 10 011:
IEC205I DD1,OCEFS005,G.STEP05,FILESEQ=10011, COMPLETE VOLUME LIST,
DSN=DS10011,VOLS=TAPE01,TOTALBLOCKS=1

Example of Creating a Tape Data Set Using Any File Sequence

Number
The following example shows how to use the OPEN macro to create several tape
data sets with file sequence numbers ranging from 1 to 10 010. In the JCL
statement, specify the LABEL=(fsn,labeltype) parameter, where fsn is the file
sequence number and labeltype is the type of tape label such as SL or NL.

Example:
//* STEP06
//* Create files 1 through 10 010 on a single volume.
//*--------------------------------------------------------------
//STEP06 EXEC ASMHCLG
//[Link] DD *
. . .
L 6,=F’10010’ CREATE 10 010 FILES
LA 5,1 START AT FILE 1 AND DS1
RDJFCB (DCBAD) READ JFCB
MVC JFCBAREA(44),=CL44’DS’ DSNAME IS ’DSfsn’ WHERE

Chapter 1. Working with Data Sets 13

Working with Data Sets

* fsn IS FSN 1 TO 10 010

* -------------------------------------------------------------
* This loop creates file sequence numbers from 1 to 10 010.
* -------------------------------------------------------------
LOOP EQU *
STCM 5,B'0011’,JFCBAREA+68 STORE NEW FSN IN JFCB
CVD 5,WORKAREA UPDATE DSNAME
UNPK JFCBAREA+2(5),WORKAREA(8) LOAD JFCB
OI JFCBAREA+6,X'F0’ SET DSfsn
MVC RECORD+6(5),JFCBAREA+2 MOVE FSN INTO RECORD
* RECORD FORMAT IS ’RECORDfsn’
OPEN (DCBAD, (OUTPUT)),TYPE=J CREATE FILE NUMBER
PUT DCBAD,RECORD WRITE RECORD
CLOSE (DCBAD,LEAVE) CLOSE FILE NUMBER
CONTIN EQU *
RDJFCB (DCBAD) READ JFCB
SR 5,5
ICM 5,B’0011’,JFCBAREA+68 GET CURRENT FSN
LA 5,1(5) INCREMENT FSN
BCT 6,LOOP CONTINUE PROCESSING UNTIL DONE
. . .
* DEFINITIONS
DS 0D
SAVE DC 18F’0’
DCBAD DCB DDNAME=DD1,DSORG=PS,EXLST=LSTA,MACRF=PM,BLKSIZE=80,RECFM=F
LSTA DS 0F RJFCB EXIT LIST
DC X’87’
DC AL3(JFCBAREA)
JFCBAREA DC 50F’0’ JFCB AREA
RECORD DC CL80’RECORD’ RECORD AREA
DS 0D
WORKAREA DC 2F’0’ WORK AREA
END
/*
* JCL FOR ALLOCATING TAPE DATA SET

Result: This excerpt from the output shows information about the tape data set
with a file sequence number of 9999:
IEC205I DD1,OCEFS001,G.STEP06,FILESEQ=09999, COMPLETE VOLUME LIST,
DSN=DS09999,VOLS=TAPE01,TOTALBLOCKS=1

Identifying Unlabeled Tapes

When you want to store a data set on unlabeled tape volumes, the system needs a
volume serial number to identify each volume. If the data set is in an automatic
tape library, the system uses the volume serial number that is encoded in the bar
code on the outside of each cartridge. If the data set is not in an automatic tape
library, it is advisable to specify enough volume serial numbers to contain the data
set. If you do not specify any volume serial numbers or do not specify enough of
them, the system or a tape management system assigns a serial number to each
unidentified volume. If the system assigns a serial number, the serial number is in
the form Lxxxyy, in which xxx is the data set sequence number and yy is the
volume sequence number for the data set.

If you want to catalog or pass data sets that reside on unlabeled volumes, specify
the volume serial numbers for the required volumes. Specifying the volume serial
numbers ensures that data sets residing on multiple volumes are not cataloged or
passed with duplicate volume serial numbers. Retrieving such data sets can give
unpredictable errors.

14 z/OS V1R7.0 DFSMS Using Data Sets

 Working with Data Sets

Using Tape Marks

A tape mark must follow each data set and data set label group. Tape marks
cannot exist within a data set. When a program writes data on a standard labeled
or unlabeled tape, the system automatically reads and writes labels and tape
marks. Two tape marks follow the last trailer label group on a standard-label
volume. On an unlabeled volume, the two tape marks appear after the last data
set.

When a program writes data on a nonstandard labeled tape, the installation must
supply routines to process labels and tape marks and to position the tape. If you
want the system to retrieve a data set, the installation routine that creates
nonstandard labels must write tape marks. Otherwise, tape marks are not required
after nonstandard labels because installation routines manage positioning of the
tape volumes.

Data Management Macros

You can use macros to process all the data set types supported by the access
methods just described. Macros control data set allocation, input and output, the
buffering techniques used, and data security. See z/OS DFSMS Macro Instructions
for Data Sets for information about data management macros. See z/OS DFSMSdfp
Advanced Services for information about system programming macros.

Table 1 contains a summary of data management access methods:

Table 1. Data Management Access Methods
Data Set Organization Access Methods
Direct BDAM
ESDS VSAM
KSDS VSAM
LDS VSAM DIV1
Partitioned2 BPAM BSAM3 QSAM
4
RRDS VSAM
5
Sequential BSAM QSAM
6 7
UNIX file BSAM QSAM7 BPAM8 VSAM9

Notes:
1. The data-in-virtual (DIV) macro, which is used to access a linear data set, is
described in z/OS MVS Programming: Assembler Services Guide.
2. PDSs and PDSEs are both partitioned organization data sets.
3. BSAM and QSAM cannot be used to create or modify user data in directory
entries.
4. Refers to fixed-length and variable-length RRDSs.
5. Sequential data sets and extended-format data sets are both sequential
organization data sets.
6. A UNIX file can be in any type of z/OS UNIX file system such as HFS, NFS,
TFS, or zFS.
7. When you access a UNIX file with BSAM or QSAM, the file is simulated as a
single-volume sequential data set.

Chapter 1. Working with Data Sets 15

Working with Data Sets

8. When you access a UNIX directory and its files with BPAM, they are simulated
as if they were a PDS or PDSE. One or more directories (with separate DD
statements) can be in a concatenation with real PDSs and PDSEs
9. When you access a UNIX file with VSAM, the file is simulated as an ESDS.

Data sets can also be organized as PDSE program libraries. PDSE program libraries
can be accessed with BSAM, QSAM, or the program management binder. The first
member written in a PDSE library determines the library type, either program or
data.

Data Set Processing

To process a data set, first allocate it (establish a link to it), then access the data
using macros for the access method that you have chosen. For information about
accessing UNIX files, see “Processing UNIX Files with an Access Method” on page
20.

Allocating Data Sets

Allocate means either or both of two things:
v To set aside (create) space for a new data set on a disk.
v To establish a logical link between a job step and any data set.

Related reading: For information about dynamic allocation, see z/OS MVS
Programming: Authorized Assembler Services Guide.

You can use any of the following methods to allocate a data set.

Access Method Services

You can define data sets and establish catalogs by using a multifunction services
program called access method services. Use the following commands with all data
sets.
Table 2. Access Method Services Commands
Command Description
ALLOCATE Allocate a new data set
ALTER Change the attributes of a data set
DEFINE NONVSAM Catalog a data set
DELETE Delete a data set
LISTCAT List catalog entries
PRINT Print a data set

ALLOCATE Command
You can issue the ALLOCATE command either through access method services or
TSO/E to define VSAM and non-VSAM data sets.

JCL
All data sets can be defined directly through JCL.

Related reading: For information about access method services commands see
z/OS DFSMS Access Method Services for Catalogs. For information about TSO
commands, see z/OS TSO/E Command Reference. For information about using JCL,
see z/OS MVS JCL Reference and z/OS MVS JCL User’s Guide.

16 z/OS V1R7.0 DFSMS Using Data Sets

 Working with Data Sets

Processing Data Sets through Programs

Programs process data sets in the following sequence:
1. Allocate the data set to establish the logical link between a program and a data
set. You can do this either outside the program with JCL or the TSO
ALLOCATE command or inside the program with dynamic allocation.
2. Open the data set, identifying it with a DDNAME.
3. Do reads and writes using an access method.
4. Close the data set.
5. Deallocate the data set. There are three ways to do this:
v For non-VSAM data sets only, specifying FREE=CLOSE when closing the
data set. (The FREE=CLOSE parameter is ignored for VSAM data sets.)
v Your program can call dynamic deallocation.
v During the step termination process, the operating system automatically
deallocates any remaining allocated data sets.

Using Access Methods

All the access methods described in this document allow you to do the following:
v Share a data set among different systems, different jobs in a single system,
multiple access method control blocks (ACBs) or data control blocks (DCBs) in a
task, or different subtasks in an address space. See Chapter 12, “Sharing VSAM
Data Sets,” on page 191 for information about sharing a VSAM data set. See
Chapter 23, “Sharing Non-VSAM Data Sets,” on page 371 for information about
sharing a non-VSAM data set.
v Share buffers and control blocks among VSAM data sets. See Chapter 13,
“Sharing Resources Among VSAM Data Sets,” on page 207.
v Provide user exit routines to analyze logical and physical errors, and to perform
end-of-data processing. See Chapter 31, “Using Non-VSAM User-Written Exit
Routines,” on page 519 and Chapter 16, “Coding VSAM User-Written Exit
Routines,” on page 241.
v Back up and recover data sets. See Chapter 4, “Backing Up and Recovering Data
Sets,” on page 45.
v Maintain data security and integrity. See Chapter 5, “Protecting Data Sets,” on
page 53.

BSAM, QSAM, BPAM, and VSAM convert between record-oriented data and
byte-stream oriented data that is stored in UNIX files.

Non-VSAM access methods also let you:

v Convert non-VSAM data from ASCII to EBCDIC, and the reverse.
v Position and reposition tape volumes automatically.
v Process user labels for data sets on DASD and magnetic tape.

Using Addressing Modes

The 24-bit and 31-bit access method interfaces use real addresses above the 2 GB
bar. When you use a 24-bit or 31-bit addressing mode, different rules apply for
VSAM programs and non-VSAM programs.

VSAM Addressing Modes

You can use either 24-bit or 31-bit addressing mode for VSAM programs. You can
issue the OPEN and CLOSE macros for any access method in 24-bit or 31-bit
addressing mode. VSAM lets you create buffers, user exits, shared resource pools,
and some control blocks in virtual storage above 16 MB. Your program must run in

Chapter 1. Working with Data Sets 17

Working with Data Sets

31-bit addressing mode to access these areas above 16 MB. See Chapter 17, “Using
31-Bit Addressing Mode with VSAM,” on page 263.

Non-VSAM Addressing Modes

You can run most BSAM, BPAM, QSAM, and BDAM macros in 24-bit or 31-bit
addressing mode. Data to which the macros refer must reside below the 16 MB line
if you run the macro in 24-bit mode.

The BSAM, BPAM, QSAM, and BDAM access methods let you create certain data
areas, buffers, certain user exits, and some control blocks in virtual storage above
the 16 MB line if you run the macro in 31-bit mode. See z/OS DFSMS Macro
Instructions for Data Sets.

Using Hiperspace and Hiperbatch

Hiperbatch can significantly reduce the execution time of batch job streams that
access QSAM or VSAM data sets. Hiperspace improves the performance for VSAM
applications that use local shared resources (LSR). Batch LSR lets you use the
advantages of Hiperspace for VSAM applications that use nonshared resources
without changing the application. See “Using Hiperbatch” on page 406 and “Using
Hiperspace Buffers with LSR” on page 208.

Processing VSAM Data Sets

There are two types of VSAM macro instructions:
v Control block macros. Generate control blocks of information that VSAM needs
to process the data set.
v Request macros. Retrieve, update, delete, or insert logical records.

VSAM has two major parts:

v Catalog management. VSAM maintains extensive information about data sets
and direct access storage space in a catalog. The catalog’s collection of
information about a particular data set defines that data set’s characteristics.
Every VSAM data set must be defined in a catalog. You cannot, for example,
load records into a VSAM data set until it has been defined. See z/OS DFSMS
Managing Catalogs for information about catalog management.
v Record management. You can use VSAM to organize records into four types of
data sets: key-sequenced, entry-sequenced, linear, or relative record. The primary
difference among these types of data sets is the way their records are stored and
accessed.

Restriction: VSAM data sets cannot be concatenated in JCL statements.

Processing PDSs, PDSEs, and UNIX Directories

The following guidelines apply to processing PDSs, PDSEs, and UNIX directories:
v Use BPAM to process the directory of a PDS, PDSE, or UNIX file.
v Each PDS or PDSE must be on one direct-access volume. However, you can
concatenate multiple input data sets that are on the same or different volumes.
v A PDSE can be used as a data library or program library, but not both. The first
member stowed in a library determines the library type.
v You can use BSAM or QSAM macros to add or retrieve PDS and PDSE members
without specifying the BLDL, FIND, or STOW macro. Code the DSORG=PS
parameter in the DCB macro, and the DDNAME parameter of the JCL DD
statement with both the data set and member names as follows:

18 z/OS V1R7.0 DFSMS Using Data Sets

 Working with Data Sets

//ddname DD DSN=LIBNAME(MEMNAME),...
v You can use BSAM or QSAM macros to add or retrieve UNIX files. The OPEN
and CLOSE macros handle data set positioning and directory maintenance. Code
the DSORG=PS parameter in the DCB macro, and the DDNAME parameter of
the JCL DD statement with a complete path and filename as follows:
//ddname DD PATH=’/dir1/dir2/file’, ...
You can then use BPAM to read files as if they were members of a PDS or PDSE.
v When you create a PDS, the SPACE parameter defines the size of the data set
and its directory so the system can allocate data set space. For a PDS, the SPACE
parameter preformats the directory. The specification of SPACE for a PDSE is
different from the specification for a PDS. See “Allocating Space for a PDSE” on
page 447.
v You can use the STOW macro to add, delete, change, or replace a member name
or alias in the PDS or PDSE directory, or clear a PDSE directory. You can also
use the STOW macro to delete all the members of a PDSE. However, you cannot
use the STOW macro to delete all the members of a PDS. For program libraries,
you cannot use STOW to add or replace a member name or alias in the
directory.
v You can read multiple members of PDSs, PDSEs, or UNIX directories by passing
a list of members to BLDL; then use the FIND macro to position to a member
before processing it.
v You can code a DCBE and use 31-bit addressing for BPAM.
v PDSs, PDSEs, members, and UNIX files cannot use sequential data striping. See
Chapter 26, “Processing a Partitioned Data Set (PDS),” on page 415 and
Chapter 27, “Processing a Partitioned Data Set Extended (PDSE),” on page 439.
Also see z/OS DFSMS Macro Instructions for Data Sets for information about
coding the DCB (BPAM) and DCBE macros.

Processing Sequential Data Sets and Members of PDSEs and

PDSs
To process a sequential data set or members of a PDS or PDSE, you can use BSAM
or QSAM. You can be in 31-bit addressing mode when issuing BSAM and QSAM
macros. Data areas can be above the 16 MB line for BSAM and QSAM macros, and
you can request that OPEN obtain buffers above the 16 MB line for QSAM. This
permits larger amounts of data to be transferred.

BSAM Processing
When you use BSAM to process a sequential data set and members of a PDS or
PDSE, the following rules apply:
v BSAM can read a member of a PDSE program library, but not write the member.
v The application program must block and unblock its own input and output
records. BSAM only reads and writes data blocks.
v The application program must manage its own input and output buffers. It must
give BSAM a buffer address with the READ macro, and it must fill its own
output buffer before issuing the WRITE macro.
v The application program must synchronize its own I/O operations by issuing a
CHECK macro for each READ and WRITE macro issued.
v BSAM lets you process blocks in a nonsequential order by repositioning with the
NOTE and POINT macros.
v You can read and write direct access storage device record keys with BSAM.
PDSEs and extended-format data sets are an exception.

Chapter 1. Working with Data Sets 19

 Working with Data Sets

v BSAM automatically updates the directory when a member of a PDS or PDSE is

added or deleted.

QSAM Processing
When you use QSAM to process a sequential data set and members of a PDS or
PDSE, the following rules apply:
v QSAM processes all record formats except blocks with keys.
v QSAM blocks and unblocks records for you automatically.
v QSAM manages all aspects of I/O buffering for you automatically. The GET
macro retrieves the next sequential logical record from the input buffer. The PUT
macro places the next sequential logical record in the output buffer.
v QSAM gives you three transmittal modes: move, locate, and data. The three
modes give you greater flexibility managing buffers and moving data.

Processing UNIX Files with an Access Method

| Examples of UNIX file systems are zSeries file system (zFS), hierarchical file system
| (HFS), Network File System (NFS), and temporary file system (TFS). You can use
| z/OS UNIX system services to access UNIX files. For more information, see z/OS
| UNIX System Services User’s Guide.

Programs can access the information in UNIX files through z/OS UNIX system
calls or through standard z/OS access methods and macro instructions. To identify
and access a data file, specify the path leading to it.

You can access a UNIX file through BSAM or QSAM (DCB DSORG=PS), BPAM
(DSORG=PO), or VSAM (simulated as an ESDS) by specifying PATH=pathname in
the JCL data definition (DD) statement, SVC 99, or TSO ALLOCATE command.

BSAM, QSAM, BPAM, and VSAM use the following types of UNIX files:
v Regular files
v Character special files
v First-in-first-out (FIFO) special files
v Hard or soft links
v Named pipes

BPAM permits read-only access to UNIX directories.

BSAM, QSAM, and VSAM do not support the following types of UNIX files:
v Directories, except BPAM, which does not support direct reading of the directory
v External links

Data can reside on a system other than the one the user program is running on
without using shared DASD. The other system can be z/OS or non-z/OS. NFS
transports the data.

Because the system stores UNIX files in a byte stream, UNIX files cannot simulate
all the characteristics of sequential data sets, partitioned data sets, or ESDSs.
Certain macros and services have incompatibilities or restrictions when they
process UNIX files. For example:
v Data set labels and unit control blocks (UCBs) do not exist for UNIX files. Any
service that relies on a DSCB or UCB for information might not work with these
files.

20 z/OS V1R7.0 DFSMS Using Data Sets

 Working with Data Sets

v With traditional MVS data sets, other than VSAM linear data sets, the system
maintains record boundaries. That is not true with byte-stream files such as
UNIX files.

Related Reading: For more information about the following topics, see:
v Chapter 28, “Processing z/OS UNIX Files,” on page 481
v “Simulated VSAM Access to UNIX files” on page 81
v For information on coding the DCB and DCBE macros for BSAM, QSAM,
BPAM, and EXCP, see z/OS DFSMS Macro Instructions for Data Sets.

Processing EXCP, EXCPVR, and XDAP Macros

It is possible to control an I/O device directly while processing a data set with
almost any data organization without using a specific access method. The EXCP
(execute channel program), EXCPVR, and XDAP macros use the system function
that provides for scheduling and queuing I/O requests, efficient use of channels
and devices, data protection, interruption procedures, error recognition, and retry.
See z/OS DFSMSdfp Advanced Services for information about the EXCP, EXCPVR,
and XDAP macros.

Guideline: Do not use the EXCP and XDAP macros to access data. These macros
cannot be used to process PDSEs, extended-format data sets, VSAM data sets,
UNIX files, dummy data sets, TSO/E terminals, spooled data sets, or OAM objects.
The use of EXCP, EXCPVR, and XDAP require detailed knowledge of channel
programs, error recovery, and physical data format. Use BSAM, QSAM, BPAM, or
VSAM instead of the EXCP and XDAP macros to access data.

Distributed Data Management (DDM) Attributes

Distributed file manager is the z/OS implementation of Systems Application
Architecture (SAA) distributed data management (DDM). Distributed file manager
facilitates access by programs running on non-z/OS systems to data sets stored on
a z/OS system. Distributed file manager allows you to use remote record and
stream access to sequential and VSAM data sets and PDSE members. DDM
attributes associated with these data sets and members can be propagated when
the data sets and members are moved or copied.

Distributed file manager creates and associates DDM attributes with data sets. The
DDM attributes describe the characteristics of the data set, such as the file size
class and last access date. The end user can determine whether a specific data set
has associated DDM attributes by using the ISMF Data Set List panel and the
IDCAMS DCOLLECT command.

Distributed file manager also provides the ability to process data sets along with
their associated attributes. Any DDM attributes associated with a data set cannot
be propagated with the data set unless DFSMShsm uses DFSMSdss as its data
mover. See z/OS DFSMS DFM Guide and Reference for information about the DDM
file attributes.

Virtual I/O for Temporary Data Sets

Temporary data sets can be handled by a function called virtual I/O (VIO). Data
sets for which VIO is specified are located in external page storage. However, to
the access methods, the data sets appear to reside on real direct access storage
devices. A VIO data set must be a non-VSAM data set; it can be sequential,

Chapter 1. Working with Data Sets 21

Working with Data Sets

partitioned, or direct, but not a PDSE or extended-format. VIO simulates a real

device and provides the following advantages:
v Elimination of some of the usual I/O device allocation and data management
overhead for temporary DASD data sets.
v Generally more efficient use of direct access storage space.

A VIO data set appears to the application program to occupy one unshared virtual
(simulated) direct access storage volume. This simulated volume is like a real
direct access storage volume except for the number of tracks and cylinders. A VIO
data set can occupy up to 65 535 tracks even if the device being simulated does not
have that many tracks.

A VIO data set always occupies a single extent (area) on the simulated device. The
size of the extent is equal to the primary space amount plus 15 times the
secondary amount (VIO data size = primary space + (15 × secondary space)). An
easy way to specify the largest possible VIO data set in JCL is SPACE=(TRK,65535).
You can set this limit lower. Specifying ALX (all extents) or MXIG (maximum
contiguous extents) on the SPACE parameter results in the largest extent allowed
on the simulated device, which can be less than 65 535 tracks.

There is no performance or resource penalty for overestimating how much space

you need unless your system’s accounting functions charge for it.

Do not allocate a VIO data set with zero space. Failure to allocate space to a VIO
data set will cause unpredictable results when reading or writing.

A summary of the effects of ALX or MXIG with VIO data sets follows.

Simulated IBM Device Number of Cylinders

3380 885
3390 1113
9345 1440

Data Set Names

When you allocate a new data set (or when the operating system does), you must
give the data set a unique name. Usually, the data set name is the dsname value in
JCL.

The following rules apply to naming data sets:

v If quotation marks delimit a data set name in a JCL DD statement, JCL
processing cannot perform syntax checking on the statement, and SMS rejects
the input based on its parsing of the data set name. SMS does not allow the
name to be catalogued because quoted data sets cannot be SMS managed.
v IDCAMS does not allow the specification of non-valid data set names.
v When you invoke Dynamic Allocation services or directly invoke SVC 26, it is
possible to create data set names that are not valid. When the CATALOG routine
is called to add the data set to a catalog, there is no way to determine whether
the original name was in JCL or whether quotation marks delimit the name. The
catalog component validates the syntax of a data set name and fails the request
if the syntax is not valid, unless the syntax-checking option for data set names is
off. See the description of the MODIFY CATALOG command’s DSNCHECK
parameter in z/OS DFSMS Managing Catalogs.

22 z/OS V1R7.0 DFSMS Using Data Sets

 Working with Data Sets

A data set name can be from one to a series of twenty-two joined name segments.
Each name segment represents a level of qualification. For example, the data set
name [Link].DATA3 is composed of three name segments. The first name on
the left is called the high-level qualifier, the last is the low-level qualifier.

Each name segment (qualifier) is 1 to 8 characters, the first of which must be

alphabetic (A to Z) or national (# @ $). The remaining seven characters are either
alphabetic, numeric (0 - 9), national, a hyphen (-). Name segments are separated by
a period (.).

Data set names must not exceed 44 characters, including all name segments and
periods.

See “Naming a Cluster” on page 104 and “Naming an Alternate Index” on page
119 for examples of naming a VSAM data set.

Restriction: The use of name segments longer than 8 characters would produce
unpredictable results.

You should use only the low-level qualifier GxxxxVyy, in which xxxx and yy are
numbers, in the names of generation data sets. Define a data set with GxxxxVyy as
the low-level qualifier of non-generation data sets only if a generation data group
with the same base name does not exist. However, IBM recommends that you
restrict GxxxxVyy qualifiers to generation data sets, to avoid confusing generation
data sets with other types of non-VSAM data sets.

For example, the following names are not valid data set names:
v A name that is longer than 8 characters ([Link])
v A name that contains two successive periods (HLQ..ABC)
v A name that ends with a period ([Link].)
v A name that contains a segment that does not start with an alphabetic or
national character ([Link])

Catalogs and Volume Table of Contents

DFSMS uses a catalog and a volume table of contents (VTOC) on each DASD to
manage the storage and placement of data sets.

VTOC
The VTOC lists the data sets that reside on its volume, along with information
about the location and size of each data set, and other data set attributes. See z/OS
DFSMSdfp Advanced Services for information about the VTOC structure.
(Application programmers usually do not need to know the contents of the VTOC.)
Also see Appendix A, “Using Direct Access Labels,” on page 561.

Catalogs
A catalog describes data set attributes and indicates the volumes on which a data
set is located. Data sets can be cataloged, uncataloged, or recataloged. All
system-managed DASD data sets are cataloged automatically in a catalog.
Cataloging of data sets on magnetic tape is not required but usually it simplifies
users jobs. All data sets can be cataloged in a catalog.

All types of data sets can be cataloged through:

v Job control language (DISP parameter)

Chapter 1. Working with Data Sets 23

Working with Data Sets

v Access method services (ALLOCATE or DEFINE commands)

v TSO ALLOCATE command
v Dynamic allocation (SVC 99) or DYNALLOC macro

Non-VSAM data sets can also be cataloged through the catalog management
macros (CATALOG and CAMLST). An existing data set can be cataloged through
the access method services DEFINE RECATALOG command.

Access method services is also used to establish aliases for data set names and to
connect user catalogs to the master catalog. See z/OS DFSMS Managing Catalogs for
information about using catalog management macros.

Data Set Names and Metadata

z/OS provides application programming interfaces (APIs), utility, and service aids
programs so that you can access the names of data sets and their metadata.
Metadata is information about data.

The APIs that access data set names include the following:
OBTAIN macro Reads a data set control block (DSCB) from a
VTOC.
CVAF macros Reads a VTOC and VTOC index. These macros are
CVAFDIR, CVAFDSM, CVAFFILT, CVAFSEQ, and
CVAFTST.
RDJFCB macro You can use the RDJFCB macro to learn the name
of a data set and the volume serial number of a
VSAM data set. You also can use RDJFCB with the
OPEN TYPE=J macro to read a VTOC. When you
use the RDJFCB macro, use a DCB and the exit list
for the DCB because using an ACB and VSAM exit
list would not work.
OPEN TYPE=J macro Can be used to open and read a VTOC. This macro
supplies a job file control block (JFCB), which
represents the information in the DD statement.
VSAM does not support OPEN TYPE=J.
LOCATE macro Locates and extracts information from catalogs.
Catalog search interface Locates and extracts information from catalogs. For
more information, see z/OS DFSMS Managing
Catalogs.

Related reading: For more information on these macros, see z/OS DFSMSdfp
Advanced Services.

The utility and service aid programs include:

ISPF A full-screen editor and dialog manager, it
generates standard screen panels and interactive
dialogues between the application programmer and
terminal user. For more information, see z/OS ISPF
User’s Guide Vol I.
ISMF Is the interactive interface of DFSMS that allows
you to access the storage management functions.

24 z/OS V1R7.0 DFSMS Using Data Sets

 Working with Data Sets

For more information, see z/OS DFSMS Using the

Interactive Storage Management Facility.
IEHLIST utility Lists entries in the directory of a PDS or PDSE, or
entries in a non-indexed or indexed VTOC. For
more information, see z/OS DFSMSdfp Utilities.
SPZAP service aid Edits data sets on a DASD. You also can use
SPZAP to apply fixes to programs to bring them
up to the current level of the operating system.
Because SPZAP can alter data sets, use Resource
Access Control Facility (RACF®) or an equivalent
security product to protect those data sets that you
do not want changed. (RACF is a component of the
z/OS Security Server.) For more information, see
z/OS MVS Diagnosis: Tools and Service Aids.

Security of Data Set Names

You can prevent unauthorized users from accessing data set names that they do
not already know. This function is called RACF name-hiding. If the user’s request
includes the fully-qualified data set name, the system does not hide the name
unless you are using ISPF 3.4 or the catalog search interface (CSI) to access the
data set. (ISPF 3.4 and CSI treat fully-qualified data set names like generic names.)
If name-hiding is in effect, you cannot access the names of protected data sets
using the programs listed in “Data Set Names and Metadata” on page 24. For more
information, see “Hiding Data Set Names” on page 55.

Chapter 1. Working with Data Sets 25

26 z/OS V1R7.0 DFSMS Using Data Sets
Chapter 2. Using the Storage Management Subsystem
This chapter covers the following topics.

Topic Location
Using Automatic Class Selection Routines 29
Allocating Data Sets 30

When you allocate or define a data set to use SMS, you specify your data set
requirements by using a data class, a storage class, and a management class.
Typically, you do not need to specify these classes because a storage administrator
has set up automatic class selection (ACS) routines to determine which classes to
use for a data set.

Descriptions of the classes follow:

v A data class is a named list of data set allocation and space attributes that SMS
assigns to a data set when it is allocated. You can also use a data class with a
non-system-managed data set.
v A storage class is a named list of data set service or performance objectives that
SMS uses to identify performance and availability requirements for data sets.
The object access method (OAM) uses storage classes to control the placement of
objects in an object storage hierarchy. Each data set has a storage class if and
only if the data set is SMS-managed.
v A management class is a named list of management attributes that DFSMShsm
uses to control action for retention, migration, backup, and release of allocated
but unused space in data sets. OAM uses management classes to control action
for the retention, backup, and class transition of objects in an object storage
hierarchy. DFSMSrmm can use the management class name assigned to a tape
data set to identify a policy which should be used to manage the data set. For
non-system-managed tape data sets, DFSMSrmm calls the management class
ACS routine. See z/OS DFSMSrmm Implementation and Customization Guide.

Your storage administrator defines the attributes of each class in an SMS

configuration. An SMS configuration is a complete set of definitions, ACS routines,
and other system information SMS uses to manage your data sets. The definitions
group data sets according to common characteristics. As you allocate new data
sets, the ACS routines assign those characteristics. With the information contained
in the SMS configuration, SMS manages your data sets most effectively with a
knowledgeable use of the available hardware. See z/OS DFSMSdfp Storage
Administration Reference for information about using SMS classes and managing
data sets and volumes.

The Storage Management Subsystem (SMS) can manage tape data sets on native
volumes in a tape library and on the logical volumes in a Virtual Tape Server
(VTS). DFSMSrmm provides some services for the stacked volumes contained in a
Virtual Tape Server. See z/OS DFSMSrmm Implementation and Customization Guide.

Some requirements for using SMS follow:

v Extended-format data sets and compressed-format data sets must be system
managed.

© Copyright IBM Corp. 1987, 2005 27

Using the Storage Management Subsystem

v SMS must be active when you allocate a new data set to be SMS managed.
v Job steps in which a JOBCAT or STEPCAT DD statement is used cannot use
system-managed data sets.
v Your storage administrator must be aware that ACS routines are used for data
sets created with distributed file manager (DFM). These data sets must be
system managed. If the storage class ACS routine does not assign a storage class,
distributed file manager deletes the just-created data set, because distributed file
manager does not create non-system-managed data sets. Distributed file
manager does, however, access non-system-managed data sets.

Table 3 lists the storage management functions and products you can use with
system-managed and non-system-managed data sets. For details, see z/OS
DFSMSdfp Storage Administration Reference.
Table 3. Data Set Activity for Non-System-Managed and System-Managed Data Sets
Activity Allocation Non-System-Managed Data System-Managed Data
Data placement JCL, storage pools ACS, storage groups
Allocation control Software user installation ACS
exits
Allocation authorization, RACF3, JCL, IDCAMS, RACF3, data class, JCL,
definition TSO/E, DYNALLOC IDCAMS, TSO/E,
DYNALLOC

Access
Access authorization RACF3 RACF3
Read/write performance, Manual placement, JCL, Management and storage
availability DFSMSdss1, DFSMShsm2 class
Access method access to Not available JCL (PATH=)
UNIX byte stream

Space Management
Backup DFSMShsm2, DFSMSdss1, Management class
utilities
Expiration JCL Management class
Release unused space DFSMSdss1, JCL Management class, JCL
Deletion DFSMShsm2, JCL, utilities Management class, JCL
Migration DFSMShsm2 Data and management class,
JCL
Notes:
1. DFSMSdss: Moves data (dump, restore, copy, and move) between volumes on DASD
devices, manages space, and converts data sets or volumes to SMS control. See z/OS
DFSMSdss Storage Administration Guide for information about using DFSMSdss.
2. DFSMShsm: Manages space, migrates data, and backs up data through SMS classes and
groups. See z/OS DFSMShsm Managing Your Own Data for information about using
DFSMShsm.
3. RACF: Controls access to data sets and use of system facilities.

The following types of data sets cannot be system managed:

v Data sets having the same name as an already cataloged data set
v DASD data sets not cataloged

28 z/OS V1R7.0 DFSMS Using Data Sets

 Using the Storage Management Subsystem

v Unmovable data sets (DSORG is xxU) except when set by a checkpoint function
v Data sets with absolute track allocations (ABSTR value for SPACE parameter on
DD statement)
v Tape data sets
v Spooled data sets

Direct data sets (BDAM) can be system-managed but if a program uses OPTCD=A,
the program might become dependent on where the data set is on the disk. For
example, the program might record the cylinder and head numbers in a data set.
Such a data set should not be migrated or moved. You can specify a management
class that prevents automatic migration.

Tape volumes in a system-managed tape library can be managed as

system-managed storage classes.

Using Automatic Class Selection Routines

ACS routines determine if a data set is system managed and which classes are to
be used.

You can use a storage class and a management class only with system-managed
data sets. You can use a data class for data sets that are either system managed or
not system managed, and for data sets on either DASD or tape volumes. SMS can
manage tape data sets on physical volumes in a tape library and on the logical
volumes in a Virtual Tape Server (VTS). DFSMSrmm provides some services for
the stacked volumes contained in a Virtual Tape Server (see z/OS DFSMSrmm
Implementation and Customization Guide). Your storage administrator defines the data
classes, storage classes, and management classes your installation will use. Your
storage administrator provides a description of each named class, including when
to use the class.

Recommendation: Your storage administrator must code storage class ACS

routines to ensure data sets allocated by remote applications using distributed file
management are system managed.

Using a data class, you can easily allocate data sets without specifying all of the
data set attributes normally required. Your storage administrator can define
standard data set attributes and use them to create data classes, for use when you
allocate your data set. For example, your storage administrator might define a data
class for data sets whose names end in LIST and OUTLIST because they have
similar allocation attributes. The ACS routines can then be used to assign this data
class, if the data set names end in LIST or OUTLIST.

You can request a data class explicitly, by specifying it in the DD statement,

DYNALLOC macro, the TSO or IDCAMS ALLOCATE command, or the DEFINE
CLUSTER command. Request a data class implicitly, by not specifying a data class
and letting the ACS routines assign the data class defined by your storage
administrator. Whichever method is used, you need to know:
v The data set characteristics
v The data class that describes what this data set looks like
v Whether the ACS routines will pick this data class automatically
v Which characteristics to code in the JCL to override the data class attributes
You can override any of the attributes specified in the assigned data class by
specifying the values in the DD statement, or the ALLOCATE or the DEFINE
CLUSTER commands. See z/OS DFSMS Access Method Services for Catalogs

Chapter 2. Using the Storage Management Subsystem 29

 Using the Storage Management Subsystem

(ALLOCATE and DEFINE CLUSTER command sections) for information about the
attributes that can be assigned through the SMS class parameters, and examples of
defining data sets.

Another way to allocate a data set without specifying all of the data set attributes
normally required is to model the data set after an existing data set. You can do
this by referring to the existing data set in the DD statement for the new data set,
using the JCL keywords LIKE or REFDD. See z/OS MVS JCL Reference and z/OS
MVS JCL User’s Guide.

Allocating Data Sets

Allocation has two related meanings:
1. Setting aside DASD space for a new data set.
2. Connecting a program to a new or existing data set or to a device.
The program can then use the DD name to issue an OPEN macro and use an
access method to read or write data.

| In this book we often use the term “creation” to refer to the first meaning of
| “allocation” although creation often includes the meaning of writing data into the
| data set.

To allocate a new data set on DASD, you can use any of the following methods:
v JCL DD statements. See z/OS MVS JCL Reference.
v Access method services ALLOCATE command or DEFINE command. See z/OS
DFSMS Access Method Services for Catalogs for the syntax and more examples.
v TSO ALLOCATE command. See z/OS TSO/E Command Reference for the syntax
and more examples.
v DYNALLOC macro using the SVC 99 parameter list. See z/OS MVS
Programming: Authorized Assembler Services Guide.

There are two ways to cause a new data set to be system-managed:

v Specify the SMS parameter STORCLAS explicitly. You can also specify
MGMTCLAS and DATACLAS.
v Let the ACS routines assign the SMS classes to the data set.

To allocate non-system-managed data sets, you can specify the DATACLAS

parameter. Do not specify the MGMTCLAS and STORCLAS parameters.

Allocating Data Sets with JCL

To allocate a new data set using JCL, specify DISP=(NEW,CATLG,DELETE). If the
application program completes normally, the data set is cataloged, but if the
application program fails, the data set is deleted. All system-managed data sets are
automatically cataloged, even if you use a disposition of KEEP.

To update an existing data set, specify a DISP value of OLD, MOD, or SHR. Do
not use DISP=SHR while updating a sequential data set unless you have some
other means of serialization because you might lose data.

To share a data set during access, specify a DISP value of SHR. If a DISP value of
NEW, OLD, or MOD is specified, the data set cannot be shared.

30 z/OS V1R7.0 DFSMS Using Data Sets

 Using the Storage Management Subsystem

Tip: If SMS is active and a new data set is a type that SMS can manage, it is
impossible to determine if the data set will be system-managed based solely on the
JCL because an ACS routine can assign a storage class to any data set.

Allocating an HFS Data Set

An HFS data set is allocated if the DSNTYPE value is HFS and the SPACE
parameter specifies the number of directory blocks, in either JCL or the data class.
You must specify the number of directory blocks for an HFS data set, but the value
has no effect on allocation.

Related reading: For more information, see “Using HFS Data Sets” on page 483.

Allocating System-Managed Data Sets

Allocating a new data set under SMS, using the ACS routines defined by your
storage administrator, is easier than without SMS. With SMS it is unnecessary to
specify the UNIT, VOL=SER, SPACE, or the DCB parameters in the DD statement.
For this allocation to succeed, the ACS routines must select a data class that
defines the space and data set attributes required by the application.

You can request the name of the data class, storage class, and management class in
the JCL DD statement. However, in most cases, the ACS routines pick the classes
needed for the data set.

Allocating a PDSE. The DSNTYPE parameter determines if the data set is

allocated as a PDSE or as a PDS. A DSNTYPE of LIBRARY causes the data set to
be a PDSE. The DSNTYPE parameter can be specified in the JCL DD statement, the
data class, or the system default, or by using the JCL LIKE keyword to refer to an
existing PDSE.

If the SPACE parameter is omitted in the DD statement, it must be supplied by the

data class. You can omit STORCLAS and DATACLAS in the DD statement if the
default storage class and data class contain the data set attributes you want. A
PDSE also can be allocated using access method services.

When first allocated, the PDSE is neither a program library or a data library. If the
first member written, by either the binder or by IEBCOPY, is a program object, the
library becomes a program library and remains such until the last member has
been deleted. If the first member written is not a program object, then the PDSE
becomes a data library. Program objects and other types of data cannot be mixed in
the same PDSE library.

Allocating an Extended-Format Data Set. Extended format data sets must be

system-managed. The mechanism for requesting extended format is through the
SMS data class DSNTYPE=EXT parameter and subparameters R (required) or P
(preferred). The storage administrator can specify R to ensure the data set is
extended. Then, for VSAM data sets the storage administrator can set the extended
addressability attribute to Y to request extended addressability.

In addition to a DSNTYPE of EXTENDED, COMPACTION=YES in a data class

definition must be specified if you want to request allocation of an extended
format data set in the compressed format. A compressed data set can be created
using the LIKE keyword on the DD statement and not just through a data class.

| Allocating a Large Format Data Set. Large format data sets are sequential data
| sets that can grow beyond 65 535 tracks (4369 cylinders) per volume. Large format
| data sets can be system-managed or not. You can allocate a large format data set

Chapter 2. Using the Storage Management Subsystem 31

 Using the Storage Management Subsystem

| using the DSNTYPE=LARGE parameter on the DD statement, dynamic allocation

| (SVC 99), TSO/E ALLOCATE, or the access method services ALLOCATE
| command. The SMS data class can also provide the DSNTYPE value of LARGE, if
| the data set does not have another DSNTYPE specified or a DSORG value other
| than PS or PSU.

| Allocating a Basic Format Data Set. Basic format data sets are sequential data sets
| that are specified as neither extended format nor large format. Basic format data
| sets have a size limit of 65 535 tracks (4369 cylinders) per volume. Basic format
| data sets can be system-managed or not. You can allocate a basic format data set
| using the DSNTYPE=BASIC parameter on the DD statement, dynamic allocation
| (SVC 99), TSO/E ALLOCATE or the access method services ALLOCATE command,
| or the data class. If no DSNTYPE value is specified from any of these sources, then
| its default is BASIC.

| Note: The data class cannot contain a DSNTYPE of BASIC; leave DSNTYPE blank
| to get BASIC as the default value.

Allocating a VSAM Data Set. See Chapter 18, “Using Job Control Language for
VSAM,” on page 265 for information about allocating VSAM data sets using JCL.

Allocating Non-System-Managed Data Sets

If your installation is running SMS, you can use a data class with a
non-system-managed data set, such as a tape data set. The DCB information
defined in the data class is used as the default. If you do not use a data class, you
need to supply in the JCL, or in the program, the DCB information such as LRECL
and RECFM, and the DSORG. You cannot use data class if your installation is not
running SMS.

Allocating System-Managed Data Sets with the Access Method

Services ALLOCATE Command
The examples in the following sections show you how to allocate a new data set to
the job step using the access method services ALLOCATE command. See z/OS
DFSMS Access Method Services for Catalogs (ALLOCATE section).

Allocating a Data Set Using Class Specifications

In the following example, the ALLOCATE command is used to allocate a new data
set using the SMS classes. SMS must be active. The data set can be VSAM or
non-VSAM.
//ALLOC JOB ...
//STEP1 EXEC PGM=IDCAMS,DYNAMNBR=1
//SYSPRINT DD SYSOUT=A
//SYSIN DD *
ALLOC -
DSNAME([Link].EXAMP1) -
NEW CATALOG -
DATACLAS(STANDARD) -
STORCLAS(FAST) -
MGMTCLAS(VSAM)
/*

The command parameters follow:

v DSNAME specifies the name of the data set being allocated is
[Link].EXAMP1.
v NEW specifies the data set being allocated is new.

32 z/OS V1R7.0 DFSMS Using Data Sets

 Using the Storage Management Subsystem

Allocating a VSAM Data Set Using Class Specifications

The following example uses the ALLOCATE command to allocate a new VSAM
data set. Data class is not assigned, and attributes assigned through the default
data class will be overridden by explicitly specified parameters:
//ALLOC JOB ...
//STEP1 EXEC PGM=IDCAMS,DYNAMNBR=1
//SYSPRINT DD SYSOUT=A
//SYSIN DD *
ALLOC -
DSNAME([Link].EXAMP2) -
NEW CATALOG -
SPACE(10,2) -
AVBLOCK(80) -
AVGREC(K) -
LRECL(80) -
RECORG(ES) -
STORCLAS(FAST) -
MGMTCLAS(VSAM)
/*

Allocating a System-Managed Non-VSAM Data Set

The following example uses the ALLOCATE command to allocate a non-VSAM
data set. ALLOCATE, unlike DEFINE NONVSAM, lets you specify the SMS classes
for a non-VSAM data set:
//ALLOC JOB ...
//STEP1 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=A
//SYSABEND DD SYSOUT=A
//SYSIN DD *
ALLOC -
DSNAME([Link]) -
NEW -
DATACLAS(PS000000) -
MGMTCLAS(S1P01M01) -
STORCLAS(S1P01S01)
/*

Allocating a PDSE
The following example shows the ALLOCATE command used with the DSNTYPE
keyword to create a PDSE. DSNTYPE(LIBRARY) indicates the data set being
allocated is a PDSE.
//ALLOC EXEC PGM=IDCAMS,DYNAMNBR=1
//SYSPRINT DD SYSOUT=A
//SYSIN DD *
ALLOC -
DSNAME([Link].EXAMPLE1) -
NEW -
STORCLAS(SC06) -
MGMTCLAS(MC06) -
DSNTYPE(LIBRARY)
/*

Allocating a New Non-System-Managed Data Set

The following example uses the ALLOCATE command to allocate a new data set:
//ALLOC JOB ...
//STEP1 EXEC PGM=IDCAMS,DYNAMNBR=1
//SYSPRINT DD SYSOUT=A
//SYSIN DD *
ALLOC -
DSNAME([Link].EXAMP3) -
NEW CATALOG -
SPACE(10,5) TRACKS -

Chapter 2. Using the Storage Management Subsystem 33

Using the Storage Management Subsystem

BLKSIZE(1000) -
LRECL(100) -
DSORG(PS) -
UNIT(3380) -
VOL(338002) -
RECFM(F,B)
/*

Allocating Data Sets with the TSO ALLOCATE Command

The following example allocates a new sequential data set with space allocated in
tracks:
ALLOC DA([Link]) DSORG(PS) SPACE(2,0) TRACKS LRECL(80) RECFM(F,B) NEW

The new data set name: [Link]

The number of tracks: 2
The logical record length: 80
The block size: determined by the system
The record format: fixed block

You do not have to specify the user ID, GOLD, as an explicit qualifier. Because the
BLKSIZE parameter is omitted, the system determines a block size that optimizes
space usage.

The following example allocates a new VSAM entry-sequenced data set, with a
logical record length of 80, a block size of 8000, on two tracks. To allocate a VSAM
data set, specify the RECORG keyword on the ALLOCATE command. RECORG is
mutually exclusive with DSORG and with RECFM. To allocate a key-sequenced
data set, you also must specify the KEYLEN parameter. RECORG specifies the type
of data set you want.
ALLOC DA([Link]) RECORG(ES) SPACE(2,0) TRACKS LRECL(80)
BLKSIZE(8192) NEW

ES—Entry-sequenced data set

KS—Key-sequenced data set
LS—Linear data set
RR—Relative record data set

Allocating Data Sets with Dynamic Allocation

See z/OS MVS Programming: Authorized Assembler Services Guide for examples of
allocating a data set using the DYNALLOC macro. To allocate a VSAM data set
using the DYNALLOC macro with the SVC 99 parameter list, specify text unit
800B - RECORG.

34 z/OS V1R7.0 DFSMS Using Data Sets

Chapter 3. Allocating Space on Direct Access Volumes
This chapter covers the following topics.

Topic Location
Specification of Space Requirements 35
Maximum Data Set Size 37
Primary and Secondary Space Allocation without the Guaranteed Space 38
Attribute
Allocation of Data Sets with the Guaranteed Space Attribute 40
Allocation of Data Sets with the Space Constraint Relief Attributes 41
Extension to Another DASD Volume 42
Multiple Volume Considerations for Sequential Data Sets 44
Additional Information on Space Allocation 44

Specification of Space Requirements

You can specify the amount of space required in blocks, records, tracks, or
cylinders. When creating a DASD data set, specify the amount of space needed
explicitly by using the SPACE parameter, or specify the amount of space implicitly
by using the information available in a data class. The data class is not used if SMS
is inactive at the time of your allocation.

The system can use a data class if SMS is active even if the data set is not SMS
managed. For system-managed data sets, the system selects the volumes.
Therefore, you do not need to specify a volume when you define your data set.

If you specify your space request by average record length, space allocation is
independent of device type. Device independence is especially important to
system-managed storage.

Blocks
When the amount of space required is expressed in blocks, you must specify the
number and average length of the blocks within the data set, as in this example:
// DD SPACE=(300,(5000,100)), ...

300 = average block length in bytes

5000 = primary quantity (number of blocks)
100 = secondary quantity, to be allocated if the primary
quantity is not enough (in blocks)

From this information, the operating system estimates and allocates the number of
tracks required.

The system uses this block length value only to calculate space. This value does
not have to be the same as the BLKSIZE value. If the data set is extended format,
the system adds 32 to this value when calculating space.

© Copyright IBM Corp. 1987, 2005 35

Allocating Space on Direct Access Volume

Recommendation: For sequential and partitioned data sets, let the system calculate
the block size instead of requesting space by average block length. See
“System-Determined Block Size” on page 329.

If the average block length of the real data does not match the value coded here,
the system might allocate much too little or much too much space.

Average Record Length

When the amount of space required is expressed in average record length, you
must specify the number of records within the data set and their average length.
Use the AVGREC keyword to modify the scale of your request. When AVGREC is
specified, the first subparameter of SPACE becomes the average record length. The
system applies the scale value to the primary and secondary quantities specified
for the SPACE keyword. Possible values for the AVGREC keyword follow:

U—Use a scale of 1
K—Use a scale of 1024
M—Use a scale of 1048576

When the AVGREC keyword is specified, the values specified for primary and
secondary quantities in the SPACE keyword are multiplied by the scale and those
new values will be used in the space allocation. For example, the following request
results in the primary and secondary quantities being multiplied by 1024:
// DD SPACE=(80,(20,2)),AVGREC=K, ...

80 = average record length in bytes

80 * 20 * 1024 = 1.6 MB = primary space
80 * 2 * 1024 = 160 KB = secondary space, to be allocated if the
primary space is not enough

From this information, the operating system estimates and allocates the number of
tracks required using one of the following block lengths, in the order indicated:
1. 4096, if the data set is a PDSE.
2. The BLKSIZE parameter on the DD statement or the BLKSIZE subparameter of
the DCB parameter on the DD.
3. The system determined block size, if available.
4. A default value of 4096.

For an extended-format data set, the operating system uses a value 32 larger than
the above block size. The primary and secondary space are divided by the block
length to determine the number of blocks requested. The operating system
determines how many blocks of the block length can be written on one track of the
device. The primary and secondary space in blocks is then divided by the number
of blocks per track to obtain a track value, as shown in the examples below. These
examples assume a block length of 23200. Two blocks of block length 23200 can be
written on a 3380 device:
(1.6MB / 23200) / 2 = 36 = primary space in tracks
(160KB / 23200) / 2 = 4 = secondary space in tracks

In the preceding calculations, the system does not consider if it is a compressed

format data set. This means the calculation is done with the user-perceived
uncompressed block size and not the actual block size that the system calculates.

Tracks or Cylinders
The following example shows the amount of space required in tracks or cylinders:

36 z/OS V1R7.0 DFSMS Using Data Sets

 Allocating Space on Direct Access Volume

// DD SPACE=(TRK,(100,5)), ...
// DD SPACE=(CYL,(3,1)), ...

Absolute Track
If the data set contains location-dependent information in the form of an actual
track address (such as MBBCCHHR or CCHHR), you can request space in the number of
tracks and the beginning address. In this example, 500 tracks is required, beginning
at relative track 15, which is cylinder 1, track 0:
// DD SPACE=(ABSTR,(500,15)),UNIT=3380, ...

Restriction: Data sets that request space by absolute track are not eligible to be
system managed and they interfere with DASD space management done by the
space management products and the storage administrator. Avoid using absolute
track allocation.

Additional Space-Allocation Options

The DD statement provides flexibility in specifying space requirements. See z/OS
MVS JCL Reference about option information.

Maximum Data Set Size

This section contains information about the following maximum amounts for data
sets:
v Maximum size on one volume
v Maximum number of volumes
v Maximum size for a VSAM data set

Maximum Size on One Volume

Many types of data sets are limited to 65 535 total tracks allocated on any one
volume, and if a greater number of tracks is required, this attempt to create a data
set will fail.

Data sets that are not limited to 65 535 total tracks allocated on any one volume
are:
| v Large format sequential
v Extended-format sequential
v UNIX files
v PDSE
v VSAM

If a virtual input-output (VIO) data set is to be SMS managed, the VIO maximum
size is 2 000 000 KB, as defined in the Storage Group VIO Maxsize parameter.

Maximum Number of Volumes

PDS and PDSE data sets are limited to one volume. All other DASD data sets are
limited to 59 volumes. A data set on a VIO simulated device is limited to 65 535
tracks and is limited to one volume. Tape data sets are limited to 255 volumes.

| A multivolume direct (BDAM) data set is limited to 255 extents across all volumes.
| The system currently does not enforce this limit when creating the data set.

Chapter 3. Allocating Space on Direct Access Volumes 37

 Allocating Space on Direct Access Volume

Maximum VSAM Data Set Size

A VSAM data set is limited to 4 GB across all volumes unless Extended
Addressability is specified in the SMS data class definition. System requirements
restrict the number of volumes that can be used for one data set to 59.

| Using extended addressability, the size limit for a VSAM data set is determined by
| either:
| v Control interval size multiplied by 4 GB
| v The volume size multiplied by 59.
| A control interval size of 4 KB yields a maximum data set size of 16 TB, while a
| control interval size of 32 KB yields a maximum data set size of 128 TB. A control
| interval size of 4 KB is preferred by many applications for performance reasons.
| No increase in processing time is expected for extended format data sets that grow
| beyond 4 GB. To use extended addressability, the data set must be:
| v SMS-managed
| v Defined as extended format.

| Minimum data set size

| The minimum size for any type of sequential data set that contains data is one
| track, which is about 56 000 bytes. You can create a data set that has no space. The
| purpose for such a data set might be to serve as a model for data set attributes
| with the LIKE parameter on DD statements. Another purpose might be to allow
| reading before the data set contains data. For example you might give the data set
| a secondary space amount such as with SPACE=(CYL,(0,5)).

Primary and Secondary Space Allocation without the Guaranteed

Space Attribute
Space is allocated for non-system-managed data sets or system-managed data sets
without the guaranteed space attribute in the storage class as follows. If you
allocate a new data set and specify SPACE=(TRK,(2,4)); this initially allocates two
tracks for the data set. As each record is written to the data set and these two
tracks are used up, the system automatically obtains four more tracks. When these
four tracks are used, another four tracks are obtained. The same sequence is
followed until the extent limit for the type of data set is reached.
v A sequential data set can have 16 extents on each volume.
v An extended-format sequential data set can have 123 extents per volume.
v A PDS can have 16 extents.
v A direct data set can have 16 extents on each volume.
| v A non-system-managed VSAM data set can have up to 255 extents per
| component. System-managed VSAM data sets can have this limit removed if the
| associated data class has extent constraint removal specified.
| v A striped VSAM data set that is not system-managed can have up to 255 extents
| per stripe. Striped VSAM data sets that are system-managed can have this limit
| removed if the associated data class has extent constraint removal specified.
v A PDSE can have 123 extents.
v An HFS data set can have 123 extents on each volume.
You can allocate space for a multivolume data set the same as for a single volume
data set. DASD space is initially allocated on the first volume only (exceptions are
striped extended-format data sets and guaranteed space data sets). When the

38 z/OS V1R7.0 DFSMS Using Data Sets

 Allocating Space on Direct Access Volume

primary allocation of space is filled, space is allocated in secondary storage

amounts (if specified). The extents can be allocated on other volumes. VIO space
allocation is handled differently from other data sets. See “Virtual I/O for
Temporary Data Sets” on page 21.

Multivolume VSAM Data Sets

When a multivolume VSAM data set extends to the next volume, the data class
specifies if the initial space allocated on that volume is the primary or secondary
amount. The default is the primary amount. After the primary amount of space is
used up, space is allocated in secondary amounts. By using a data class, it is
possible to indicate whether to take a primary or secondary amount when VSAM
extends to a new volume. The previous comments do not pertain to VSAM data
that is striped. See Chapter 6, “Organizing VSAM Data Sets,” on page 73 about
VSAM data in the striped format.

Multivolume Non-VSAM Data Sets

When a multivolume non-VSAM, non-extended-format data set extends to the next
volume, the initial space allocated on that volume is the secondary amount.

Extended-Format Data Sets

When space for a striped extended-format data set is allocated, the system divides
the primary amount among the volumes. If it does not divide evenly, the system
rounds the amount up. For extended-format data sets, when the primary space on
any volume is filled, the system allocates space on that volume. The amount is the
secondary amount divided by the number of stripes. If the secondary amount
cannot be divided evenly, the system rounds up the amount.

Data sets allocated in the extended-format achieve the added benefits of improved
error detection when writing to DASD as well as the use of a more efficient and
functionally complete interface to the I/O subsystem.

Table 4 shows how stripes for an extended-format sequential data set are different
from stripes for an extended-format VSAM data set.
Table 4. Differences Between Stripes in Sequential and VSAM Data Sets
Sequential Extended-Format Striped VSAM Extended-Format Striped
The data set can have a maximum of 59 stripes. The data set can have a maximum of 16
stripes.
Each stripe must reside on one volume and Each stripe can reside on one or more
cannot be extended to another volume. volumes. There is no advantage to
increasing the number of stripes for
VSAM to be able to acquire additional
space. When extending a stripe to a new
volume, the system derives the amount of
the first space allocated according to the
Additional Volume Amount in the data
class. This space derived from the
primary or secondary space. The default
value is the primary space amount.
After the system fills a track, it writes the After the system writes a control interval
following blocks on a track in the next stripe. (CI), it writes the next CI on a track in the
next stripe. A CI cannot span stripes.
You can use the BSAM and QSAM access You can use the VSAM access method.
methods.

Chapter 3. Allocating Space on Direct Access Volumes 39

Allocating Space on Direct Access Volume

Allocation of Data Sets with the Guaranteed Space Attribute

You can allocate space and load a guaranteed space data set in one step or in
separate steps.

Guaranteed Space with DISP=NEW or MOD

When you code DISP=NEW or DISP=MOD, space is allocated to system-managed
multivolume (non-extended-format) data sets with the guaranteed space attribute
in the storage class, as follows:
1. Initially, primary space is preallocated on all the volumes.
2. When the primary amount on the first volume is used up, a secondary amount
is allocated on the first volume until the volume is out of space or the data set
has reached its extent limit.
3. The preallocated primary space on the next volume is then used.
4. When the primary space on the next volume is used up, a secondary amount is
allocated.
5. Secondary amounts continue to be allocated until the volume is out of space or
the data set extent limit is reached.

All succeeding volumes follow the same sequence.

Guaranteed Space for VSAM

For nonstriped VSAM data sets, space is allocated to system-managed multivolume
data sets with the guaranteed space attribute in the storage class, as follows:
v Initially, primary space is preallocated on all the volumes.
v When the primary amount on the first volume is used up, a secondary amount
is allocated on the first volume until the volume is out of space or the data set
has reached its extent limit.
v The preallocated primary space on the next volume is then used.
v When the primary space on the next volume is used up, a secondary amount is
allocated.
v Secondary amounts continue to be allocated until the volume is out of space or
the data set extent limit is reached. For a non-EA data set, if the extend fails, the
system attemps to extend to a new volume by the primary amount.

All succeeding volumes follow the same sequence.

Guaranteed Space with DISP=OLD or SHR

When you code DISP=OLD or DISP=SHR, space is allocated to system-managed
multivolume (non-extended-format) data sets with the guaranteed space attribute
in the storage class, as follows:
1. Initially, the system preallocated primary space on all the volumes when you
coded DISP=NEW.
2. When the allocated space on each volume is used up, the system switches to
the next volume. Some volumes might already have secondary space
allocations because you extended the data set when you coded DISP=NEW or
DISP=MOD earlier. The system will use those secondary allocations.
3. The existing space on the next volume is then used.

40 z/OS V1R7.0 DFSMS Using Data Sets

 Allocating Space on Direct Access Volume

4. The system will attempt to allocate new space only on the last volume. On
that volume secondary amounts continue to be allocated until the volume is
out of space or the data set extent limit is reached.

The system works this way so that it is similar to nonguaranteed preallocated

space on non-SMS volumes.

Guaranteed Space with Extended-Format Data Sets

When guaranteed space is specified for a multivolume extended-format sequential
data set, the primary space is preallocated on all the volumes. Because data is
written to an extended-format data set using data striping (logically consecutive
tracks or CIs are written to the data set in a circular manner), secondary space is
not allocated until the preallocated primary space on all volumes is used up. For a
striped VSAM data set with guaranteed space that has more than 16 volumes, only
the first 16 volumes have preallocated space. The secondary amount specified is
divided by the number of volumes and rounded up for allocation on each volume.

The amount of preallocated space for VSAM striped data is limited to 16 volumes.

Guaranteed Space Example

The following example allocates 100 MB of primary space on each of five volumes:
//DD1 DD DSN=[Link],DISP=(,KEEP),STORCLAS=GS,
// SPACE=(1,(100,25)),AVGREC=M,UNIT=(3380,5)
1. After 100 MB is used on the first volume, 25 MB extents of secondary space is
allocated on it until the extent limit is reached or the volume is full. The system
assumes DISP=NEW because the user omitted the first DISP value.
2. If more space is needed, the 100 MB of preallocated primary space is used on
the second volume. Then, more secondary space is allocated on that volume.
3. The same process is repeated on each volume.

Allocation of Data Sets with the Space Constraint Relief Attributes

To reduce allocation failures, three data class attributes can influence the allocation
and extension of data sets to new volumes. Allocations that might have failed for
lack of space can succeed.

These three attributes follow:

v Space Constraint Relief (values are YES or NO)
v Reduce Space Up To % (0 - 99%)
v Dynamic Volume Count (1 - 59 or blank)

Allocations and extends to new volumes proceed normally until space cannot be
obtained by normal means.

The system performs space constraint relief in two situations: when a new data set
is allocated and when a data set is extended to a new volume. During EOV
processing, space constraint relief affects the primary or secondary allocation
amount for VSAM data sets, or the secondary allocation amount for non-VSAM
data sets. During CREATE processing, the primary quantity might be reduced for
both non-VSAM and VSAM data sets.

Exception: The system does not use space constraint relief when data sets are
extended on the same volume.

Chapter 3. Allocating Space on Direct Access Volumes 41

 Allocating Space on Direct Access Volume

Space constraint relief, if requested, occurs in one or two methods, depending on

the volume count that you specified for the failing allocation.
1. If the volume count is greater than 1, SMS attempts to satisfy the allocation by
spreading the requested primary allocation over more than one volume, but no
more than the volume count specified.
2. If method 1 also fails or if the volume count is 1, SMS modifies the requested
primary space or the secondary space for extension, by the percentage that you
specified in the REDUCE SPACE UP TO parameter.

The allocation fails as before if either or both methods 1 and 2 are not successful.

Recommendation: You can specify 0% in the data class for this parameter so space
is not reduced.

SMS removes the 5-extent-at-a-time limit. (For example, sequential data sets can
have a maximum of 16 extents.) Without this change, the system tries to satisfy
your primary or secondary space request with no more than five extents. If you
request a large amount of space or the space is fragmented, the system might need
more than five extents.

Restriction: VSAM and non-VSAM multistriped data sets do not support space
constraint relief. However, single-striped VSAM and non-VSAM data sets use
space constraint relief.

Extension to Another DASD Volume

The system attempts to extend to another DASD volume if all of the following
conditions exist:
v The current volume does not have the secondary space amount available, or the
data set reached the extent limit for that type of data set, or the application
program issued the FEOV macro.
v The volume count has not yet been reached. For a system-managed data set, the
volume count was determined when the data set was created (DISP=NEW) and
is the largest of the volume count (VOL=(,,,nn)), the number of volumes coded
with the VOL parameter, and the unit count (UNIT=(xxxx,nn)).
For either system-managed or non-system-managed data sets, the volume count
can come from the data class. The volume count can be increased after data set
creation with the IDCAMS ADDVOL command.
v The dynamic volume count has not been reached for a system-managed data set.
You can define the Space Constraint Relief and Dynamic Volume Count
attributes in the data class. If Space Constraint Relief=YES, you can specify a
dynamic volume count from 1 to 59 for SMS to extend a data set automatically
to another volume or volumes. For more information, see z/OS DFSMSdfp
Storage Administration Reference.
v A secondary allocation amount is available. This can come from the data class
when the data set was created even if the data set is not system managed. When
the data set is created with DISP=NEW or IDCAMS DEFINE, the secondary
amount permanently overrides data class for the data set. For a non-VSAM data
set the above two sources of the secondary amount can be overridden
temporarily with DISP other than NEW.

| Note: After a multivolume data set is unable to extend on the current volume and
| the data set is extended to a new volume, then all previous volumes can no
| longer be selected for future extensions.

42 z/OS V1R7.0 DFSMS Using Data Sets

 Allocating Space on Direct Access Volume

Examples of Dynamic Volume Count When Defining a Data Set

These examples are of using the Volume Count attribute from the data class or
volume count information from a JCL, TSO, or IDCAMS command. Using the
dynamic volume count causes the number of primary volumes to increase, if
necessary. The use of dynamic volume count does not add any candidate volumes
to the catalog:
1. Example 1:
Volume count: 6
Dynamic volume count: 0
Required volumes: 1
Volumes in catalog: 1 primary, 5 candidates
2. Example 2:
Volume count: 6
Dynamic volume count: 12
Required volumes: 1
Volumes in catalog: 1 primary, 5 candidates
3. Example 3:
Volume Count: 6
Dynamic volume count: 12
Required volumes: 7
Volumes in catalog: 7 primary, 0 candidates
4. Example 4:
Volume count: 6
Dynamic volume count: 12
Required volumes: 13
Volumes in catalog: None; request fails

In example 2, although the catalog contains only five candidate volumes, the data
set can be extended to 11 candidate volumes, including the primary volume.

Examples of Dynamic Volume Count When Allocating an

Existing Data Set
In the following examples, a list of specific volumes is returned to allocation, and a
count of nonspecific volumes. Also, the allocation in Example 7 fails because the
total volume count exceeds the limit of 59 volumes.
1. Example 5: VSAM KSDS
Specific volume count: 2
Nonspecific volume count: 4
Cluster dynamic volume count: 20
Specific volumes returned to allocation: 2
Nonspecific volumes returned to allocation: 18
Total count of volumes returned to allocation: 20
2. Example 6: VSAM Path
Specific volume count (base cluster): 5
Nonspecific volume count (base cluster): 1
Specific and total volume count (alternate index): 1
Base cluster dynamic volume count: 20
Specific volumes returned to allocation: 6
Nonspecific volumes returned to allocation: 15
Total count of volumes returned to allocation: 21
3. Example 7: Alternate Indexes in Upgrade Set
Specific and total volume count (base cluster): 5
Specific and total volume count (first alternate index): 1
Specific and total volume count (second alternate index): 1
Base cluster dynamic volume count: 59

Chapter 3. Allocating Space on Direct Access Volumes 43

 Allocating Space on Direct Access Volume

Specific volumes returned to allocation: 7

Nonspecific volumes returned to allocation: 54
Total count of volumes returned to allocation: 61

Multiple Volume Considerations for Sequential Data Sets

Consider the following when working with multiple volumes: Your program is
extending a sequential data set if it uses the EXTEND or OUTINX option of OPEN
or it uses the OUTPUT or OUTIN option of OPEN with DISP=MOD on the DD
statement. If you plan to rewrite a multivolume sequential data set that is not SMS
managed, and you might later extend the data set, you should delete and
reallocate the data set. This avoids the problems described in item 2 below and the
system will extend on the volume that you want.
1. When writing to a sequential data set, EOV turns off the last volume bit as it
finishes each volume and CLOSE turns on the last volume bit in the DSCB on
the current volume. It identifies the last volume containing data, not necessarily
the last volume allocated to the data set. The DSCB on a later volume can also
have this bit on, either due to earlier writings or due to guaranteed space.
2. Writing with the DISP=MOD, OPEN EXTEND, or OUTINX option works
differently with system-managed and non-system-managed data sets. On
system-managed volumes, OPEN determines where to start writing using the
following algorithm. No matter which volume you finish writing on, OPEN
will find that volume to resume. Starting with the first volume, OPEN searches
for the last volume bit. The first new block will be written immediately after
the previous last block. If the old last block was short, it does not get larger.
This specifically applies to SMS volumes.
Writing with the DISP=MOD, OPEN EXTEND, or OUTINX option on non-SMS
volumes, OPEN determines where to start writing using the following
algorithm: It looks first on the last volume in the JFCB or its extensions to see if
its DSCB has the last volume bit ON. If it is not ON, OPEN searches the other
volumes in order starting with the first volume. This means that if the last
volume and an earlier volume each have the last volume bit ON, your added
data will not be reachable when reading sequentially.
For striped data sets, which are SMS only, the last volume bit works a little
different but it has the same effect as for other SMS data sets. The bit is ON on
the last volume, even if that volume does not contain the last record of the data
set. OPEN uses the DS1LSTAR fields to calculate the volume containing the last
record.
3. With partial release, CLOSE releases the unused space only on the current
| volume except with a striped data set that has a stripe count of greater than 1.
It does not release space on later volumes that can contain data either from a
prior writing or due to guaranteed space. With a system-managed data set this
has no effect on a later use of DISP=MOD but it does mean that the space on
the later volumes can be there due to guaranteed space allocation.

Additional Information on Space Allocation

If you want to know how many DASD tracks your data set requires, see the
appropriate device document. See z/OS DFSMSdfp Storage Administration Reference
for information about allocating space for system-managed data sets. See
“Allocating Space for a PDS” on page 419 and “Allocating Space for a PDSE” on
page 447 for information about PDS/PDSE space allocation.

44 z/OS V1R7.0 DFSMS Using Data Sets

Chapter 4. Backing Up and Recovering Data Sets
This chapter covers the following topics.

Topic Location
Using REPRO for Backup and Recovery 46
Using EXPORT and IMPORT for Backup and Recovery of VSAM Data Sets 47
Writing a Program for Backup and Recovery 48
Using Concurrent Copy for Backup and Recovery 49
Updating a Data Set After Recovery 49
Synchronizing Catalog and VSAM Data Set Information During Recovery 49

It is important to establish backup and recovery procedures for data sets so you
can replace a destroyed or damaged data set with its backup copy. Generally data
administrators set up automated procedures for backup so you do not have to be
concerned with doing it yourself. SMS facilitates this automation by means of
management class.

There are several methods of backing up and recovering VSAM and non-VSAM
data sets:
v Using Data Facility Storage Management Subsystem Hierarchical Storage
Manager (DFSMShsm™). You can use DFSMShsm only if DSS and DFSMShsm
are installed on your system and your data sets are cataloged in a catalog. For
information about using DFSMShsm backup and recovery, see z/OS DFSMShsm
Managing Your Own Data.
v Using the access method services REPRO command.
v Using the Data Facility Storage Management Subsystem Data Set Services
(DFSMSdss™) DUMP and RESTORE commands. You can use DSS if it is
installed on your system and your data sets are cataloged in a catalog. For
uncataloged data sets, DSS provides full volume, and physical or logical data set
dump functions. For compressed extended format data sets, DFSMShsm
processes the compressed data sets using DFSMSdss as the data mover. When
using DFSMSdss for logical dump/restore with VSAM compressed data sets, the
target data set allocation must be consistent with the source data set allocation.
For DFSMShsm, a VSAM extended format data set migrated and/or backed up
will only be recalled and/or recovered as an extended format data set. For
information about using DFSMSdss, see z/OS DFSMSdss Storage Administration
Reference.
v Writing your own program for backup and recovery.
v For VSAM data sets, using the access method services EXPORT and IMPORT
commands.
v For PDSs using IEBCOPY utility.
v Using concurrent copy to take an instantaneous copy. You can use concurrent
copy if your data set resides on DASD attached to IBM storage controls that
support the concurrent copy function.

Each of these methods of backup and recovery has its advantages. You need to
decide the best method for the particular data you want to back up. For the

© Copyright IBM Corp. 1987, 2005 45

Backing Up and Recovering Data Sets

requirements and processes of archiving, backing up, and recovering data sets
using DFSMShsm, DSS, or ISMF, see z/OS DFSMShsm Managing Your Own Data,
which also contains information on disaster recovery.

Using REPRO for Backup and Recovery

Use the REPRO command to create a duplicate data set for back up. For
information about using REPRO, see “Copying and Merging Data Sets” on page
117.

Using REPRO for backup and recovery has the following advantages:
v Backup copy is accessible. The backup copy obtained by using REPRO is
accessible for processing. It can be a VSAM data set or a sequential data set.
v Type of data set can be changed. The backup copy obtained by using REPRO
can be a different type of data set than the original. For example, you could back
up a VSAM key-sequenced data set by copying it to a VSAM entry-sequenced
data set. A compressed VSAM key-sequenced data set cannot be copied to a
VSAM entry-sequenced data set using REPRO. The data component of a
compressed key-sequenced data set cannot be accessed by itself.
v Key-sequenced data set or variable-length RRDS is reorganized. Using REPRO
for backup results in data reorganization and the recreation of an index for a
key-sequenced data set or variable-length RRDS. The data records are
rearranged physically in ascending key sequence and free-space quantities are
restored. (Control interval and control area splits can have placed the records
physically out of order.) When a key-sequenced data set is reorganized, absolute
references using the relative byte address (RBA) are no longer valid.

If you are accessing a data set using RLS, see Chapter 14, “Using VSAM
Record-Level Sharing,” on page 219.

REPRO provides you with several options for creating backup copies and using
them for data set recovery. The following are suggested ways to use REPRO:
1. Use REPRO to copy the data set to a data set with a different name.
Either change your references to the original copy or delete the original and
rename the copy.
2. Create a backup copy on another catalog, then use the backup copy to replace
the original.
v Define a data set on another catalog, and use REPRO to copy the original
data set into the new data set you have defined.
v You can leave the backup copy in the catalog it was copied to when you
want to replace the original with the backup copy. Then, change the JCL
statements to reflect the name of the catalog that contains the backup copy.
3. Create a copy of a nonreusable VSAM data set on the same catalog, then delete
the original data set, define a new data set, and load the backup copy into the
newly defined data set.
v To create a backup copy, define a data set, and use REPRO to copy the
original data set into the newly defined data set. If you define the backup
data set on the same catalog as the original data set or if the data set is SMS
managed, the backup data set must have a different name.
v To recover the data set, use the DELETE command to delete the original data
set if it still exists. Next, redefine the data set using the DEFINE command,
then restore it with the backup copy using the REPRO command.

46 z/OS V1R7.0 DFSMS Using Data Sets

 Backing Up and Recovering Data Sets

4. Create a copy of a reusable VSAM data set, then load the backup copy into the
original data set. When using REPRO, the REUSE attribute permits repeated
backups to the same VSAM reusable target data set.
v To create a backup copy, define a data set, and use REPRO to copy the
original reusable data set into the newly defined data set.
v To recover the data set, load the backup copy into the original reusable data
set.
5. Create a backup copy of a data set, then merge the backup copy with the
damaged data set. When using REPRO, the REPLACE parameter lets you
merge a backup copy into the damaged data set. You cannot use the REPLACE
parameter with entry-sequenced data sets, because records are always added to
the end of an entry-sequenced data set.
v To create a backup copy, define a data set, and use REPRO to copy the
original data set into the newly defined data set.
v To recover the data set, use the REPRO command with the REPLACE
parameter to merge the backup copy with the destroyed data set. With a
key-sequenced data set, each source record whose key matches a target
record’s key replaces the target record. Otherwise, the source record is
inserted into its appropriate place in the target cluster. With a fixed-length or
variable-length RRDS, each source record, whose relative record number
identifies a data record in the target data set, replaces the target record.
Otherwise, the source record is inserted into the empty slot its relative record
number identifies. When only part of a data set is damaged, you can replace
only the records in the damaged part of the data set. The REPRO command
lets you specify a location to begin copying and a location to end copying.
6. If the index of a key-sequenced data set or variable-length RRDS becomes
damaged, follow this procedure to rebuild the index and recover the data set.
This does not apply to a compressed key-sequenced data set. It is not possible
to REPRO just the data component of a compressed key-sequenced data set.
v Use REPRO to copy the data component only. Sort the data.
v Use REPRO with the REPLACE parameter to copy the cluster and rebuild
the index.
Restrictions:
1. Do not use JOBCAT or STEPCAT DD statements for system-managed data sets.
The JOBCAT or STEPCAT DD statement fails if it references a system-managed
catalog, or if the data set that is being searched is system managed. Also, you
must connect all referenced catalogs to the system master catalog.
2. JOBCAT and STEPCAT DD statements are disabled by default. For information
on enabling JOBCAT and STEPCAT DD statements, see z/OS DFSMS Managing
Catalogs.

Using EXPORT and IMPORT for Backup and Recovery of VSAM Data
Sets
Using EXPORT/IMPORT for backup and recovery has the following advantages:
v Key-sequenced data set or variable-length RRDS is reorganized. Using
EXPORT for backup results in data reorganization and the recreation of an index
for a key-sequenced data set or variable-length RRDS. The data records are
rearranged physically in ascending key sequence and free-space quantities are
balanced. (Control interval and control area splits can have placed the records
physically out of order.) When a key-sequenced data set is reorganized, absolute
references using the RBA are no longer valid.

Chapter 4. Backing Up and Recovering Data Sets 47

Backing Up and Recovering Data Sets

v Redefinition is easy. Because most catalog information is exported along with

the data set, you are not required to define a data set before importing the copy.
The IMPORT command deletes the original copy, defines the new object, and
copies the data from the exported copy into the newly defined data set.
v Attributes can be changed or added. When you IMPORT a data set for recovery,
you can specify the OBJECTS parameter to show new or changed attributes for
the data set. Importing a data set lets you change the name of the data set, the
key ranges, the volumes on which the data set is to reside, and the SMS classes.
For information about accessing a data set using RLS, see Chapter 14, “Using
VSAM Record-Level Sharing,” on page 219.

Structure of an Exported Data Set

An exported data set is an unloaded copy of the data set. The backup copy can be
only a sequential data set.

Most catalog information is exported along with the data set, easing the problem
of redefinition. The backup copy contains all of the information necessary to
redefine the VSAM cluster or alternate index when you IMPORT the copy.

EXPORT and IMPORT Commands

When you export a copy of a data set for backup, specify the TEMPORARY
attribute. Exporting a data set means that the data set is not to be deleted from the
original system.

You can export entry-sequenced or linear data set base clusters in control interval
mode by specifying the CIMODE parameter. When CIMODE is forced for a linear
data set, a RECORDMODE specification is overridden.

Use the IMPORT command to totally replace a VSAM cluster whose backup copy
was built using the EXPORT command. The IMPORT command uses the backup
copy to replace the cluster’s contents and catalog information.

You can protect an exported data set by specifying the INHIBITSOURCE or

INHIBITTARGET parameters. Using these parameters means the source or target
data set cannot be accessed for any operation other than retrieval.

IMPORT will not propagate distributed data management (DDM) attributes if you
specify the INTOEMPTY parameter. Distributed file manager (DFM) will
reestablish the DDM attributes when the imported data set is first accessed.

Compressed data must not be considered portable. IMPORT will not propagate
extended format or compression information if the user specifies the INTOEMPTY
parameter.

Writing a Program for Backup and Recovery

There are two methods of creating your own program for backup and recovery:
v If you periodically process a data set sequentially, you can easily create a backup
copy as a by-product of normal processing. The backup copy can be used like
one made by REPRO.
v You can write your own program to back up your data sets. Whenever possible,
this program should be integrated into the regular processing procedures.
In VSAM, the JRNAD user exit routine is one way to write your own backup
program. When you request a record for update, VSAM calls the JRNAD exit

48 z/OS V1R7.0 DFSMS Using Data Sets

 Backing Up and Recovering Data Sets

routine to copy the record you are going to update, and write it to a different
data set. When you return to VSAM, VSAM completes the requested update. If
something goes wrong, you have a backup copy. See “JRNAD Exit Routine to
Journalize Transactions” on page 247.

Using Concurrent Copy for Backup and Recovery

Concurrent copy takes what appears to be an instantaneous copy of data. The copy
can be a backup copy (such as to tape) or for replicating a database from one set of
DASD volumes to another. Concurrent copy also benefits the nondatabase
environment by permitting a backup or copy occur with only a very short
serialization.

Using concurrent copy for backup has the following advantages:

v It has little or no disruption.
v It is logically consistent.
v It is not necessary to take down the application using the data.
v It runs without regard to how the data is being used by the application.
v It works for any kind of DSS dump or copy operation.
v It eliminates the unavailability of DFSMShsm while control data sets are being
backed up.

DFSMShsm can use concurrent copy to copy its own control data sets and journal.

Running concurrent copy (like any copy or backup) during off-peak hours results
in better system throughput.

Related reading: For information about using concurrent copy, see z/OS DFSMSdss
Storage Administration Guidey.

Updating a Data Set After Recovery

After replacing a damaged data set with its backup copy, you can update the
restored data set. To update the restored data set, rerun the jobs that updated the
original between the time it was backed up and the time it became inaccessible.

Synchronizing Catalog and VSAM Data Set Information During

Recovery
Because the physical and logical description of a VSAM data set is contained in its
catalog entries, VSAM requires up-to-date catalog entries to access data sets. If
either your data set or your catalog is damaged, your recovery procedure must
match both data set and catalog entry status. Recovery by reloading the data set
automatically takes care of this problem. A new catalog entry is built when the
data set is reloaded.

Backing up the data sets in a user catalog lets you recover from damage to the
catalog. You can import the backup copy of a data set whose entry is lost or you
can redefine the entry and reload the backup copy.

For information about backing up and recovering a catalog, see z/OS DFSMS
Managing Catalogs and z/OS DFSMShsm Managing Your Own Data.

Chapter 4. Backing Up and Recovering Data Sets 49

Backing Up and Recovering Data Sets

Handling an Abnormal Termination

When a user program closes a VSAM data set, the system uses the data set’s
end-of-data information to update its cataloged information. If a system failure
occurs before the user program closes the data set, its cataloged information is not
updated and any records in unwritten buffers are not written to the data set.

If an error occurs while a component is opened for update processing, it can

improperly close (leaving the open-for-output indicator on). At OPEN, VSAM
implicitly issues a VERIFY command when it detects an open-for-output indicator
on and issues an informational message stating whether the VERIFY command is
successful.

When the last CLOSE for a VSAM data set completes successfully, VSAM turns off
the open-for-output indicator. If the data set is opened for input, however, VSAM
leaves the open-for-output indicator on. It is the successful CLOSE after an OPEN
for output that causes the open-for-output indicator to turn off. Before you use any
data set that was not successfully closed, determine the status of the data in the
data set. Turning off the open-for-output indicator in the catalog does not make the
data set error free.

Using VERIFY to Process Improperly Closed Data Sets

You can use a VSAM VERIFY macro call with certain types of opened VSAM data
sets to ensure that fields in the VSAM control blocks are accurate. The VERIFY
macro does not change the data in the data set. VERIFY does not correct missing
or duplicate records or repair any damage in the index structure. The verification
of control-block fields enables you to perform recovery actions on the improperly
closed data set, if necessary.

You can also use the IDCAMS VERIFY command to verify a VSAM data set. When
you issue this command, IDCAMS opens the VSAM data set for output, issues a
VSAM VERIFY macro call, and closes the data set. The IDCAMS VERIFY
command and the verification by VSAM OPEN are the same. Neither changes the
data in the verified data set.

The catalog will be updated from the verified information in the VSAM control
blocks when the VSAM data set which was opened for output is successfully
closed.

The actual VSAM control-block fields that get updated depend on the type of data
set being verified. VSAM control block fields that can be updated include “High
used RBA/CI” for the data set, “High key RBA/CI”, “number of index levels”,
and “RBA/CI of the first sequence set record”.

The VERIFY command should be used following a system failure that caused a
component opened for update processing to be improperly closed. Clusters,
alternate indexes, entry-sequenced data sets, and catalogs can be verified. Paths
over an alternate index and linear data sets cannot be verified. Paths defined
directly over a base cluster can be verified. The VERIFY macro will perform no
function when VSAM RLS is being used. VSAM RLS is responsible for maintaining
data set information in a shared environment.

Although the data and index components of a key-sequenced cluster or alternate

index can be verified, the timestamps of the two components are different
following the separate verifies, possibly causing further OPEN errors. Therefore,
use the cluster or alternate index name as the target of your VERIFY command.

50 z/OS V1R7.0 DFSMS Using Data Sets

 Backing Up and Recovering Data Sets

You should issue the VERIFY command every time you open a VSAM cluster that
is shared across systems. For information about using VERIFY with clusters that
are shared, see “Cross-System Sharing” on page 200.

Recovering from Errors Due to an Improperly Closed VSAM Data

Set
Sometimes a data set is closed properly, but an error occurred. The most likely
error is an incorrect high RBA in the catalog. Other possible errors are an
incomplete write to a DASD or duplicate data exists. One way to avoid these
errors is by doing synchronous direct inserts. Another way is by using abnormal
termination user exits in which you issue a CLOSE (perhaps with the TYPE=T
parameter) to close the data set properly.

If you suspect that a write operation is incomplete, issue either an IMPORT or

REPRO command to get an old copy of the data. Intermediate updates or inserts
are lost. You must have an exported version of the data set available to use
IMPORT. Use a backup copy for REPRO.

Duplicate data in a key-sequenced data set, the least likely error to occur, can
result from a failure during a control interval or control area split. To reduce the
number of splits, specify free space for both control intervals and control areas. If
the failure occurred before the index was updated, the insert is lost, no duplicate
exits, and the data set is usable.

If the failure occurred between updating the index and writing the updated control
interval into secondary storage, some data is duplicated. However, you can access
both versions of the data by using addressed processing. If you want the current
version, use REPRO to copy it to a temporary data set and again to copy it back to
a new key-sequenced data set. If you have an exported copy of the data, use the
IMPORT command to obtain a reorganized data set without duplicate data.

If the index is replicated and the error occurred between the write operations for
the index control intervals, but the output was not affected, both versions of the
data can be retrieved. The sequence of operations for a control area split is similar
to that for a control interval split. To recover the data, use the REPRO or IMPORT
command in the same way as for the failure described in the previous paragraph.

Use the journal exit (JRNAD) to determine control interval and control area splits
and the RBA range affected.

Using VERIFY with Catalogs

VSAM OPEN calls VERIFY when it opens a catalog.

You cannot use VERIFY to correct catalog records for a key-sequenced data set, or
a fixed-length or variable-length RRDS after load-mode failure. An entry-sequenced
data set defined with the RECOVERY attribute can be verified after a create (load)
mode failure; however, you cannot run VERIFY against an empty data set or a
linear data set. Any attempt to do either will result in a VSAM logical error. For
information about VSAM issuing the implicit VERIFY command, see “Opening a
Data Set” on page 137.

Chapter 4. Backing Up and Recovering Data Sets 51

Backing Up and Recovering Data Sets

CICS VSAM Recovery

IBM CICS® VSAM Recovery (CICSVR) recovers lost or damaged VSAM data sets.
CICSVR is for organizations where the availability and integrity of VSAM data is
vital. CICSVR provides automated complete recovery, forward recovery, and
backout functions, as well as logging for batch applications.

The following are some of the tasks that you can perform with CICSVR:
v Perform complete recovery to restore and recover lost or damaged VSAM data
sets that were updated by CICS and batch applications.
v Perform logging for batch applications.
v Recover groups of VSAM data sets.
v Process backup-while-open (BWO) VSAM data sets.
v Automate the creation and submission of recovery jobs using an ISPF dialog
interface.
v Use Change Accumulation to consolidate log records and reduce the amount of
time required to recover a VSAM data set.
v Use Selective Forward Recovery to control which log records get applied to the
VSAM data set when you recover it.

Related reading: For more information, see IBM CICS VSAM Recovery
Implementation Guide.

52 z/OS V1R7.0 DFSMS Using Data Sets

Chapter 5. Protecting Data Sets
You can prevent unauthorized access to payroll data, sales forecast data, and all
other data sets that require special security attention. You can protect confidential
data in a data set using Resource Access Control Facility (RACF) or passwords.

This chapter covers the following topics.

Topic Location

Data Set Password Protection 55

User-Security-Verification Routine 60
Erasure of Residual Data 60
Authorized Program Facility and Access Method Services 62
Access Method Services Cryptographic Option 63

z/OS Security Server (RACF)

The z/OS Security Server is the primary tool that IBM recommends for managing
security. Often the Security Server is called the Resource Access Control Facility
(RACF). In the MVS™ environment, you can use RACF identify and verify users’
authority to access data and to use system facilities. RACF protection can apply to
a catalog and to individual VSAM data sets.

The system ignores password protection for SMS-managed data sets. See “Data Set
Password Protection” on page 55.

If a discrete profile or a generic profile does not protect a data set, password
protection is in effect.

Related reading: For more information about RACF, see z/OS Security Server RACF
Security Administrator’s Guide.

RACF Protection for VSAM Data Sets

A catalog that contains a VSAM data set does not have to be RACF protected for
its data sets to be RACF protected.

RACF and password protection can coexist for the same VSAM data set. The
RACF authorization levels of alter, control, update, and read correspond to the
VSAM password levels of master, control, update, and read.

To have password protection take effect for a non-system-managed data set, the
catalog that contains the data set must be either RACF protected or password
protected, and the data set itself must not be defined to RACF. Although
passwords are not supported for an RACF-protected data set, they can still provide
protection if the data set is moved to a system that does not have RACF protection.

If a user-security-verification routine (USVR) exists, it is not invoked for

RACF-defined data sets.

© Copyright IBM Corp. 1987, 2005 53

Protecting Data Sets

Deleting any type of RACF-protected entry from an RACF-protected catalog

requires alter-level authorization for the catalog or the entry being deleted. Altering
the passwords in an RACF-protected catalog entry requires RACF alter authority
for the entry being altered or the operations attribute. Alter authority for the
catalog itself is not sufficient for this operation.

Note: VSAM OPEN routines bypass RACF security checking if the program
issuing OPEN is in supervisor state or protection key 0.

Generic and Discrete Profiles for VSAM Data Sets

For cataloged clusters, a generic profile is used to verify access to the entire cluster,
or any of its components. Discrete profiles for the individual components might
exist, but only the cluster’s profile (generic or discrete) is used to protect the
components in the cluster.

Profiles that automatic data set protection (ADSP) processing defines during a data
set define operation are cluster profiles only.

If a data set protected by a discrete profile is moved to a system where RACF is

not installed, no user is given authority to access the data set. However, if the data
set is protected with a generic profile, access authority is determined by normal
VSAM password protection.

RACF Protection for Non-VSAM Data Sets

You can define a data set to RACF automatically or explicitly. The automatic
definition occurs when space is allocated for the DASD data set, if you have the
automatic data set protection attribute, or if you code PROTECT=YES or
SECMODEL=(,) in the DD statement. SECMODEL=(,) lets you specify the name of
the model profile RACF should use in creating a discrete profile for your data set.
The explicit definition of a data set to RACF is by use of the RACF command
language.

Multivolume data sets. To protect multivolume non-VSAM DASD and tape data
sets, you must define each volume of the data set to RACF as part of the same
volume set.
v When an RACF-protected data set is opened for output and extended to a new
volume, the new volume is automatically defined to RACF as part of the same
volume set.
v When a multivolume physical-sequential data set is opened for output, and any
of the data set’s volumes are defined to RACF, either each subsequent volume
must be RACF-protected as part of the same volume set, or the data set must
not yet exist on the volume.
v The system automatically defines all volumes of an extended sequential data set
to RACF when the space is allocated.
v When an RACF-protected multivolume tape data set is opened for output, either
each subsequent volume must be RACF-protected as part of the same volume
set, or the tape volume must not yet be defined to RACF.
v If the first volume opened is not RACF protected, no subsequent volume can be
RACF protected. If a multivolume data set is opened for input (or a
nonphysical-sequential data set is opened for output), no such consistency check
is performed when subsequent volumes are accessed.

54 z/OS V1R7.0 DFSMS Using Data Sets

 Protecting Data Sets

Tape data sets. You can use RACF to provide access control to tape volumes that
have no labels (NL), IBM standard labels (SL), ISO/ANSI standard labels (AL), or
tape volumes referred to with bypass label processing (BLP).

RACF protection of tape data sets is provided on a volume basis or on a data set
basis. A tape volume is defined to RACF explicitly by use of the RACF command
language, or automatically. A tape data set is defined to RACF whenever a data set
is opened for OUTPUT, OUTIN, or OUTINX and RACF tape data set protection is
active, or when the data set is the first file in a sequence. All data sets on a tape
volume are RACF protected if the volume is RACF protected.

If a data set is defined to RACF and is password protected, access to the data set is
authorized only through RACF. If a tape volume is defined to RACF and the data
sets on the tape volume are password protected, access to any of the data sets is
authorized only through RACF. Tape volume protection is activated by issuing the
RACF command SETROPTS CLASSACT(TAPEVOL). Tape data set name
protection is activated by issuing the RACF command SETROPTS
CLASSACT(TAPEDSN). Data set password protection is bypassed. The system
ignores data set password protection for system-managed DASD data sets.

ISO/ANSI Version 3 and Version 4 installation exits that run under RACF will
receive control during ISO/ANSI volume label processing. Control goes to the
RACHECK preprocessing and postprocessing installation exits. The same
IECIEPRM exit parameter list passed to ISO/ANSI installation exits is passed to
the RACF installation exits if the accessibility code is any alphabetic character from
A through Z.

Related reading: For more information about these exits, see z/OS DFSMS
Installation Exits.

Note: ISO/ANSI Version 4 tapes also permits special characters

!*″%&’()+,-./:;<=>?_ and numeric 0-9.

Hiding Data Set Names

To ensure that your enterprise’s information is protected, the security administrator
can enable RACF name-hiding for those data sets that contain critical information.
When name-hiding is in effect, you cannot obtain data set names unless you have
at least READ authority to access that data set. If you have access to the RACF
FACILITY class [Link] for the VTOC, you can see all
data sets on the volume including the ones for which you do not have RACF
READ authority. If you don’t have access to [Link] for
a volume on the VTOC, you can display only data sets for which you have specific
READ access.

Related reading: For more information on name-hiding and RACF protection of

data set names, see z/OS DFSMS Using the New Functions and z/OS Security Server
RACF Security Administrator’s Guide.

Data Set Password Protection

Passwords are ignored for all system-managed data sets, new and existing.
However, passwords can still be defined for system-managed data sets, and used
to protect those data sets when you are sharing them with non-SMS systems that
do not have RACF or an equivalent product.

Chapter 5. Protecting Data Sets 55

Protecting Data Sets

Passwords for VSAM Data Sets

To use password protection effectively, you need to understand the difference
between operations on a catalog and operations on a data set represented by a
catalog entry:
v Referring to a catalog entry when new entries are defined (ALLOCATE or
DEFINE), or existing entries are altered (ALTER), deleted (DELETE), or listed
(LISTCAT).
v Using the data set represented by a catalog entry when it is connected to a
user’s program (OPEN), or disconnected (CLOSE).

Different passwords might be needed for each type of operation. Operations on a

catalog can be authorized by the catalog’s password or, sometimes, by the
password of the data set defined in the catalog. For information about password
levels, see z/OS DFSMS Access Method Services for Catalogs.

The following are examples of passwords required for defining, listing, and
deleting non-system-managed catalog entries:
v Defining a non-system-managed data set in a password-protected catalog
requires the catalog’s update (or higher) password.
v Listing, altering, or deleting a data set’s catalog entry requires the appropriate
password of either the catalog or the data set. However, if the catalog, but not
the data set, is protected, no password is needed to list, alter, or delete the data
set’s catalog entry.

OPEN and CLOSE operations on a data set can be authorized by the password
pointed to by the PASSWD parameter of the ACB macro. For information about
the password level required for each type of operation, see z/OS DFSMS Macro
Instructions for Data Sets.

Passwords to Authorize Access

You can define passwords for access to clusters, cluster components (data and
index), page spaces, alternate indexes, alternate index components (data and
index), paths, master and user catalogs. Different passwords have various degrees
of security, with higher levels providing greater protection than lower levels:
v Full access. The full access password is the master password, which lets you
perform all operations (retrieving, updating, inserting, and deleting) on an entire
VSAM data set and any index and catalog record associated with it. The master
password permits all operations and bypasses any additional verification
checking by the user-security-verification routine.
v Control access. The control-access password authorizes you to use control
interval access. For more information, see Chapter 11, “Processing Control
Intervals,” on page 179.
v Update access. The update-access password authorizes you to retrieve, update,
insert, or delete records in a data set. The update password does not let you
alter passwords or other security information.
v Read access. The read-only password allows you to examine data records and
catalog records, but not add, alter, or delete them, nor see password information
in a catalog record.

Each higher-level password allows all operations permitted by lower levels. Any
level can be null (not specified), but if a low-level password is specified, the
DEFINE and ALTER commands give the higher passwords the value of the highest
password specified. For example, if only a read-level password is specified, the
read-level becomes the update-, control-, and master-level password as well. If you
56 z/OS V1R7.0 DFSMS Using Data Sets
 Protecting Data Sets

specify a read password and a control password, the control password value
becomes the master-level password as well. However, in this case, the update-level
password is null because the value of the read-level password is not given to
higher passwords.

Catalogs are themselves VSAM data sets, and can have passwords. For some
operations (for example, listing all the catalog’s entries with their passwords or
deleting catalog entries), the catalog’s passwords can be used instead of the entry’s
passwords. If the master catalog is protected, the update- or higher-level password
is required when defining a user catalog, because all user catalogs have an entry in
the master catalog. When deleting a protected user catalog, the user catalog’s
master password must be specified.

Some access method services operations might involve more than one password
authorization. For example, importing a data set involves defining the data set and
loading records into it. If the catalog into which the data set is being imported is
password protected, its update-level (or higher-level) password is required for the
definition; if the data set is password protected, its update-level (or higher-level)
password is required for the load. The IMPORT command lets you specify the
password of the catalog; the password, if any, of the data set being imported is
obtained by the commands from the exported data.

Every VSAM data set is represented in a catalog by two or more components: a

cluster component and a data component, or, if the data set is a key-sequenced
data set, a cluster component, a data component, and an index component. Of the
two or three components, the cluster component is the controlling component.
Each of the two or three components can have its own set of four passwords; the
passwords you assign have no relationship to each other. For example, password
protecting a cluster but not the cluster’s data component, lets you issue LISTCAT
to determine the name of your cluster’s data component, open the data
component, and access records in it, even though the cluster itself is password
protected.

One reason for password-protecting the components of a cluster is to prevent

access to the index of a key-sequenced data set. (One way to gain access to an
index is to open it independently of the cluster.)

Password-Protection Precautions
When you use protection commands for a non-system-managed catalog or for a
data set, you need to observe certain password-protection precautions, which the
following lists describe.

For a Catalog. Observe the following precautions when you use protection
commands for a non-system-managed catalog:
v To create a non-system-managed catalog entry using the DEFINE command, the
update-level or higher-level password of the catalog is required.
v To modify a catalog entry using the ALTER command, the master password of
the entry, or the master password of the catalog that contains the entry, is
required. However, if the entry to be modified is a non-VSAM or generation
data group entry, the update-level password of the catalog is sufficient.
v To gain access to passwords in a catalog (for example, to list or change
passwords), specify the master-level password of either the entry or the catalog.
A master-level password must be specified with the DEFINE command to model
an entry’s passwords.

Chapter 5. Protecting Data Sets 57

Protecting Data Sets

v To delete a protected data set entry from a catalog, requires the master-level
password of the entry or the master-level password of the catalog containing the
entry. However, if the entry in a catalog describes a VSAM data space, the
update-level password of the catalog is sufficient.
v To delete a non-VSAM, generation data group, or alias entry, the update-level
password of the catalog is sufficient.
v To list catalog entries with the read-level passwords, specify the read password
of the entry or the catalog’s read-level password. However, entries without
passwords can be listed without specifying the catalog’s read-level password.
v To list the passwords associated with a catalog entry, specify the master
password of the entry or the catalog’s master password.
To avoid unnecessary prompts, specify the catalog’s password, which permits
access to all entries the operation affects. A catalog’s master-level password lets
you refer to all catalog entries. However, a protected cluster cannot be processed
with the catalog’s master password.
Specification of a password where none is required is always ignored.

For a Data Set. Observe the following precautions when you use protection
commands for a data set:
v To access a VSAM data set using its cluster name instead of data or index
names, specify the proper level password for the cluster even if the data or
index passwords are null.
v To access a VSAM data set using its data or index name instead of its cluster
name, specify the proper data or index password. However, if cluster passwords
are defined, the master password of the cluster can be specified instead of the
data or index password.
v Null means no password was specified, if a cluster has only null passwords,
access the data set using the cluster name without specifying passwords, even if
the data and index entries of the cluster have defined passwords. Using null
passwords permits unrestricted access to the VSAM cluster but protects against
unauthorized modification of the data or index as separate components.

Data Set and Catalog Protection

If you define passwords for any data sets in a catalog, you must also protect the
catalog by defining passwords for the catalog or by defining the catalog to RACF.
If you do not protect the catalog, no password checking takes place during
operations on the data set’s catalog entries or during open processing of data sets
cataloged in that catalog.

Password Prompting
Computer operators and TSO/E terminal users should supply a correct password
if a processing program does not give the correct one when it tries to open a
password-protected data set. When the data set is defined, use the CODE
parameter to specify a code instead of the data set name to prompt the operator or
terminal user for a password. The prompting code keeps your data secure by not
permitting the operator or terminal user to know both the name of the data set
and its password.

A data set’s code is used for prompting for any operation against a
password-protected data set. The catalog code is used for prompting when the
catalog is opened as a data set, when an attempt is made to locate catalog entries
that describe the catalog, and when an entry is to be defined in the catalog.

58 z/OS V1R7.0 DFSMS Using Data Sets

 Protecting Data Sets

If you do not specify a prompting code, VSAM identifies the job for which a
password is needed with the JOBNAME and DSNAME for background jobs or
with the DSNAME alone for foreground (TSO/E) jobs.

When you define a data set, use the ATTEMPTS parameter to specify the number
of times the computer operator or terminal user is permitted to give the password
when a processing program is trying to open a data set.

If the ATTEMPTS parameter is coded with 0, no password prompting is done. If

you exceed the allowed number of attempts When you use System Management
Facilities, a record is written to the SMF data set to indicate a security violation.

If you are logged in to TSO/E, VSAM tries the login password before prompting at
your terminal. Using the TSO/E login password counts as one attempt.

Passwords for Non-VSAM Data Sets

IBM recommends not using passwords for data sets. The security provided by data
set passwords is not as good as security provided by RACF. See z/OS DFSMSdfp
Advanced Services.

The system ignores data set password protection for system-managed data sets.

Assigning a Password
Use the PROTECT macro or the IEHPROGM PROTECT command to assign a
password to the non-VSAM data set. See z/OS DFSMSdfp Advanced Services and
z/OS DFSMSdfp Utilities.

Protecting a Data Set When You Define It

When you define a non-VSAM data set in a catalog, the data set is not protected
with passwords in its catalog entry. However, you can password-protect the
catalog.

Two levels of protection options for your data set are available. Specify these
options in the LABEL field of a DD statement with the parameter PASSWORD or
NOPWREAD. See z/OS MVS JCL Reference.
v Password protection (specified by the PASSWORD parameter) makes a data set
unavailable for all types of processing until a correct password is entered by the
system operator, or for a TSO/E job by the TSO/E user.
v No-password-read protection (specified by the NOPWREAD parameter) makes a
data set available for input without a password, but requires that the password
be entered for output or delete operations.

The system sets the data set security indicator either in the standard header label 1,
as shown in z/OS DFSMS Using Magnetic Tapes, or in the data set control block
(DSCB). After you have requested security protection for magnetic tapes, you
cannot remove it with JCL unless you overwrite the protected data set.

Supplying a Password for a Catalog

If the catalog is update protected, you must supply the catalog’s update- or
higher-level password to define, delete, or alter a non-VSAM data set. The
password can be supplied as a subparameter of the command’s CATALOG
parameter, or as a response to the password-prompting message.

Chapter 5. Protecting Data Sets 59

 Protecting Data Sets

Handling Incorrect Passwords

If an incorrect password is entered twice when a password is being requested by
the open or EOV routine, the system issues an ABEND 913. For a SCRATCH or
RENAME request, a return code is given.

Entering a Record in the PASSWORD Data Set

In addition to requesting password protection in your JCL, you must enter at least
one record for each protected data set in a data set named PASSWORD. The
PASSWORD data set must be created on the system-residence volume. The
system-residence volume contains the nucleus of the operating system. The system
programmer should also request password protection for the PASSWORD data set
itself to prevent both reading and writing without knowledge of the password.

For a data set on direct access storage devices, place the data set under protection
when you enter its password in the PASSWORD data set. Use the PROTECT macro
or the IEHPROGM utility program to add, change, or delete an entry in the
PASSWORD data set. Using either of these methods, the system updates the DSCB
of the data set to reflect its protected status. Therefore, you do not need to use JCL
whenever you add, change, or remove security protection for a data set on direct
access storage devices. For information about maintaining the PASSWORD data
set, including the PROTECT macro, see z/OS DFSMSdfp Advanced Services. For
information about the IEHPROGM utility, see z/OS DFSMSdfp Utilities.

User-Security-Verification Routine
Besides password protection, VSAM lets you protect data by specifying a program
that verifies a user’s authorization. “User-Security-Verification Routine” on page
261 describes specific requirements. To use this additional protection, specify the
name of your authorization routine in the AUTHORIZATION parameter of the
DEFINE or ALTER command.

If a password exists for the type of operation you are performing, you must
specify the password, either in the command or in response to prompting. VSAM
calls the user-security-verification routine only after it verifies the password. VSAM
bypasses this routine whenever you specify a correct master password, whether
the operation requires the master password.

You can use the USVR to detect VSAM password usage.

Erasure of Residual Data

When you release media space, you can erase your data.

Erasing DASD Data

When you delete any DASD data set or release part of the space, the system makes
the space available for allocation for new data sets. There are ways that the creator
of the new data set can read residual data that was in the previous data set. To
prevent others from reading your deleted data, run a program that overwrites the
data before you delete it. Alternatively, you can have the system erase (overwrite)
the data during data set deletion or space release, with its erase-on-scratch
function. The system erasure is faster than a program that writes new data. If the
system erasure fails, then the deletion or space release fails.

| The objective of the erase-on-scratch function is to ensure that none of the data on
| the released tracks can be read by any host software even if the device is

60 z/OS V1R7.0 DFSMS Using Data Sets

 Protecting Data Sets

| mis-configured and connected to a different computer with different software.

| However, after the erasure, the old data on those tracks remains exposed to the
| following risks, which you must evaluate:
| v After the operating system completes the operation, the operation may continue
| asynchronously in the DASD subsystem. As long as the IBM subsystem is
| powered up, there is no command that any software can issue to retrieve the
| data. If the power fails and the battery inside the subsystem also fails and the
| actual erasure has not completed, then the data might be retrievable again
| through software after the subsystem is online again.
| v If someone gains physical access to the disks in the DASD subsystem even after
| the subsystem has completed the asynchronous erase, that person might be able
| to recover the disk contents.
| If you wish to obliterate the data so that your enterprise can dispose of the disk
| without revealing confidential information, then this section might not apply to
| you. Consider using the ERASEDATA and CYCLES parameters of the TRKFMT
| command of ICKDSF. See Device Support Facilities User’s Guide and Reference.

To have the system erase sensitive data with RACF, the system programmer can
start the erase feature with the RACF SETROPTS command. This feature controls
the erasure of DASD space when it is releases. Space release occurs when you
delete a data set or release part of a data set. SETROPTS selects one of the
following methods for erasing the space:
v The system erases all released space.
v The system erases space only in data sets that have a security level greater than
or equal to a certain level.
v The system erases space in a data set only if its RACF data set profile specifies
the ERASE option.
v The system never erases space.

If the ERASE option is set in the RACF profile, you cannot override the option by
specifying NOERASE in access methods services commands.

System Erasure of Data

If DASD data erasure is in effect and you use any of the following items, the
system overwrites the entire data set area:
v The DELETE subparameter in the JCL DISP parameter of a data definition (DD)
statement
v The TSO DELETE command (for non-VSAM objects)
v The SCRATCH macro
v The SCRATCH control statement for the IEHPROGM utility program
v The access method services DELETE command

For a sequential, partitioned, PDSE, or VSAM extended-format data set, if DASD

data erasure is in effect, the system also overwrites the released area when you use
any of the following:
v RLSE subparameter in the JCL SPACE parameter in a DD statement to which a
program writes
v Partial release option in the management class
v PARTREL macro

RAMAC Virtual Array

With RAMAC® Virtual Array, the DDSR option of IXFP does almost the same thing
as the erase-on-scratch function. The storage administrator uses DDSR to manage

Chapter 5. Protecting Data Sets 61

Protecting Data Sets

disk space more efficiently. DDSR has the side effect of usually erasing released
tracks, even if you do not request the ERASE option. DDSR is faster than the
erase-on-scratch function on other types of disks. Without erase-on-scratch,
however, DDSR is less secure. The erasure might not complete before data set
deletion or space release. After a successful erasure, your data remains physically
on disk, in a compressed form, but is not accessible by any software.

If you request erase-on-scratch on a RAMAC Virtual Array for which DDSR is

active, the system optimizes the erasure so that it happens much faster than on
other kinds of disks. The erasure is guaranteed to complete before data set deletion
or space release. After a successful erasure, your data is not accessible by any
software.

Erasing Tape Data

If you want to prevent the reading of residual data on tape volumes, you can
implement some method of overwriting the volume. A DFSMSrmm™ user can
define security classes in EDGRMMxx, a DFSMSrmm PARMLIB member, by using
name masks to identify data sets that must be erased before the volume can be
released for use as scratch. If DFSMSrmm determines that the security class of a
data set requires erasure, DFSMSrmm sets release actions of ERASE and INIT for
any volume that contains the data set. When all data sets on the volume have
expired, DFSMSrmm holds the volume until these actions have been confirmed.

To automate the overwriting of residual data, schedule a regular EDGINERS job to

process volumes that have the erase action pending. DFSMSrmm selects the
volumes to process and prompts the operator to mount each one. After verifying
that the correct volume is mounted, DFSMSrmm erases the volume, using the
hardware-security erase feature, where supported, to free the channel for other
activity during the erasure.

If the hardware-security erase feature is not available, DFSMSrmm overwrites

volumes with a bit pattern of X'FF'. When erasing volumes, DFSMSrmm also
reinitializes them so that the correct volume labels are written, and the volumes are
ready for reuse in a single operation.

Authorized Program Facility and Access Method Services

The authorized program facility (APF) limits the use of sensitive system services
and resources to authorized system and user programs. For information about
program authorization, see z/OS MVS Programming: Authorized Assembler Services
Guide.

All access method services load modules are contained in [Link], and the
root segment load module (IDCAMS) is link edited with the SETCODE AC(1)
attribute.

APF authorization is established at the job step level. If, during the execution of an
APF-authorized job step, a load request is satisfied from an unauthorized library,
the task is abnormally terminated. It is the installation’s responsibility to ensure
that a load request cannot be satisfied from an unauthorized library during access
method services processing.

The following situations could cause the invalidation of APF authorization for
access method services:
v An access method services module is loaded from an unauthorized library.

62 z/OS V1R7.0 DFSMS Using Data Sets

 Protecting Data Sets

v A user-security-verification routine (USVR) is loaded from an unauthorized

library during access method services processing.
v An exception exit routine is loaded from an unauthorized library during access
method services processing.
v A user-supplied special graphics table is loaded from an unauthorized library
during access method services processing.

Because APF authorization is established at the job-step task level, access method
services is not authorized if invoked by an unauthorized application program or
unauthorized terminal monitor program (TMP).

The system programmer must enter the names of those access method services
commands that require APF authorization to run under TSO/E in the authorized
command list.

Programs that are designed to be called from an APF-authorized program should

never be linked or bound with APF authorization. Someone could invoke the
routine directly through JCL, and it would be operating with APF authorization in
an environment for which it was not designed. Programs that you intend to be
called by an APF-authorized program should be in APF-authorized libraries.

The following restricted access method services functions cannot be requested in

an unauthorized state:

DEFINE—When the RECATALOG parameter is specified

DELETE—When the RECOVERY parameter is specified

EXPORT—When the object to be exported is a catalog

IMPORT—When the object to be imported is a catalog

PRINT—When the object to be printed is a catalog

REPRO—When copying a catalog or when the catalog unload/reload is to be used

VERIFY—When a catalog is to be verified

If the above functions are required and access method services is invoked from an
application program or TSO/E terminal monitor program, the invoking program
must be authorized.

For information about authorizing for TSO/E and ISPF, see z/OS DFSMSdfp Storage
Administration Reference.

Access Method Services Cryptographic Option

Although you can provide security for online data by using such facilities as
VSAM password protection and RACF, these facilities do not protect data when it
is stored offline. Sensitive data stored offline is susceptible to misuse.

Cryptography is an effective means of protecting offline data, if the enciphering

techniques are adequate. The enciphering function is available by using the access
method services REPRO ENCIPHER command. The data remains protected until
you use the REPRO DECIPHER command to decipher it with the correct key.

Chapter 5. Protecting Data Sets 63

Protecting Data Sets

When you use the REPRO ENCIPHER command, you can specify whether to use
the Programmed Cryptographic Facility or Integrated Cryptographic Service
Facility (ICSF) to manage the cryptographic keys, depending on which
cryptographic facility is running as a started task. You can use the REPRO
ENCIPHER and REPRO DECIPHER to perform simple encryption and decryption
of sensitive data. The data remains protected until you use the REPRO DECIPHER
option to decipher it with the correct key. If you also have cryptographic hardware
and RACF, you can use these REPRO commands with ICSF to perform more
sophisticated encryption and decryption.

Related reading: For information on using the REPRO command to encrypt and
decrypt data, see z/OS DFSMS Access Method Services for Catalogs. For information
on using ICSF, z/OS Cryptographic Services ICSF Overview.

Data Enciphering and Deciphering

In the following three types of offline environments, the enciphering of sensitive
data adds to data security:
v Data sets are transported to another installation, where data security is required
during transportation and while the data is stored at the other location.
v Data sets are stored for long periods of time at a permanent storage location
v Data sets are stored offline at the site at which they are normally used.

You can use the REPRO command to copy a plaintext (not enciphered) data set to
another data set in enciphered form. Enciphering converts data to an unintelligible
form called a ciphertext. You can then store the enciphered data set offline or send
it to a remote location. When desired, you can bring back the enciphered data set
online and use the REPRO command to recover the plaintext from the ciphertext
by copying the enciphered data set to another data set in plaintext (deciphered)
form.

Enciphering and deciphering are based on an 8-byte binary value called the key.
Using the REPRO DECIPHER option, you can either decipher the data on the
system that it was enciphered on, or decipher the data on another system that has
the required key to decipher the data.

The input data set for the decipher operation must be an enciphered copy of a data
set produced by REPRO. The output data set for the encipher operation can only
be a VSAM entry-sequenced, linear, or sequential data set. The target (output) data
set of both an encipher and a decipher operation must be empty. If the target data
set is a VSAM data set that has been defined with the reusable attribute, use the
REUSE parameter of REPRO to reset it to empty.

For both REPRO ENCIPHER and REPRO DECIPHER, if the input data set
(INDATASET) is system managed, the output data set (OUTDATASET) can be
either system managed or not system managed, and must be cataloged.

The REPRO ENCIPHER parameter indicates that REPRO is to produce an

enciphered copy of the data set. The INFILE or INDATASET parameter identifies
and allocates the plaintext (not enciphered) source data set.

The REPRO DECIPHER parameter indicates that REPRO is to produce a

deciphered copy of the data set. The OUTFILE or OUTDATASET parameter
identifies and allocates a target data set to contain the plaintext data.

64 z/OS V1R7.0 DFSMS Using Data Sets

 Protecting Data Sets

Figure 2 is a graphic representation of the input and output data sets involved in
REPRO ENCIPHER and DECIPHER operations.

Input Encipher Output Input Decipher Output

Source Data Set Target Data Set Source Data Set Target Data Set
(Plaintext) (Ciphertext) (Ciphertext) (Plaintext)

Any data set VSAM ESDS, VSAM ESDS,

VSAM
REPRO can copy REPRO LDS or SAM LDS or SAM REPRO
ESDS
into (except Encipher Decipher
KSDS
catalogs): LDS
RRDS
VSAM SAM
ESDS
KSDS
LDS
RRDS
SAM

Figure 2. REPRO Encipher and Decipher Operations

When you encipher a data set, specify any of the delimiter parameters available
with the REPRO command (SKIP, COUNT, FROMADDRESS, FROMKEY,
FROMNUMBER, TOADDRESS, TOKEY, TONUMBER) that are appropriate to the
data set being enciphered. However, you cannot specify delimiter parameters when
deciphering a data set. If DECIPHER is specified together with any REPRO
delimiter parameter, your REPRO command terminates with a message.

When the REPRO command copies and enciphers a data set, it precedes the
enciphered data records with one or more records of clear header data. The header
data preceding the enciphered data contains information necessary for the
deciphering of the enciphered data, such as:
v Number of header records
v Number of records to be ciphered as a unit
v Key verification data
v Enciphered data encrypting keys

Tip: If the output data set for the encipher operation is a compressed format data
set, little or no space is saved. Save space for the output if the input data set is in
compressed format and is compressed.

Encryption of VSAM Data Sets

When a VSAM relative record data set (RRDS) is enciphered, the record size of the
output data set must be at least four bytes greater than the record size of the
RRDS. (The extra four bytes are needed to prefix a relative record number to the
output record.) Specify the record size of an output VSAM entry-sequenced data
set through the RECORDSIZE parameter of the DEFINE CLUSTER command.
Specify the record size of an output sequential data set through the DCB LRECL
parameter in the DD statement of the output data set. When an enciphered RRDS
is deciphered with a RRDS as the target, any empty slots in the original data set
are reestablished. When a linear data set is enciphered, both the input and output
data sets must be linear data sets.

Chapter 5. Protecting Data Sets 65

Protecting Data Sets

Restriction: You should not build an alternate index over a VSAM

entry-sequenced data set that is the output of a REPRO ENCIPHER
operation.

Data Encryption Keys

Use the plaintext data encrypting key to encipher or decipher the data using the
Data Encryption Standard. REPRO lets you supply an 8-byte value as the plaintext
data encrypting key. If you do not supply the data encrypting key, REPRO
provides an 8-byte value to be used as the plaintext data encrypting key. Using the
REPRO DECIPHER option, you can either decipher the data on the system that it
was enciphered on or decipher the data on another system that has this functional
capability and the required key to decipher the data. Given the same key, encipher
and decipher are inverse operations.

If you supply your own plaintext data encrypting key on ENCIPHER or

DECIPHER through the REPRO command, you risk exposing that key when the
command is listed on SYSPRINT. To avoid this exposure, direct REPRO to a data
encrypting key data set to obtain the plaintext data encrypting key.

Secondary Key-Encrypting Keys

When you want to decipher the data, you must supply the data encrypting key
that enciphered the data. However, as a security precaution, you might want to
supply the data encrypting key in a disguised form. When enciphering the data
set, supply the name of a key-encrypting key. The REPRO command uses the
key-encrypting keys indicated by the supplied name to disguise the data
encrypting key. When deciphering the data set, supply the name of the file key
and the disguised data encrypting key rather than the plaintext data encrypting
key. In this way, the actual plaintext data encrypting key is not revealed.

You can use the Programmed Cryptographic Facility or ICSF to install the
secondary key-encrypting keys. If you are using the Programmed Cryptographic
Facility, use the Programmed Cryptographic Facility key generator utility to set up
the key pairs.

If you are using ICSF, use the Key Generation Utility Program (KGUP) to set up
the key pairs on both the encrypting and decrypting systems.

The key generator utility generates the key-encrypting keys you request and stores
the keys, in enciphered form, in the cryptographic key data set (CKDS). It lists the
external name of each secondary key and the plaintext form of the secondary key.
If the secondary encrypting key is to be used on a system other than the system on
which the keys were generated, the utility must also be run on the other system to
define the same plaintext key-encrypting keys. The plaintext key-encrypting keys
can be defined in the CKDS of the other system with different key names. If you
want to manage your own private keys, no key-encrypting keys are used to
encipher the data encrypting key; it is your responsibility to ensure the secure
nature of your private data encrypting key.

Related reading: For more information on setting up keys with KGUP, see z/OS
Cryptographic Services ICSF Administrator’s Guide.

REPRO ENCIPHER and DECIPHER on ICSF

In planning to use the ENCIPHER and DECIPHER functions of the REPRO
command, you should be aware of the following requirements:

66 z/OS V1R7.0 DFSMS Using Data Sets

 Protecting Data Sets

v Code COMPAT(YES) for the data set for the ICSF options. This option enables
REPRO to invoke the Programmed Cryptographic Facility macros on ICSF.
v If you are migrating from PCF to ICSF, convert the Programmed Cryptographic
Facility CKDS to ICSF format. New ICSF users do not need to perform this
conversion.
v If you are using ICSF, you must start it before executing the REPRO command.
If you are using the Programmed Cryptographic Facility, you must start it before
executing the REPRO command.

Chapter 5. Protecting Data Sets 67

Protecting Data Sets

68 z/OS V1R7.0 DFSMS Using Data Sets

Part 2. VSAM Access to Data Sets and UNIX Files
Chapter 6. Organizing VSAM Data Sets . . . . 73 Data Compression . . . . . . . . . . . . 100
VSAM Data Formats . . . . . . . . . . . 73
Data Set Size . . . . . . . . . . . . . 73 Chapter 7. Defining VSAM Data Sets . . . . . 103
Control Intervals . . . . . . . . . . . 74 Using Cluster Names for Data and Index
Control Information Fields . . . . . . . . 74 Components . . . . . . . . . . . . . . 104
Compressed Control Information Field . . . . 76 Defining a Data Set with Access Method Services 104
Control Areas. . . . . . . . . . . . . 77 Naming a Cluster . . . . . . . . . . . 104
Spanned Records . . . . . . . . . . . 77 Duplicate Data Set Names . . . . . . . 105
Selection of VSAM Data Set Types . . . . . . . 78 Temporary Data Set Names . . . . . . 105
Entry-Sequenced Data Sets . . . . . . . . 79 Specifying Cluster Information . . . . . . 106
Simulated VSAM Access to UNIX files . . . . 81 Using Access Method Services Parameters . . . 106
Record Processing for UNIX Files . . . . . 81 Descriptive Parameters . . . . . . . . 106
Restrictions on UNIX Files . . . . . . . 81 Performance Parameters . . . . . . . . 107
Services and Utilities for UNIX Files . . . . 82 Security and Integrity Parameters . . . . 108
Key-Sequenced Data Sets . . . . . . . . . 82 Allocating Space for VSAM Data Sets . . . . 108
Free Space . . . . . . . . . . . . . 83 Partial Release . . . . . . . . . . . 109
Considerations for Increasing Keys and Space 83 Small Data Sets . . . . . . . . . . . 109
Insertion of a Logical Record in a CI . . . . 84 Multiple Cylinder Data Sets . . . . . . 110
Prime Index . . . . . . . . . . . . 85 Linear Data Sets . . . . . . . . . . 110
Key Compression . . . . . . . . . . 85 Using VSAM Extents . . . . . . . . . 110
Control Interval Splits . . . . . . . . . 85 VSAM Extent Consolidation . . . . . . 111
Linear Data Sets . . . . . . . . . . . . 85 Calculating Space for the Data Component of a
Fixed-Length Relative-Record Data Sets . . . . 86 KSDS . . . . . . . . . . . . . . . 111
Variable-Length Relative-Record Data Sets . . . 87 Calculating Space for the Index Component . . 112
Summary of VSAM Data Set Types . . . . . 87 Using ALTER to Modify Attributes of a
Extended-Format VSAM Data Sets. . . . . . . 88 Component . . . . . . . . . . . . . 112
Restrictions on Defining Extended-Format Data Using ALTER to Rename Data Sets . . . . . 112
Sets . . . . . . . . . . . . . . . . 89 Defining a Data Set with JCL . . . . . . . . 113
VSAM Data Striping . . . . . . . . . . 89 Loading a VSAM Data Set . . . . . . . . . 113
Layering Concept for Data Striping . . . . 91 Using REPRO to Copy a VSAM Data Set . . . 114
Other Considerations for Data Striping . . . 92 Using a Program to Load a Data Set . . . . . 115
Compressed Data . . . . . . . . . . . 93 Reusing a VSAM Data Set as a Work File . . . 116
Access to Records in a VSAM Data Set . . . . . 94 Copying and Merging Data Sets . . . . . . . 117
Access to Entry-Sequenced Data Sets . . . . . 95 Defining Alternate Indexes . . . . . . . . . 119
Access to Key-Sequenced Data Sets . . . . . 95 Naming an Alternate Index . . . . . . . . 119
Keyed-Sequential Access . . . . . . . . 95 Specifying Alternate Index Information . . . . 119
Keyed-Direct Access . . . . . . . . . 95 Specifying Descriptive Information for an
Skip-Sequential Access. . . . . . . . . 96 Alternate Index . . . . . . . . . . . 120
Addressed Access . . . . . . . . . . 96 Specifying RECORDSIZE for an Alternate
Access to Linear Data Sets . . . . . . . . 96 Index with Nonunique Keys . . . . . . 120
Access to Fixed-Length Relative-Record Data Sets 96 Building an Alternate Index . . . . . . . 121
Keyed-Sequential Access . . . . . . . . 96 Maintaining Alternate Indexes . . . . . . . 121
Skip-Sequential Access. . . . . . . . . 96 How Reorganization Affects Alternate
Keyed-Direct Access . . . . . . . . . 97 Indexes . . . . . . . . . . . . . 122
Access to Variable-Length Relative-Record Data Alternate Index Backups. . . . . . . . 122
Sets . . . . . . . . . . . . . . . . 97 Defining a Path. . . . . . . . . . . . 122
Keyed-Sequential Access . . . . . . . . 97 Defining a Page Space . . . . . . . . . . 123
Skip-Sequential Access. . . . . . . . . 97 Checking for Problems in Catalogs and Data Sets 124
Keyed-Direct Access . . . . . . . . . 97 Listing Catalog Entries . . . . . . . . . 124
Access to Records through Alternate Indexes . . . 97 Printing the Contents of Data Sets . . . . . 125
Alternate Index Structure for a Key-Sequenced Deleting Data Sets . . . . . . . . . . . . 125
Data Set . . . . . . . . . . . . . . 98
Alternate Index Structure for an Entry-Sequenced Chapter 8. Defining and Manipulating VSAM
Data Set . . . . . . . . . . . . . . 99 Data Sets: Examples . . . . . . . . . . 127
Building of an Alternate Index . . . . . . 100 Example of Defining a VSAM Data Set . . . . . 128
Automatic Upgrade of Alternate Indexes . . . 100 Examples of Defining Temporary VSAM Data Sets 130

© Copyright IBM Corp. 1987, 2005 69

 Example 1: Defining a Temporary VSAM Data Optimizing Control Area Size . . . . . . . . 161
Set Using ALLOCATE . . . . . . . . . 130 Advantages of a Large Control Area Size . . . 162
Example 2: Creating a Temporary Data Set with Disadvantages of a Large Control Area Size . . 162
Default Parameter Values . . . . . . . . 131 Optimizing Free Space Distribution . . . . . . 162
Examples of Defining Alternate Indexes and Paths 131 Selecting the Optimal Percentage of Free Space 164
JCL Statements . . . . . . . . . . . . 131 Altering the Free Space Specification When
Commands . . . . . . . . . . . . . 132 Loading a Data Set . . . . . . . . . . 165
Determining I/O Buffer Space for Nonshared
Chapter 9. Processing VSAM Data Sets . . . . 135 Resource . . . . . . . . . . . . . . . 166
Creating an Access Method Control Block . . . . 136 Obtaining Buffers Above 16 MB . . . . . . 166
Creating an Exit List . . . . . . . . . . . 136 Virtual Storage Constraint Relief . . . . . 167
Opening a Data Set . . . . . . . . . . . 137 Dynamic Allocation Options for Reducing
Creating a Request Parameter List . . . . . . 138 Storage Usage . . . . . . . . . . . 167
Manipulating the Contents of Control Blocks . . . 140 Tuning for System-Managed Buffering . . . . 167
Generating a Control Block . . . . . . . . 140 Processing Techniques . . . . . . . . 168
Testing the Contents of ACB, EXLST, and RPL Internal Processing Techniques . . . . . 170
Fields . . . . . . . . . . . . . . . 140 Processing Guidelines and Restrictions . . . 170
Modifying the Contents of an ACB, EXLST, or General Considerations for the Use of SMB 172
RPL . . . . . . . . . . . . . . . 141 Allocating Buffers for Concurrent Data Set
Displaying the Contents of ACB, EXLST, and Positioning . . . . . . . . . . . . . 173
RPL Fields . . . . . . . . . . . . . 141 Allocating Buffers for Direct Access . . . . . 173
Requesting Access to a Data Set . . . . . . . 141 Data Buffers for Direct Access . . . . . . 173
Inserting and Adding Records . . . . . . . 142 Index Buffers for Direct Access . . . . . 173
Insertions into an Entry-Sequenced Data Set 142 Example of Buffer Allocation for Direct
Insertions into a Key-Sequenced Data Set . . 142 Access . . . . . . . . . . . . . . 174
Insertions into a Fixed-Length Allocating Buffers for Sequential Access . . . 175
Relative-Record Data Set . . . . . . . 143 Allocating Buffers for a Path . . . . . . . 176
Insertions into a Variable-Length Acquiring Buffers . . . . . . . . . . . 176
Relative-Record Data Set . . . . . . . 143 Using Index Options . . . . . . . . . . . 177
Insertions into a Linear Data Set . . . . . 144 Increasing Virtual Storage for Index Set Records 177
Retrieving Records . . . . . . . . . . 144 Avoiding Control Area Splits . . . . . . . 177
Sequential Retrieval . . . . . . . . . 144 Putting the Index and Data on Separate
POINT Macro for Positioning . . . . . . 145 Volumes . . . . . . . . . . . . . . 178
Direct Retrieval . . . . . . . . . . . 146 Obtaining Diagnostic Information . . . . . . 178
Updating Records . . . . . . . . . . . 146 Migrating from the Mass Storage System . . . . 178
Changing Record Length . . . . . . . 146 Using Hiperbatch . . . . . . . . . . . . 178
Processing the Data Component of a
Key-Sequenced Data Set . . . . . . . . 146 Chapter 11. Processing Control Intervals . . . 179
Deleting Records . . . . . . . . . . . 147 Access to a Control Interval . . . . . . . . 180
Deferring and Forcing Buffer Writing . . . . 147 Structure of Control Information . . . . . . . 181
Retaining and Positioning Data Buffers . . . . 147 CIDF—Control Interval Definition Field . . . 182
Processing Multiple Strings . . . . . . . . 148 RDF—Record Definition Field . . . . . . . 182
Making Concurrent Requests . . . . . . . 149 Control Field Values for Nonspanned
Using a Path to Access Records . . . . . . 149 Key-Sequenced, Entry-Sequenced, and
Making Asynchronous Requests . . . . . . 150 Variable-Length Relative Record Data Sets . . 183
Specifying Asynchronous Mode . . . . . 150 Control Field Values for Spanned
Checking for Completion of Asynchronous Key-Sequenced and Entry-Sequenced Data
Requests . . . . . . . . . . . . . 150 Sets . . . . . . . . . . . . . . 185
Ending a Request . . . . . . . . . . . 151 Control Field Values for Fixed-Length
Closing Data Sets . . . . . . . . . . . . 151 Relative-Record Data Sets . . . . . . . 186
Operating in SRB or Cross-Memory Mode . . . . 152 User Buffering . . . . . . . . . . . . . 186
Using VSAM Macros in Programs . . . . . . 153 Improved Control Interval Access . . . . . . 187
Opening an Object for Improved Control
Chapter 10. Optimizing VSAM Performance . . 157 Interval Access . . . . . . . . . . . . 187
Optimizing Control Interval Size . . . . . . . 157 Processing a Data Set with Improved Control
Control Interval Size Limitations . . . . . . 157 Interval Access . . . . . . . . . . . . 187
Physical Block Size and Track Capacity . . . 158 Fixing Control Blocks and Buffers in Real
Track Allocations versus Cylinder Allocations 159 Storage . . . . . . . . . . . . . . 188
Data Control Interval Size . . . . . . . . 159 Control Blocks in Common (CBIC) Option . . . 188
Index Control Interval Size . . . . . . . . 160
How VSAM Adjusts Control Interval Size . . . 160 Chapter 12. Sharing VSAM Data Sets . . . . 191

70 z/OS V1R7.0 DFSMS Using Data Sets

Subtask Sharing . . . . . . . . . . . . 192 | Using 64-Bit Addressable Data Buffers . . . . 225
Building a Single Control Block Structure . . . 192 | Setting a Data Class for 64-bit data buffering 225
Resolving Exclusive Control Conflicts . . . . 193 | Setting IGDSMSxx PARMLIB values for
Preventing Deadlock in Exclusive Control of | VSAM RLS data buffering . . . . . . . 225
Shared Resources . . . . . . . . . . . 195 Read Sharing of Recoverable Data Sets . . . . 226
Data Set Name Sharing . . . . . . . . 195 Read-Sharing Integrity across KSDS CI and CA
Consistent Processing Options . . . . . . 196 Splits . . . . . . . . . . . . . . . 227
Shared Subtasks . . . . . . . . . . 197 Read and Write Sharing of Nonrecoverable Data
Cross-Region Sharing . . . . . . . . . . . 197 Sets . . . . . . . . . . . . . . . 227
Cross-Region Share Options . . . . . . . 197 Using Non-RLS Access to VSAM Data Sets . . 227
Read Integrity During Cross-Region Sharing . . 198 | RLS Access Rules . . . . . . . . . . . 228
Invalidating Index Buffers . . . . . . . 199 Comparing RLS Access and Non-RLS Access 228
Invalidating Data Buffers . . . . . . . 199 Share Options . . . . . . . . . . . 228
Write Integrity During Cross-Region Sharing 199 Locking . . . . . . . . . . . . . 229
Cross-System Sharing . . . . . . . . . . 200 VSAM Options Not Used by RLS . . . . 230
Control Block Update Facility (CBUF) . . . . . 201 Requesting VSAM RLS Run-Mode . . . . . 231
Considerations for CBUF Processing . . . . . 202 Using VSAM RLS Read Integrity Options . . . 231
Checkpoints for Shared Data Sets. . . . . . 203 Using VSAM RLS with ESDS . . . . . . . . 232
Techniques of Data Sharing . . . . . . . . . 203 Specifying Read Integrity . . . . . . . . . 233
Cross-Region Sharing . . . . . . . . . . 203 Specifying a Timeout Value for Lock Requests . . 233
Cross-System Sharing . . . . . . . . . 205 | Index Trap . . . . . . . . . . . . . . 234
User Access to VSAM Shared Information . . . 206
Chapter 15. Checking VSAM Key-Sequenced
Chapter 13. Sharing Resources Among VSAM Data Set Clusters for Structural Errors . . . . 235
Data Sets . . . . . . . . . . . . . . 207 EXAMINE Command . . . . . . . . . . 235
Provision of a Resource Pool . . . . . . . . 207 Types of Data Sets . . . . . . . . . . . 235
Building a Resource Pool: BLDVRP . . . . . 207 EXAMINE Users . . . . . . . . . . . 235
Using Hiperspace Buffers with LSR . . . . 208 How to Run EXAMINE . . . . . . . . . . 236
Deciding the Size of a Virtual Resource Pool 209 Deciding to Run INDEXTEST, DATATEST, or
Displaying Information about an Unopened Both Tests . . . . . . . . . . . . . 236
Data Set . . . . . . . . . . . . . 210 Skipping DATATEST on Major INDEXTEST
Displaying Statistics about a Buffer Pool . . 210 Errors . . . . . . . . . . . . . . . 236
Connecting a Data Set to a Resource Pool: Examining a User Catalog . . . . . . . . 236
OPEN . . . . . . . . . . . . . . . 211 Understanding Message Hierarchy . . . . . 237
Deleting a Resource Pool Using the DLVRP Controlling Message Printout . . . . . . . 237
Macro . . . . . . . . . . . . . . . 211 Samples of Output from EXAMINE Runs . . . . 238
Management of I/O Buffers for Shared Resources 212 INDEXTEST and DATATEST Tests of an
Deferring Write Requests . . . . . . . . 212 Error-Free Data Set . . . . . . . . . . 238
Relating Deferred Requests by Transaction ID 213 INDEXTEST and DATATEST Tests of a Data Set
Writing Buffers Whose Writing is Deferred: with a Structural Error . . . . . . . . . 238
WRTBFR . . . . . . . . . . . . . . 213 INDEXTEST and DATATEST Tests of a Data Set
Handling Exits to Physical Error Analysis with a Duplicate Key Error . . . . . . . . 239
Routines . . . . . . . . . . . . . 214
Using the JRNAD Exit with Shared Chapter 16. Coding VSAM User-Written Exit
Resources . . . . . . . . . . . . 214 Routines . . . . . . . . . . . . . . 241
Accessing a Control Interval with Shared Guidelines for Coding Exit Routines . . . . . . 241
Resources . . . . . . . . . . . . . 215 Programming Guidelines . . . . . . . . . 242
Locating an RBA in a Buffer Pool: SCHBFR 215 Multiple Request Parameter Lists or Data Sets 243
Marking a Buffer for Output: MRKBFR . . . 215 Return to a Main Program . . . . . . . . 243
Restrictions and Guidelines for Shared Resources 216 IGW8PNRU Routine for Batch Override . . . . 244
Register Contents . . . . . . . . . . . 244
Chapter 14. Using VSAM Record-Level Sharing 219 Programming Considerations . . . . . . . 244
Controlling Access to VSAM Data Sets . . . . . 219 EODAD Exit Routine to Process End of Data . . . 245
Accessing Data Sets Using DFSMStvs and VSAM Register Contents . . . . . . . . . . . 245
Record-Level Sharing . . . . . . . . . . . 219 Programming Considerations . . . . . . . 246
Record-Level Sharing CF Caching . . . . . 220 EXCEPTIONEXIT Exit Routine . . . . . . . 246
Using VSAM RLS with CICS . . . . . . . 222 Register Contents . . . . . . . . . . . 246
Recoverable and Nonrecoverable Data Sets 224 Programming Considerations . . . . . . . 246
CICS Transactional Recovery for VSAM JRNAD Exit Routine to Journalize Transactions . . 247
Recoverable Data Sets . . . . . . . . 224 Register Contents . . . . . . . . . . . 247
Non-CICS Use of VSAM RLS . . . . . . . 225 Programming Considerations . . . . . . . 247

Part 2. VSAM Access to Data Sets and UNIX Files 71

 Journalizing Transactions . . . . . . . 248 Index Update Following a Control Interval Split 285
RBA Changes . . . . . . . . . . . 248 Index Entries for a Spanned Record . . . . . 286
Control Interval Splits . . . . . . . . 248
Parameter List . . . . . . . . . . . 250
LERAD Exit Routine to Analyze Logical Errors . . 253
Register Contents . . . . . . . . . . . 254
Programming Considerations . . . . . . . 254
RLSWAIT Exit Routine . . . . . . . . . . 254
Register Contents . . . . . . . . . . . 255
Request Environment . . . . . . . . . . 255
SYNAD Exit Routine to Analyze Physical Errors 256
Register Contents . . . . . . . . . . . 256
Programming Considerations . . . . . . . 256
Example of a SYNAD User-Written Exit Routine 257
UPAD Exit Routine for User Processing . . . . 258
Register Contents . . . . . . . . . . . 259
Programming Considerations . . . . . . . 260
User-Security-Verification Routine . . . . . . 261

Chapter 17. Using 31-Bit Addressing Mode with

VSAM . . . . . . . . . . . . . . . 263
VSAM Options . . . . . . . . . . . . . 263

Chapter 18. Using Job Control Language for

VSAM . . . . . . . . . . . . . . . 265
Using JCL Statements and Keywords . . . . . 265
Data Set Name . . . . . . . . . . . . 265
Disposition . . . . . . . . . . . . . 265
Creating VSAM Data Sets with JCL . . . . . . 266
Temporary VSAM Data Sets . . . . . . . 269
Data Set Names . . . . . . . . . . 269
Allocation . . . . . . . . . . . . 269
Restrictions for Temporary VSAM Data Sets 269
Examples Using JCL to Allocate VSAM Data
Sets . . . . . . . . . . . . . . . 270
Example 1: Allocate a Key-Sequenced Data
Set . . . . . . . . . . . . . . . 270
Example 2: Allocate a System-Managed
Key-Sequenced Data Set Using Keywords . . 271
Example 3: Allocate a VSAM Data Set Using
Keyword Defaults . . . . . . . . . . 271
Example 4: Allocate a Temporary VSAM
Data Set . . . . . . . . . . . . . 272
Example 5: Allocate a Temporary VSAM
Data Set Taking All Defaults . . . . . . 272
Retrieving an Existing VSAM Data Set . . . . . 273
Migration Consideration . . . . . . . . . 273
Keywords Used to Process VSAM Data Sets . . 273

Chapter 19. Processing Indexes of

Key-Sequenced Data Sets . . . . . . . . 275
Access to a Key-Sequenced Data Set Index . . . 275
Access to an Index with GETIX and PUTIX . . 275
Access to the Index Component Alone . . . . 275
Prime Index . . . . . . . . . . . . . 276
Index Levels . . . . . . . . . . . . . 277
Format of an Index Record . . . . . . . . . 279
Header Portion . . . . . . . . . . . . 279
Free Control Interval Entry Portion . . . . . 281
Index Entry Portion . . . . . . . . . . 281
Key Compression . . . . . . . . . . . . 282

72 z/OS V1R7.0 DFSMS Using Data Sets

 Chapter 6. Organizing VSAM Data Sets
This chapter covers the following topics.

Topic Location
VSAM Data Formats 73
VSAM Data Striping 89
Selection of VSAM Data Set Types 78
Extended-Format VSAM Data Sets 88
Access to Records in a VSAM Data Set 94
Access to Records through Alternate Indexes 97
Data Compression 100

VSAM Data Formats

The organization of data in all VSAM data sets, except linear data sets, is arranged
in records, also called logical records. A logical record is the user record requested
from, or given to, the VSAM record management function.

Logical records of VSAM data sets are stored differently from logical records in
non-VSAM data sets. VSAM stores records in control intervals. A control interval is
a continuous area of direct access storage that VSAM uses to store data records
and control information that describes the records. Whenever a record is retrieved
from direct access storage, the entire control interval containing the record is read
into a VSAM I/O buffer in virtual storage. The desired record is transferred from
the VSAM buffer to a user-defined buffer or work area. Figure 3 shows how a
logical record is retrieved from direct access storage.

DASD storage
Virtual storage

I/O buffer

CI I/O path R1 R2 R3

Work R2
area

CI = Control interval
R = Record

Figure 3. VSAM Logical Record Retrieval

Data Set Size

| The maximum size of a VSAM data set is 4 GB (4 294 967 295 bytes) unless it is
| defined with a data class that specifies a DSNTYPE of EXT (extended format) with
| the extended addressability (also in the data class) set to Y (yes). A VSAM data set

© Copyright IBM Corp. 1987, 2005 73

 Organizing VSAM Data Sets

| can be expanded to 123 extents per volume. In addition to the limit of 123 extents
| per volume, these are the other limits on the number of extents for a VSAM data
| set:
| v If non-SMS-managed, then up to 255 extents per component.
| v If SMS-managed, then the following are true:
| – If not striped and without the extent constraint removal parameter in the data
| class, then up to 255 extents per component.
| – If striped and without the extent constraint removal parameter in the data
| class, then up to 255 extents per stripe.
| – If the extent contraint removal parameter in the data class is set to a value of
| Y, then the number of extents is limited by the number of volumes for the
| data set.

| VSAM attempts to extend a data set when appropriate. Each attempt to extend the
| data set might result in up to five extents.

Related reading: For information about space allocation for VSAM data sets, see
“Allocating Space for VSAM Data Sets” on page 108.

Control Intervals
The size of control intervals can vary from one VSAM data set to another, but all
the control intervals within the data portion of a particular data set must be the
same length. Use the access method services DEFINE command and let VSAM
select the size of a control interval for a data set, or request a particular control
interval size. For information about selecting the best control interval size, see
“Optimizing Control Interval Size” on page 157.

A control interval consists of:

v Logical records
v Free space
v Control information fields

In a linear data set all of the control interval bytes are data bytes. There is no
imbedded control information.

Control Information Fields

Figure 4 on page 75 contains control information consisting of two types of fields:
one control interval definition field (CIDF), and one or more record definition
fields (RDFs).

74 z/OS V1R7.0 DFSMS Using Data Sets

 Organizing VSAM Data Sets

Figure 4. Control Interval Format

CIDFs are 4 bytes long, and contain the amount and location of free space. RDFs
are 3 bytes long, and describe the length of records and how many adjacent
records are of the same length.

If two or more adjacent records have the same length, only two RDFs are used for
this group. One RDF gives the length of each record, and the other gives the
number of consecutive records of the same length. Figure 5 shows RDFs for records
of the same and different lengths:

Chapter 6. Organizing VSAM Data Sets 75

Organizing VSAM Data Sets

Control interval 1
Control interval size = 512 bytes
Record length = 160-byte records
Record definition fields: Only 2 RDFs are needed because all
records are the same length.

R1 R2 R3 FS RDF RDF CIDF

2 3

Record length 160 160 160 22 3 3 4

Control interval 2
Control interval size = 512 bytes
Record length: All records have different lengths
Record definition fields: One RDF is required for each logical record
(RDF 1 for record 1, RDF 2 for record 2, and so forth.)

R1 R2 R3 R4 FS RDF RDF RDF RDF CIDF

4 3 2 1

130 70 110 140 46 3 3 3 3 4

Control Interval 3
Control interval size = 512 bytes
Record length: Records 1 through 3 are 80-byte records
Records 4 and 5 have different length
Record definition fields: Two RDFs are used for records 1 through 3
Record 4 and 5 each have their own RDF

R1 R2 R3 R4 R5 FS RDF RDF RDF RDF CIDF

80 80 80 100 93 63 3 3 3 3 4
FS = Free space

Figure 5. Record Definition Fields of Control Intervals

If a record exceeds the maximum record length, an error message is generated. If a

record in an entry-sequenced or key-sequenced data set, or variable-length RRDS is
smaller than the maximum record length, VSAM saves disk space by storing the
actual record length in the RDF. However, in a fixed-length RRDS, records do not
vary in length. The RDF reflects the length of the record slot, and cannot be
adjusted.

Compressed Control Information Field

Compressed data records in an extended-format key-sequenced data set have a
different format than noncompressed data records. This format includes a record
prefix that contains internal compression information. When the record is a
spanned record, each segment of the record contains a segment prefix with

76 z/OS V1R7.0 DFSMS Using Data Sets

 Organizing VSAM Data Sets

information similar to the record prefix for describing the segment. The length of
the record prefix for nonspanned records is 3 bytes, and the length for spanned
records is 5 bytes.

The stored record format has no affect on the data seen by the user as a result of a
VSAM GET request. In addition, no special processing is required to place the
record in the data set in a compressed format.

The presence of the record prefix does result in several incompatibilities that can
affect the definition of the key-sequenced data set or access to the records in the
key-sequenced data set. When a VSAM data set is in compressed format, VSAM
must be used to extract and expand each record to obtain data that is usable. If a
method other than VSAM is used to process a compressed data set and the
method does not recognize the record prefix, the end result is unpredictable and
could result in loss of data. See “Compressed Data” on page 93.

Control Areas
The control intervals in a VSAM data set are grouped together into fixed-length
contiguous areas of direct access storage called control areas. A VSAM data set is
actually composed of one or more control areas. The number of control intervals in
a control area is fixed by VSAM.

The maximum size of a control area is one cylinder, and the minimum size is one
track of DASD storage. When you specify the amount of space to be allocated to a
data set, you implicitly define the control area size. For information about defining
an alternate index, see “Defining Alternate Indexes” on page 119. For information
about optimizing control area size, see “Optimizing Control Area Size” on page
161.

Spanned Records
Sometimes a record is larger than the control interval size used for a particular
data set. In VSAM, you do not need to break apart or reformat such records,
because you can specify spanned records when defining a data set. The SPANNED
parameter permits a record to extend across or span control interval boundaries.

Spanned records might reduce the amount of DASD space required for a data set
when data records vary significantly in length, or when the average record length
is larger compared to the CI size. The following figures show the use of spanned
records for more efficient use of space.

In Figure 6, each control interval is 10 240 bytes long.

CI1 CI2 CI3

Con- Con- Con-

R Free space trol R FS trol R Free space trol
info info info

CI length 10240 bytes

Figure 6. Data Set with Nonspanned Records

In Figure 6 control interval 1 contains a 2000-byte record. Control interval 2

contains a 10 000-byte record. Control interval 3 contains a 2000-byte record. All
together, these three records use 30 720 bytes of storage.

Chapter 6. Organizing VSAM Data Sets 77

 Organizing VSAM Data Sets

Figure 7 contains a data set with the same space requirements as in Figure 6, but
one that permits spanned records.

CI1 CI2 CI3 CI4 CI5

Con- Con- Con- R Con- Con-

R FS trol R seg 1 trol R seg 2 trol seg FS trol R FS trol
info info info 3 info info

CI length 4096 bytes

Figure 7. Data Set with Spanned Records

The control interval size is reduced to 4096 bytes. When the record to be stored is
larger than the control interval size, the record is spanned between control
intervals. In Figure 7, control interval 1 contains a 2000-byte record. Control
| intervals 2, 3, and 4 together contain one 10 000-byte record. Control interval 5
| contains a 2000-byte record. By changing control interval size and permitting
spanned records, you can store the three records in 20 480 bytes, reducing the
amount of storage needed by 10 240 bytes.

Remember the following rules:

v A spanned record always begins on a control interval boundary and fills more
than one control interval within a single control area.
v For compressed data sets with spanned records, the length of the record prefix is
5 bytes. Because of the additional 5 bytes, the key offset plus the key length (that
is, relative key position) must be less than or equal to the CI size less 15.
v For key-sequenced data sets, the entire key field of a spanned record must be in
the first control interval.
v The control interval containing the last segment of a spanned record might also
contain unused space. Use the unused space only to extend the spanned record;
it cannot contain all or part of any other record.
v Spanned records can only be used with key-sequenced data sets and
entry-sequenced data sets.
v To span control intervals, you must specify the SPANNED parameter when you
define your data set. VSAM decides whether a record is spanned or
nonspanned, depending on the control interval length and the record length.
Spanned/nonspanned can also be specified in the data class.
v Locate mode (OPTCD=LOC on the RPL) is not a valid processing mode for
spanned records. A nonzero return code will be issued if locate mode is used.

Selection of VSAM Data Set Types

VSAM supports several data set types: entry-sequenced (ESDS), key-sequenced
(KSDS), linear (LDS), fixed-length, and variable-length relative record (RRDS).
Before you select a data set type, consider the following questions:
v Will you need to access the records in sequence, randomly, or both ways?
v Are all the records the same length?
v Will the record length change?
v How often will you need to move records?
v How often will you need to delete records?
v Do you want spanned records?
v Do you want to keep the data in order by the contents of the record?
v Do you want to access the data by an alternate index?

78 z/OS V1R7.0 DFSMS Using Data Sets

 Organizing VSAM Data Sets

v Do you want to use access method services utilities with an IBM DB2® cluster?

Entry-sequenced data sets are best for the following kinds of applications:
v Applications that require sequential access only. It is better to use
entry-sequenced data sets or variable-length RRDSs for sequential access,
because they support variable-length records and can be expanded as records
are added.
v Online applications that need to use an existing entry-sequenced data set. If you
want to use an entry-sequenced data set in an online application, load the data
set sequentially by a batch program and access the data set directly by the
relative byte address (RBA).

Key-sequenced data sets are best for the following kinds of applications:
v Applications that require that each record have a key field.
v Applications that require both direct and sequential access.
v Applications that use high-level languages which do not support RBA use.
v Online applications usually use key-sequenced data sets.
v You want to access the data by an alternate index.
v The advantage of key-sequenced data sets over fixed-length RRDS using direct
access is ease of programming.
v You want to have compressed data.

Linear data sets, although rarely used, are best for the following kinds of
applications:
v Specialized applications that store data in linear data sets
v Data-in-virtual (DIV)

Relative-record data sets are best for the following kinds of applications:
v Applications that require direct access only.
v Applications in which there is a one-to-one correspondence between records and
relative record numbers. For example, you could assign numeric keys to records
sequentially, starting with the value 1. Then, you could access a RRDS both
sequentially and directly by key.
v Fixed-length RRDSs use less storage and are usually faster at retrieving records
than key-sequenced data sets or variable-length RRDSs.
v If the records vary in length, use a variable-length RRDS.
v Variable-length RRDSs can be used for COBOL applications.

Entry-Sequenced Data Sets

An entry-sequenced data set is comparable to a sequential (non-VSAM) data set. It
contains records that can be either spanned or nonspanned. As Figure 8 on page 80
shows, records are sequenced by the order of their entry in the data set, rather
than by a key field in the logical record.

Chapter 6. Organizing VSAM Data Sets 79

Organizing VSAM Data Sets

R5
R4

R1 R2 R3

Figure 8. Entry-Sequenced Data Set

Records are added only at the end of the data set. Existing records cannot be
deleted. If you want to delete a record, you must flag that record as inactive. As
far as VSAM is concerned, the record is not deleted. Records can be updated, but
they cannot be lengthened. To change the length of a record in an entry-sequenced
data set, you must store it either at the end of the data set (as a new record) or in
the place of a record of the same length that you have flagged as inactive or that is
no longer required.

When a record is loaded or added, VSAM indicates its relative byte address (RBA).
The RBA is the offset of this logical record from the beginning of the data set. The
first record in a data set has an RBA of 0. The value of the RBA for the second and
subsequent records depends on whether the file is spanned and on the control
interval size chosen for the file, either manually or automatically. In general, it is
not possible to predict the RBA of each record, except for the case of fixed-length
records and a known control interval size. For a more detailed description of the
internal format of VSAM files, see “VSAM Data Formats” on page 73.

You build an alternate index to keep track of these RBAs. Although an

entry-sequenced data set does not contain an index component, alternate indexes
are permitted. See “Defining Alternate Indexes” on page 119. Figure 9 shows the
record lengths and corresponding RBAs for the data set shown in Figure 8.

RBA X'00' X'62' X'9A' X'D6' X'11C' X'162'

R1 R2 R3 R4 R5

Record Length 98 56 60 70 70

Figure 9. Example of RBAs of an Entry-Sequenced Data Set

Table 5 lists the operations and types of access for processing entry-sequenced data
sets.
Table 5. Entry-Sequenced Data Set Processing
Operation Sequential Access Direct Access
Loading the data set Yes No
Adding records Space after the last record is used for adding No
records
Retrieving records Yes (returned in entry sequence) Yes (by RBA)
Updating records Yes, but you cannot change the record length Yes (by RBA), but you cannot change the
record length
Deleting records Records cannot be deleted, but you can reuse Records cannot be deleted, but you can reuse
its space for a record of the same length its space for a record of the same length

80 z/OS V1R7.0 DFSMS Using Data Sets

 Organizing VSAM Data Sets

Simulated VSAM Access to UNIX files

You can have simulated VSAM access to a UNIX file (simulated as an ESDS) by
specifying PATH=pathname in the JCL DD statement, SVC 99, or TSO ALLOCATE
command. For information about access using MVS access methods, see
“Processing UNIX Files with an Access Method” on page 20.

When you use simulated VSAM, the application program sees the UNIX file as if it
were an ESDS.

Because the system does not actually store UNIX files as ESDSs, the system cannot
simulate all the characteristics of an ESDS. Certain macros and services have
incompatibilities or restrictions when dealing with UNIX files.

Related reading: For information about VSAM interfaces and UNIX files, see
Chapter 28, “Processing z/OS UNIX Files,” on page 481 and z/OS DFSMS Macro
Instructions for Data Sets.

Record Processing for UNIX Files

Record boundaries are not maintained within binary files. Text files are presumed
to be EBCDIC. Repositioning functions (such as POINT, CLOSE TYPE=T, GET
DIRECT) are not permitted for FIFO or character special files.

| When a file is accessed as binary, the length of each record is returned in the RPL
| as the largest possible record, except, possibly, the last record. The length of the
| last record is whatever remains after the previous GET or READ macro.

When a file is accessed as text, if any record in the file consists of zero bytes (that
is, a text delimiter is followed by another text delimiter), the record returned
consists of one blank. If any record is longer than the length of the buffer, it results
in an error return code for GET (for an ACB).

Restrictions on UNIX Files

The following VSAM restrictions are associated with UNIX files:
v Only ESDS is simulated.
v No file sharing or buffer sharing is supported except for multiple readers and, of
course, for a reader and a writer for FIFO.
v STRNO > 1 is not supported.
v Chained RPLs are not supported.
v Shared resources is not supported.
v Updated and backward processing is not supported.
v Direct processing or POINT for FIFO and character special files are not
supported.
| v There is no catalog support for UNIX files. The data set that contains the files
| might be cataloged.
v Alternate indexes are not supported.
v There is no support for JRNAD, UPAD, or the EXCEPTION exit.
v There is no cross-memory support.
v ERASE, VERIFY, and SHOWCAT are not supported.
v Certain SHOWCB requests return dummy values.
v Variable-length binary records do not retain record boundaries during
conversion to a byte stream. During reading, each record, except the last, is
assumed to be the maximum length.

Chapter 6. Organizing VSAM Data Sets 81

Organizing VSAM Data Sets

v To specify the maximum record size, code the LRECL keyword on the JCL DD
statement, SVC 99, or TSO ALLOCATE. If not specified, the default is 32 767.
v On return from a synchronous PUT or a CHECK associated with an
asynchronous PUT, it is not guaranteed that data written has been synchronized
to the output device. To ensure data synchronization, use ENDREQ, CLOSE, or
CLOSE TYPE=T.
v There is no CI (control interval) access (MACRF=CNV).

Services and Utilities for UNIX Files

The following services and utilities support UNIX files:
v Access method services (IDCAMS) REPRO—REPRO by DD name is supported
and uses QSAM.
v IDCAMS PRINT—PRINT by DD name is supported and uses QSAM. Instead of
displaying ’RBA OF RECORD’, PRINT displays ’RECORD NUMBER’.
v DEVTYPE macro—DEVTYPE provides information related to the UNIX file. If
PATH is specified in the DD statement, DEVTYPE returns a return code of 0, a
UCBTYP simulated value of X’00000103’, and a maximum block size of 32 760.

The following services and utilities do not support UNIX files. Unless stated
otherwise, these services and utilities return an error or unpredictable value when
issued for a UNIX file:
v IDCAMS—ALTER, DEFINE, DELETE, DIAGNOSE, EXAMINE, EXPORT,
IMPORT, LISTCAT, and VERIFY
v OBTAIN, SCRATCH, RENAME, TRKCALC, and PARTREL macros
These macros require a DSCB or UCB. z/OS UNIX files do not have DSCBs or
valid UCBs.

Guideline: ISPF Browse/Edit does not support UNIX files, but you can use the
OBROWSE command.

Key-Sequenced Data Sets

In a key-sequenced data set, logical records are placed in the data set in ascending
collating sequence by a field, called the key. Figure 10 shows that the key contains
a unique value, such as an employee number or invoice number, that determines
the record’s collating position in the data set.

Key Field

4265 654 1598 100

Part number Invoice number Unit price Quantity

The key must be:

Unique
In the same position in each record
In the first segment of a spanned record

Figure 10. Record of a Key-Sequenced Data Set

The key must be in the same position in each record, the key data must be
contiguous, and each record’s key must be unique. After it is specified, the value of

82 z/OS V1R7.0 DFSMS Using Data Sets

 Organizing VSAM Data Sets

the key cannot be altered, but the entire record can be erased or deleted. For
compressed data sets, the key itself and any data before the key will not be
compressed.

When a new record is added to the data set, it is inserted in its collating sequence
by key, as shown in Figure 11.

Key Field

654

198 389 771

Figure 11. Inserting Records into a Key-Sequenced Data Set

Table 6 lists the operations and types of access for processing key-sequenced data
sets.
Table 6. Key-Sequenced Data Set Processing
Direct or Skip-Sequential
Operation Sequential Access Access
Loading the data set Yes No
Adding records Yes (records must be written Yes (records are added
in key sequence) randomly by key)
Retrieving records Yes (records are returned in Yes (by key)
key sequence)
Updating records Yes Yes
Deleting records Yes Yes

Free Space
When a key-sequenced data set is defined, unused space can be scattered
throughout the data set to permit records to be inserted or lengthened. The unused
space is called free space. When a new record is added to a control interval (CI) or
an existing record is lengthened, subsequent records are moved into the following
free space to make room for the new or lengthened record. Conversely, when a
record is deleted or shortened, the space given up is reclaimed as free space for
later use. When you define your data set, use the FREESPACE parameter to specify
what percentage of each CI is to be set aside as free space when the data set is
initially loaded.

Within each CA, reserve free space by using free CIs. If you have free space in
your CA, it is easier to avoid splitting your control area when you want to insert
additional records or lengthen existing records. When you define your data set,
specify what percentage of the control area is to be set aside as free space, using
the FREESPACE parameter.

For information about specifying the optimal amount of CI and CA free space, see
“Optimizing Free Space Distribution” on page 162.

Considerations for Increasing Keys and Space

The structure of VSAM prime indexes for a KSDS and a VRRDS is built to create a
single index record at the lowest level of the index, the sequence set, to provide

Chapter 6. Organizing VSAM Data Sets 83

Organizing VSAM Data Sets

pointers to each CI within a single CA. Each entry contains a compressed value
representing the highest key that can be contained within that control interval. The
value stored for the control interval containing records with the highest key in that
control area represents the highest record-key value that can be contained in that
control area. Once all the records are deleted from any single control interval, the
current high-key value is no longer associated with that control interval’s entry in
the sequence set record. It becomes a “free” control interval in which records
containing any key within the range of keys for that control area can be inserted.
This is called a CI reclaim.

However, this does not apply when it is the last empty control interval within the
control area. In that case, the high-key value for that control interval is maintained
and it becomes the highest key for any record that can be inserted into that control
area. There is no reclaim capability for control areas that is comparable to that
provided for control intervals. What can occasionally be observed as a normal
result of not reclaiming control areas is data sets that just continue to grow in size.
This will result when applications continually add records with keys that are in
ascending sequence, followed by another or the same application that deletes old
records after they have undergone some type of processing. During the deletion
processing, the high-key value that was associated with that CA will be
maintained, requiring that only records falling within that high-key range are
eligible for insertion into that control area.

Since the record keys are always getting higher, no additional records will qualify
for insertion into these empty control areas. The result is a data set in which a
majority of the space is occupied by empty control intervals. When such a
condition is detected, the only option a user has to reclaim this space is to rebuild
the data set. This will require a logical copy of the data set, followed by a deletion
of the old data set and a reload operation from the logical copy.

For more information, see z/OS DFSMS Managing Catalogs.

Insertion of a Logical Record in a CI

Figure 12 shows how CI free space is used to insert and delete a logical record in a
KSDS or variable-length RRDS.

Figure 12. Inserting a Logical Record into a CI

Two logical records are stored in the first control interval shown in Figure 12. Each
logical record has a key (11 and 14). The second control interval shows what
happens when you insert a logical record with a key of 12.

84 z/OS V1R7.0 DFSMS Using Data Sets

 Organizing VSAM Data Sets

1. Logical record 12 is inserted in its correct collating sequence in the CI.

2. The CI definition field (CIDF) is updated to show the reduction of available
free space.
3. A corresponding record definition field (RDF) is inserted in the appropriate
location to describe the length of the new record.

When a record is deleted, the procedure is reversed, and the space occupied by the
logical record and corresponding RDF is reclaimed as free space.

Prime Index
A key-sequenced data set always has a prime index that relates key values to the
relative locations of the logical records in a data set. The prime index, or simply
index, has two uses in locating:
v The collating position when inserting records
v Records for retrieval

When initially loading a data set, records must be presented to VSAM in key
sequence. The index for a key-sequenced data set is built automatically by VSAM
as the data set is loaded with records.

When a data control interval is completely loaded with logical records, free space,
and control information, VSAM makes an entry in the index. The entry consists of
the highest possible key in the data control interval and a pointer to the beginning
of that control interval.

Key Compression
The key in an index entry is stored by VSAM in a compressed form. Compressing
the key eliminates from the front and back of a key those bytes that are not
necessary to distinguish it from the adjacent keys. Compression helps achieve a
smaller index by reducing the size of keys in index entries. VSAM automatically
does key compression in any key-sequenced data set. It is independent of whether
the data set is in compressed format.

Control Interval Splits

When a data set is first loaded, the key sequence of data records and their physical
order are the same. However, when data records are inserted, control interval splits
can occur, causing the data control intervals to have a physical order that differs
from the key sequence.

Linear Data Sets

A linear data set is a VSAM data set with a control interval size of 4096 bytes to 32
768 bytes in increments of 4096 bytes. A linear data set does not have imbedded
control information. All linear data set bytes are data bytes.

| A linear data set is processed as an entry-sequenced data set, with certain

| restrictions. Because a linear data set does not contain control information (CIDFs
| and RDFs), it cannot be accessed as if it contained individual records. You can
| access a linear data set using these techniques:
| v VSAM
| v DIV, if the control interval size is 4096 bytes.
| v Window services, if the control interval size is 4096 bytes.

Related reading: For information about using data-in-virtual (DIV), see z/OS MVS
Programming: Assembler Services Guide.

Chapter 6. Organizing VSAM Data Sets 85

Organizing VSAM Data Sets

Fixed-Length Relative-Record Data Sets

A fixed-length RRDS consists of several fixed-length slots. A fixed-length RRDS is
defined using NUMBERED and a RECORDSIZE whose average and maximum
lengths are the same.

Each slot has a unique relative record number, and the slots are sequenced by
ascending relative record number. Each record occupies a slot and is stored and
retrieved by the relative record number of that slot. The position of a data record is
fixed; its relative record number cannot change. A fixed-length RRDS cannot have
a prime index or an alternate index.

Because the slot can either contain data or be empty, a data record can be inserted
or deleted without affecting the position of other data records in the fixed-length
RRDS. The record definition field (RDF) shows whether the slot is occupied or
empty. Free space is not provided in a fixed-length RRDS because the entire data
set is divided into fixed-length slots.

In a fixed-length RRDS, each control interval contains the same number of slots.
The number of slots is determined by the control interval size and the record
length. Figure 13 shows the structure of a fixed-length RRDS after adding a few
records. Each slot has a relative record number and an RDF. Table 7 shows the
access options available for RRDS processing.

Figure 13. Fixed-length Relative-Record Data Set

Table 7 lists the operations and types of access for processing fixed-length RRDSs.
Table 7. RRDS Processing
Direct or Skip- Sequential
Operation Sequential Access Access
Loading the data set Yes Yes
Adding records Yes (empty slots are used) Yes (empty slots are used)
Retrieving records Yes Yes (by relative record
number)

86 z/OS V1R7.0 DFSMS Using Data Sets

 Organizing VSAM Data Sets

Table 7. RRDS Processing (continued)

Direct or Skip- Sequential
Operation Sequential Access Access
Updating records Yes Yes
Deleting records Yes (a slot given up by a Yes (a slot given up by a
deleted record can be reused) deleted record can be reused)

Variable-Length Relative-Record Data Sets

A variable-length RRDS (VRRDS) is similar to a fixed-length RRDS, except that it
contains variable-length records. Each record has a unique relative record number,
and is placed in ascending relative record number order. Each record is stored and
retrieved using its relative record number. Unlike a fixed-length RRDS, a
variable-length RRDS does not have slots. The relative record number of a record
cannot change. When that record is erased, the relative record number can be
reused for a new record.

You must load the variable-length RRDS sequentially in ascending relative record
number order. To define a variable-length RRDS, specify NUMBERED and
RECORDSIZE. The average record length and maximum record length in
RECORDSIZE must be different.

Free space is used for inserting and lengthening variable-length RRDS records.
When a record is deleted or shortened, the space given up is reclaimed as free
space for later use. When you define your data set, use the FREESPACE parameter
to specify what percentage of each control interval and control area is to be set
aside as free space when the data set is initially loaded. “Insertion of a Logical
Record in a CI” on page 84 shows how free space is used to insert and delete a
logical record.

A variable-length RRDS cannot have spanned records and alternate indexes.

VRRDS is a KSDS processed as an RRDS so a prime index is created.

Variable-length RRDS performance is similar to a key-sequenced data set, and is

slower than for a fixed-length RRDS. Table 8 shows the operations available for
key-sequenced data sets and direct or skip-sequential access.
Table 8. Variable-Length RRDS Processing
Direct or Skip- Sequential
Operation Sequential Access Access
Loading the data set Yes, in ascending relative No
record number order
Adding records Yes Yes (free space is used)
Retrieving records Yes Yes (by relative record
number)
Updating records Yes Yes
Deleting records Yes (free space is reclaimed) Yes (free space is reclaimed)

Summary of VSAM Data Set Types

Table 9 summarizes what each data set format offers.

Chapter 6. Organizing VSAM Data Sets 87

 Organizing VSAM Data Sets

Table 9. Comparison of ESDS, KSDS, Fixed-Length RRDS, Variable-Length RRDS, and Linear Data Sets
Variable-Length
ESDS KSDS Fixed-Length RRDS RRDS Linear Data Sets
Records are in order Records are in Records are in relative Records are in relative No processing at
as they are entered collating sequence by record number order record number order record level
key field
Direct access by RBA Direct access by key Direct access by Direct access by Access with
or by RBA relative record relative record data-in-virtual (DIV)
number number
Alternate indexes Alternate indexes No alternate indexes No alternate indexes No alternate indexes
permitted1 permitted permitted permitted permitted
A record’s RBA A record’s RBA can A record’s relative A record’s relative No processing at
cannot change change record number cannot record number cannot record level
change change
Space at the end of Free space is used for Empty slots in the Free space is used for No processing at
the data set is used inserting and data set are used for inserting and record level
for adding records lengthening records adding records lengthening records
A record cannot be Space given up by a A slot given up by a Space given up by a No processing at
deleted, but you can deleted or shortened deleted record can be deleted or shortened record level
reuse its space for a record becomes free reused record becomes free
record of the same space space
length1
Spanned records Spanned records No spanned records No spanned records No spanned records
permitted permitted
Extended format Extended format or Extended format Extended format Extended format
permitted1 compression permitted permitted permitted
permitted
Note:
1. Not supported for HFS data sets.

Extended-Format VSAM Data Sets

| VSAM extended format data sets might have any combination of the following
| optional attributes:
| v Data striping. This is called a striped data set.
| v Data compression. This is called a compressed format data set.
| v Extended addressability.
| For example, a data set might be a striped compressed format data set with
| extended addressability. Striping can reduce sequential access time. Compression
| can reduce the disk space. Extended addressability increases the maximum size of
| the data set.

VSAM data sets must also be in extended-format to be eligible for the following
advanced functions:
v Partial space release (PARTREL)
v Candidate volume space
v System-managed buffering (SMB)

An extended-format data set for VSAM can be allocated for key-sequenced data
sets, entry-sequenced data sets, variable-length or fixed-length relative-record data
sets, and linear data sets.

88 z/OS V1R7.0 DFSMS Using Data Sets

 Organizing VSAM Data Sets

Certain types of key-sequenced data set types are excluded. The following data
sets cannot have an extended format:
v Catalogs
v Other system data sets
v Temporary data sets

When a data set is allocated as an extended format data set, the data and index are
extended format. Any alternate indexes related to an extended format cluster are
also extended format.

If a data set is allocated as an extended format data set, 32 bytes (X’20’) are added
to each physical block. Consequently, when the control interval size is calculated or
explicitly specified, this physical block overhead may increase the amount of space
actually needed for the data set. Figure 14 shows the percentage increase in space
as indicated. Other control intervals do not result in an increase in needed space

- 3390 Direct Access Device

Control Interval Size Additional Space Required

512 2.1%
1536 4.5%
18432 12.5%

- 3380 Direct Access Device

Control Interval Size Additional Space Required

512 2.2%
1024 3.2%

Figure 14. Control Interval Size

Restrictions on Defining Extended-Format Data Sets

The following restrictions apply to defining extended-format data sets:
v An extended-format data set does not permit the indexes to be imbedded with
the data (IMBED parameter) or the data to be split into key ranges
(KEYRANGES parameter).
| v Extended-format data sets must be SMS managed. These are the mechanisms for
| requesting extended format for VSAM data sets:
| – Using a data class that has a DSNTYPE value of EXT and the subparameter R
| or P to indicate required or preferred.
| – Coding DSNTYPE=EXTREQ (extended format is required) or
| DSNTYPE=EXTPREF (extended format is preferred) on the DD statement.
| – Coding the LIKE= parameter on the DD statement to refer to an existing
| extended format data set.
v An open for improved control interval (ICI) processing is not permitted for
extended format data sets.

VSAM Data Striping

To use striped data, a data set must be in extended format. All VSAM data set
organizations are supported for striped data:
v Key-sequenced data set (KSDS)
v Entry-sequenced data set (ESDS)
v Relative-record data set (RRDS)
v Variable-length relative-record data set (VRRDS)
v Linear data set (LDS)

Chapter 6. Organizing VSAM Data Sets 89

Organizing VSAM Data Sets

A striped data set has tracks that spread across multiple devices, as is the case for
sequential access method or the CIs for VSAM. This format allows a single
application request for records in multiple tracks or CIs to be satisfied by
concurrent I/O requests to multiple volumes. The result is improved performance
for sequential data access by achieving data transfer into the application at a rate
greater than any single I/O path. The scheduling of I/O to multiple devices to
satisfy a single application request is referred to as an I/O packet.

VSAM data striping applies only to data sets that are defined with more than one
stripe. Any data set listed with one stripe is in the extended format and is not
considered to be a striped data set.

Figure 15 illustrates primary and secondary space allocations on multiple volumes

for a striped VSAM data set.

Stripe 1 Stripe 2 Stripe 3

Layer 1:

VOLA - single primary allocation VOLA VOLB VOLC

VOLB - single primary allocation

VOLC - single primary allocation

Layer 2:

VOLA - single secondary allocation VOLD

VOLD - single secondary allocation

VOLC - single secondary allocation

Layer 3:

VOLE - two secondary allocations VOLE VOLF VOLG

VOLF - two secondary allocations

VOLG - two secondary allocations

Primary space allocation

Secondary space allocation

DA6D4999

Figure 15. Primary and Secondary Space Allocations for Striped Data Sets

Figure 16 shows examples of the CIs within a control area (CA) on multiple
volumes for a four-stripe VSAM data set.

90 z/OS V1R7.0 DFSMS Using Data Sets

 Organizing VSAM Data Sets

Figure 16. Control Interval in a Control Area

Layering Concept for Data Striping

Layering is a concept generally associated with data that is striped. A layer in a
striped environment is defined as the relationship of the volumes that make up the
total number of stripes. That is, those volumes that will participate as part of the
I/O packet. Once any volume or volumes, up to a maximum of stripe count,
composing this I/O packet changes, this constitutes another layer. As relates to
striped data, the volumes that constitute this I/O packet should be viewed in the
same context as a single volume data set, as opposed to multivolume if the data
were not striped. Once the data set extends to a second layer, this would be
analogous to a multivolume nonstriped data set. Again, the definition of striped is
a stripe count greater than 1. The sequential access method (SAM) does not
support the concept of multilayering. VSAM supports multilayering. Figure 17
shows an example of the concept of layering with a four-stripe data set.

Chapter 6. Organizing VSAM Data Sets 91

Organizing VSAM Data Sets

Figure 17. Layering (Four-Stripe Data Set)

Other Considerations for Data Striping

To use data striping, you also need to consider space allocation, control area size,
and processing.

Space Allocation for Striped VSAM Data Sets: The general rules discussed for
striped extended format data sets apply to striped VSAM data sets. When the
system allocates space for a striped extended-format data set, the system divides
the primary amount among the volumes. If it does not divide evenly, the system
rounds up the amount. For extended-format data sets, when the primary space on
any volume is full, the system allocates space on that volume. The amount is the
secondary amount divided by the number of stripes. If the secondary amount does
not divide evenly, the system rounds up the amount.

Some additional considerations apply to the control area (CA) for VSAM. All
allocations must be rounded to a CA boundary. The number of stripes influences
the size of the control area, resulting in some differences in allocation quantity
required to meet the stripe count and CA requirements. The following section on
CA size considerations discusses this in more detail.

All data set extends are as described for striped data set extends. Basically, the
system divides the secondary amount by the stripe count and allocates the result
to each stripe. This occurs in all cases, including a data set with the guaranteed
space attribute from the associated storage class (SC), as well as extending to a
new layer.

Restriction: Volume High Used RBA statistics do not apply for multistriped VSAM
data sets. The high-use RBA is kept on the volume for the first stripe because the
value is the same for all stripes.

Secondary Allocation Quantity of Zero: When you specify a secondary allocation

quantity of zero for nonstriped VSAM data sets, an extend causes the allocation to
occur on a new volume, using the primary-space amount. You can also use this
feature to spread data over multiple volumes. For striped VSAM data sets,

92 z/OS V1R7.0 DFSMS Using Data Sets

 Organizing VSAM Data Sets

extensions occur by stripe and can occur on the same volume or on a new volume,
using the primary-space amount when a secondary-space amount of zero is
specified.

Increased Number of Extents: A striped VSAM data set can have 255 extents per
stripe in the data component. Only the data component is striped. The index
component of a striped VSAM data set has a limit of 255 extents, regardless of
striping. Because a striped VSAM data set can have a maximum of 16 stripes, a
striped data component can have a maximum of 4080 extents.

| Starting in z/OS V1R7, the 255-extent per stripe limit is removed if the extent
| constraint removal parameter in the data class is set to Y (yes). The default value is
| N (no), to enforce the 255-extent limit. This limit should be enforced if the data set
| may be shared with a pre-V1R7 system.

Allocation Restrictions: The Space Constraint Relief attribute will not be considered
for striped data sets. The intended purposes for data striping follow:
v Spread the data across volumes (a basic implementation technique for any data
that is striped).
v Provide >5 extent relief (completed for all allocations for VSAM striped data,
regardless of the specification).

Control Area Size Calculation: The control area (CA) size for striped VSAM data
is a factor of the stripe count. A VSAM striped data set can be striped up to a
count of 16. The minimum size for an allocation is a single track. The maximum
CA size is a cylinder. Traditionally that would have meant that the maximum CA
size, based on 3390 geometry, would be 15 tracks. That changes with striped
VSAM data set in that the maximum CA size now has to accommodate the
maximum stripe count (16), and the maximum CA now becomes 16 tracks.

The required allocation quantity now becomes a factor of both user specified
amount and stripe count. As an example, take a specification for space of
TRACKS(1 1) with the following results:
v For nonstriped, traditional VSAM, a control areas size of one track with a
resulting primary and secondary allocation quantity of 1 track.
v For a striped data set with a striped count = maximum =16, the control area size
is then 16 tracks with a resulting primary and secondary quantity of 16 tracks.

A larger CA results in a larger number of control intervals (CIs) in the CA,

resulting in a larger number of entries to index in a data set organization
containing an index (KSDS and VRRDS), with the end result being a requirement
for a larger index CI size.

Processing Considerations for Striped Data Sets: The basic restrictions associated
with data sets in the extended format also apply to striped data sets.

In addition, VSAM striped data sets do not support:

v RLS access
v Improved CI access

For the alternate index, neither the data nor the index will be striped.

Compressed Data
To use compression, a data set must be in extended format. Only extended-format
key-sequenced data sets can be compressed. The compressed data records have a

Chapter 6. Organizing VSAM Data Sets 93

Organizing VSAM Data Sets

slightly different format than logical records in a data set that will not hold
compressed data. This results in several incompatibilities that can affect the
definition of the data set or access to records in the data set:
v The maximum record length for nonspanned data sets is three bytes less than
the maximum record length of data sets that do not contain compressed data
(this length is CISIZE−10).
v The relative byte address (RBA) of another record, or the address of the next
record in a buffer, cannot be determined using the length of the current record
or the length of the record provided to VSAM.
v The length of the stored record can change when updating a record without any
length change.
v The key and any data in front of the key will not be compressed. Data sets with
large key lengths and RKP data lengths might not be good candidates for
compression.
v Only the data component of the base cluster is eligible for compression.
Alternate indexes are not eligible for compression.
v The global shared resources (GSR) option is not permitted for compressed data
sets.

In addition to these incompatibilities, the data set must meet certain requirements
to permit compression at the time it is allocated:
v The data set must have a primary allocation of at least 5 MBs, or 8 MBs if no
secondary allocation is specified.
v The maximum record length specified must be at least key offset plus key length
plus forty bytes.
v Compressed data sets must be SMS managed. The mechanism for requesting
compression for VSAM data sets is through the SMS data class
COMPACTION=Y parameter.

Spanned record data sets require the key offset plus the key length to be less than
or equal to the control interval size minus fifteen. These specifications regarding
the key apply to alternate keys as well as primary keys.

Compressed data sets cannot be accessed using control interval (CI) processing
except for VERIFY and VERIFY REFRESH processing and may not be opened for
improved control interval (ICI) processing. A compressed data set can be created
using the LIKE keyword and not just using a data class.

Access to Records in a VSAM Data Set

You can use addressed-sequential and addressed-direct access for the following
types of data sets:
v Entry-sequenced data sets
v Key-sequenced data sets
You can use keyed-sequential, keyed-direct, and skip-sequential access for the
following types of data sets:
v Key-sequenced data sets
v Fixed-length RRDSs
v Variable-length RRDS

All types of VSAM data sets, including linear, can be accessed by control interval
access, but this is used only for very specific applications. CI mode processing is
not permitted when accessing a compressed data set. The data set can be opened

94 z/OS V1R7.0 DFSMS Using Data Sets

 Organizing VSAM Data Sets

for CI mode processing to permit VERIFY and VERIFY REFRESH processing only.
Control interval access is described in Chapter 11, “Processing Control Intervals,”
on page 179.

Access to Entry-Sequenced Data Sets

Entry-sequenced data sets are accessed by address, either sequentially or directly.
When addressed sequential processing is used to process records in ascending
relative byte address (RBA) sequence, VSAM automatically retrieves records in
stored sequence.

To access a record directly from an entry-sequenced data set, you must supply the
RBA for the record as a search argument. For information about obtaining the
RBA, see “Entry-Sequenced Data Sets” on page 79.

Skip-sequential processing is not supported for entry-sequenced data sets.

Access to Key-Sequenced Data Sets

The most effective way to access records of a key-sequenced data set is by key,
using the associated prime index.

Keyed-Sequential Access
Sequential access is used to load a key-sequenced data set and to retrieve, update,
add, and delete records in an existing data set. When you specify sequential as the
mode of access, VSAM uses the index to access data records in ascending or
descending sequence by key. When retrieving records, you do not need to specify
key values because VSAM automatically obtains the next logical record in
sequence.

Sequential processing can be started anywhere within the data set. While
positioning is not always required (for example, the first use of a data set starts
with the first record), it is best to specify positioning using one of the following
methods:
v Use the POINT macro.
v Issue a direct request with note string positioning (NSP), and change the request
parameter list with the MODCB macro from “direct” to “sequential” or “skip
sequential”.
v Use MODCB to change the request parameter list to last record (LRD), backward
(BWD), and direct NSP; then change the RPL to SEQ, BWD, and SEQ.

Sequential access enables you to avoid searching the index more than once.
Sequential is faster than direct for accessing multiple data records in ascending key
order.

Keyed-Direct Access
Direct access is used to retrieve, update, delete and add records. When direct
processing is used, VSAM searches the index from the highest level index-set
record to the sequence-set for each record to be accessed. Searches for single
records with random keys is usually done faster with direct processing. You need
to supply a key value for each record to be processed.

For retrieval processing, either supply the full key or a generic key. The generic
key is the high-order portion of the full key. For example, you might want to
retrieve all records whose keys begin with the generic key AB, regardless of the

Chapter 6. Organizing VSAM Data Sets 95

 Organizing VSAM Data Sets

full key value. Direct access lets you avoid retrieving the entire data set
sequentially to process a small percentage of the total number of records.

Skip-Sequential Access
Skip-sequential access is used to retrieve, update, delete, and add records. When
skip-sequential is specified as the mode of access, VSAM retrieves selected records,
but in ascending sequence of key values. Skip-sequential processing lets you avoid
retrieving a data set or records in the following inefficient ways:
v Entire data set sequentially to process a small percentage of the total number of
records
v Desired records directly, which would cause the prime index to be searched
from the top to the bottom level for each record

Addressed Access
Another way of accessing a key-sequenced data set is addressed access, using the
RBA of a logical record as a search argument. If you use addressed access to
process key-sequenced data, you should be aware that RBAs might change when a
control interval split occurs or when records are added, deleted, or changed in size.
With compressed data sets, the RBAs for compressed records are not predictable.
Therefore, access by address is not suggested for normal use.

Access to Linear Data Sets

| You can access a linear data set with VSAM, the DIV macro, or window services.

The following family of window services for accessing linear data sets is described
in z/OS MVS Programming: Assembler Services Guide and z/OS MVS Programming:
Assembler Services Reference ABE-HSP:
v CSRIDAC -- Request or Terminate Access to a Data Object
v CSRVIEW -- View an Object
v CSREVW -- View an Object and Sequentially Access It
v CSRREFR -- Refresh an Object
v CSRSCOT -- Save Object Changes in a Scroll Area
v CSRSAVE -- Save Changes Made to a Permanent Object

Related reading: For information about using data-in-virtual (DIV), see z/OS MVS
Programming: Assembler Services Guide.

Access to Fixed-Length Relative-Record Data Sets

The relative record number is always used as a search argument for a fixed-length
RRDS.

Keyed-Sequential Access
Sequential processing of a fixed-length RRDS is the same as sequential processing
of an entry-sequenced data set. Empty slots are automatically skipped by VSAM.

Skip-Sequential Access
Skip-sequential processing is treated like direct requests, except that VSAM
maintains a pointer to the record it just retrieved. When retrieving subsequent
records, the search begins from the pointer, rather than from the beginning of the
data set. Records must be retrieved in ascending sequence.

96 z/OS V1R7.0 DFSMS Using Data Sets

 Organizing VSAM Data Sets

Keyed-Direct Access
A fixed-length RRDS can be processed directly by supplying the relative record
number as a key. VSAM converts the relative record number to an RBA and
determines the control interval containing the requested record. If a record in a slot
flagged as empty is requested, a no-record-found condition is returned. You cannot
use an RBA value to request a record in a fixed-length RRDS.

Access to Variable-Length Relative-Record Data Sets

The relative record number is used as a search argument for a variable-length
RRDS.

Keyed-Sequential Access
Sequential processing of a variable-length RRDS is the same as for an
entry-sequenced data set. On retrieval, relative record numbers that do not exist
are skipped. On insert, if no relative record number is supplied, VSAM uses the
next available relative record number.

Skip-Sequential Access
Skip-sequential processing is used to retrieve, update, delete, and add
variable-length RRDS records. Records must be retrieved in ascending sequence.

Keyed-Direct Access
A variable-length RRDS can be processed directly by supplying the relative record
number as a key. If you want to store a record in a specific relative record position,
use direct processing and assign the desired relative record number. VSAM uses
the relative record number to locate the control interval containing the requested
record. You cannot use an RBA value to request a record in a variable-length
RRDS.

Access to Records through Alternate Indexes

You can use access method services to define and build one or more alternate
indexes over a key-sequenced or entry-sequenced data set, which is called the base
cluster. An alternate index provides access to records by using more than one key.
The alternate index accesses records in the same way as the prime index of a
key-sequenced data set. An alternate index eliminates the need to store multiple
copies of the same information for different applications. The alternate index is
built from all the records in a base cluster. However, it is not possible to build an
alternate index from only specific records in the base cluster.

Unlike a primary key, which must be unique, the key of an alternate index can
refer to more than one record in the base cluster. An alternate-key value that points
to more than one record is nonunique. If the alternate key points to only one
record, the pointer is unique.

Restriction: The maximum number of nonunique pointers associated with an

alternate index data record cannot exceed 32 767.

Alternate indexes are not supported for linear data sets, RRDS, or reusable data
sets (data sets defined with the REUSE attribute). For information about defining
and building alternate indexes, see “Defining Alternate Indexes” on page 119.

The alternate index is a key-sequenced data set; it consists of an index component

and a data component. The records in the data component contain an alternate key

Chapter 6. Organizing VSAM Data Sets 97

Organizing VSAM Data Sets

and one or more pointers to data in the base cluster. For an entry-sequenced base
cluster, the pointers are RBA values. For a key-sequenced base cluster, the pointers
are primary-key values.

Each record in the data component of an alternate index is of variable length and
contains header data, the alternate key, and at least one pointer to a base data
record. Header data is fixed length and provides the following information:
v Whether the alternate index data record contains primary keys or RBA pointers
v Whether the alternate index data record contains unique or nonunique keys
v The length of each pointer
v The length of the alternate key
v The number of pointers

Alternate Index Structure for a Key-Sequenced Data Set

Figure 18 shows the structure of an alternate index with nonunique keys connected
to a key-sequenced data set. The person’s name is the alternate key in this
example. The customer number is the primary key.

Figure 18. Alternate Index Structure for a Key-Sequenced Data Set

If you ask to access records with the alternate key of BEN, VSAM does the
following:

98 z/OS V1R7.0 DFSMS Using Data Sets

 Organizing VSAM Data Sets

1. VSAM scans the index component of the alternate index, looking for a value
greater than or equal to BEN.
2. The entry FRED points VSAM to a data control interval in the alternate index.
3. VSAM scans the alternate index data control interval looking for an entry that
matches the search argument, BEN.
4. When located, the entry BEN has an associated key, 21. The key, 21, points
VSAM to the index component of the base cluster.
5. VSAM scans the index component for an entry greater than or equal to the
search argument, 21.
6. The index entry, 38, points VSAM to a data control interval in the base cluster.
The record with a key of 21 is passed to the application program.
RBAs are always written as fullword binary integers.

Alternate Index Structure for an Entry-Sequenced Data Set

Figure 19 illustrates the structure of an alternate index connected to an
entry-sequenced data set. The salesman’s name is the alternate key in this example.

H
Index a D FRED TOM
R

b
c
Alternate H Con-
Index D BEN 400 BILL 000 FRED 140 540 940 Free space trol
R info

Data d

H Con-
D MIKE 12 TOM 10 41 54 Free space trol
R info

RBA X'00' X'140' X'280' X'3C0'

Con-
36 BILL 23 FRED 10 TOM Free space trol
info

X'400' X'540' X'680' X'7C0'

Base e
Con-
Cluster 21 BEN 23 FRED 12 MIKE Free space trol
info
X'800' X'940' X'A80' X'BC0'
Con-
41 TOM 39 FRED 54 TOM Free space trol
info

Note: RBAs are always written as full word binary integers.

Figure 19. Alternate Index Structure for an Entry-Sequenced Data Set

Chapter 6. Organizing VSAM Data Sets 99

Organizing VSAM Data Sets

If you ask to access records with the alternate key of BEN, VSAM does the
following:
1. VSAM scans the index component of the alternate index, looking for a value
greater than or equal to BEN.
2. The entry FRED points VSAM to a data control interval in the alternate index.
3. VSAM scans the alternate index data control interval looking for an entry that
matches the search argument, BEN.
4. When located, the entry BEN has an associated pointer, 400, that points to an
RBA in the base cluster.
5. VSAM retrieves the record with an RBA of X'400' from the base cluster.

Building of an Alternate Index

When you build an alternate index, the alternate key can be any field in the base
data set’s records that has a fixed length and a fixed position in each record. The
alternate-key field must be in the first segment of a spanned record. Keys in the
data component of an alternate index are not compressed; the entire key is
represented in the alternate-index data record.

A search for a given alternate key reads all the base cluster records containing this
alternate key. For example, Figure 18 on page 98 and Figure 19 on page 99 show
that one salesman has several customers. For the key-sequenced data set, several
primary-key pointers (customer numbers) are in the alternate-index data record.
There is one for each occurrence of the alternate key (salesman’s name) in the base
data set. For the entry-sequenced data set, several RBA pointers are in the alternate
index data record. There is one for each occurrence of the alternate key (salesman’s
name) in the base data set. The pointers are ordered by arrival time.

Before a base cluster can be accessed through an alternate index, a path must be
defined. A path provides a way to gain access to the base data through a specific
alternate index. To define a path use the access method services command DEFINE
PATH.

For information about defining an alternate index, see “Defining Alternate

Indexes” on page 119. For information about defining a path, see “Defining a Path”
on page 122.

Automatic Upgrade of Alternate Indexes

VSAM determines the number of resources required to complete upgrading all the
alternate indexes defined for the base VSAM cluster. If there are insufficient
resources, the request fails and the application has the option of retrying the failed
request.

Data Compression
When deciding whether to compress data, consider the following guidelines and
rules:
v Compress when an existing data set is approaching the 4 gigabyte VSAM size
limit or when you have capacity constraints
v Only SMS-managed data is eligible for compression
v The data set must be an extended format key-sequenced data set
v Control interval access is not permitted.

100 z/OS V1R7.0 DFSMS Using Data Sets

 Organizing VSAM Data Sets

v Compression could require excessive amounts of storage when processed in

locate mode (OPTCD=LOC).
v The GSR option is not permitted for compressed data sets.

You can convert an application to compression processing if the application uses

data that can be highly compressible based on the structure or type of data. One
consideration could be the length of the data records:
v The records can be large relative to the size of a control interval.
v Smaller control interval sizes can be desirable because of the random structure of
the data.
v When a smaller control interval size is used without compressing data records,
the length of the records can require a spanned data set. Records placed in a
spanned data set are less likely to span control intervals when compression is
used. The result could improve performance when VSAM processes the data
because the amount of input/output required to GET or PUT the record is
reduced.

Any program other than DFSMSdss, REPRO, and any other physical data
copy/move program that does direct input/output to DASD for data sets which
have data in compressed format can compromise data integrity. These programs
must be modified to access the data using VSAM keyed access to permit expansion
of compressed data.

Chapter 6. Organizing VSAM Data Sets 101

102 z/OS V1R7.0 DFSMS Using Data Sets
Chapter 7. Defining VSAM Data Sets
This chapter covers the following topics.

Topic Location
Using Cluster Names for Data and Index Components 104
Defining a Data Set with Access Method Services 104
Defining a Data Set with JCL 113
Loading a VSAM Data Set 113
Copying and Merging Data Sets 117
Defining Alternate Indexes 119
Defining a Page Space 123
Checking for Problems in Catalogs and Data Sets 124
Deleting Data Sets 125

This chapter explains how to define VSAM data sets. Other chapters provide
examples and related information:
v For an example of defining a VSAM data set, see Chapter 8, “Defining and
Manipulating VSAM Data Sets: Examples,” on page 127.
v For examples of defining VSAM data sets, see z/OS DFSMS Access Method
Services for Catalogs.
v For information about defining a data set using RLS, see “Locking” on page 229.

VSAM data sets are defined using either access method services commands or JCL
dynamic allocation. A summary of defining a VSAM data sets follows:
1. VSAM data sets must be cataloged. If you want to use a new catalog, use
access method services commands to create a catalog. The procedure for
defining a catalog is described in z/OS DFSMS Managing Catalogs.
2. Define a VSAM data set in a catalog using the TSO ALLOCATE command, the
access method services ALLOCATE or DEFINE CLUSTER command, dynamic
allocation, or JCL. Before you can define a VSAM data set with dynamic
allocation or JCL, SMS must be active on your system. Dynamic allocation and
JCL do not support most of the DEFINE options available with access method
services.
3. Load the data set with either the access method services REPRO command or
your own loading program.
4. Optionally, define any alternate indexes and relate them to the base cluster. Use
the access method services DEFINE ALTERNATEINDEX, DEFINE PATH, and
BLDINDEX commands to do this.

After any of these steps, you can use the access method services LISTCAT and
PRINT commands to verify what has been defined, loaded, or processed. The
LISTCAT and PRINT commands are useful for identifying and correcting
problems.

© Copyright IBM Corp. 1987, 2005 103

Defining VSAM Data Sets

Using Cluster Names for Data and Index Components

For a key-sequenced data set, a cluster is the combination of the data component
and the index component. The cluster provides a way to treat the index and data
components as a single component with its own name. You can also give each
component a name. Fixed-length RRDSs, entry-sequenced data sets, and linear data
sets are considered to be clusters without index components. To be consistent,
cluster names are normally used for processing these data sets.

Defining a Data Set with Access Method Services

VSAM data sets can be defined with either the DEFINE CLUSTER command or
the ALLOCATE command. When a cluster is defined, VSAM uses the following
catalog entries to describe the cluster:
v A cluster entry describes the cluster as a single component.
v A data entry describes the cluster’s data component.
v For a key-sequenced data set, an index entry describes the cluster’s index
component.
All of the cluster’s attributes are recorded in the catalog. The information that is
stored in the catalog provides the details needed to manage the data set and to
access the VSAM cluster or the individual components.

If you use DEFINE CLUSTER, attributes of the data and index components can be
specified separately from attributes of the cluster.
v If attributes are specified for the cluster and not the data and index components,
the attributes of the cluster (except for password and USVR security attributes)
apply to the components.
v If an attribute that applies to the data or index component is specified for both
the cluster and the component, the component specification overrides the
cluster’s specification.

If you use ALLOCATE, attributes can be specified only at the cluster level.

Naming a Cluster
You specify a name for the cluster when defining it. Usually, the cluster name is
given as the dsname in JCL. A cluster name that contains more than 8 characters
must be segmented by periods; 1 to 8 characters can be specified between periods.
A name with a single segment is called an unqualified name. A name with more
than 1 segment is called a qualified name. Each segment of a qualified name is
called a qualifier.

You can, optionally, name the components of a cluster. Naming the data
component of an entry-sequenced cluster or a linear data set, or the data and index
components of a key-sequenced cluster, makes it easier to process the components
individually.

If you do not explicitly specify a data or index component name when defining a
VSAM data set or alternate index, VSAM generates a name. Also, when you define
a user catalog, VSAM generates only an index name for the user catalog (the name
of the user catalog is also the data component name). VSAM uses the following
format to generate names for both system-managed and non-system-managed data
sets:
1. If the last qualifier of the name is CLUSTER, replace the last qualifier with DATA
for the data component and INDEX for the index component.

104 z/OS V1R7.0 DFSMS Using Data Sets

 Defining VSAM Data Sets

Cluster name: [Link]

Generated data name = [Link]
Generated index name = [Link]
2. ELSE if the cluster name is less than or equal to 38 characters, then append
.DATA to the end of the cluster name for the data component and a .INDEX for
the index component.
Cluster name: [Link]
Generated data name = [Link]
Generated index name = [Link]
3. ELSE if the cluster name is between 39 and 42 characters inclusive, then
append a .D to the end of the cluster name for the data component and a .I for
the index component.
Cluster name: [Link]
Generated data name = [Link].D
Generated index name = [Link].I
4. ELSE if the name is longer than 42 characters, and the last qualifier is not
CLUSTER, use the first (N-1) qualifiers of the cluster, alternate index, or user
catalog name up to the first four qualifiers, and append as many 8-character
qualifiers as necessary to produce a 5-qualifier name.
Cluster name: [Link]
Generated data name = [Link].TY7RESNO
Generated index name = [Link]

After a name is generated, VSAM searches the catalog to ensure that the name is
unique. If a duplicate name is found, VSAM continues generating new names
using the format outlined in 4 until a unique one is produced.

Duplicate Data Set Names

VSAM prevents you from cataloging two objects with the same name in the same
catalog. VSAM also prevents you from altering the name of an object so that its
new name duplicates the name of another object in the same catalog. VSAM does
not prevent duplication of names from one catalog to another however. If you
have multiple catalogs, you should ensure that a data set name in one catalog is
not duplicated in another catalog. The multilevel alias facility assigns a data set
name to a unique catalog. However, if the number of alias levels searched is
changed, it is possible that duplicate data set names could occur. If the number of
alias search levels is changed, the former name cannot be located with the
multilevel alias facility unless the levels are changed back. See z/OS DFSMS
Managing Catalogs.

z/OS DFSMS Access Method Services for Catalogs describes the order in which one of
the catalogs available to the system is selected to contain the to-be-defined catalog
entry. When you define an object, you should ensure that the catalog the system
selects is the catalog you want the object entered.

Data set name duplication is not prevented when a user catalog is imported into a
system. No check is made to determine if the imported catalog contains an entry
name that already exists in another catalog in the system.

Temporary Data Set Names

You can use the access method services ALLOCATE or TSO ALLOCATE command
to define a temporary system-managed VSAM data set. A temporary
system-managed data set can also be allocated directly through JCL.

Temporary system-managed VSAM data sets do not require that you specify a data
set name. If you specify a data set name it must begin with & or &&:

Chapter 7. Defining VSAM Data Sets 105

Defining VSAM Data Sets

DSNAME(&CLUSTER)

See “Examples of Defining Temporary VSAM Data Sets” on page 130 for
information about using the ALLOCATE command to define a temporary
system-managed VSAM data set. See “Temporary VSAM Data Sets” on page 269
for information about restrictions on using temporary data sets.

Specifying Cluster Information

When you define a cluster, you can directly specify certain descriptive,
performance, security and integrity information. Other sources provide information
you omit or the system does not let you provide.

If the Storage Management Subsystem (SMS) is active, and you are defining a
system-managed cluster, you can explicitly specify the data class, management
class, and storage class parameters and take advantage of attributes defined by
your storage administrator. You can also implicitly specify the SMS classes by
taking the system determined defaults if such defaults have been established by
your storage administrator. The SMS classes are assigned only at the cluster level.
You cannot specify them at the data or index level.

If SMS is active and you are defining a non-system-managed cluster, you can also
explicitly specify the data class or take the data class default if one is available.
Management class and storage class are not supported for non-system-managed
data sets.

If you are defining a non-system-managed data set and you do not specify the
data class, you must explicitly specify all necessary descriptive, performance,
security, and integrity information through other access method services
parameters. Most of these parameters can be specified for the data component, the
index component, or both. Specify information for the entire cluster with the
CLUSTER parameter. Specify information for only the data component with the
DATA parameter and for only the index component with the INDEX parameter.
See “Using Access Method Services Parameters” for an explanation of the types of
descriptive, performance, security, and integrity information specified using these
parameters.

Both the data class and some other access method services parameters can be used
to specify values to the same parameter, for example, the control interval size. The
system uses the following order of precedence, or filtering, to determine which
parameter value to assign.
1. Explicitly specified DEFINE command parameters
2. Modeled attributes (assigned by specifying the MODEL parameter on the
DEFINE command)
3. Data class attributes
4. DEFINE command parameter defaults

Using Access Method Services Parameters

If you do not use the SMS classes to specify the necessary descriptive,
performance, security, and integrity information, you must use access method
services parameters.

Descriptive Parameters
The following access method services parameters provide descriptive information:

106 z/OS V1R7.0 DFSMS Using Data Sets

 Defining VSAM Data Sets

v INDEXED|NONINDEXED|NUMBERED|LINEAR parameter—Specifies the

type of data organization used (key sequenced, entry sequenced, relative record,
or linear).
v RECORDSIZE parameter—Specifies the average and maximum lengths of data
records. The RECORDSIZE parameter is not used for a linear data set.
A variable-length RRDS is defined using NUMBERED and RECORDSIZE, where
the average and maximum record length must be different.
If the actual length of an entry-sequenced, key-sequenced, or variable-length
RRDS record is less than the maximum record length, VSAM saves disk space
by storing the actual record length in the record definition field (RDF). The RDF
is not adjusted for fixed-length RRDSs.
v KEYS parameter—Specifies the length and position of the key field in the
records of a key-sequenced data set.
v CATALOG parameter—Specifies the name and password of the catalog in which
the cluster is to be defined.
v VOLUMES parameter—Specifies the volume serial numbers of the volumes on
which space is allocated for the cluster. You can specify up to 59 DASD volumes.
v RECORDS|KILOBYTES|MEGABYTES|TRACKS|CYLINDERS
parameter—Specifies the amount of space to allocate for the cluster. The
CYLINDERS, TRACKS, MEGABYTES, KILOBYTES, and RECORDS parameters
are permitted for a linear data set. If you specify the RECORDS parameter for a
linear data set, the system allocates space with the number of control intervals
equal to the number of records. (Linear data sets do not have records; they have
objects that are contiguous strings of data.)
v RECATALOG parameter—Specifies if an entry is recreated from information in
the VSAM volume data set (VVDS), or defined for the first time.
v REUSE|NOREUSE parameter—Specifies if the cluster is reusable for temporary
storage of data. See “Reusing a VSAM Data Set as a Work File” on page 116.
v BUFFERSPACE parameter—Specifies the minimum amount of I/O buffer space
that must be allocated to process the data set. See “Determining I/O Buffer
Space for Nonshared Resource” on page 166.

Performance Parameters
The following access method services parameters provide performance
information. All these performance options are discussed in Chapter 10,
“Optimizing VSAM Performance,” on page 157.
v CONTROLINTERVALSIZE parameter—Specifies the control interval size for
VSAM to use (instead of letting VSAM calculate the size).
The size of the control interval must be large enough to hold a data record of
the maximum size specified in the RECORDSIZE parameter unless the data set
was defined with the SPANNED parameter.
Specify the CONTROLINTERVALSIZE parameter for data sets that use shared
resource buffering, so you know what control interval size to code on the
BLDVRP macro.
v SPANNED parameter—Specifies whether records can span control intervals. The
SPANNED parameter is not permitted for fixed-length and variable-length
RRDSs, and linear data sets.
v SPEED|RECOVERY parameter—Specifies whether to preformat control areas
during initial loading of a data set. See “Using a Program to Load a Data Set”
on page 115.
v VOLUMES parameter for the index component—Specifies whether to place the
cluster’s index on a separate volume from data.

Chapter 7. Defining VSAM Data Sets 107

 Defining VSAM Data Sets

v FREESPACE parameter—Specifies the amount of free space to remain in the

data component of a key-sequenced data set or variable-length RRDS’s control
intervals and control areas when the data records are loaded.

Security and Integrity Parameters

The following access method services parameters provide security and integrity
information. See Chapter 5, “Protecting Data Sets,” on page 53 for more
information about the types of data protection available.
v Passwords—Because passwords are not supported for system-managed data
sets, this information pertains to non-system-managed data sets only. See z/OS
DFSMS Access Method Services for Catalogs.
v AUTHORIZATION parameter—Specifies your own authorization routine to
verify that a requester has the right to gain access to data.
v EXCEPTIONEXIT parameter—Specifies an I/O error-handling routine (the
exception exit routine) that is entered if the program does not specify a SYNAD
exit. See Chapter 16, “Coding VSAM User-Written Exit Routines,” on page 241
for information about VSAM user-written exit routines.
v WRITECHECK parameter—Specifies whether to verify that write operations
have completed and that the data can be read.
v SHAREOPTIONS parameter—Specifies whether and to what extent data is to
be shared among systems, and jobs.
v ERASE parameter—Specifies whether to erase the information a data set
contains when you delete the data set.
To control the erasure of data in a VSAM component whose cluster is RACF
protected and cataloged, you can use an ERASE attribute in a generic or discrete
profile. For information about specifying and using the ERASE option, see
“Erasing DASD Data” on page 60 and “Generic and Discrete Profiles for VSAM
Data Sets” on page 54.

| Restriction:

Defining a new KEYRANGE data set is no longer supported. For more information
about converting key-range data sets, see the z/OS DFSMShsm Implementation and
Customization Guide.

Allocating Space for VSAM Data Sets

When you define a data set, you or SMS must specify the amount of space to
allocate for the data set. If SMS is active, you can specify a data class and take
advantage of the space allocation set by your storage administrator. If you want to
specify space explicitly, you can specify it for VSAM data sets in units of records,
kilobytes, megabytes, tracks, or cylinders. To maintain device independence,
specify records, kilobytes or megabytes. The amount of space you allocate depends
on the size of your data set and the index options you selected. “Using Index
Options” on page 177 explains the index options that improve performance.

If a guaranteed space storage class (STORAGECLASS parameter) is assigned to the

data set and volume serial numbers are specified, primary space is allocated on all
specified volumes if the following conditions are met. If these conditions are not
met, the command fails and IGDxxxxI messages are printed:
v All volumes specified belong to the same storage group.
v The storage group to which these volumes belong is in the list of storage groups
selected by the ACS routines for this allocation.

108 z/OS V1R7.0 DFSMS Using Data Sets

 Defining VSAM Data Sets

You can specify space allocation at the cluster or alternate-index level, at the data
level only, or at both the data and index levels. It is best to allocate space at the
cluster or data levels. VSAM allocates space if:
v Allocation is specified at the cluster or alternate index level only, the amount
needed for the index is subtracted from the specified amount. The remainder of
the specified amount is assigned to data.
v Allocation is specified at the data level only, the specified amount is assigned to
data. The amount needed for the index is in addition to the specified amount.
v Allocation is specified at both the data and index levels, the specified data
amount is assigned to data and the specified index amount is assigned to the
index.
v Secondary allocation is specified at the data level, secondary allocation must be
specified at the index level or the cluster level.

VSAM acquires space in increments of control areas. The control area size
generally is based on primary and secondary space allocations. See “Optimizing
Control Area Size” on page 161 for information about optimizing control area size.

Partial Release
Partial release is used to release unused space from the end of an extended format
data set and is specified through SMS management class or by the JCL RLSE
subparameter. All space after the high used RBA is released on a CA boundary up
to the high allocated RBA. If the high used RBA is not on a CA boundary, the high
used amount is rounded to the next CA boundary. Partial release restrictions
include:
v Partial release processing is supported only for extended format data sets.
v Only the data component of the VSAM cluster is eligible for partial release.
v Alternate indexes opened for path or upgrade processing are not eligible for
partial release. The data component of an alternate index when opened as
cluster could be eligible for partial release.
v Partial release processing is not supported for temporary close.
v Partial release processing is not supported for data sets defined with guaranteed
space.

VSAM CLOSE will request partial release processing only if:

v Partial release was specified through SMS management class or by the JCL
SPACE=(,,RLSE) parameter on the DD statement.
v The data set is defined as extended format.
v The data set was opened for OUTPUT processing.
v This is the last ACB closing for the data set (this includes all closes in the
current address space, other address spaces in the system, and other systems).

Small Data Sets

If you allocate space for a data set in a unit smaller than one cylinder, VSAM
allocates space in tracks when defining the data set. For data sets less than 1
cylinder in size, it is best to specify the maximum number of tracks required in the
primary allocation for the data component, 1 track for the sequence set index
(which should not be imbedded), and no secondary allocation for either data or
index.

VSAM checks the smaller of primary and secondary space values against the
specified device’s cylinder size. If the smaller quantity is greater than or equal to
the device’s cylinder size, the control area is set equal to the cylinder size. If the

Chapter 7. Defining VSAM Data Sets 109

 Defining VSAM Data Sets

smaller quantity is less than the device’s cylinder size, the size of the control area
is set equal to the smaller space quantity. The minimum control area size is one
track. See “Optimizing Control Area Size” on page 161 for information about
creating small control areas.

Multiple Cylinder Data Sets

First, calculate the amount of space needed for the primary allocation. If the data
set is larger than one cylinder, calculate and specify the number of cylinders
needed for data in a newly defined data set for the primary allocation. Make the
secondary allocation equal to or greater than one cylinder, but less than the
primary allocation. “Calculating Space for the Data Component of a KSDS” on
page 111 demonstrates how to calculate the size of a data set.

See “Using Index Options” on page 177 for information about index options.

Linear Data Sets

You must allocate space in tracks, cylinders, records, kilobytes, or megabytes for a
linear data set.

When you define a linear data set, you can specify a control interval size of 4096 to
32 768 bytes in increments of 4096 bytes. If not an integer multiple of 4096, the
control interval size is rounded up to the next 4096 increment. The system chooses
the best physical record size to use the track size geometry. For example, if you
specify CISIZE(16384), the block size is set to 16 384. If the specified
BUFFERSPACE is greater than 8192 bytes, it is decremented to a multiple of 4096.
If BUFFERSPACE is less than 8192, access method services issues a message and
fails the command.

Using VSAM Extents

A primary space allocation is the initial amount of allocated space. When the primary
amount on the first volume is used up, a secondary amount is allocated on that
volume. Each time a new record does not fit in the allocated space, the system
allocates more space in the secondary space amount. The system repeats allocating
this space until the volume is out of space or the volume extent limit of 123 is
reached.

| For nonstriped VSAM data sets, you can specify in the SMS data class parameter
| whether to use primary or secondary allocation amounts when extending to a new
| volume. You can expand the space for a nonstriped VSAM component to 255
| extents. For SMS-managed VSAM data sets, this extent limit is removed, and the
| theoretical limit is the maximum number of volumes (59), times 123 extents per
| volume, or 7257 extents.

| You can expand the space for a striped VSAM component to 255 times the number
| of stripes. The VSAM limit of 255 extents is still enforced for any
| non-SMS-managed data set. The system reserves the last four extents for extending
| a component when the system cannot allocate the last extent in one piece.

For both guaranteed and nonguaranteed space allocations, when you allocate space
for your data set, you can specify both a primary and a secondary allocation.
Guaranteed and nonguaranteed space allocation work similarly until the system
extends the data set to a new volume. The difference is that the guaranteed space
data set uses the “candidate with space” amount that is already allocated on that
volume.

110 z/OS V1R7.0 DFSMS Using Data Sets

 Defining VSAM Data Sets

With guaranteed space allocations, the primary allocation is allocated on the first
volume as “PRIME” and all of the other guaranteed space volumes as “candidate
with space”. When all of the space on the primary volume is used, the system gets
space on the primary volume using the secondary amount. When no more space
can be allocated on the primary volume, the system uses the “candidate with
space” amount on the next volume. Subsequent extends again use the secondary
amounts to allocate space until the volume is full. Then the system uses the
“candidate with space” amount on the next volume, and so forth.

VSAM Extent Consolidation

The system consolidates adjacent extents for VSAM data sets when extending on
the same volume. VSAM extent consolidation is automatic and requires no action
on your part. If the extents are adjacent, the new extent is incorporated into the
previous extent.

Example: The old extent begins on cylinder 6, track 0, and ends on cylinder 9,
track 14, and the new extent begins on cylinder 10, track 0, and ends on cylinder
12, track 14. The two extents are combined into one extent beginning on cylinder 6,
track 0, and ending on cylinder 12, track 14. Instead of two extents, there is only
one extent. Because VSAM combines the two extents, it does not increment the
extent count, which reduces the amount of extents.

Example: You allocate a VSAM data set with CYLINDERS(3 1). The data set
initially gets three cylinders and an additional cylinder every time the data set is
extended. Suppose you extend this data set five times. If none of the extents are
adjacent, the LISTCAT output shows allocations of cylinders 3,1,1,1,1,1, or a total of
eight cylinders.

Results: Depending on which extents are adjacent, the LISTCAT output might
show allocations of cylinders 5,1,1,1, or cylinders 3,5, or cylinders 3,2,3, as follows:
v For the 5,1,1,1 example, only the first three extents are adjacent.
v For the 3,5 example, the first and second extent are not adjacent, but the third
through eighth extent are adjacent.
v For the 3,2,3 example, the first and second extent are not adjacent, the second
and third extents are adjacent, the third and fourth extents are not adjacent, and
the last three extents are adjacent.

All types of SMS-managed VSAM data sets (KSDS, ESDS, RRDS, VRRDS, and
LDS) use extent consolidation.

Restriction: VSAM does not support extent consolidation for the following types of
data sets:
v Key-range data sets
v System data sets such as page spaces
v Catalogs
v VVDSs
v Non-system managed data sets
v Imbedded or replicated indexes
v VSAM data sets that you access using record-level sharing

Calculating Space for the Data Component of a KSDS

You can use the following formula for any DASD. The number of blocks per track
and control intervals per track depends on the DASD you are using. The following

Chapter 7. Defining VSAM Data Sets 111

 Defining VSAM Data Sets

example shows how to calculate the size of the data component for a
key-sequenced data set. The following are assumed for the calculations:

Device type. 3390

Unit of space allocation. Cylinders
Data control interval size. 1024 bytes
Physical block size (calculated by VSAM). 1024 bytes
Record size. 200 bytes
Free space definition – control interval. 20%
Free space definition – control area. 10%
Number of records to be loaded. 3000

You can calculate space for the data component as follows:

1. Number of bytes of free space (20% × 1024) = 204 (round down)
2. Number of loaded records per control interval (1024–10–204)/200 = 4.
3. Number of physical blocks per track = 33.
4. Number of control intervals per track = 33.
| 5. Maximum number of control intervals per control area (33 × 16) = 528.
6. Number of loaded control intervals per control area (495 – 10% × 495) = 446.
7. Number of loaded records per cylinder (4 × 446) = 1784.
8. Total space for data component (3000/1784) (rounded) = 2 cylinders.

| The value (1024 – 10) is the control interval length minus 10 bytes for two RDFs
| and one CIDF. The record size is 200 bytes. On an IBM 3380, 31 physical blocks
| with 1024 bytes can be stored on one track. The value (33 × 16) is the number of
| physical blocks per track multiplied by the number of data tracks per cylinder.

Calculating Space for the Index Component

There is no specific formula for calculating the space required for the index
component. Use the access method services command LISTCAT to see how much
space was allocated to the index component.

Using ALTER to Modify Attributes of a Component

After a data set has been defined, you can change some of its attributes using the
access method services command, ALTER. You identify the component by name,
and specify the new attributes. ALTER can also be used to change an
entry-sequenced data set, with the proper attributes, to a linear data set. The
contents of the data set are not modified. See z/OS DFSMS Access Method Services
for Catalogs for an example of changing an entry-sequenced data set to a linear data
set.

You cannot use ALTER to change a fixed-length RRDS into a variable-length RRDS,
or vice versa.

Using ALTER to Rename Data Sets

| You can use the ALTER command to rename VSAM data sets and members of
| PDSs and PDSEs. ALTER can also convert system-managed data sets to non-system
| managed. See z/OS DFSMS Access Method Services for Catalogs to determine which
| values or attributes you can alter for a particular data set type.

112 z/OS V1R7.0 DFSMS Using Data Sets

 Defining VSAM Data Sets

Defining a Data Set with JCL

SMS must be active on your system before you can use JCL to define a VSAM data
set. Any VSAM data set can be defined using JCL, except for a variable-length
RRDS. Defining a VSAM data set using JCL has certain advantages. It takes less
time to input and it makes syntax for defining the VSAM data set very similar to
that used for accessing it.

DB2 provides striping on partitioned table spaces. Each of the partitions is a

separate linear data set. Striping is used to perform parallel I/O concurrently
against more than one of these partitions. The benefit of striping is only achievable
if multiple partitions do not get allocated on the same volume. You can achieve
volume separation without resorting to the storage class guaranteed space
allocations on system-managed volumes.

Allocate all of the partitions in a single IEFBR14 job step using JCL. If an adequate
number of volumes exist in the storage groups, and the volumes are not above the
allocation threshold, the SMS allocation algorithms with SRM will ensure each
partition is allocated on a separate volume.

DB2 striping is unrelated to VSAM striping (see “Extended-Format VSAM Data

Sets” on page 88). You can use both DB2 striping and VSAM striping for the same
set of linear extended format data sets.

Related reading: See Chapter 18, “Using Job Control Language for VSAM,” on
page 265 for information about the JCL keywords used to define a VSAM data set.
See z/OS MVS JCL Reference and z/OS MVS JCL User’s Guide for information about
JCL keywords and the use of JCL.

Loading a VSAM Data Set

After a data set is defined, you can load records into it from a source data set.
Depending on the type of VSAM data set being loaded, the source data set records
might or might not need to be in a particular order.
v Records being loaded into an entry-sequenced data set do not have to be
submitted in any particular order. Entry-sequenced data set records are
sequenced by their time of arrival rather than by any field in the logical record.
v Fixed-length RRDS records are placed into slots specified either by a
user-supplied or a VSAM-supplied relative record number. The relative record
number is not part of the logical record, so it is not necessary that the records be
submitted in any particular order.
v Records being loaded into a key-sequenced data set must be in ascending order
by key, with no duplicate keys in the input data set.
v Records being loaded into a variable-length RRDS must be in ascending order
by key, with no duplicate keys in the input data set. If they are loaded in
sequential mode, VSAM assigns the relative record number.

With entry-sequenced or key-sequenced data sets, or RRDSs, you can load all the
records either in one job or in several jobs. If you use multiple jobs to load records
into a data set, VSAM stores the records from subsequent jobs in the same manner
that it stored records from preceding jobs, extending the data set as required.

Chapter 7. Defining VSAM Data Sets 113

 Defining VSAM Data Sets

Using REPRO to Copy a VSAM Data Set

The REPRO command lets you retrieve records from a sequential,
indexed-sequential, or VSAM data set and store them in VSAM format in a
key-sequenced, entry-sequenced, relative-record, or a sequential data set. The
REPRO command is also used to load data from one linear data set into another
linear data set.

| When records are to be stored in key sequence, index entries are created and
| loaded into an index component as data control intervals and control areas are
| filled. Free space is left as indicated in the cluster definition in the catalog.

VSAM data sets must be cataloged. Sequential and indexed sequential data sets
need not be cataloged. Sequential data sets that are system managed must be
cataloged.

If a sequential or indexed-sequential data set is not cataloged, include the

appropriate volume and unit parameters on your DD statement. Also, supply a
minimum set of DCB parameters when the input data set is sequential or indexed
sequential, and/or the output data set is sequential. The following table shows the
four key parameters:

Parameters User Can Supply Default if Not Supplied

DSORG IS PS
RECFM F, FB, V, VB, VS, VBS U
BLKSIZE Block size None
LRECL Logical record length BLKSIZE for F or FB BLKSIZE-4 for
V, VB, VS, VBS

The only way to specify the DSORG parameter is to use the DD statement. The
DCB parameters RECFM, BLKSIZE, and LRECL can be supplied using the DSCB
or header label of a standard labeled tape, or by the DD statement. The system can
determine the optimum block size.

If you use REPRO to copy to a sequential data set, you do not need to supply a
block size because the system determines the block size when it opens the data set.
You can optionally supply a BLKSIZE value using JCL or when you define the
output data set.

If you are loading a VSAM data set into a sequential data set, you must remember
that the 3-byte VSAM record definition field (RDF) is not included in the VSAM
record length. When REPRO attempts to copy a VSAM record whose length is
more than the non-VSAM LRECL−4, a recoverable error occurs and the record is
not copied. (Each non-VSAM record has a four-byte prefix that is included in the
length. Thus, the length of each VSAM variable-length record is four bytes less
than the length of the non-VSAM record.)

Access method services does not support records greater than 32 760 bytes for
non-VSAM data sets (LRECL=X is not supported). If the logical record length of a
non-VSAM input data set is greater than 32 760 bytes, or if a VSAM data set
defined with a record length greater than 32 760 is to be copied to a sequential
data set, the REPRO command terminates with an error message.

Records in an indexed sequential data set that have a fixed-length, unblocked

format with a relative-key position of zero are preceded by the key string when

114 z/OS V1R7.0 DFSMS Using Data Sets

 Defining VSAM Data Sets

used as input. The records in the output data set must have a record length
defined that includes the extended length caused by the key string. To copy
“dummy” indexed-sequential records (with X'FF' in the first byte), specify the
DUMMY option in the ENVIRONMENT parameter.

The REPRO operation is terminated if:

v One physical I/O error is found while writing to the output data set
v A total of four errors is found in any combination of the following:
– Logical error while writing to the output data set
– Logical error while reading the input data set
– Physical error while reading the input data set

Related reading: For information about physical and logical errors, see z/OS
DFSMS Macro Instructions for Data Sets.

Using a Program to Load a Data Set

To use your own program to load a key-sequenced data set, first sort the records
(or build them) in key sequence, then store them sequentially (using the PUT
macro). When you are initially loading a data set, direct access is not permitted.
For more information about inserting records into a data set, see “Inserting and
Adding Records” on page 142.

VSAM uses the high-used RBA field to determine whether a data set is empty. An
implicit verify can update the high-used RBA. Immediately after definition of a
data set, the high-used RBA value is zero. An empty data set cannot be verified.

The terms create mode, load mode, and initial data set load are synonyms for the
process of inserting records into an empty VSAM data set. To start loading an
empty VSAM data set, call the VSAM OPEN macro. Following a successful open,
the load continues while records are added and concludes when the data set is
closed.

Restriction: If an entry-sequenced data set fails to load, you cannot open it.

Certain restrictions apply during load mode processing:

v PUT and CHECK are the only macros you can use.
v Do not use improved control interval processing.
v You cannot do update or input processing until the data set has been loaded and
closed.
v Specify only one string in the ACB (STRNO>1 is not permitted).
v Do not specify local shared resources (LSR) or global shared resources (GSR).
v You cannot share the data set.
v Direct processing is not permitted (except relative record keyed direct).

If the design of your application calls for direct processing during load mode, you
can avoid this restriction by following these steps:
1. Open the empty data set for load mode processing.
2. Sequentially write one or more records, which could be dummy records.
3. Close the data set to terminate load mode processing.
4. Reopen the data set for normal processing. You can now resume loading or do
direct processing. When using this method to load a VSAM data set, be
cautious about specifying partial release. Once the data set is closed, partial
release will attempt to release all space not used.

Chapter 7. Defining VSAM Data Sets 115

Defining VSAM Data Sets

For information about using user-written exit routines when loading records into a
data set, see Chapter 16, “Coding VSAM User-Written Exit Routines,” on page 241.

During load mode, each control area can be preformatted as records are loaded
into it. Preformatting is useful for recovery if an error occurs during loading.
However, performance is better during initial data set load without preformatting.
The RECOVERY parameter of the access method services DEFINE command is
used to indicate that VSAM is to preformat control areas during load mode. In the
case of a fixed-length RRDS and SPEED, a control area in which a record is
inserted during load mode will always be preformatted. With RECOVERY, all
control areas will be preformatted.

Preformatting clears all previous information from the direct access storage area
and writes end-of-file indicators. For VSAM, an end-of-file indicator consists of a
control interval with a CIDF equal to zeros.
v For an entry-sequenced data set, VSAM writes an end-of-file indicator in every
control interval in the control area.
v For a key-sequenced data set, VSAM writes an end-of-file indicator in the first
control interval in the control area following the preformatted control area. (The
preformatted control area contains free control intervals.)
v For a fixed-length RRDS, VSAM writes an end-of-file indicator in the first
control interval in the control area following the preformatted control area. All
RDFs in an empty preformatted control interval are marked “slot empty”.

As records are loaded into a preformatted control area of an entry-sequenced data

set, an end-of-file indicator following the records indicates how far loading has
progressed. You can then resume loading at that point, after verifying the data set.
(You cannot open the data set unless you first verify it.) If an error occurs that
prevents loading from continuing, you can identify the last successfully loaded
record by reading to end of file.

The SPEED parameter does not preform at the data control areas. It writes an
end-of-file indicator only after the last record is loaded. Performance is better if
you use the SPEED parameter and if using extended format data sets. Extended
format data sets may use system-managed buffering. This permits the number of
data buffers to be optimized for load mode processing. This can be used with the
REPRO parameter for a new data set for reorganization or recovery. If an error
occurs that prevents loading from continuing, you cannot identify the last
successfully loaded record and you might have to reload the records from the
beginning. For a key-sequenced data set, the SPEED parameter only affects the
data component.

Rule: Remember that, if you specify SPEED, it will be in effect for load mode
processing. After load mode processing, RECOVERY will be in effect, regardless of
the DEFINE specification.

Reusing a VSAM Data Set as a Work File

VSAM enables you to define reusable data sets to use as work files. Define the
data set as reusable and specify that it be reset when you open it. You also can
reuse a striped VSAM data set.

A data set that is not reusable can be loaded only once. After the data set is
loaded, it can be read and written to, and the data in it can be modified. However,
the only way to remove the set of data is to use the access method services

116 z/OS V1R7.0 DFSMS Using Data Sets

 Defining VSAM Data Sets

command DELETE, which deletes the entire data set. If you want to use the data
set again, define it with the access method services command DEFINE, by JCL, or
by dynamic allocation.

Instead of using the DELETE - DEFINE sequence, you can specify the REUSE
parameter in the DEFINE CLUSTER|ALTERNATEINDEX command. The REUSE
parameter lets you treat a filled data set as if it were empty and load it again and
again regardless of its previous contents.

A reusable data set can be a KSDS, an ESDS, an LDS, or a RRDS that resides on
one or more volumes. A reusable base cluster cannot have an alternate index, and
it cannot be associated with key ranges. When a reusable data set is opened with
the reset option, it cannot be shared with other jobs.

VSAM uses a high-used relative byte address (RBA) field to determine if a data set
is empty or not. Immediately after you define a data set, the high-used RBA value
is zero. After loading and closing the data set, the high-used RBA is equal to the
offset of the last byte in the data set. In a reusable data set, you can reset to zero
this high-used RBA field at OPEN by specifying MACRF=RST in the ACB at
OPEN. VSAM can use this reusable data set like a newly defined data set.

For compressed format data sets, in addition to the high-used RBA field being
reset to zero for MACRF=RST, OPEN resets the compressed and uncompressed
data set sizes to zero. The system does not reset the compression dictionary token
and reuses it to compress the new data. Because the dictionary token is derived
from previous data, this action could affect the compression ratio depending on the
nature of the new data.

Copying and Merging Data Sets

You might want to copy a data set or merge two data sets for a variety of reasons.
For example, you might want to create a test copy, you might want two copies to
use for two different purposes, or you might want to keep a copy of back records
before updating a data set. You can use the access method services REPRO
command to copy data sets.

For information about accessing a data set using RLS, see Chapter 14, “Using
VSAM Record-Level Sharing,” on page 219.

You can use the REPRO command to do any of the following:

v Copy or merge a VSAM data set into another VSAM data set.
v Copy or merge a sequential data set into another sequential data set.
v Copy an alternate index as a key-sequenced VSAM data set.
v Copy a VSAM data set whose records are fixed length into an empty
fixed-length RRDS.
v Convert a sequential or indexed sequential data set into a VSAM data set.
v Copy a VSAM data set into a sequential data set.
v Copy a data set (other than a catalog) to reorganize it. Data sets are reorganized
automatically.
v Copy individual members of a PDS or PDSE. A PDS or PDSE cannot be copied,
but individual members can be copied.

Chapter 7. Defining VSAM Data Sets 117

Defining VSAM Data Sets

When copying to a key-sequenced data set, the records to be copied must be in

ascending order, with no duplicates in the input data set. All the keys must be
unique. With an entry-sequenced data set, the records to be copied can be in any
order.

Because data is copied as single logical records in either key order or physical
order, automatic reorganization can take place as follows:
v Physical relocation of logical records
v Alteration of a record’s physical position within the data set
v Redistribution of free space throughout the data set
v Reconstruction of the VSAM indexes

If you are copying to or from a sequential data set that is not cataloged, you must
include the appropriate volume and unit parameters on your DD statements. For
more information about these parameters see “Using REPRO to Copy a VSAM
Data Set” on page 114.

Table 10 describes how the data from the input data set is added to the output data
set when the output data set is an empty or nonempty entry-sequenced, sequential,
key-sequenced, or linear data set, or fixed-length or variable-length RRDS.
Table 10. Adding Data to Various Types of Output Data Sets
Type of Data Set Empty Nonempty
Entry sequenced Loads new data set in Adds records in sequential order to the end of the data
sequential order. set.
Sequential Loads new data set in Adds records in sequential order to the end of the data
sequential order. set.
Key sequenced Loads new data set in key Merges records by key and updates the index. Unless the
sequence and builds an REPLACE option is specified, records whose key
index. duplicates a key in the output data set are lost.
Linear Loads new linear data set in Adds data to control intervals in sequential order to the
relative byte order. end of the data set.
Fixed-length RRDS Loads a new data set in Records from another fixed-length or variable-length
relative record sequence, RRDS are merged, keeping their old record numbers.
beginning with relative Unless the REPLACE option is specified, a new record
record number 1. whose number duplicates an existing record number is
lost. Records from any other type of organization cannot
be copied into a nonempty fixed-length RRDS.
Variable-length RRDS Loads a new data set in Records from another fixed-length or variable-length
relative record sequence, RRDS are merged, keeping their old record numbers.
beginning with relative Unless the REPLACE option is specified, a new record
record number 1. whose number duplicates an existing record number is
lost. Records from any other type of organization cannot
be copied into a nonempty fixed-length RRDS.

The REPRO operation is terminated if:

v One physical I/O error is found while writing to the output data set
v A total of four errors is found in any combination of the following:
– Logical error while writing to the output data set
– Logical error while reading the input data set
– Physical error while reading the input data set.

118 z/OS V1R7.0 DFSMS Using Data Sets

 Defining VSAM Data Sets

Defining Alternate Indexes

An alternate index is a key-sequenced data set containing index entries organized
by the alternate keys of its associated base data records. It provides another way of
locating records in the data component of a cluster.

An alternate index can be defined over a key-sequenced or entry-sequenced cluster.

| An alternate index cannot be defined for a reusable cluster, a fixed- or
| variable-length RRDS, an extended addressable ESDS, a catalog, a VVDS (data set
| name ’[Link]’), another alternate index, a linear data set, or a
| non-VSAM data set. The data class parameter can be specified for a
system-managed alternate index. Access method services DEFINE will assign the
same management class and storage class as the alternate index’s base cluster. If a
base cluster is defined as extended format, then the alternate index it relates to
must be able to be defined as extended format. Alternate indexes cannot be
compressed. See “Access to Records through Alternate Indexes” on page 97 for
information about the structure of an alternate index.

The sequence for building an alternate index is as follows:

1. Define the base cluster, using either the ALLOCATE command, the DEFINE
CLUSTER command, or JCL.
2. Load the base cluster either by using the REPRO command or by writing your
own program to load the data set.
3. Define the alternate index, using the DEFINE ALTERNATEINDEX command.
4. Relate the alternate index to the base cluster, using the DEFINE PATH
command. The base cluster and alternate index are described by entries in the
same catalog.
5. Build the alternate index, using the BLDINDEX command.

VSAM uses three catalog entries to describe an alternate index:

v An alternate index entry describes the alternate index as a key-sequenced cluster.
v A data entry describes the alternate index’s data component.
v An index entry describes the alternate index’s index component.

Except for data class, attributes of the alternate index’s data and index components
can be specified separately from the attributes of the whole alternate index. If
attributes are specified for the whole alternate index and not for the data and
index components, these attributes (except for password and USVR security
attributes) apply to the components as well. If the attributes are specified for the
components, they override any attributes specified for the entire alternate index.

Naming an Alternate Index

You specify an entry name for an alternate index when you define it. You can
specify the entry name as the dsname in a JCL DD statement. For details on how
VSAM can generate component names for you, see “Naming a Cluster” on page
104.

Specifying Alternate Index Information

When you define an alternate index, you specify descriptive information and
performance, security, and data integrity options. The information can apply to the
alternate index’s data component, its index component, or the whole alternate
index. Information for the entire alternate index is specified with the

Chapter 7. Defining VSAM Data Sets 119

Defining VSAM Data Sets

ALTERNATEINDEX parameter and its subparameters. Information for the data

component or the index component is specified with the parameter DATA or
INDEX.

Passwords are not supported for system-managed alternate indexes. To define an

alternate index, you must have RACF alter authority for the base cluster.

Specifying Descriptive Information for an Alternate Index

You need to specify the following descriptive information for an alternate index:
v The name and password of the base cluster related to the alternate index, as
specified in the RELATE parameter. The RELATE entry name must be selected
so that the multilevel alias facility selects the correct catalog. See z/OS DFSMS
Managing Catalogs for information about the multilevel alias facility and z/OS
DFSMS Access Method Services for Catalogs for information about the order of
catalog search.
v Amount of space to allocate for the alternate index, as specified in the
CYLINDERS|KILOBYTES|MEGABYTES|RECORDS|TRACKS parameter.
v Volume serial numbers of the volumes on which space is allocated for the
alternate index, as designated in the VOLUMES parameter. If you specify the
VOLUMES parameter for system-managed data sets, however, the volumes
designated might or might not be used, and sometimes can result in a failure.
You can indicate nonspecific volumes for a system-managed data set by
designating an asterisk (*) for each volume serial. SMS then determines the
volume serial. The default is one volume. Note that if both specific and
nonspecific volumes are designated, the specified volume serials must be named
first.
v The minimum amount of I/O buffer space that OPEN must provide when the
program processes the alternate index’s data, as designated in the
BUFFERSPACE parameter.
v Name and password of the catalog containing the alternate index’s entries, as
designated in the CATALOG parameter. This must be the same catalog that
contains the base cluster’s entries.
v Data class, for alternate indexes, to take advantage of the attributes assigned by
the storage administrator.
v Length and position of the alternate key field in data records of the base cluster,
as specified in the KEYS parameter.
v Average and maximum lengths of alternate index records, as specified in the
RECORDSIZE parameter.
v Whether the alternate index is reusable, as specified in the REUSE parameter.
v Whether the data set is extended format and whether it has extended
addressability. These characteristics for the alternate index are the same as those
for the cluster.

The performance options and the security and integrity information for the
alternate index are the same as that for the cluster. See “Using Access Method
Services Parameters” on page 106.

Specifying RECORDSIZE for an Alternate Index with Nonunique

Keys
When you define an alternate index with many nonunique keys, specify a
RECORDSIZE value that is large enough to handle all the nonunique keys. All
occurrences of primary keys for a particular alternate key must be within a single
alternate index logical record. If the maximum RECORDSIZE value is 1000, for

120 z/OS V1R7.0 DFSMS Using Data Sets

 Defining VSAM Data Sets

example, you would not be able to support as many nonunique keys as you would
if the maximum RECORDSIZE value were 5000.

Building an Alternate Index

When an alternate index is built by BLDINDEX processing, the alternate index’s
volume and the base cluster’s volume must be mounted. Any volumes identified
with the WORKFILES parameter must also be mounted. If one of the data sets
identified by the WORKFILES ddname is system managed, the other data set must
be either a system-managed data set or a non-system-managed data set cataloged
in the catalog determined by the catalog search order. The base cluster cannot be
empty (that is, its high-used RBA value cannot be zero). Each record’s alternate key
value must be unique, unless the alternate index was defined with the
NONUNIQUEKEY attribute.

Access method services opens the base cluster to read the data records sequentially,
sorts the information obtained from the data records, and builds the alternate
index data records.

The base cluster’s data records are read and information is extracted to form the
key-pointer pair:
v When the base cluster is entry sequenced, the alternate-key value and the data
record’s RBA form the key-pointer pair.
v When the base cluster is key sequenced, the alternate-key value and the
primary-key value of the data set record form the key-pointer pair.

The key-pointer pairs are sorted in ascending alternate-key order.

After the key-pointer pairs are sorted into ascending alternate key order, access
method services builds alternate index records for key-pointer pairs. When all
alternate index records are built and loaded into the alternate index, the alternate
index and its base cluster are closed.

Related reading: For information about calculating the amount of virtual storage
required to sort records, using the BLDINDEX command, and the catalog search
order, see z/OS DFSMS Access Method Services for Catalogs.

Maintaining Alternate Indexes

VSAM assumes alternate indexes are always synchronized with the base cluster
and does not check synchronization during open processing. Therefore, all
structural changes made to a base cluster must be reflected in its alternate index or
indexes. This is called index upgrade.

You can maintain your own alternate indexes or have VSAM maintain them. When
the alternate index is defined with the UPGRADE attribute of the DEFINE
command, VSAM updates the alternate index whenever there is a change to the
associated base cluster. VSAM opens all upgrade alternate indexes for a base
cluster whenever the base cluster is opened for output. If you are using control
interval processing, you cannot use UPGRADE. See Chapter 11, “Processing
Control Intervals,” on page 179.

You can define a maximum of 125 alternate indexes in a base cluster with the
UPGRADE attribute.

Chapter 7. Defining VSAM Data Sets 121

Defining VSAM Data Sets

All the alternate indexes of a given base cluster that have the UPGRADE attribute
belong to the upgrade set. The upgrade set is updated whenever a base data
record is inserted, erased, or updated. The upgrading is part of a request and
VSAM completes it before returning control to your program. If upgrade
processing is interrupted because of a machine or program error so that a record is
missing from the base cluster but its pointer still exists in the alternate index,
record management will synchronize the alternate index with the base cluster by
letting you reinsert the missing base record. However, if the pointer is missing
from the alternate index, that is, the alternate index does not reflect all the base
cluster data records, you must rebuild your alternate index to resolve this
discrepancy.

Note that when you use SHAREOPTIONS 2, 3, and 4, you must continue to ensure
read/write integrity when issuing concurrent requests (such as GETs and PUTs) on
the base cluster and its associated alternate indexes. Failure to ensure read/write
integrity might temporarily cause “No Record Found” or “No Associated Base
Record” errors for a GET request. You can bypass such errors by reissuing the GET
request, but it is best to prevent the errors by ensuring read/write integrity.

If you specify NOUPGRADE in the DEFINE command when the alternate index is
defined, insertions, deletions, and changes made to the base cluster will not be
reflected in the associated alternate index.

When a path is opened for update, the base cluster and all the alternate indexes in
the upgrade set are allocated. If updating the alternate indexes is unnecessary, you
can specify NOUPDATE in the DEFINE PATH command and only the base cluster
is allocated. In that case, VSAM does not automatically upgrade the alternate
index. If two paths are opened with MACRF=DSN specified in the ACB macro, the
NOUPDATE specification of one can be nullified if the other path is opened with
UPDATE specified.

How Reorganization Affects Alternate Indexes

If you reorganize a base cluster, you do not need to rebuild the alternate indexes,
because the relationships between the base cluster and the alternate indexes have
not changed. If you unload a VSAM data set, delete the existing cluster on DASD,
redefine the CLUSTER on DASD, then load the new data set from the unloaded
copy, then you do not need to rebuild the alternate index.

Alternate Index Backups

You can use DFSMShsm to back up a base cluster and its associate alternate
indexes. For more information see z/OS DFSMShsm Managing Your Own Data.

Defining a Path
After an alternate index is defined, you need to establish the relationship between
an alternate index and its base cluster, using the access method services command,
DEFINE PATH. You must name the path and can also give it a password. The path
name refers to the base cluster/alternate index pair. When you access the data set
through the path, you must specify the path name in the DSNAME parameter in
the JCL.

When your program opens a path for processing, both the alternate index and its
base cluster are opened. When data in a key-sequenced base cluster is read or
written using the path’s alternate index, keyed processing is used. RBA processing
is permitted only for reading or writing an entry-sequenced data set’s base cluster.

122 z/OS V1R7.0 DFSMS Using Data Sets

 Defining VSAM Data Sets

Related reading: See z/OS DFSMS Access Method Services for Catalogs for
information about using the DEFINE PATH command.

Defining a Page Space

A page space is a system data set that contains pages of virtual storage. The pages
are stored into and retrieved from the page space by the auxiliary storage manager.
A page space is an entry-sequenced cluster that is preformatted (unlike other data
sets) and is contained on a single volume. You cannot open a page space as a user
data set. A page space has a size limit of 4 GB.

A page space has a maximum size equal to 16 777 215 slots (records). However, the
actual usable page space is much less because it has a size limit of 4 GB.

The considerations for defining a page space are much like those for defining a
cluster. The DEFINE PAGESPACE command has many of the same parameters as
the DEFINE CLUSTER command, so the information you must supply for a page
space is similar to what you would specify for a cluster. A page space data set
cannot be in extended format. For a 3390 DASD, the maximum size of a page
space that you can specify on the DEFINE PAGESPACE with CYLINDERS is 5 825.

You can define a page space in a user catalog, then move the catalog to a new
system, and establish it as the system’s master catalog. For page spaces to be
system managed, they must be cataloged, and you must let the system determine
which catalog to use. Page spaces also cannot be duplicate data sets. The system
cannot use a page space if its entry is in a user catalog.

When you issue a DEFINE PAGESPACE command, the system creates an entry in
the catalog for the page space, then preformats the page space. If an error occurs
during the preformatting process (for example, an I/O error or an allocation error),
the page space’s entry remains in the catalog even though no space for it exists.
Issue a DELETE command to remove the page space’s catalog entry before you
redefine the page space.

Each page space is represented by two entries in the catalog: a cluster entry and a
data entry. (A page space is an entry-sequenced cluster.) Both of these entries
should be password protected if the page space is password protected.

The system recognizes a page space if it is defined as a system data set at system
initialization time or if it is named in [Link]. To be used as a page space,
it must be defined in a master catalog.

Recommendations:
1. When you define page spaces during system initialization, use the ALTER
command to add passwords to each entry because passwords cannot be
specified during system initialization. The passwords you specify with the
DEFINE PAGESPACE command are put in both the page space’s cluster entry
and its data entry. Unless you ensure that the catalog containing the page space
entry is either password protected or RACF protected, a user can list the
catalog’s contents and find out each entry’s passwords.
2. Passwords are ignored for system-managed data sets. For these, you must have
RACF alter authority.

Related reading:

Chapter 7. Defining VSAM Data Sets 123

Defining VSAM Data Sets

v For information about using the DEFINE PAGESPACE parameter to define the
page size, see z/OS DFSMS Access Method Services for Catalogs.
v For details on specifying information for a data set, especially for
system-managed data sets, see “Specifying Cluster Information” on page 106
and “Using Access Method Services Parameters” on page 106.
v For information about how VSAM handles duplicate data sets, see “Duplicate
Data Set Names” on page 105.

Checking for Problems in Catalogs and Data Sets

VSAM provides you with several means of locating problems in your catalogs and
data sets. This section describes procedures for listing catalog entries and printing
the contents of data sets.

You can also use the access method services REPRO command to copy a data set
to an output device. For more information about REPRO see “Copying and
Merging Data Sets” on page 117.

The access method services VERIFY command provides a means of checking and
restoring end-of-data-set values after system failure.

The access method services EXAMINE command lets the user analyze and report
on the structural inconsistencies of key-sequenced data set clusters. The EXAMINE
command is described in Chapter 15, “Checking VSAM Key-Sequenced Data Set
Clusters for Structural Errors,” on page 235.

Related reading: For more information about VERIFY, see “Using VERIFY to
Process Improperly Closed Data Sets” on page 50. For information about using the
DIAGNOSE command to indicate the presence of nonvalid data or relationships in
the BCS and VVDS, see z/OS DFSMS Managing Catalogs.

Listing Catalog Entries

After you define a catalog or data set, use the access method services command
LISTCAT to list all or part of a catalog’s entries. LISTCAT shows information about
objects defined in the catalog, such as:
v Attributes of the object, including SMS attributes
v Creation and expiration dates
v Protection specification
v Statistics on dynamic usage or data set accessing represented by the entry
v Space allocation
v Volume information
v Structure of the data set

The listing can be customized by limiting the number of entries, and the
information about each entry, that is printed.

You can obtain the same list while using the interactive storage management
facility (ISMF) by issuing the CATLIST line operator on the Data Set List panel.
The list is placed into a data set, which you can view immediately after issuing the
request.

Related reading: See z/OS DFSMS Using the Interactive Storage Management Facility
for information about the CATLIST line operator.

124 z/OS V1R7.0 DFSMS Using Data Sets

 Defining VSAM Data Sets

Printing the Contents of Data Sets

If a problem occurs, you can use the access method services command PRINT to
print part or all of the contents of a fixed-length or variable-length RRDS; a
key-sequenced, linear, or entry-sequenced VSAM data set; an alternate index; or a
catalog. If you use the relative byte address, you can print part of a linear data set.
Partial printing is rounded up to 4096 byte boundaries. The components of a
key-sequenced data set or an alternate index can be printed individually by
specifying the component name as the data set name. An alternate index is printed
as though it were a key-sequenced cluster.

Entry-sequenced and linear data sets are printed in physical sequential order.
Key-sequenced data sets can be printed in key order or in physical-sequential
order. Fixed-length or variable-length RRDSs are printed in relative record number
sequence. A base cluster can be printed in alternate key sequence by specifying a
path name as the data set name for the cluster.

Only the data content of logical records is printed. System-defined control fields
are not printed. Each record printed is identified by one of the following:
v The relative byte address (RBA) for entry-sequenced data sets.
v The key for indexed-sequential and key-sequenced data sets, and for alternate
indexes
v The record number for fixed-length or variable-length RRDSs.

Related reading: See z/OS MVS Programming: Authorized Assembler Services Guide
for information about program authorization. See “Authorized Program Facility
and Access Method Services” on page 62 for information about using the PRINT
command to print a catalog.

Restriction: If the system finds four logical and/or physical errors while
attempting to read the input, printing ends abnormally.

Deleting Data Sets

Use the access method services DELETE command, described in z/OS DFSMS
Access Method Services for Catalogs, to delete data sets, catalogs, and objects.
DELETE entry name removes the data set from the volume on which it resides, and
the catalog entry for the data set. You can delete the entire cluster, or just the
alternate index, path, or alias, for example. Use DELETE entry name VVR FILE
(ddname) to delete an uncataloged VSAM data set. DELETE entry name VVR FILE
(ddname) removes the VSAM volume record (VVR) from the VSAM volume data
set (VVDS), and the data set control block from the volume table of contents
(VTOC).

Use the ERASE parameter if you want to erase the components of a cluster or
alternate index when deleting it. ERASE overwrites the data set. Use the
NOSCRATCH parameter if you do not want the data set entry (DSCB) removed
from the VTOC. NOSCRATCH nullifies an ERASE parameter on the same DELETE
command.

Use access method services to delete a VSAM cluster or a path which has
associated alternate indexes defined with NOUPGRADE. However, if you perform
the delete using JCL by specifying a DD statement with DISP=(OLD,DELETE), all
volumes that are necessary to delete the alternate index are not allocated. The
delete operation fails with an error message when the job step ends.

Chapter 7. Defining VSAM Data Sets 125

126 z/OS V1R7.0 DFSMS Using Data Sets
Chapter 8. Defining and Manipulating VSAM Data Sets:
Examples
This chapter covers the following topics.

Topic Location
Example of Defining a VSAM Data Set 128
Examples of Defining Temporary VSAM Data Sets 130
Examples of Defining Alternate Indexes and Paths 131

The following set of examples contain a wide range of functions available through
access method services commands that let you define:
v VSAM data sets
v Temporary VSAM data sets
v Alternate indexes and paths

See z/OS DFSMS Access Method Services for Catalogs for examples of the other
functions available through access method services.

An existing system catalog is assumed to be security protected at the

update-password, control-password, and master-password levels. Because
passwords are not supported for system-managed data sets and catalogs, assume
that you have RACF authority for the operation being performed in the examples
that define or manipulate system-managed data sets and catalogs.

© Copyright IBM Corp. 1987, 2005 127

Defining and Manipulating VSAM Data Sets: Examples

Example of Defining a VSAM Data Set

The following example shows a typical sequence of commands to create a catalog,
define a data set (that is cataloged in the newly created catalog), load the data set
with data, list the data set’s catalog entry, and print the data set:
//DEFINE JOB ...
//STEP1 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *

DEFINE USERCATALOG (NAME (USERCATX) ICFCATALOG CYLINDERS(15 5) -

VOLUMES(VSER05)) DATA (CYLINDERS(3 1))

IF LASTCC = 0 THEN -
DEFINE CLUSTER(NAME ([Link]) VOLUMES(VSER05)) -
DATA (KILOBYTES (50 5))
/*
//STEP2 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//AMSDUMP DD SYSOUT=*
//INDSET4 DD DSNAME=[Link],DISP=OLD,
// VOL=SER=VSER02,UNIT=3380
//SYSIN DD *

REPRO INFILE(INDSET4) OUTDATASET([Link])

IF LASTCC = 0 THEN -
LISTCAT ENTRIES([Link])

IF LASTCC = 0 THEN -
PRINT INDATASET([Link])
/*

The following access method services commands are used in this example:

DEFINE USERCATALOG Create the catalog

DEFINE CLUSTER Define the data set
REPRO Load the data set
LISTCAT List the catalog entry
PRINT Print the data set

See Chapter 18, “Using Job Control Language for VSAM,” on page 265 for
examples of creating VSAM data sets through JCL. See z/OS DFSMS Access Method
Services for Catalogs for more details and examples of these or other access method
services commands.

128 z/OS V1R7.0 DFSMS Using Data Sets

 Defining and Manipulating VSAM Data Sets: Examples

The first DEFINE command defines a user catalog named USERCATX. The
USERCATALOG keyword specifies that a user catalog is to be defined. The
command’s parameters follow.

NAME NAME is required and names the catalog being defined.

ICFCATALOG Specifies the catalog format.
CYLINDERS Specifies the amount of space to be allocated from the volume’s
available space. If it is specified for a system-managed catalog, it
overrides the DATACLAS space specification. A space parameter is
required.
VOLUMES Specifies the volume to contain the catalog.

If the catalog is system-managed, then the system picks the volume.

SMS ignores the value that is specified in the VOLUMES parameter.

However, if the catalog belongs to a storage class with guaranteed space,

SMS selects the volume that you specify in the VOLUMES parameter.
You also can write an ACS routine that uses the volume specified in the
VOLUMES parameter to select a storage class.
DATA DATA is required when attributes are to be explicitly specified for the
data component of the cluster.
CYLINDERS Specifies the amount of space allocated for the data component. A space
parameter is required.

The second DEFINE command defines a key-sequenced data set named

[Link]. The command’s parameters are:

CLUSTER The CLUSTER keyword is required, and specifies that a cluster is to be

defined. The CLUSTER keyword is followed by the parameters specified
for the whole clusters, and, optionally, by the parameters specified
separately for the data and index components.
NAME NAME is required and specifies the cluster being defined.
VOLUMES Specifies the volumes that a cluster’s components are allocated space.
You can specify up to 59 volumes per cluster for system-managed
clusters.
DATA DATA is required when parameters are explicitly specified for the data
component of the cluster.
KILOBYTES Specifies the amount of space allocated for the data component.

The REPRO command here loads the VSAM key-sequenced data set named
[Link] from an existing data set called [Link] (that is described
by the INDSET4 DD statement). The command’s parameters are:

INFILE Identifies the data set containing the source data. The ddname of the DD
statement for this data set must match the name specified on this
parameter.
OUTDATASET Identifies the name of the data set to be loaded. Access method services
dynamically allocates the data set. The data set is cataloged in the
master catalog.

Chapter 8. Defining and Manipulating VSAM Data Sets: Examples 129

Defining and Manipulating VSAM Data Sets: Examples

Because the cluster component is not password protected, a password is not

required.

If the REPRO operation is successful, the data set’s catalog entry is listed, and the
contents of the data set just loaded are printed.

LISTCAT Lists catalog entries. The ENTRIES parameter identifies the names of the
entries to be listed.
PRINT Prints the contents of a data set. The INDATASET parameter is required
and identifies the name of the data set to be printed. Access method
services dynamically allocates the data set. The data set is cataloged in
the master catalog. No password is required because the cluster
component is not password protected.

Examples of Defining Temporary VSAM Data Sets

The following examples uses the ALLOCATE command to define a new temporary
VSAM data set. See “Example 4: Allocate a Temporary VSAM Data Set” on page
272 for an example of creating temporary VSAM data sets through JCL. For
information on using JCL to define a permanent VSAM data set, see “Examples
Using JCL to Allocate VSAM Data Sets” on page 270.

Example 1: Defining a Temporary VSAM Data Set Using

ALLOCATE
//ALLOC JOB ...
//STEP1 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=A
//SYSIN DD *

ALLOC -
DSNAME(&CLUSTER) -
NEW -
RECORG(ES) -
SPACE(1,10) -
AVGREC(M) -
LRECL(256) -
STORCLAS(TEMP)
/*

The command’s parameters are:

DSNAME Specifies the data set name. If you specify a data set name for a
system-managed temporary data set, it must begin with & or &&. The
DSNAME parameter is optional for temporary data sets only. If you do
not specify a DSNAME, the system generates a qualified data set name
for the temporary data set.
NEW Specifies that a new data set is created in this job step.
RECORG Specifies a VSAM entry-sequenced data set.
SPACE Specifies an average record length of 1 and a primary quantity of 10.
AVGREC Specifies that the primary quantity specified on the SPACE keyword
represent the number of records in megabytes (multiplier of 1,048,576).
LRECL Specifies a record length of 256 bytes.

130 z/OS V1R7.0 DFSMS Using Data Sets

 Defining and Manipulating VSAM Data Sets: Examples

STORCLAS Specifies a storage class for the temporary data set. The STORCLAS
keyword is optional. If you do not specify STORCLAS for the new data
set and your storage administrator has provided an ACS routine, the
ACS routine can select a storage class.

Example 2: Creating a Temporary Data Set with Default

Parameter Values
The following example shows the minimum number of parameters required to
create a temporary non-VSAM sequential data set. If you want to create a
temporary VSAM data set, specify the RECORG parameter.
//ALLOC JOB ...
//STEP1 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=A
//SYSIN DD *
ALLOC -
FILE(ddname)
NEW -
RECORG(ES)
*/

If no DSNAME name is specified, the system generates one. If no STORCLAS

name is specified, and your storage administrator has provided an ACS routine,
the ACS routine can select a storage class.

Examples of Defining Alternate Indexes and Paths

In this section, the access method services DEFINE ALTERNATEINDEX and
DEFINE PATH commands are used to define alternate indexes and a path.

JCL Statements
The IDCUT1 and IDCUT2 DD statements describe the DSNAMES and a volume
containing data space made available to BLDINDEX for defining and using two
sort work data sets in the event an external sort is performed. The data space is
not used by BLDINDEX if enough virtual storage is available to perform an
internal sort.

Chapter 8. Defining and Manipulating VSAM Data Sets: Examples 131

Defining and Manipulating VSAM Data Sets: Examples

Commands
The first DEFINE command defines a VSAM alternate index over the base cluster
[Link].

NAME NAME is required and names the object being defined.

RELATE RELATE is required and specifies the name of the base cluster on
which the alternate index is defined.
MASTERPW and Specifies the master and update passwords, respectively, for the
UPDATEPW alternate index.
KEYS Specifies the length of the alternate key and its offset in the
base-cluster record.
RECORDSIZE Specifies the length of the alternate-index record. The average and
maximum record lengths are 40 and 50 bytes, respectively. Because
the alternate index is being defined with the NONUNIQUEKEY
attribute, the index must be large enough to contain the primary
keys for all occurrences of any one alternate key.
VOLUMES VOLUMES is required only for non-system-managed data sets and
specifies the volume that contains the alternate index
([Link]).
CYLINDERS Specifies the amount of space allocated to the alternate index. A
space parameter is required.
NONUNIQUEKEY Specifies that the base cluster can contain multiple occurrences of
any one alternate key.
UPGRADE Specifies that the alternate index is to reflect all changes made to
the base-cluster records, such as additions or deletions of records.
CATALOG Because the master catalog is password protected, the CATALOG
parameter is required. It specifies the name of the master catalog
and its update or master password, which is required for defining
in a protected catalog.

The second DEFINE command defines a path over the alternate index. After the
alternate index is built, opening with the path name causes processing of the base
cluster through the alternate index.

NAME The NAME parameter is required and names the object being defined.
PATHENTRY The PATHENTRY parameter is required and specifies the name of the
alternate index over which the path is defined and its master password.
READPW Specifies a read password for the path; it is propagated to the
master-password level.
CATALOG The CATALOG parameter is required, because the master catalog is
password protected. It specifies the name of the master catalog and its
update or master password that is required for defining in a protected
catalog.

132 z/OS V1R7.0 DFSMS Using Data Sets

 Defining and Manipulating VSAM Data Sets: Examples

The BLDINDEX command builds an alternate index. Assume that enough virtual
storage is available to perform an internal sort. However, DD statements with the
default ddnames of IDCUT1 and IDCUT2 are provided for two external sort work
data sets if the assumption is incorrect and an external sort must be performed.

INDATASET The INDATASET parameter identifies the base cluster. Access method
services dynamically allocates the base cluster. The base cluster’s cluster
entry is not password protected even though its data and index
components are.
OUTDATASET The OUTDATASET parameter identifies the alternate index. Access
method services dynamically allocates the alternate index. The update-
or higher-level password of the alternate index is required.
CATALOG The CATALOG parameter specifies the name of the master catalog. If it
is necessary for BLDINDEX to use external sort work data sets, they will
be defined in and deleted from the master catalog. The master password
permits these actions.

The PRINT command causes the base cluster to be printed using the alternate key,
using the path defined to create this relationship. The INDATASET parameter
identifies the path object. Access method services dynamically allocates the path.
The read password of the path is required.

Chapter 8. Defining and Manipulating VSAM Data Sets: Examples 133

134 z/OS V1R7.0 DFSMS Using Data Sets
Chapter 9. Processing VSAM Data Sets
This chapter covers the following topics.

Topic Location
Creating an Access Method Control Block 136
Creating an Exit List 136
Opening a Data Set 137
Creating a Request Parameter List 138
Manipulating the Contents of Control Blocks 140
Requesting Access to a Data Set 141
Closing Data Sets 151
Operating in SRB or Cross-Memory Mode 152
Using VSAM Macros in Programs 153

To process VSAM data sets, you use VSAM macros. You can use the following
procedure for processing a VSAM data set to read, update, add, or delete data:
1. Create an access method control block to identify the data set to be opened
using the ACB or GENCB macro.
2. Create an exit list to specify the optional exit routines that you supply, using
the EXLST or GENCB macro.
3. Optionally, create a resource pool, using the BLDVRP macro. (See Chapter 13,
“Sharing Resources Among VSAM Data Sets,” on page 207.)
4. Connect your program to the data set you want to process, using the OPEN
macro.
5. Create a request parameter list to define your request for access, using the RPL
or GENCB macro.
6. Manipulate the control block contents using the GENCB, TESTCB, MODCB and
SHOWCB macros.
7. Request access to the data set, using one or more of the VSAM request macros
(GET, PUT, POINT, ERASE, CHECK, and ENDREQ).
8. Disconnect your program from the data set, using the CLOSE macro.

The virtual resource pool for all components of the clusters or alternate indexes
must be successfully built before any open is issued to use the resource pool;
otherwise, the results might be unpredictable or performance problems might
occur.

For information about the syntax of each macro, and for coded examples of the
macros, see z/OS DFSMS Macro Instructions for Data Sets.

The ACB, RPL, and EXLST are created by the caller of VSAM. When storage is
obtained for these blocks, virtual storage management assigns the PSW key of the
requestor to the subpool storage. An authorized task can change its PSW key. Since
VSAM record management runs in the protect key of its caller, such a change

© Copyright IBM Corp. 1987, 2005 135

Processing VSAM Data Sets

might make previously acquired control blocks unusable because the storage key
of the subpool containing these control blocks no longer matches the VSAM
caller’s key.

Creating an Access Method Control Block

Before opening a data set for processing, you must create an access method control
block (ACB) that:
v Identifies the data set to be opened
v Specifies the type of processing
v Specifies the basic options
v Indicates if a user exit routine is to be used while the data set is being processed

Include the following information in your ACB for OPEN to prepare the kind of
processing your program requires:
v The address of an exit list for your exit routines. Use the EXLST macro to
construct the list.
v If you are processing concurrent requests, the number of requests (STRNO)
defined for processing the data set. For more information about concurrent
requests see “Making Concurrent Requests” on page 149.
v The size of the I/O buffer virtual storage space and/or the number of I/O
buffers that you are supplying for VSAM to process data and index records.
v The password required for the type of processing desired. Passwords are not
supported for system-managed data sets. You must have RACF authorization for
the type of operation to be performed.
v The processing options that you plan to use:
– Keyed, addressed, or control interval, or a combination
– Sequential, direct, or skip sequential access, or a combination
– Retrieval, storage, or update (including deletion), or a combination
– Shared or nonshared resources.
v The address and length of an area for error messages from VSAM.
v If using RLS, see Chapter 14, “Using VSAM Record-Level Sharing,” on page 219.

You can use the ACB macro to build an access method control block when the
program is assembled, or the GENCB macro to build a control block when the
program is run. See “Manipulating the Contents of Control Blocks” on page 140 for
information about the advantages and disadvantages of using GENCB.

Creating an Exit List

To access exit routines during data set processing, you must specify the addresses
of your exit routines using the EXLST macro. Any number of ACB macros in a
program can indicate the same exit list for the same exit routines to do all the
special processing for them, or they can indicate different exit lists. Use exit
routines for the following tasks:
v Analyzing physical errors. When VSAM finds an error in an I/O operation that
the operating system’s error routine cannot correct, the error routine formats a
message for your physical error analysis routine (the SYNAD user exit) to act
on.
v Analyzing logical errors. Errors not directly associated with an I/O operation,
such as an nonvalid request, cause VSAM to exit to your logical error analysis
routine (the LERAD user exit).

136 z/OS V1R7.0 DFSMS Using Data Sets

 Processing VSAM Data Sets

v End-of-data-set processing. When your program requests a record beyond the

last record in the data set, your end-of-data-set routine (the EODAD user exit) is
given control. The end of the data set is beyond either the highest addressed or
the highest keyed record, if your program is using addressed or keyed access.
v Journalizing transactions. To journalize the transactions against a data set, you
might specify a journal routine (the JRNAD user exit). To process a
key-sequenced data set using addressed access, you need to know if any RBAs
changed during keyed processing. When you are processing by key, VSAM exits
to your routine for noting RBA changes before writing a control interval in
which there is an RBA change. When journalizing transactions for compressed
data sets, the RBAs and data lengths represent compressed data. VSAM does not
exit to the JRNAD routine for RBA change if the data set is extended
addressable.
v User processing. User processing exits (UPAD) are available to assist subsystems
that need to dispatch new units of work. The UPAD wait exit is given control
before VSAM issues any WAIT SVCs. Use the UPAD post exit to make it easier
to use cross-memory processing. See Table 26 on page 260.

The EXLST macro is coordinated with the EXLST parameter of an ACB or GENCB
macro used to generate an ACB. To use the exit list, you must code the EXLST
parameter in the ACB.

You can use the EXLST macro to build an exit list when the program is assembled,
or the GENCB macro to build an exit list when the program is run. For
information about the advantages and disadvantages of using GENCB see
“Manipulating the Contents of Control Blocks” on page 140.

Opening a Data Set

Before accessing a data set, your program must issue the OPEN macro to open the
data set for processing. Opening a data set causes VSAM to take the following
actions:
v Verify that the data set matches the description specified in the ACB or GENCB
macro (for example, MACRF=KEY implies that the data set is a key-sequenced
data set).
v Construct the internal control blocks that VSAM needs to process your requests
for access to the data set.
To determine which processing options to use, VSAM merges information from
the data definition (DD) statement and catalog definition of the data set with
information in the access method control block and exit list. The order of
precedence follows:
1. The DD statement AMP parameters
2. The ACB, EXLST, or GENCB parameters
3. The catalog entry for the data set
For example, if both an ACB or GENCB macro and the DD statement have
values for buffer space, the values in the DD statement override those in the
macro. The catalog entry is the minimum buffer space when it is not specified in
the DD statement or macro or when it is less than the amount specified in the
data set definition.
v Check for consistency of updates to the prime index and data components if you
are opening a key-sequenced data set, an alternate index, or a path. If separate
updates occur to data set and its index, VSAM issues a warning message to
indicate a time stamp discrepancy.

Chapter 9. Processing VSAM Data Sets 137

Processing VSAM Data Sets

v An error during OPEN can cause a component that is open for update
processing to close improperly, leaving on the open-for-output indicator. When
VSAM detects an open-for-output indicator, it issues an implicit VERIFY
command and a message that indicates whether the VERIFY command was
successful.
If a subsequent OPEN is issued for update, VSAM turns off the open-for-output
indicator at CLOSE. If the data set was open for input, however, VSAM leaves
on the open-for-output indicator.
v Check the password your program specified in the ACB PASSWD parameter
against the appropriate password (if any) in the catalog definition of the data.
The system does not support passwords for system-managed data sets. A
password of one level authorizes you to do everything that a password of a
lower level authorizes. You must have RACF authorization for the operation.
The password requirement depends on the kind of access that is specified in the
access method control block:
– Full access lets you perform all operations (retrieve, update, insert, and
delete) on a data set on any associated index or catalog record. The master
password lets you delete or alter the catalog entry for the data set or catalog
it protects.
– Control-interval update access requires the control password or RACF control
authority. The control lets you use control-interval access to retrieve, update,
insert, or delete records in the data set it protects. For information about the
use of control-interval access, see Chapter 11, “Processing Control Intervals,”
on page 179.
Control-interval read access requires only the read password or RACF read
authority, that lets you examine control intervals in the data set it protects.
The read password or RACF read authority does not let you add, change, or
delete records.
– Update access requires the update password, which lets you retrieve, update,
insert, or delete records in the data set it protects.
– Read access requires the read password, that lets you examine records in the
data set it protects. The read password does not permit you to add, change,
or delete records.

Note: RACF protection supersedes password protection for a data set. RACF
checking is bypassed for a caller that is in supervisor state or key 0. For
more information on password and RACF protection, see Chapter 5,
“Protecting Data Sets,” on page 53.

Creating a Request Parameter List

After you have connected your program to a data set, you can issue requests for
access. A request parameter list defines a request. This list identifies the data set to
which the request is directed by naming the ACB macro that defines the data set.
Each request macro (GET, PUT, ERASE, POINT, CHECK, and ENDREQ) gives the
address of the request parameter list that defines the request.

You can use the RPL macro to generate a request parameter list (RPL) when your
program is assembled, or the GENCB macro to build a request parameter list when
your program is run. For information about the advantages and disadvantages of
using GENCB, see “Manipulating the Contents of Control Blocks” on page 140.

When you define your request, specify only the processing options appropriate for
that particular request. Parameters not required for a request are ignored. For

138 z/OS V1R7.0 DFSMS Using Data Sets

 Processing VSAM Data Sets

example, if you switch from direct to sequential retrieval with a request parameter
list, you do not have to zero out the address of the field containing the search
argument (ARG=address).

The following information defines your request:

v Access by address (RBA), key, or relative record number. Address access can be
sequential or direct. Key or relative record number access can be sequential, skip
sequential, or direct. Access can be forward (next sequential record) or backward
(previous sequential record). Access can be for updating or not updating. A
nonupdate direct request to retrieve a record causes VSAM to position to the
following record for subsequent sequential access. For more information about
VSAM positioning, see “POINT Macro for Positioning” on page 145.
v RPLs (including RPLs defined by a chain), either synchronous, so that VSAM
does not give control back to your program until the request completes, or
asynchronous, so that your program can continue to process or issue other
requests while the request is active. With asynchronous requests, your program
must use the CHECK macro to suspend its processing until the request
completes. For more information about synchronous and asynchronous
processing, see “Making Asynchronous Requests” on page 150.
v For a keyed request, either a generic key (a leading portion of the key field), or a
full key to which the key field of the record is to be compared.
v For retrieval, either a data record to be placed in a work area in your program
or the address of the record within VSAM’s buffer to be passed to your
program. For requests that involve updating or inserting, the work area in your
program contains the data record.
v For a request to directly access a control interval, specify the RBA of the control
interval. With control interval access, you are responsible for maintaining the
control information in the control interval. If VSAM’s buffers are used, VSAM
permits control interval and stored record operations simultaneously. If your
program provides its own buffers, only control interval processing is permitted.
For information about control interval access, see Chapter 11, “Processing
Control Intervals,” on page 179.

You can chain request parameter lists together to define a series of actions for a
single GET or PUT. For example, each parameter list in the chain could contain a
unique search argument and point to a unique work area. A single GET macro
would retrieve a record for each request parameter list in the chain. All RPLs in a
chain must refer to the same ACB.

A chain of request parameter lists is processed serially as a single request.

(Chaining request parameter lists is not the same as processing concurrent requests
in parallel. Processing in parallel requires that VSAM keep track of many positions
in a data set.)

Each request parameter list in a chain should have the same OPTCD
subparameters. Having different subparameters can cause logical errors. You
cannot chain request parameter lists for updating or deleting records—only for
retrieving records or storing new records. You cannot process records in the I/O
buffer with chained request parameter lists. (RPL OPTCD=UPD and RPL
OPTCD=LOC are nonvalid for a chained request parameter list.)

With chained request parameter lists, a POINT, a sequential or skip-sequential

GET, or a direct GET with positioning requested (RPL OPTCD=NSP) causes VSAM
to position itself at the record following the record identified by the last request
parameter list in the chain.

Chapter 9. Processing VSAM Data Sets 139

Processing VSAM Data Sets

When you are using chained RPLs, if an error occurs anywhere in the chain, the
RPLs following the one in error are made available without being processed and
are posted complete with a feedback code of zero.

Manipulating the Contents of Control Blocks

VSAM provides a set of macros, GENCB, TESTCB, MODCB, and SHOWCB, to let
you manipulate the contents of control blocks at execution time. Use these macros
to generate, test, modify, and display the contents of fields in the access method
control block, the exit list, and the request parameter list. You do not have to know
the format of the control block when you use these macros.

The GENCB, MODCB, TESTCB, and SHOWCB macros build a parameter list that
describes, in codes, the actions indicated by the parameters you specify. The
parameter list is passed to VSAM to take the indicated actions. An error can occur
if you specify the parameters incorrectly.

If you issue a MODCB, SHOWCB, or TESTCB for a non-VSAM ACB, unpredictable

results occur.

Generating a Control Block

The GENCB macro can be used to generate an access method control block, an exit
list, or a request parameter list when your program is run. Generating the control
block at execution time with GENCB has the advantage of requiring no reassembly
of the program when you adopt a new version of VSAM in which control block
formats might have changed. If you use the ACB, EXLST, and RPL macros to build
control blocks, and adopt a subsequent release of VSAM in which the control block
format has changed, you have to reassemble your program. GENCB also gives you
the ability to generate multiple copies of the ACB, EXLST, or RPL to be used for
concurrent requests. The disadvantage of using GENCB is that the path length is
longer. It takes more instructions to build a control block using GENCB than to
code the control block directly.

You can use the WAREA parameter to provide an area of storage in which to
generate the control block. This work area has a 64K (X'FFFF') size limit. If you do
not provide storage when you generate control blocks, the ACB, RPL, and EXLST
reside below 16 MB unless LOC=ANY is specified.

Testing the Contents of ACB, EXLST, and RPL Fields

With the TESTCB macro, VSAM compares the contents of a field you specify with
a value that you specify. To show the result of this comparison, VSAM sets the
condition code in the PSW (program status word). Only one keyword can be
specified each time TESTCB is issued. Use TESTCB to find out:
v If an action has been done by VSAM or your program (for example, opening a
data set or activating an exit).
v What kind of a data set is being processed to alter your program logic as a
result of the test.

After issuing a TESTCB macro, examine the PSW condition code. If the TESTCB is
not successful, register 15 contains an error code and VSAM passes control to an
error routine, if one has been specified. For a keyword specified as an option or a
name, you test for an equal or unequal comparison; for a keyword specified as an
address or a number, you test for an equal, unequal, high, low, not-high, or
not-low condition.

140 z/OS V1R7.0 DFSMS Using Data Sets

 Processing VSAM Data Sets

VSAM compares A to B, where A is the contents of the field and B is the value to
compare. A low condition means, for example, A is lower than B — that is, the
value in the control block is lower than the value you specified. If you specify a
list of option codes for a keyword (for example, MACRF=(ADR,DIR)), each of
them must equal the corresponding value in the control block for you to get an
equal condition.

Some of the fields can be tested at any time; others, only after a data set is opened.
The ones that can be tested only after a data set is opened can, for a key-sequenced
data set, pertain either to the data or to the index, as specified in the OBJECT
parameter.

You can display fields using the SHOWCB macro at the same time you test the
fields.

Modifying the Contents of an ACB, EXLST, or RPL

The MODCB macro lets you customize the control blocks generated with the
GENCB macro. The MODCB macro can be used to modify the contents of an
access method control block, an exit list, or a request parameter list. Typical
reasons to modify a request parameter list are to change the length of a record
(RECLEN) when you are processing a data set whose records are not all the same
length, and to change the type of request (OPTCD), such as from direct to
sequential access or from full-key search argument to generic key search argument.

Displaying the Contents of ACB, EXLST, and RPL Fields

The SHOWCB macro causes VSAM to move the contents of various fields in an
access method control block, an exit list, or a request parameter list into your work
area. You might want to learn the reason for an error or to collect statistics about a
data set to permit your program to print a message or keep records of transactions.

Requesting Access to a Data Set

After your program is opened and a request parameter list is built, use the action
request macros GET, PUT, ERASE, POINT, CHECK, and ENDREQ. Each request
macro uses a request parameter list that defines the action to be taken. For
example, when a GET macro points to a request parameter list that specifies
synchronous, sequential retrieval, the next record in sequence is retrieved. When an
ENDREQ macro points to a request parameter list, any current request (for
example, a PUT) for that request parameter list finishes, and the resources held by
the request parameter list are released.

The action request macros lets you do the following tasks:

v Insert new records
v Retrieve existing records
v Point to existing records
v Update existing records
v Delete existing records
v Write buffers
v Retain buffers
v Perform multistring processing
v Perform concurrent requests
v Access records using a path
v Check for completion of asynchronous requests
v End request processing

Chapter 9. Processing VSAM Data Sets 141

Processing VSAM Data Sets

Inserting and Adding Records

Record insertions in VSAM data sets occur in several ways:
v PUT RPL OPTCD=DIR,NSP—Inserting records directly. VSAM remembers its
position for subsequent sequential access.
v PUT RPL OPTCD=DIR,NUP—Inserting a record directly. VSAM does not
remember its position.
v PUT RPL OPTCD=SEQ,NUP or NSP—Inserting records sequentially. VSAM
remembers its position for subsequent sequential access.
v PUT RPL OPTCD=SKP,NUP or NSP—Inserting records in skip sequential order.
VSAM remembers its position for subsequent sequential access.

Insertions into an Entry-Sequenced Data Set

VSAM does not insert new records into an entry-sequenced data set. All records
are added at the end of the data set.

Insertions into a Key-Sequenced Data Set

Insertions into a key-sequenced data set use the free space provided during the
definition of the data set or the free space that develops because of control interval
and control area splits. To create a data set or make mass insertions, use RPL
OPTCD=SEQ,NUP or NSP. RPL OPTCD=SEQ,NUP or NSP inserts the records
sequentially and maintains free space during load mode and during mass
insertions. All the other types use the direct insert strategy. If MACRF=SIS is
specified in the ACB, all inserts use sequential insert strategy.

With addressed access of a key-sequenced data set, VSAM does not insert or add
new records.

Sequential Insertion. If the new record belongs after the last record of the control
interval and the record contains free space, the new record is inserted into the
existing control interval. If the control interval does not contain sufficient free
space, the new record is inserted into a new control interval without a true split.

If the new record does not belong at the end of the control interval and there is
free space in the control interval, it is placed in sequence into the existing control
interval. If adequate free space does not exist in the control interval, a control
interval split occurs at the point of insertion. The new record is inserted into the
original control interval and the following records are inserted into a new control
interval.

Mass Sequential Insertion. When VSAM detects two or more records to be

inserted in sequence into a collating position (between two records) in a data set,
VSAM uses a technique called mass sequential insertion to buffer the records being
inserted, and to reduce I/O operations. Using sequential instead of direct access
takes advantage of this technique. Also extend your data set (resume loading) by
using sequential insertion to add records beyond the highest key or relative record
number. There are possible restrictions to extending a data set into a new control
area depending on the specified share options. See Chapter 12, “Sharing VSAM
Data Sets,” on page 191.

Mass sequential insertion observes control interval and control area free space
specifications when the new records are a logical extension of the control interval
or control area (that is, when the new records are added beyond the highest key or
relative record number used in the control interval or control area).

142 z/OS V1R7.0 DFSMS Using Data Sets

 Processing VSAM Data Sets

When several groups of records in sequence are to be mass inserted, each group
can be preceded by a POINT with RPL OPTCD=KGE to establish positioning. KGE
specifies that the key you provide for a search argument must be equal to the key
or relative record number of a record.

Direct Insertion—CI Split. If the control interval has enough available space, the
record is inserted. If the control interval does not have enough space to hold the
record, the entire CI is split, unless the record is the last key in the file. The last
record is always placed in a new, empty CI and does not show up as a CI split.

Direct Insertion—CA Split. If no additional CI is available to allow a CI split, the

CA is split. For the last record in the file, however, the new record is inserted as
the first record in a new, empty CA. This does not show up as a CA split. If the
new record belongs after the last record of the control interval and there is still
space, the new record is added to the end of the existing control interval. If the
control interval does not contain sufficient free space, the new record is inserted
into an unused control interval.

Insertions into a Fixed-Length Relative-Record Data Set

You can insert records into a fixed-length RRDS either sequentially or directly.

Sequential Insertion. Insertions into a fixed-length RRDS go into empty slots.

When a record is inserted sequentially into a fixed-length RRDS it is assigned the
next relative record number in sequence. If the slot is not empty, VSAM sets an
error return code, indicating a duplicate record. The assigned number is returned
in the argument field of the RPL.

Direct Insertion. Direct or skip-sequential insertion of a record into a fixed-length

RRDS places the record as specified by the relative record number in the argument
field of the RPL. You must insert the record into a slot that does not contain a
record. If the slot specified does contain a record, VSAM sets an error return code
in the RPL and rejects the request.

If the insertion is to the end of the control interval, the record is placed in a new
control interval.

Insertions into a Variable-Length Relative-Record Data Set

A variable-length RRDS is processed in the same way as a fixed-length RRDS, with
the following exceptions:
v You must specify the record length in the RECLEN field of the RPL macro.
v Insertions into a variable-length RRDS use the free space provided during the
definition of the data set or the free space that develops because of control
interval and control area splits.

Chapter 9. Processing VSAM Data Sets 143

Processing VSAM Data Sets

As for a fixed-length RRDS, you can insert records into a variable-length RRDS
either sequentially or directly.

Sequential Insertion. When a record is inserted sequentially into a variable-length

RRDS, it is assigned the next available relative record number in sequence. The
assigned number is returned in the argument field of the RPL. Use mass sequential
insertion with a variable-length RRDS.

Direct Insertion. Direct or skip-sequential insertion of a record into a

variable-length RRDS places the record as specified by the relative record number
in the argument field of the RPL. If you specify a duplicate relative record number,
VSAM sets an error return code in the RPL and rejects the request.

Insertions into a Linear Data Set

Linear data sets cannot be processed at the record level. Use of the GET, PUT and
POINT macros is not permitted at the record level. You must use the DIV macro to
process a linear data set. See z/OS MVS Programming: Assembler Services Guide for
information about using DIV.

Retrieving Records
The GET macro is used to retrieve records. To retrieve records for update, use the
GET macro with the PUT macro. When you retrieve records either sequentially or
directly, VSAM returns the length of the retrieved record to the RECLEN field of
the RPL.

Sequential Retrieval
Records can be retrieved sequentially using keyed access or addressed access.

Keyed Sequential Retrieval. The first time your program accesses a data set for
keyed sequential access (RPL OPTCD=(KEY,SEQ)), VSAM is positioned at the first
record in the data set in key sequence if and only if the following is true:
1. Nonshared resources are being used.
2. There have not been any previous requests against the file.

If VSAM picks a string that has been used previously this implicit positioning does
not occur. Therefore, with concurrent or multiple RPL’s, it is best to initiate your
own POINTs and positioning to prevent logic errors.

With shared resources, you must always use a POINT macro to establish position.
A GET macro can then retrieve the record. Certain direct requests can also hold
position. See Table 11 on page 147 for details on when positioning is retained or
released. VSAM checks positioning when processing modes are changed between
requests.

For keyed sequential retrieval of a fixed-length or variable-length RRDS, the

relative record number is treated as a full key. If a deleted record is found during
sequential retrieval, it is skipped and the next record is retrieved. The relative
record number of the retrieved record is returned in the argument field of the RPL.

144 z/OS V1R7.0 DFSMS Using Data Sets

 Processing VSAM Data Sets

Addressed Sequential Retrieval. Retrieval by address is identical to retrieval by

key, except the search argument is a RBA, which must be matched to the RBA of a
record in the data set. When a processing program opens a data set with
nonshared resources for addressed access, VSAM is positioned at the record with
RBA of zero to begin addressed sequential processing. A sequential GET request
causes VSAM to retrieve the data record at which it is positioned, and positions
VSAM at the next record. The address specified for a GET or a POINT must
correspond to the beginning of a data record; otherwise the request is not valid.
Spanned records stored in a key-sequenced data set cannot be retrieved using
addressed retrieval.

You cannot predict the RBAs of compressed records.

GET-previous (backward-sequential) processing is a variation of normal keyed or

addressed-sequential processing. Instead of retrieving the next record in ascending
sequence (relative to current positioning in the data set), GET-previous processing
retrieves the next record in descending sequence. To process records in descending
sequence, specify BWD in the RPL OPTCD parameter. Select GET-previous
processing for POINT, GET, PUT (update only), and ERASE operations. The initial
positioning by POINT, other than POINT LRD, requires that you specify a key. The
following GET-previous processing does not need any specified key to retrieve the
next record in descending sequence.

GET-previous processing is not permitted with control interval or skip-sequential

processing.

POINT Macro for Positioning

You can use the POINT macro to begin retrieving records sequentially at a place
other than the beginning of the data set. The POINT macro places VSAM at the
record with the specified key or relative byte address. However, it does not
provide data access to the record. If you specify a generic key (a leading portion of
the key field), the record pointed to is the first of the records having the same
generic key. The POINT macro can position VSAM for either forward or backward
processing, if FWD or BWD was specified in the RPL OPTCD parameter.

If, after positioning, you issue a direct request through the same request parameter
list, VSAM drops positioning unless NSP or UPD was specified in the RPL OPTCD
parameter.

When a POINT is followed by a VSAM GET/PUT request, both the POINT and
the subsequent request must be in the same processing mode. For example, a
POINT with RPL OPTCD=(KEY,SEQ,FWD) must be followed by GET/PUT with
RPL OPTCD=(KEY,SEQ,FWD); otherwise, the GET/PUT request is rejected.

For skip-sequential retrieval, you must indicate the key of the next record to be
retrieved. VSAM skips to the next record’s index entry by using horizontal pointers
in the sequence set to find the appropriate sequence-set index record and scan its
entries. The key of the next record to be retrieved must always be higher in
sequence than the key of the preceding record retrieved.

If your request fails, with an error code, positioning cannot be maintained. To

determine if positioning is maintained when a logical error occurs, see z/OS
DFSMS Macro Instructions for Data Sets. Positioning is always released when you
specify the ENDREQ macro.

Chapter 9. Processing VSAM Data Sets 145

Processing VSAM Data Sets

Direct Retrieval
Records can also be retrieved directly using keyed access or addressed access.

Keyed Direct Retrieval. For a key-sequenced data set does not depend on prior
positioning. VSAM searches the index from the highest level down to the sequence
set to retrieve a record. Specify the record to be retrieved by supplying one of the
following:
v The exact key of the record
v An approximate key, less than or equal to the key field of the record
v A generic key

You can use an approximate specification when you do not know the exact key. If
a record actually has the key specified, VSAM retrieves it. Otherwise, it retrieves
the record with the next higher key. Generic key specification for direct processing
causes VSAM to retrieve the first record having that generic key. If you want to
retrieve all the records with the generic key, specify RPL OPTCD=NSP in your
direct request. That causes VSAM to position itself at the next record in key
sequence. Then retrieve the remaining records sequentially.

To use direct or skip-sequential access to process a fixed-length or variable-length

RRDS, you must supply the relative record number of the record you want in the
argument field of the RPL macro. For a variable-length RRDS, you also must
supply the record length in the RECLEN field of the RPL macro. If you request a
deleted record, the request causes a no-record-found logical error.

A fixed-length RRDS has no index. VSAM takes the number of the record to be
retrieved and calculates the control interval that contains it and its position within
the control interval.

Addressed Direct Retrieval. Requires the RBA of each individual record is

specified; previous positioning is not applicable.

With direct processing, optionally specify RPL OPTCD=NSP to indicate the

position is maintained following the GET. Your program can then process the
following records sequentially in either a forward or backward direction.

Updating Records
The GET and PUT macros are used to update records. A GET for update retrieves
the record and the following PUT for update stores the record the GET retrieved.

When you update a record in a key-sequenced data set, you cannot alter the
primary-key field.

Changing Record Length

You can update the contents of a record with addressed access, but you cannot
alter the record’s length. To change the length of a record in an entry-sequenced
data set, you must store it either at the end of the data set (as a new record) or in
the place of an inactive record of the same length. You are responsible for marking
the old version of the record as inactive.

Processing the Data Component of a Key-Sequenced Data Set

You can process the data component separately from the index component.
Processing the data component separately lets you print or dump the data
component and the index component of a key-sequenced data set individually.

146 z/OS V1R7.0 DFSMS Using Data Sets

 Processing VSAM Data Sets

However, do not process only the data component if you plan to update the data set.
Always open the cluster when updating a key-sequenced data set.

Deleting Records
After a GET for update retrieves a record, an ERASE macro can delete the record.
The ERASE macro can be used only with a key-sequenced data set or a
fixed-length or variable-length RRDS. When you delete a record in a
key-sequenced data set or variable-length RRDS, the record is physically erased.
The space the record occupied is then available as free space.

You can erase a record from the base cluster of a path only if the base cluster is a
key-sequenced data set. If the alternate index is in the upgrade set in which
UPGRADE was specified when the alternate index was defined, it is modified
automatically when you erase a record. If the alternate key of the erased record is
unique, the alternate index data record with that alternate key is also deleted.

When you erase a record from a fixed-length RRDS, the record is set to binary
zeros and the control information for the record is updated to indicate an empty
slot. Reuse the slot by inserting another record of the same length into it.

With an entry-sequenced data set, you are responsible for marking a record you
consider to be deleted. As far as VSAM is concerned, the record is not deleted.
Reuse the space occupied by a record marked as deleted by retrieving the record
for update and storing in its place a new record of the same length.

Deferring and Forcing Buffer Writing

For integrity reasons, it is sometimes desirable to force the data buffer to be
written after a PUT operation. At other times, it is desirable to defer the writing of
a buffer when possible to improve performance. At the time the PUT is issued, if
the RPL OPTCD specifies direct processing (DIR), and NSP is not specified, forced
writing of the buffer occurs. Otherwise, writing is deferred. An ERASE request
follows the same buffer writing rules as the PUT request. If LSR and GSR deferred
writes are not specified, an ENDREQ macro always forces the current modified
data buffer to be written.

Retaining and Positioning Data Buffers

Some operations retain positioning while others release it. In a similar way, some
operations hold onto a buffer and others release it with its contents. Table 11 shows
which RPL options result in the retention of data buffers and positioning, and
which options result in the release of data buffers and positioning.
Table 11. Effect of RPL Options on Data Buffers and Positioning
RPL Options Retained Released
SEQ *
SKP *
DIR NSP *
DIR (no NSP) *
DIR LOC *
UPD (with Get) *

Note:

Chapter 9. Processing VSAM Data Sets 147

Processing VSAM Data Sets

1. A sequential GET request for new control intervals releases the previous buffer.
2. The ENDREQ macro and the ERASE macro with RPL OPTCD=DIR release data
buffers and positioning.
3. Certain options that retain positioning and buffers on normal completion
cannot do so if the request fails with an error code. See z/OS DFSMS Macro
Instructions for Data Sets to determine if positioning is maintained if a logical
error occurs.

The following operation uses but immediately releases a buffer and does not retain
positioning:
GET RPL OPTCD=(DIR,NUP,MVE)

Processing Multiple Strings

In multiple string processing, there can be multiple independent RPLs within an
address space for the same data set. The data set can have multiple tasks that
share a common control block structure. There are several ACB and RPL
arrangements to indicate that multiple string processing occurs:
v In the first ACB opened, STRNO or BSTRNO is greater than 1.
v Multiple ACBs are opened for the same data set within the same address space
and are connected to the same control block structure.
v Multiple concurrent RPLs are active against the same ACB using asynchronous
requests.
v Multiple RPLs are active against the same ACB using synchronous processing
with each requiring positioning to be held.

If you are doing multiple string update processing, you must consider VSAM
lookaside processing and the rules surrounding exclusive use. Lookaside means
VSAM checks its buffers to see if the control interval is already present when
requesting an index or data control interval.

For GET nonupdate requests, an attempt is made to locate a buffer already in

storage. As a result, a down-level copy of the data can be obtained either from
buffers attached to this string or from secondary storage.

For GET to update requests, the buffer is obtained in exclusive control, and read
from the device for the latest copy of the data. If the buffer is already in exclusive
control of another string, the request fails with an exclusive control feedback code.
If you are using shared resources, the request can be queued, or can return an
exclusive control error.

The exclusive use rules follow:

1. If a given string obtains a record with a GET for update request, the control
interval is not available for update or insert processing by another string.
2. If a given string is in the process of a control area split caused by an update
with length change or an insert, that string obtains exclusive control of the
entire control area being split. Other strings cannot process insert or update
requests against this control area until the split is complete.

If you are using nonshared resources, VSAM does not queue requests that have
exclusive control conflicts, and you are required to clear the conflict. If a conflict is
found, VSAM returns a logical error return code, and you must stop activity and
clear the conflict. If the RPL that caused the conflict had exclusive control of a

148 z/OS V1R7.0 DFSMS Using Data Sets

 Processing VSAM Data Sets

control interval from a previous request, you issue an ENDREQ before you attempt
to clear the problem. Clear the conflict in one of three ways:
v Queue until the RPL holding exclusive control of the control interval releases
that control, then reissue the request.
v Issue an ENDREQ against the RPL holding exclusive control to force it to release
control immediately.
v Use shared resources and issue MRKBFR MARK=RLS.

Note: If the RPL includes a correctly specified MSGAREA and MSGLEN, the
address of the RPL holding exclusive control is provided in the first word of the
MSGAREA. The RPL field, RPLDDDD, contains the RBA of the requested control
interval.

Making Concurrent Requests

With VSAM, you can maintain concurrent positioning for many requests to a data
set.

Strings (sometimes called place holders) are like cursors, each represents a position
in the data set and are like holding your finger in a book to keep the place. The
same ACB is used for all requests, and the data set needs to be opened only once.
This means, for example, you could be processing a data set sequentially using one
RPL, and at the same time, using another RPL, directly access selected records
from the same data set.

Keep in mind, though, that strings are not “owned” by the RPL any longer than
the request holds its position. Once a request gives up its position (for example,
with an ENDREQ), that string is free to be used by another request and must be
repositioned in the data set by the user.

For each request, a string defines the set of control blocks for the exclusive use of
one request. For example, if you use three RPLs, you should specify three strings.
If the number of strings you specify is not sufficient, and you are using NSR, the
operating system dynamically extends the number of strings as needed by the
concurrent requests for the ACB. Strings allocated by dynamic string addition are
not necessarily in contiguous storage.

Dynamic string addition does not occur with LSR and GSR. Instead, you get a
logic error if you have more requests than available strings.

The maximum number of strings that can be defined or added by the system is
255. Therefore, the maximum number of concurrent requests holding position in
one data set at any one time is 255.

Using a Path to Access Records

When you are processing records sequentially using a path, records from the base
cluster are returned according to ascending or, if you are retrieving the previous
record, descending alternate key values. If there are several records with a
nonunique alternate key, those records are returned in the order they were entered
into the alternate index. READNEXT and READPREV returns these nonunique
alternate index records in the same sequence. VSAM sets a return code in the RPL
when there is at least one more record with the same alternate key to be processed.
For example, if there are three data records with the alternate key 1234, the return
code would be set during the retrieval of records one and two and would be reset
during retrieval of the third record.

Chapter 9. Processing VSAM Data Sets 149

Processing VSAM Data Sets

When you use direct or skip-sequential access to process a path, a record from the
base data set is returned according to the alternate key you specified in the
argument field of the RPL macro. If the alternate key is not unique, the record first
entered with that alternate key is returned and a feedback code (duplicate key) is
set in the RPL. To retrieve the remaining records with the same alternate key,
specify RPL OPTCD=NSP when retrieving the first record with a direct request,
and switch to sequential processing.

You can insert and update data records in the base cluster using a path if:
v The PUT request does not result in nonunique alternate keys in an alternate
index (defined with the UNIQUEKEY attribute). However, if a nonunique
alternate key is generated and the NONUNIQUEKEY attribute is specified,
updating can occur.
v You do not change the key of reference between the time the record was
retrieved for update and the PUT is issued.
v You do not change the primary key.

When the alternate index is in the upgrade set, the alternate index is modified
automatically by inserting or updating a data record in the base cluster. If the
updating of the alternate index results in an alternate index record with no
pointers to the base cluster, the alternate-index record is erased.

Rule: When you use SHAREOPTIONS 2, 3, and 4, you must continue to ensure
read/write integrity when issuing concurrent requests (such as GETs and PUTs) on
the base cluster and its associated alternate indexes. Failure to ensure read/write
integrity might temporarily cause “No Record Found” or “No Associated Base
Record” errors for a GET request. Bypass such errors by reissuing the GET request,
but it is best to prevent the errors by ensuring read/write integrity.

Making Asynchronous Requests

In synchronous mode, VSAM does not return to your program from a PUT or GET
operation until it has completed the operation. In asynchronous mode, VSAM
returns control to your program before completing a PUT or a GET. A program in
asynchronous mode can perform other useful work while a VSAM PUT or GET is
completed.

Asynchronous mode can improve throughput with direct processing because it

permits processing to overlap with accesses from and to the direct access device.
When reading records directly, each read often involves a seek on the direct access
device, a slow operation. In synchronous mode, this seek time does not overlap
with other processing.

Specifying Asynchronous Mode

To specify asynchronous mode, you must specify OPTCD=ASY rather than
OPTCD=SYN in the RPL.

Checking for Completion of Asynchronous Requests

Suppose your program is ready to process the next record, but VSAM is still trying
to obtain that record. (The next record is not yet read in from the direct access
device.) You might need to stop execution of the program and wait for VSAM to
complete reading in the record. The CHECK macro stops executing the program
until the operation in progress is complete. You must issue a CHECK macro after
each request for an RPL. If you attempt another request without an intervening
CHECK, that request is rejected.

150 z/OS V1R7.0 DFSMS Using Data Sets

 Processing VSAM Data Sets

Once the request is completed, CHECK releases control to the next instruction in
your program, and frees up the RPL for use by another