IBM z/OS DFSMS Data Sets User manual

z/OS
IBM
DFSMS Using Data Sets
Version 2 Release 3
SC23-6855-30
Note
Before using this information and the product it supports, read the information in “Notices” on page 677.
This edition applies to Version 2 Release 3 of z/OS (5650-ZOS) and to all subsequent releases and modifications
until otherwise indicated in new editions.
Last updated: December 7, 2017
© Copyright IBM Corporation 1987, 2017.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . xiii
Tables . . . . . . . . . . . . . . . xv
About This Document. . . . . . . . xvii
Major Divisions of This Document
Required product knowledge . .
Referenced documents . . . .
z/OS information . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xvii
. xvii
. xviii
. xviii
.
.
How to send your comments to IBM
If you have a technical problem .
.
.
.
.
xix
.
. xix
Summary of changes . . . . . . . . xxi
Summary of changes for z/OS Version 2
(V2R3) . . . . . . . . . . . .
Summary of changes for z/OS Version 2
(V2R2) . . . . . . . . . . . .
Summary of changes for z/OS Version 2
(V2R1) as updated March 2014 . . .
Summary of changes for z/OS Version 2
(V2R1) as updated December 2013 . .
Release 3
. . . . xxi
Release 2
. . . . xxi
Release 1
. . . . xxii
Release 1
. . . . xxii
Part 1. All Data Sets. . . . . . . . . 1
Chapter 1. Working with Data Sets . . . 3
Data Storage and Management . . . . . . . . 3
System-Managed Data Sets . . . . . . . . 4
Distributed File Manager . . . . . . . . . 4
Access Methods . . . . . . . . . . . . . 4
Basic Direct Access Method . . . . . . . . 4
Basic Partitioned Access Method. . . . . . . 5
Basic Sequential Access Method . . . . . . . 5
Data-in-Virtual (DIV) . . . . . . . . . . 6
Indexed Sequential Access Method . . . . . . 6
Object Access Method . . . . . . . . . . 6
Queued Sequential Access Method . . . . . . 6
Virtual Storage Access Method . . . . . . . 7
Access to z/OS UNIX Files . . . . . . . . 7
Selection of an Access Method . . . . . . . 8
Direct Access Storage Device (DASD) Volumes . . . 8
DASD Labels . . . . . . . . . . . . . 8
Track Format . . . . . . . . . . . . . 9
Track Overflow . . . . . . . . . . . . 10
VSAM Record Addressing . . . . . . . . 10
Actual and Relative Addressing with Non-VSAM
Access Methods . . . . . . . . . . . . 10
Magnetic Tape Volumes . . . . . . . . . . 12
Using Magnetic Tape Labels . . . . . . . . 12
Specifying the File Sequence Number. . . . . 12
Identifying Unlabeled Tapes . . . . . . . . 15
Using Tape Marks . . . . . . . . . . . 15
Data Management Macros . . . . . . . . . 15
Data Set Processing. . . . . . . . . . . . 16
© Copyright IBM Corp. 1987, 2017
|
Allocating Data Sets . . . . . . . . .
Processing Data Sets through Programs . . .
Using Access Methods. . . . . . . . .
Using Addressing Modes . . . . . . . .
Using Hiperspace and Hiperbatch . . . . .
Processing VSAM Data Sets . . . . . . .
Processing PDSs, PDSEs, and UNIX Directories
Processing Sequential Data Sets and Members of
PDSEs and PDSs . . . . . . . . . .
Processing UNIX Files with an Access Method
Processing EXCP, EXCPVR, and XDAP Macros
Processing data sets on read-only devices . .
Distributed Data Management (DDM) Attributes .
Virtual I/O for Temporary Data Sets . . . . .
Data Set Names . . . . . . . . . . . .
Catalogs and Volume Table of Contents . . . .
VTOC . . . . . . . . . . . . . .
Catalogs . . . . . . . . . . . . .
Data Set Names and Metadata . . . . . .
Security of Data Set Names . . . . . . .
.
.
.
.
.
.
16
17
17
18
19
19
19
. 20
. 21
22
. 22
. 26
. 27
. 27
. 28
. 28
. 29
. 29
. 30
Chapter 2. Using the Storage
Management Subsystem . . . . . . . 31
Using Automatic Class Selection Routines . . .
Allocating Data Sets . . . . . . . . . .
Allocating Data Sets with JCL . . . . . .
Allocating System-Managed Data Sets with the
Access Method Services ALLOCATE Command
Allocating Data Sets with the TSO ALLOCATE
Command . . . . . . . . . . . . .
Allocating Data Sets with Dynamic Allocation .
. 33
. 34
. 34
. 36
. 38
. 38
Chapter 3. Allocating Space on Direct
Access Volumes . . . . . . . . . . 41
Specification of Space Requirements . . . . .
Blocks . . . . . . . . . . . . . .
Average Record Length . . . . . . . .
Tracks or Cylinders . . . . . . . . . .
Absolute Track . . . . . . . . . . .
Additional Space-Allocation Options . . . .
Maximum Data Set Size . . . . . . . . .
Maximum Size on One Volume . . . . . .
Maximum Number of Volumes . . . . . .
Maximum VSAM Data Set Size . . . . . .
Minimum data set size . . . . . . . . .
Primary and Secondary Space Allocation without
the Guaranteed Space Attribute. . . . . . .
Multivolume VSAM Data Sets . . . . . .
Multivolume Non-VSAM Data Sets . . . .
Extended-Format Data Sets . . . . . . .
Allocation of Data Sets with the Guaranteed Space
Attribute . . . . . . . . . . . . . .
Guaranteed Space with DISP=NEW or MOD .
Guaranteed Space for VSAM . . . . . .
Guaranteed Space with DISP=OLD or SHR . .
.
.
.
.
.
.
.
.
.
.
.
41
41
42
42
43
43
43
43
43
44
44
.
.
.
.
44
45
45
45
.
.
.
.
46
46
46
47
iii
Guaranteed Space with Extended-Format Data
Sets . . . . . . . . . . . . . . . .
Guaranteed Space Example . . . . . . . .
Allocation of Data Sets with the Space Constraint
Relief Attributes . . . . . . . . . . . . .
Examples of Dynamic Volume Count When
Defining a Data Set . . . . . . . . . . .
Examples of Dynamic Volume Count When
Allocating an Existing Data Set . . . . . . .
Extension to Another DASD Volume . . . . . .
Multiple Volume Considerations for Sequential Data
Sets . . . . . . . . . . . . . . . . .
Extended Address Volumes . . . . . . . . .
Additional Information on Space Allocation . . .
47
47
48
49
49
50
50
51
53
Chapter 4. Backing Up and Recovering
Data Sets . . . . . . . . . . . . . 55
Using REPRO for Backup and Recovery . . . .
Using EXPORT and IMPORT for Backup and
Recovery of VSAM Data Sets . . . . . . .
Structure of an Exported Data Set . . . . .
EXPORT and IMPORT Commands . . . .
Writing a Program for Backup and Recovery . .
Using Concurrent Copy for Backup and Recovery
Updating a Data Set After Recovery . . . . .
Synchronizing Catalog and VSAM Data Set
Information During Recovery . . . . . . .
Handling an Abnormal Termination . . . .
Using VERIFY to Process Improperly Closed
Data Sets . . . . . . . . . . . . .
CICS VSAM Recovery . . . . . . . . . .
. 56
.
.
.
.
57
58
58
58
59
. 59
. 59
. 59
. 60
. 62
Chapter 5. Protecting Data Sets . . . . 63
|
z/OS Security Server (RACF) . . . . . . . .
RACF Protection for VSAM Data Sets . . . .
Generic and Discrete Profiles for VSAM Data Sets
RACF Protection for Non-VSAM Data Sets . . .
Hiding Data Set Names . . . . . . . . .
Data Set Encryption . . . . . . . . . . .
Data Set Password Protection . . . . . . . .
Assigning a Password . . . . . . . . . .
Protecting a Data Set When You Define It . . .
Handling Incorrect Passwords . . . . . . .
Entering a Record in the PASSWORD Data Set
User-Security-Verification Routine . . . . . . .
Erasure of Residual Data . . . . . . . . . .
Erasing DASD Data . . . . . . . . . .
Erasing Tape Data . . . . . . . . . . .
Authorized Program Facility and Access Method
Services . . . . . . . . . . . . . . .
Access Method Services Cryptographic Option . .
Data Enciphering and Deciphering . . . . .
REPRO ENCIPHER and DECIPHER on ICSF . .
63
63
64
64
65
66
75
75
75
75
75
76
76
76
77
78
79
79
82
Part 2. VSAM Access to Data Sets
and UNIX Files . . . . . . . . . . 83
Chapter 6. Organizing VSAM Data Sets
VSAM Data Formats .
iv
.
.
.
z/OS DFSMS Using Data Sets
.
.
.
.
.
.
85
. 85
Data Set Size . . . . . . . . . . . . . 85
Control Intervals . . . . . . . . . . . 86
Control Information Fields . . . . . . . . 86
Compressed Control Information Field . . . . 88
Control Areas. . . . . . . . . . . . . 88
Spanned Records . . . . . . . . . . . 88
Selection of VSAM Data Set Types. . . . . . . 90
Entry-Sequenced Data Sets . . . . . . . . 91
Simulated VSAM Access to UNIX files . . . . 92
Key-Sequenced Data Sets . . . . . . . . . 94
Linear Data Sets . . . . . . . . . . . . 97
Fixed-Length Relative-Record Data Sets . . . . 97
Variable-Length Relative-Record Data Sets . . . 98
Summary of VSAM Data Set Types . . . . . 99
Extended-Format VSAM Data Sets . . . . . . 100
Restrictions on Defining Extended-Format Data
Sets . . . . . . . . . . . . . . . 101
VSAM Data Striping . . . . . . . . . . 101
Compressed Data . . . . . . . . . . . 106
Access to Records in a VSAM Data Set . . . . . 107
Access to Entry-Sequenced Data Sets . . . . 108
Access to Key-Sequenced Data Sets . . . . . 108
Access to Linear Data Sets . . . . . . . . 109
Access to Fixed-Length Relative-Record Data
Sets . . . . . . . . . . . . . . . 109
Access to Variable-Length Relative-Record Data
Sets. . . . . . . . . . . . . . . . 110
Access to Records through Alternate Indexes . . . 110
Alternate Index Structure for a Key-Sequenced
Data Set . . . . . . . . . . . . . . 111
Alternate Index Structure for an
Entry-Sequenced Data Set . . . . . . . . 112
Building of an Alternate Index. . . . . . . 113
Automatic Upgrade of Alternate Indexes . . . 114
Data Compression . . . . . . . . . . . . 114
Chapter 7. Defining VSAM Data Sets
Using Cluster Names for Data and Index
Components . . . . . . . . . . . . .
Defining a Data Set with Access Method Services
Naming a Cluster . . . . . . . . . .
Specifying Cluster Information . . . . .
Using Access Method Services Parameters. .
Allocating Space for VSAM Data Sets . . .
Calculating Space for the Data Component of a
KSDS . . . . . . . . . . . . . .
Calculating Space for the Index Component .
Using ALTER to Modify Attributes of a
Component . . . . . . . . . . . .
Using ALTER to Rename Data Sets . . . .
Defining a Data Set with JCL . . . . . . .
Loading a VSAM Data Set . . . . . . . .
Using REPRO to Copy a VSAM Data Set . .
Using a Program to Load a Data Set. . . .
Reusing a VSAM Data Set as a Work File . .
Copying and Merging Data Sets . . . . . .
Defining Alternate Indexes . . . . . . . .
Naming an Alternate Index. . . . . . .
Specifying Alternate Index Information . . .
Building an Alternate Index . . . . . .
Maintaining Alternate Indexes. . . . . .
117
. 118
118
. 118
. 120
. 120
. 122
. 126
. 127
.
.
.
.
.
.
.
.
.
.
.
.
.
127
127
127
128
128
129
131
131
133
134
134
135
136
Defining a Path. . . . . . . . . . .
Defining a Page Space . . . . . . . . .
Checking for Problems in Catalogs and Data Sets
Listing Catalog Entries . . . . . . . .
Printing the Contents of Data Sets . . . .
Deleting Data Sets . . . . . . . . . . .
. 136
. 137
138
. 138
. 139
. 139
Chapter 8. Defining and Manipulating
VSAM Data Sets: Examples . . . . . 141
Example of Defining a VSAM Data Set . . . . .
Examples of Defining Temporary VSAM Data Sets
Example 1: Defining a Temporary VSAM Data
Set Using ALLOCATE . . . . . . . . .
Example 2: Creating a Temporary Data Set with
Default Parameter Values . . . . . . . .
Examples of Defining Alternate Indexes and Paths
JCL Statements . . . . . . . . . . . .
Commands . . . . . . . . . . . . .
141
143
143
144
144
144
145
Chapter 9. Processing VSAM Data
Sets . . . . . . . . . . . . . . . 147
Creating an Access Method Control Block . . .
Creating an Exit List . . . . . . . . . .
Opening a Data Set . . . . . . . . . .
Creating a Request Parameter List . . . . .
Manipulating the Contents of Control Blocks . .
Generating a Control Block . . . . . . .
Testing the Contents of ACB, EXLST, and RPL
Fields . . . . . . . . . . . . . .
Modifying the Contents of an ACB, EXLST, or
RPL . . . . . . . . . . . . . .
Displaying the Contents of ACB, EXLST, and
RPL Fields . . . . . . . . . . . .
Requesting Access to a Data Set . . . . . .
Inserting and Adding Records . . . . . .
Retrieving Records . . . . . . . . .
Updating Records . . . . . . . . . .
Deleting Records . . . . . . . . . .
Deferring and Forcing Buffer Writing . . .
Retaining and Positioning Data Buffers . . .
Processing Multiple Strings . . . . . . .
Making Concurrent Requests . . . . . .
Using a Path to Access Records . . . . .
Making Asynchronous Requests . . . . .
Ending a Request . . . . . . . . . .
Closing Data Sets . . . . . . . . . . .
Operating in SRB or Cross-Memory Mode. . .
Using VSAM Macros in Programs . . . . .
.
.
.
.
.
.
148
148
149
150
152
152
. 152
. 153
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
153
153
154
156
158
158
159
159
160
161
161
162
163
163
164
165
Chapter 10. Optimizing VSAM
Performance . . . . . . . . . . . . 169
Optimizing Control Interval Size . . . . .
Control Interval Size Limitations . . . .
Data Control Interval Size . . . . . .
Index Control Interval Size . . . . . .
How VSAM Adjusts Control Interval Size .
Optimizing Control Area Size . . . . . .
Advantages of a Large Control Area Size .
Disadvantages of a Large Control Area Size
Optimizing Free Space Distribution . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
169
169
171
172
172
173
174
174
174
Selecting the Optimal Percentage of Free Space
Altering the Free Space Specification When
Loading a Data Set . . . . . . . . . .
Reclaiming CA Space for a KSDS . . . . . .
Determining I/O Buffer Space for Nonshared
Resource . . . . . . . . . . . . . . .
Obtaining Buffers Above 16 MB . . . . . .
Tuning for System-Managed Buffering . . . .
Allocating Buffers for Concurrent Data Set
Positioning . . . . . . . . . . . . .
Allocating Buffers for Direct Access . . . . .
Allocating Buffers for Sequential Access . . .
Allocating Buffers for a Path . . . . . . .
Acquiring Buffers . . . . . . . . . . .
Using Index Options . . . . . . . . . . .
Increasing Virtual Storage for Index Set Records
Avoiding Control Area Splits . . . . . . .
Putting the Index and Data on Separate
Volumes . . . . . . . . . . . . . .
Obtaining Diagnostic Information . . . . . .
Migrating from the Mass Storage System . . . .
Using Hiperbatch . . . . . . . . . . . .
175
176
177
180
181
181
187
188
190
191
191
192
192
193
193
193
193
193
Chapter 11. Processing Control
Intervals . . . . . . . . . . . . . 195
Access to a Control Interval . . . . . . .
Structure of Control Information . . . . . .
CIDF—Control Interval Definition Field . .
RDF—Record Definition Field . . . . . .
User Buffering . . . . . . . . . . . .
Improved Control Interval Access . . . . .
Opening an Object for Improved Control
Interval Access . . . . . . . . . . .
Processing a Data Set with Improved Control
Interval Access . . . . . . . . . . .
Fixing Control Blocks and Buffers in Real
Storage . . . . . . . . . . . . .
Control Blocks in Common (CBIC) Option . .
.
.
.
.
.
.
196
197
197
198
202
202
. 202
. 203
. 203
. 203
Chapter 12. Sharing VSAM Data Sets
205
Subtask Sharing . . . . . . . . . . .
Building a Single Control Block Structure . .
Resolving Exclusive Control Conflicts . . .
Preventing Deadlock in Exclusive Control of
Shared Resources . . . . . . . . . .
Cross-Region Sharing . . . . . . . . . .
Cross-Region Share Options . . . . . .
Read Integrity During Cross-Region Sharing .
Write Integrity During Cross-Region Sharing
Cross-System Sharing . . . . . . . . .
Control Block Update Facility (CBUF) . . . .
Considerations for CBUF Processing. . . .
Checkpoints for Shared Data Sets. . . . .
Techniques of Data Sharing. . . . . . . .
Cross-Region Sharing. . . . . . . . .
Cross-System Sharing . . . . . . . .
User Access to VSAM Shared Information . .
. 206
. 206
. 207
.
.
.
.
.
.
.
.
.
.
.
.
209
211
211
212
213
214
215
216
217
217
217
219
219
Contents
v
Chapter 13. Sharing Resources
Among VSAM Data Sets. . . . . . . 221
Provision of a Resource Pool . . . . . . .
Building a Resource Pool: BLDVRP . . . .
Connecting a Data Set to a Resource Pool:
OPEN . . . . . . . . . . . . . .
Deleting a Resource Pool Using the DLVRP
Macro . . . . . . . . . . . . . .
Management of I/O Buffers for Shared Resources
Deferring Write Requests . . . . . . .
Relating Deferred Requests by Transaction ID
Writing Buffers Whose Writing is Deferred:
WRTBFR . . . . . . . . . . . . .
Accessing a Control Interval with Shared
Resources . . . . . . . . . . . .
Restrictions and Guidelines for Shared Resources
. 221
. 221
Set
. . 252
Set
. . 253
. 225
226
. 226
227
Guidelines for Coding Exit Routines. . . . . .
Programming Guidelines . . . . . . . . .
Multiple Request Parameter Lists or Data Sets
Return to a Main Program . . . . . . . .
IGW8PNRU Routine for Batch Override . . . .
Register Contents . . . . . . . . . . .
Programming Considerations . . . . . . .
EODAD Exit Routine to Process End of Data . . .
Register Contents . . . . . . . . . . .
Programming Considerations . . . . . . .
EXCEPTIONEXIT Exit Routine . . . . . . .
Register Contents . . . . . . . . . . .
Programming Considerations . . . . . . .
JRNAD Exit Routine to Journalize Transactions . .
Register Contents . . . . . . . . . . .
Programming Considerations . . . . . . .
LERAD Exit Routine to Analyze Logical Errors . .
Register Contents . . . . . . . . . . .
Programming Considerations . . . . . . .
RLSWAIT Exit Routine . . . . . . . . . .
Register Contents . . . . . . . . . . .
Request Environment. . . . . . . . . .
SYNAD Exit Routine to Analyze Physical Errors
Register Contents . . . . . . . . . . .
Programming Considerations . . . . . . .
Example of a SYNAD User-Written Exit Routine
UPAD Exit Routine for User Processing . . . .
Register Contents . . . . . . . . . . .
Programming Considerations . . . . . . .
User-Security-Verification Routine . . . . . .
. 227
. 229
230
233
233
234
235
236
239
239
240
241
241
241
242
242
245
245
246
247
247
248
Chapter 15. Checking VSAM
Key-Sequenced Data Set Clusters for
Structural Errors . . . . . . . . . . 249
z/OS DFSMS Using Data Sets
of a Data
. . .
of a Data
. . .
Chapter 16. Coding VSAM
User-Written Exit Routines. . . . . . 255
Controlling Access to VSAM Data Sets . . . . .
Accessing Data Sets Using DFSMStvs and VSAM
Record-Level Sharing . . . . . . . . . . .
Record-Level Sharing CF Caching . . . . .
VSAM Record-Level Sharing Multiple Lock
Structure . . . . . . . . . . . . . .
Using VSAM RLS with CICS . . . . . . .
Non-CICS Use of VSAM RLS . . . . . . .
Using 64-Bit Addressable Data Buffers . . . .
Read Sharing of Recoverable Data Sets . . . .
Read-Sharing Integrity across KSDS CI and CA
Splits . . . . . . . . . . . . . . .
Read and Write Sharing of Nonrecoverable Data
Sets . . . . . . . . . . . . . . .
Using Non-RLS Access to VSAM Data Sets . .
RLS Access Rules . . . . . . . . . . .
Comparing RLS Access and Non-RLS Access
Requesting VSAM RLS Run-Mode . . . . .
Using VSAM RLS Read Integrity Options . . .
Using VSAM RLS with ESDS . . . . . . . .
Specifying Read Integrity . . . . . . . . .
Specifying a Timeout Value for Lock Requests . .
Index Trap . . . . . . . . . . . . . .
vi
Tests
. .
Tests
. .
. 225
Chapter 14. Using VSAM Record-Level
Sharing . . . . . . . . . . . . . . 233
EXAMINE Command . . . . . . . . .
Types of Data Sets . . . . . . . . . .
EXAMINE Users . . . . . . . . . .
How to Run EXAMINE . . . . . . . . .
Deciding to Run INDEXTEST, DATATEST, or
Both Tests . . . . . . . . . . . .
Skipping DATATEST on Major INDEXTEST
Errors . . . . . . . . . . . . . .
Examining a User Catalog . . . . . . .
Understanding Message Hierarchy . . . .
Controlling Message Printout . . . . . .
Samples of Output from EXAMINE Runs . . .
INDEXTEST and DATATEST Tests of an
Error-Free Data Set . . . . . . . . .
INDEXTEST and DATATEST
with a Structural Error . .
INDEXTEST and DATATEST
with a Duplicate Key Error .
.
.
.
.
249
249
249
250
. 250
.
.
.
.
.
250
250
251
251
252
. 252
255
256
257
257
258
258
258
259
259
260
260
260
260
261
261
262
269
269
269
270
270
270
271
271
271
273
273
274
275
276
Chapter 17. Using 31-Bit Addressing
Mode with VSAM . . . . . . . . . . 279
VSAM Options .
.
.
.
.
.
.
.
.
.
.
.
. 279
Chapter 18. Using Job Control
Language for VSAM . . . . . . . . 281
Using JCL Statements and Keywords . . .
Data Set Name . . . . . . . . . .
Disposition . . . . . . . . . . .
Creating VSAM Data Sets with JCL . . . .
Temporary VSAM Data Sets . . . . .
Examples Using JCL to Allocate VSAM Data
Sets . . . . . . . . . . . . .
Retrieving an Existing VSAM Data Set . . .
Migration Consideration. . . . . . .
Keywords Used to Process VSAM Data Sets
.
.
.
.
.
.
.
.
.
.
281
281
281
282
283
.
.
.
.
.
.
.
.
284
287
287
287
Chapter 19. Processing Indexes of
Key-Sequenced Data Sets . . . . . . 289
Access to a Key-Sequenced Data Set Index . .
Access to an Index with GETIX and PUTIX .
. 289
. 289
Access to the Index Component Alone . . . .
Prime Index . . . . . . . . . . . . .
Index Levels. . . . . . . . . . . . .
VSAM index trap . . . . . . . . . . .
Format of an Index Record . . . . . . . . .
Header Portion . . . . . . . . . . . .
Free Control Interval Entry Portion . . . . .
Index Entry Portion . . . . . . . . . .
Key Compression . . . . . . . . . . . .
Index Update Following a Control Interval Split
Index Entries for a Spanned Record . . . . .
289
290
291
292
293
293
295
296
297
299
300
Part 3. Non-VSAM Access to Data
Sets and UNIX Files . . . . . . . 301
Chapter 20. Selecting Record Formats
for Non-VSAM Data Sets . . . . . . 303
Format Selection . . . . . . . . . . . .
Fixed-Length Record Formats . . . . . . . .
Standard Format . . . . . . . . . . .
Restrictions . . . . . . . . . . . . .
Variable-Length Record Formats . . . . . . .
Format-V Records . . . . . . . . . . .
Spanned Format-VS Records (Sequential Access
Method) . . . . . . . . . . . . . .
Spanned Format-V Records (Basic Direct Access
Method) . . . . . . . . . . . . . .
Undefined-Length Record Format . . . . . .
ISO/ANSI Tapes . . . . . . . . . . . .
Character Data Conversion . . . . . . . .
Format-F Records . . . . . . . . . . .
Format-D Records . . . . . . . . . . .
ISO/ANSI Format-DS and Format-DBS Records
Format-U Records . . . . . . . . . . .
Record Format—Device Type Considerations . . .
Using Optional Control Characters . . . . .
Using Direct Access Storage Devices (DASD)
Using Magnetic Tape . . . . . . . . . .
Using a Printer . . . . . . . . . . . .
Using a Card Reader and Punch . . . . . .
Using a Paper Tape Reader . . . . . . . .
303
304
305
305
306
306
308
310
312
312
312
314
315
317
320
320
321
321
322
323
324
325
Chapter 21. Specifying and Initializing
Data Control Blocks . . . . . . . . 327
Processing Sequential and Partitioned Data Sets
Using OPEN to Prepare a Data Set for Processing
Filling in the DCB . . . . . . . . . .
Specifying the Forms of Macros, Buffering
Requirements, and Addresses . . . . . .
Coding Processing Methods . . . . . .
Selecting Data Set Options . . . . . . . .
Block Size (BLKSIZE). . . . . . . . .
Data Set Organization (DSORG) . . . . .
Key Length (KEYLEN) . . . . . . . .
Record Length (LRECL) . . . . . . . .
Record Format (RECFM) . . . . . . .
Write Validity Check Option (OPTCD=W) . .
DD Statement Parameters . . . . . . .
Changing and Testing the DCB and DCBE . .
328
332
. 333
.
.
.
.
.
.
.
.
.
.
.
335
335
336
337
342
342
342
343
343
343
344
Using the DCBD Macro . . . . . . . . .
Changing an Address in the DCB . . . . .
Using the IHADCBE Macro . . . . . . .
Using CLOSE to End the Processing of a Data Set
Issuing the CHECK Macro . . . . . . . .
Closing a Data Set Temporarily . . . . . .
Using CLOSE TYPE=T with Sequential Data
Sets . . . . . . . . . . . . . . .
Releasing Space . . . . . . . . . . .
Managing Buffer Pools When Closing Data Sets
Opening and Closing Data Sets: Considerations
Parameter Lists with 31-Bit Addresses . . . .
Open and Close of Multiple Data Sets at the
Same Time . . . . . . . . . . . . .
Factors to Consider When Allocating Direct
Access Data Sets . . . . . . . . . . .
Guidelines for Opening and Closing Data Sets
Open/Close/EOV Errors . . . . . . . .
Installation Exits . . . . . . . . . . .
Positioning Volumes . . . . . . . . . . .
Releasing Data Sets and Volumes . . . . . .
Processing End-of-Volume . . . . . . . .
Positioning During End-of-Volume . . . . .
Forcing End-of-Volume . . . . . . . . .
Managing SAM Buffer Space . . . . . . . .
Constructing a Buffer Pool . . . . . . . . .
Building a Buffer Pool . . . . . . . . .
Building a Buffer Pool and a Record Area . . .
Getting a Buffer Pool . . . . . . . . . .
Constructing a Buffer Pool Automatically . . .
Freeing a Buffer Pool . . . . . . . . . .
Constructing a Buffer Pool: Examples . . . .
Controlling Buffers . . . . . . . . . . .
Queued Access Method . . . . . . . . .
Basic Access Method . . . . . . . . . .
QSAM in an Application . . . . . . . .
Exchange Buffering . . . . . . . . . .
Choosing Buffering Techniques and GET/PUT
Processing Modes . . . . . . . . . . . .
Using Buffering Macros with Queued Access
Method . . . . . . . . . . . . . . .
RELSE—Release an Input Buffer . . . . . .
TRUNC—Truncate an Output Buffer . . . .
Using Buffering Macros with Basic Access Method
GETBUF—Get a Buffer from a Pool . . . . .
FREEBUF—Return a Buffer to a Pool . . . .
345
345
346
346
346
346
347
348
348
349
349
349
349
350
350
351
351
351
352
353
354
354
355
356
357
357
357
358
358
359
359
360
360
363
363
363
363
364
364
364
364
Chapter 22. Accessing Records . . . 365
Accessing Data with READ and WRITE . . . .
Using the Data Event Control Block (DECB) . .
Grouping Related Control Blocks in a Paging
Environment . . . . . . . . . . . .
Using Overlapped I/O with BSAM . . . . .
Reading a Block . . . . . . . . . . .
Writing a Block . . . . . . . . . . . .
Ensuring I/O Initiation with the TRUNC Macro
Testing Completion of a Read or Write
Operation . . . . . . . . . . . . .
Waiting for Completion of a Read or Write
Operation . . . . . . . . . . . . .
Handling Exceptional Conditions on Tape . . .
Contents
365
365
365
366
367
367
368
368
369
369
vii
Accessing Data with GET and PUT . . . . . .
GET—Retrieve a Record . . . . . . . . .
PUT—Write a Record. . . . . . . . . .
PUTX—Write an Updated Record . . . . .
PDAB—Parallel Input Processing (QSAM Only)
Analyzing I/O Errors . . . . . . . . . .
SYNADAF—Perform SYNAD Analysis Function
SYNADRLS—Release SYNADAF Message and
Save Areas . . . . . . . . . . . . .
Device Support Facilities (ICKDSF): Diagnosing
I/O Problems . . . . . . . . . . . .
Limitations with Using SRB or Cross-Memory
Mode . . . . . . . . . . . . . . . .
Using BSAM, BPAM, and QSAM support for
XTIOT, uncaptured UCBs, and DSAB above the 16
MB line . . . . . . . . . . . . . . .
Planning to use BSAM, BPAM, QSAM and OCE
support for XTIOT, uncaptured UCBs, and
DSAB above the line . . . . . . . . . .
Adapting applications for BSAM, BPAM, QSAM
and OCE support for XTIOT, uncaptured UCBs,
and DSAB above the line . . . . . . . .
Coding the LOC=ANY DCBE option . . . .
Coding the DEVSUPxx option . . . . . . .
Diagnosing problems with BSAM, BPAM,
QSAM and OCE support for XTIOT, uncaptured
UCBs, and DSAB above the line . . . . . .
370
370
371
371
371
374
374
375
375
375
375
376
377
382
382
384
Chapter 23. Sharing Non-VSAM Data
Sets . . . . . . . . . . . . . . . 385
Enhanced Data Integrity for Shared Sequential
Data Sets . . . . . . . . . . . . . . .
Setting Up the Enhanced Data Integrity
Function . . . . . . . . . . . . . .
Synchronizing the Enhanced Data Integrity
Function on Multiple Systems . . . . . . .
Using the START IFGEDI Command . . . .
Bypassing the Enhanced Data Integrity Function
for Applications . . . . . . . . . . .
Diagnosing Data Integrity Warnings and
Violations . . . . . . . . . . . . .
PDSEs . . . . . . . . . . . . . . . .
Direct Data Sets (BDAM) . . . . . . . . .
Factors to Consider When Opening and Closing
Data Sets . . . . . . . . . . . . . . .
Control of Checkpoint Data Sets on Shared DASD
Volumes . . . . . . . . . . . . . . .
System Use of Search Direct for Input Operations
388
389
390
390
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
viii
z/OS DFSMS Using Data Sets
.
.
.
.
.
.
.
.
.
403
404
408
410
410
411
411
412
412
413
414
. 414
. 415
. 417
. 418
. 419
419
419
. 421
. 421
. 424
. 424
.
.
.
.
.
.
424
424
425
426
426
427
427
. 428
Chapter 26. Processing a Partitioned
Data Set (PDS) . . . . . . . . . . . 429
391
393
394
Structure of a PDS. . . . . . . . . . . .
PDS Directory . . . . . . . . . . . . .
Allocating Space for a PDS . . . . . . . . .
Calculating Space . . . . . . . . . . .
Allocating Space with SPACE and AVGREC . .
Creating a PDS . . . . . . . . . . . . .
Creating a PDS Member with BSAM or QSAM
Converting PDSs . . . . . . . . . . .
Copying a PDS or Member to Another Data Set
Adding Members . . . . . . . . . . .
Processing a Member of a PDS . . . . . . .
BLDL—Construct a Directory Entry List . . .
DESERV . . . . . . . . . . . . . .
FIND—Position to the Starting Address of a
Member . . . . . . . . . . . . . .
STOW—Update the Directory . . . . . . .
Retrieving a Member of a PDS . . . . . . .
Modifying a PDS . . . . . . . . . . . .
Updating in Place . . . . . . . . . . .
Rewriting a Member . . . . . . . . . .
Concatenating PDSs . . . . . . . . . . .
394
394
396
. 397
. 398
. 398
Chapter 25. Processing Sequential
Data Sets . . . . . . . . . . . . . 401
Creating a Sequential Data Set. . . .
Types of DASD Sequential Data Sets
Retrieving a Sequential Data Set . . .
.
.
.
.
.
.
.
.
.
.
390
Chapter 24. Spooling and Scheduling
Data Sets . . . . . . . . . . . . . 397
Job Entry Subsystem .
SYSIN Data Set . . .
SYSOUT Data Set . .
Concatenating Data Sets Sequentially . . . .
Concatenating Like Data Sets . . . . . .
Concatenating Unlike Data Sets . . . . .
Modifying Sequential Data Sets . . . . . .
Updating in Place . . . . . . . . . .
Using Overlapped Operations . . . . . .
Extending a Data Set . . . . . . . . .
Achieving Device Independence . . . . . .
Device-Dependent Macros . . . . . . .
DCB and DCBE Subparameters . . . . .
Improving Performance for Sequential Data Sets
Limitations on Using Chained Scheduling with
Non-DASD Data Sets. . . . . . . . .
DASD and Tape Performance . . . . . .
Determining the Length of a Block when Reading
with BSAM, BPAM, or BDAM . . . . . . .
Writing a Short Format-FB Block with BSAM or
BPAM . . . . . . . . . . . . . . .
Using Hiperbatch . . . . . . . . . . .
Processing Extended-Format Sequential Data Sets
Characteristics of Extended-Format Data Sets
Allocating Extended-Format Data Sets . . .
Allocating Compressed-Format Data Sets . .
Opening and Closing Extended-Format Data
Sets . . . . . . . . . . . . . .
Reading, Writing, and Updating
Extended-Format Data Sets Using BSAM and
QSAM. . . . . . . . . . . . . .
Concatenating Extended-Format Data Sets with
Other Data Sets . . . . . . . . . .
Extending Striped Sequential Data Sets . . .
Migrating to Extended-Format Data Sets . .
Processing Large Format Data Sets . . . . .
Characteristics of Large Format Data Sets . .
Allocating Large Format Data Sets . . . .
Opening and Closing Large Format Data Sets
Migrating to Large Format Data Sets . . .
. 401
. 402
. 403
429
430
433
433
434
434
434
436
436
436
438
439
440
443
444
445
450
450
452
452
Sequential Concatenation . . . .
Partitioned Concatenation . . . .
Reading a PDS Directory Sequentially .
.
.
.
.
.
.
.
.
.
. 452
. 452
. 453
Chapter 27. Processing a Partitioned
Data Set Extended (PDSE) . . . . . . 455
Advantages of PDSEs . . . . . . . . . .
PDSE and PDS Similarities . . . . . . . .
PDSE and PDS Differences . . . . . . . .
Structure of a PDSE . . . . . . . . . . .
PDSE Logical Block Size. . . . . . . . .
Reuse of Space . . . . . . . . . . . .
Directory Structure . . . . . . . . . .
Relative Track Addresses (TTR) . . . . . .
Processing PDSE Records . . . . . . . . .
PDSE member size limits . . . . . . . .
Using BLKSIZE with PDSEs . . . . . . .
Using KEYLEN with PDSEs . . . . . . .
Reblocking PDSE Records . . . . . . . .
Processing Short Blocks . . . . . . . . .
Processing SAM Null Segments . . . . . .
Allocating Space for a PDSE . . . . . . . .
PDSE Space Considerations . . . . . . .
Summary of PDSE Storage Requirements . . .
Defining a PDSE . . . . . . . . . . . .
PDSE version . . . . . . . . . . . . .
PDSE Member Generations . . . . . . . . .
Creating a PDSE Member . . . . . . . . .
Creating a PDSE Member with BSAM or QSAM
Adding or Replacing PDSE Members Serially
Adding or Replacing Multiple PDSE Members
Concurrently . . . . . . . . . . . .
Copying a PDSE or Member to Another Data
Set . . . . . . . . . . . . . . . .
Processing a Member of a PDSE . . . . . . .
Establishing Connections to Members . . . .
Using the BLDL Macro to Construct a Directory
Entry List . . . . . . . . . . . . .
Using the BSP Macro to Backspace a Physical
Record . . . . . . . . . . . . . .
Using the Directory Entry Services . . . . .
Using the FIND Macro to Position to the
Beginning of a Member . . . . . . . . .
Using ISITMGD to Determine Whether the Data
Set Is System Managed . . . . . . . . .
Using the NOTE Macro to Provide Relative
Position . . . . . . . . . . . . . .
Using the POINT Macro to Position to a Block
Switching between Members . . . . . . .
Using the STOW Macro to Update the Directory
Retrieving a Member of a PDSE . . . . . . .
Sharing PDSEs . . . . . . . . . . . . .
Sharing within a Computer System . . . . .
Sharing Violations . . . . . . . . . . .
Multiple System Sharing of PDSEs . . . . .
Normal or Extended PDSE Sharing . . . . .
Modifying a Member of a PDSE . . . . . . .
Updating in Place . . . . . . . . . . .
Extending a PDSE Member . . . . . . . .
Deleting a PDSE Member . . . . . . . .
Renaming a PDSE Member . . . . . . . .
455
457
457
458
458
459
459
459
460
461
462
462
462
463
463
464
464
467
467
468
469
470
470
472
473
474
474
474
475
476
476
484
485
486
486
487
488
489
490
491
491
492
494
495
495
496
496
497
Reading a PDSE Directory . . . . . . . .
Concatenating PDSEs. . . . . . . . . .
Sequential Concatenation . . . . . . .
Partitioned Concatenation . . . . . . .
Converting PDSs to PDSEs and Back . . . .
PDSE to PDS Conversion . . . . . . .
Restrictions on Converting PDSEs . . . .
Improving Performance . . . . . . . . .
Recovering Space in Fragmented PDSEs . . .
PDSE Address Spaces . . . . . . . . .
Planning to use the restartable PDSE address
space . . . . . . . . . . . . . .
Setting up the SMSPDSE1 address space . .
Hiperspace caching for PDSE . . . . . .
PDSE Address Space Tuning . . . . . .
PDSE Diagnostics . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
497
497
498
498
499
499
500
500
500
500
.
.
.
.
.
501
502
503
505
507
Chapter 28. Processing z/OS UNIX
Files . . . . . . . . . . . . . . . 509
Accessing the z/OS UNIX File System . . . .
Using a non-SMS managed data set for a zFS
version root larger than four gigabytes . . .
Characteristics of UNIX Directories and Files
Access Methods Used . . . . . . . .
Using HFS Data Sets . . . . . . . . . .
Creating HFS Data Sets . . . . . . . .
Creating Additional Directories . . . . .
Creating z/OS UNIX Files . . . . . . . .
Writing a UNIX File with BSAM or QSAM .
Creating a UNIX File Using JCL . . . . .
JCL Parameters for UNIX Files . . . . .
Creating a Macro Library in a UNIX Directory
Managing UNIX Files and Directories . . . .
Specifying Security Settings for UNIX Files and
Directories . . . . . . . . . . . .
Editing UNIX Files . . . . . . . . .
Using ISHELL to Manage UNIX Files and
Directories . . . . . . . . . . . .
Copying UNIX Files or Directories . . . .
Services and Utilities for UNIX Files. . . . .
Services and Utilities Cannot be Used with
UNIX Files . . . . . . . . . . . .
z/OS UNIX Signals . . . . . . . . .
z/OS UNIX Fork Service . . . . . . .
SMF Records . . . . . . . . . . .
Reading UNIX Files Using BPAM . . . . .
Using Macros for UNIX Files . . . . . .
BLDL—Constructing a Directory Entry List .
CHECK—Checking for I/O Completion . .
CLOSE—to Close the DCB . . . . . . .
FIND—Positioning to the Starting Address of a
File . . . . . . . . . . . . . . .
READ—Reading a UNIX File . . . . . .
STOW DISC—Closing a UNIX File . . . .
Concatenating UNIX Files and Directories . . .
Sequential Concatenation . . . . . . .
Partitioned Concatenation . . . . . . .
Contents
. 509
. 510
510
. 511
. 511
. 512
. 513
. 513
. 513
. 516
. 517
519
. 520
. 520
. 521
. 522
. 523
. 524
.
.
.
.
.
.
.
.
.
525
525
525
525
526
526
526
527
527
.
.
.
.
.
.
527
528
528
528
528
529
ix
Chapter 29. Processing Generation
Data Groups . . . . . . . . . . . . 531
Data Set Organization of Generation Data Sets .
Absolute Generation and Version Numbers . .
Relative Generation Number . . . . . . .
Programming Considerations for Multiple-Step
Jobs . . . . . . . . . . . . . . .
Cataloging Generation Data Groups . . . .
Submitting Multiple Jobs to Update a
Generation Data Group . . . . . . . .
Naming Generation Data Groups for ISO/ANSI
Version 3 or Version 4 Labels . . . . . . .
Creating a New Generation. . . . . . . .
Allocating a Generation Data Set . . . . .
Passing a Generation Data Set . . . . . .
Rolling In a Generation Data Set . . . . .
Controlling Expiration of a Rolled-Off
Generation Data Set . . . . . . . . .
Retrieving a Generation Data Set . . . . . .
Reclaiming Generation Data Sets . . . . . .
Turning on GDS Reclaim Processing. . . .
Turning off GDS Reclaim Processing. . . .
Building a Generation Data Group . . . . .
. 532
. 532
. 534
. 534
. 534
. 535
.
.
.
.
.
536
536
536
539
539
.
.
.
.
.
.
540
540
541
541
542
542
Using the CNTRL Macro to Control an I/O Device
Using the PRTOV Macro to Test for Printer
Overflow . . . . . . . . . . . . . . .
Using the SETPRT Macro to Set Up the Printer . .
Using the BSP Macro to Backspace a Magnetic
Tape or Direct Access Volume . . . . . . . .
Using the NOTE Macro to Return the Relative
Address of a Block . . . . . . . . . . .
Using the POINT Macro to Position to a Block . .
Using the SYNCDEV Macro to Synchronize Data
543
544
544
545
545
547
547
Chapter 31. Using Non-VSAM
User-Written Exit Routines. . . . . . 549
x
z/OS DFSMS Using Data Sets
. 573
. 574
.
.
.
.
.
.
.
574
574
575
576
577
578
578
581
584
. 586
. 586
Part 4. Appendixes . . . . . . . . 589
Chapter 30. Using I/O Device Control
Macros . . . . . . . . . . . . . . 543
General Guidance . . . . . . . . . . .
Programming Considerations . . . . . .
Status Information Following an Input/Output
Operation . . . . . . . . . . . .
EODAD End-of-Data-Set Exit Routine . . . .
Register Contents . . . . . . . . . .
Programming Considerations . . . . . .
SYNAD Synchronous Error Routine Exit . . .
Register Contents . . . . . . . . . .
Programming Considerations . . . . . .
DCB Exit List . . . . . . . . . . . .
Register contents for exits from EXLST . . .
Serialization . . . . . . . . . . . .
Allocation Retrieval List . . . . . . . . .
Programming Conventions . . . . . . .
Restrictions . . . . . . . . . . . .
DCB ABEND Exit . . . . . . . . . . .
Recovery Requirements . . . . . . . .
DCB Abend Installation Exit . . . . . .
DCB OPEN Exit . . . . . . . . . . .
Calls to DCB OPEN Exit for Sequential
Concatenation . . . . . . . . . . .
Installation DCB OPEN Exit . . . . . .
Defer Nonstandard Input Trailer Label Exit List
Entry . . . . . . . . . . . . . . .
Block Count Unequal Exit . . . . . . . .
EOV Exit for Sequential Data Sets . . . . .
FCB Image Exit. . . . . . . . . . . .
JFCB Exit . . . . . . . . . . . . . .
JFCBE Exit . . . . . . . . . . . . .
Open/Close/EOV Standard User Label Exit . .
Open/EOV Nonspecific Tape Volume Mount Exit
Open/EOV Volume Security and Verification Exit
QSAM Parallel Input Exit . . . . . . . .
User Totaling for BSAM and QSAM . . . . .
. 549
. 550
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
550
556
557
557
558
560
562
564
566
567
567
568
568
568
571
573
573
Appendix A. Using Direct Access
Labels . . . . . . . . . . . . . . 591
Direct Access Storage Device Architecture .
Volume Label Group . . . . . . . .
Data Set Control Block (DSCB) . . . .
User Label Groups . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
591
592
594
594
Appendix B. Using the Double-Byte
Character Set (DBCS) . . . . . . . . 597
DBCS Character Support . . .
Record Length When Using DBCS
Fixed-Length Records . . .
Variable-Length Records. . .
. . . .
Characters
. . . .
. . . .
.
.
.
.
.
.
.
.
597
597
597
598
Appendix C. Processing Direct Data
Sets . . . . . . . . . . . . . . . 599
Using the Basic Direct Access Method (BDAM) . .
Processing a Direct Data Set Sequentially . . . .
Organizing a Direct Data Set . . . . . . . .
By Range of Keys . . . . . . . . . . .
By Number of Records . . . . . . . . .
With Indirect Addressing . . . . . . . .
Creating a Direct Data Set . . . . . . . . .
Restrictions in Creating a Direct Data Set Using
QSAM. . . . . . . . . . . . . . .
With Direct Addressing with Keys . . . . .
With BDAM to Allocate a VIO Data Set . . .
Referring to a Record. . . . . . . . . . .
Record Addressing . . . . . . . . . .
Extended Search . . . . . . . . . . .
Exclusive Control for Updating . . . . . .
Feedback Option . . . . . . . . . . .
Adding or Updating Records . . . . . . . .
Format-F with Keys . . . . . . . . . .
Format-F without Keys . . . . . . . . .
Format-V or Format-U with Keys. . . . . .
Format-V or Format-U without Keys . . . .
Tape-to-Disk Add—Direct Data Set . . . . .
Tape-to-Disk Update—Direct Data Set . . . .
With User Labels . . . . . . . . . . .
Sharing DCBs . . . . . . . . . . . . .
599
600
600
600
600
601
601
601
601
602
602
602
603
603
603
604
604
604
604
605
605
605
606
606
Appendix D. Using the Indexed
Sequential Access Method. . . . . . 609
Using the Basic Indexed Sequential Access Method
(BISAM) . . . . . . . . . . . . . . .
Using the Queued Indexed Sequential Access
Method (QISAM) . . . . . . . . . . . .
Processing ISAM Data Sets . . . . . . . . .
Organizing Data Sets . . . . . . . . . . .
Prime Area . . . . . . . . . . . . .
Index Areas . . . . . . . . . . . . .
Overflow Areas. . . . . . . . . . . .
Creating an ISAM Data Set . . . . . . . . .
One-Step Method . . . . . . . . . . .
Full-Track-Index Write Option . . . . . . .
Multiple-Step Method . . . . . . . . .
Resume Load . . . . . . . . . . . .
Allocating Space . . . . . . . . . . . .
Prime Data Area . . . . . . . . . . .
Specifying a Separate Index Area . . . . . .
Specifying an Independent Overflow Area. . .
Specifying a Prime Area and Overflow Area . .
Calculating Space Requirements . . . . . . .
Step 1. Number of Tracks Required . . . . .
Step 2. Overflow Tracks Required . . . . .
Step 3. Index Entries Per Track . . . . . .
Step 4. Determine Unused Space . . . . . .
Step 5. Calculate Tracks for Prime Data Records
Step 6. Cylinders Required . . . . . . . .
Step 7. Space for Cylinder Indexes and Track
Indexes . . . . . . . . . . . . . .
Step 8. Space for Master Indexes . . . . . .
Summary of Indexed Sequential Space
Requirements Calculations . . . . . . . .
Retrieving and Updating . . . . . . . . .
Sequential Retrieval and Update . . . . . .
Direct Retrieval and Update . . . . . . .
Adding Records . . . . . . . . . . . .
Inserting New Records . . . . . . . . .
Adding New Records to the End of a Data Set
Maintaining an Indexed Sequential Data Set . . .
Buffer Requirements . . . . . . . . . .
Work Area Requirements . . . . . . . .
Space for the Highest-Level Index . . . . .
Device Control . . . . . . . . . . . .
SETL—Specifying Start of Sequential Retrieval
637
ESETL—Ending Sequential Retrieval . . . . 638
609
Appendix E. Using ISAM Programs
with VSAM Data Sets . . . . . . . . 641
609
610
610
612
612
614
614
614
615
616
617
617
619
619
619
619
620
620
620
621
621
622
622
Upgrading ISAM Applications to VSAM . . . .
How an ISAM Program Can Process a VSAM Data
Set . . . . . . . . . . . . . . . . .
Conversion of an Indexed Sequential Data Set . .
JCL for Processing with the ISAM Interface . . .
Restrictions on the Use of the ISAM Interface . .
Example: Converting a Data Set . . . . . .
Example: Issuing a SYNADAF Macro . . . .
622
622
623
624
624
625
629
630
631
632
634
635
636
637
642
643
647
648
650
651
652
Appendix F. Converting Character
Sets . . . . . . . . . . . . . . . 655
Coded Character Sets Sorted by CCSID.
Coded character sets sorted by default
LOCALNAME . . . . . . . . .
CCSID Conversion Groups . . . . .
CCSID Decision Tables . . . . . .
Tables for Default Conversion Codes .
Converting from EBCDIC to ASCII .
Converting from ASCII to EBCDIC .
.
.
.
. 655
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
658
664
666
670
670
671
Appendix G. Accessibility . . . . . . 673
Accessibility features . . . . . . .
Consult assistive technologies . . . .
Keyboard navigation of the user interface
Dotted decimal syntax diagrams . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
673
673
673
673
Notices . . . . . . . . . . . . . . 677
Terms and conditions for product documentation
IBM Online Privacy Statement. . . . . . .
Policy for unsupported hardware. . . . . .
Minimum supported hardware . . . . . .
Programming interface information . . . . .
Trademarks . . . . . . . . . . . . .
.
.
.
.
.
679
680
680
680
681
681
Glossary . . . . . . . . . . . . . 683
Index . . . . . . . . . . . . . . . 701
Contents
xi
xii
z/OS DFSMS Using Data Sets
Figures
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
DASD Volume Track Formats . . . . . . . 9
REPRO Encipher and Decipher Operations
80
VSAM Logical Record Retrieval . . . . . . 85
Control interval format. . . . . . . . . 86
Data set with nonspanned records . . . . . 89
Data set with spanned records . . . . . . 89
Entry-Sequenced Data Set . . . . . . . . 91
Example of RBAs of an entry-sequenced data
set . . . . . . . . . . . . . . . 91
Record of a Key-Sequenced Data Set . . . . 94
Inserting records into a key-sequenced data set 94
Inserting a Logical Record into a CI . . . . 96
Fixed-length relative-record data set . . . . 98
Control interval size . . . . . . . . . 101
Primary and Secondary Space Allocations for
Striped Data Sets . . . . . . . . . . 102
Control Interval in a Control Area . . . . 103
Layering (Four-Stripe Data Set) . . . . . 104
Alternate Index Structure for a
Key-Sequenced Data Set . . . . . . . . 111
Alternate Index Structure for an
Entry-Sequenced Data Set . . . . . . . 113
VSAM Macro Relationships . . . . . . . 166
Skeleton VSAM Program. . . . . . . . 167
Control Interval Size, Physical Track Size, and
Track Capacity . . . . . . . . . . . 171
Determining Free Space . . . . . . . . 175
Scheduling Buffers for Direct Access . . . . 189
General Format of a Control Interval
197
Format of Control Information for
Nonspanned Records . . . . . . . . . 200
Format of Control Information for Spanned
Records . . . . . . . . . . . . . 201
Exclusive Control Conflict Resolution
208
Relationship Between the Base Cluster and
the Alternate Index . . . . . . . . . 210
VSAM RLS address and data spaces and
requestor address spaces . . . . . . . . 234
CICS VSAM non-RLS access . . . . . . 237
CICS VSAM RLS . . . . . . . . . . 237
Example of a JRNAD exit Part 1 of 2
263
Example of a JRNAD exit Part 2 of 2
264
Example of a SYNAD exit routine . . . . 273
Relation of Index Entry to Data Control
Interval . . . . . . . . . . . . . 290
Relation of Index Entry to Data Control
Interval . . . . . . . . . . . . . 291
Levels of a Prime Index . . . . . . . . 292
General Format of an Index Record . . . . 293
Format of the Index Entry Portion of an
Index Record . . . . . . . . . . . 296
Format of an Index Record . . . . . . . 296
Example of Key Compression . . . . . . 299
Control Interval Split and Index Update
300
Fixed-Length Records . . . . . . . . . 304
Nonspanned, Format-V Records . . . . . 306
© Copyright IBM Corp. 1987, 2017
45. Spanned Format-VS Records (Sequential
Access Method) . . . . . . . . . . .
46. Spanned Format-V Records for Direct Data
Sets . . . . . . . . . . . . . . .
47. Undefined-Length Records . . . . . . .
48. Fixed-Length Records for ISO/ANSI Tapes
49. Nonspanned Format-D Records for
ISO/ANSI Tapes As Seen by the Program . .
50. Spanned Variable-Length (Format-DS)
Records for ISO/ANSI Tapes As Seen by the
Program . . . . . . . . . . . . .
51. Reading a Sequential Data Set . . . . . .
52. Reentrant—Above the 16 MB Line . . . .
53. Sources and Sequence of Operations for
Completing the DCB . . . . . . . . .
54. Opening Three Data Sets at the Same Time
55. Changing a Field in the DCB . . . . . .
56. Closing Three Data Sets at the Same Time
57. Record Processed when LEAVE or REREAD
is Specified for CLOSE TYPE=T . . . . .
58. Constructing a Buffer Pool from a Static
Storage Area . . . . . . . . . . . .
59. Constructing a Buffer Pool Using GETPOOL
and FREEPOOL. . . . . . . . . . .
60. Simple Buffering with MACRF=GL and
MACRF=PM . . . . . . . . . . . .
61. Simple Buffering with MACRF=GM and
MACRF=PM . . . . . . . . . . . .
62. Simple Buffering with MACRF=GL and
MACRF=PL . . . . . . . . . . . .
63. Simple Buffering with MACRF=GL and
MACRF=PM-UPDAT Mode . . . . . . .
64. Parallel Processing of Three Data Sets
65. JCL, Macros, and Procedures Required to
Share a Data Set Using Multiple DCBs . . .
66. Macros and Procedures Required to Share a
Data Set Using a Single DCB . . . . . .
67. Creating a Sequential Data Set—Move Mode,
Simple Buffering . . . . . . . . . .
68. Retrieving a Sequential Data Set—Locate
Mode, Simple Buffering . . . . . . . .
69. Like Concatenation Read through BSAM
70. Reissuing a READ or GET for Unlike
Concatenated Data Sets . . . . . . . .
71. One Method of Determining the Length of a
Record when Using BSAM to Read
Undefined-Length or Blocked Records . . .
72. A Partitioned Data Set (PDS) . . . . . .
73. A PDS Directory Block . . . . . . . .
74. A PDS Directory Entry . . . . . . . .
75. Creating One Member of a PDS . . . . .
76. Creating A Nonstandard member name in a
PDS. . . . . . . . . . . . . . .
77. Creating Members of a PDS Using STOW
78. BLDL List Format . . . . . . . . . .
308
311
312
315
317
318
331
332
333
336
345
346
347
359
359
361
362
362
363
373
386
387
402
403
408
409
418
430
430
431
435
436
438
440
xiii
79. DESERV GET by NAME_LIST Control Block
Structure . . . . . . . . . . . . .
80. DESERV GET by PDSDE Control Block
Structure . . . . . . . . . . . . .
81. DESERV GET_ALL Control Block Structure
82. STOW INITIALIZE Example . . . . . .
83. Retrieving One Member of a PDS . . . . .
84. Retrieving Several Members and Subgroups
of a PDS without Overlapping I/O Time and
CPU Time. . . . . . . . . . . . .
85. Reading a Member of a PDS or PDSE using
Asynchronous BPAM . . . . . . . . .
86. Updating a Member of a PDS . . . . . .
87. A Partitioned Data Set Extended (PDSE)
88. TTRs for a PDSE Member (Unblocked
Records) . . . . . . . . . . . . .
89. TTRs for Two PDSE Members (LRECL=80,
BLKSIZE=800) . . . . . . . . . . .
90. Example of How PDSE Records Are
Reblocked. . . . . . . . . . . . .
91. Example of Reblocking When the Block Size
Has Been Changed. . . . . . . . . .
92. Creating One Member of a PDSE . . . . .
93. Creating A Nonstandard member name in a
PDSE . . . . . . . . . . . . . .
94. Adding PDSE Members Serially . . . . .
95. Replacing Multiple PDSE Members
Concurrently. . . . . . . . . . . .
96. DESERV GET by NAME_LIST Control Block
Structure . . . . . . . . . . . . .
97. DESERV GET by PDSDE Control Block
Structure . . . . . . . . . . . . .
98. DESERV GET_ALL Control Block Structure
99. DESERV GET_NAMES Control Block
Structure . . . . . . . . . . . . .
100. DESERV RELEASE Input Control Block
Structure . . . . . . . . . . . . .
101. DESERV UPDATE . . . . . . . . . .
102. ISITMGD Example . . . . . . . . . .
103. Using NOTE and FIND to Switch Between
Members of a Concatenated PDSE . . . .
104. STOW INITIALIZE Example . . . . . .
105. Retrieving One Member of a PDSE . . . .
106. Retrieving Several Members of a PDSE or
PDS. . . . . . . . . . . . . . .
107. OPEN Success/Failure . . . . . . . .
108. OPEN for UPDAT and Positioning to a
Member Decision Table . . . . . . . .
xiv
z/OS DFSMS Using Data Sets
441
442
443
445
445
109.
110.
111.
112.
113.
114.
115.
447
116.
449
451
456
117.
460
460
463
463
471
472
473
473
478
479
480
118.
119.
120.
121.
122.
123.
124.
125.
126.
127.
128.
129.
130.
131.
132.
133.
134.
482
135.
483
484
485
488
489
489
490
492
493
136.
137.
138.
139.
140.
141.
142.
UNIX Directories and Files in a File System
Creating a UNIX File with QSAM. . . . .
Edit-Entry Panel . . . . . . . . . .
ISPF edit of a UNIX file . . . . . . . .
ISPF Shell Panel . . . . . . . . . .
Using OPUT to Copy Members of a PDS or
PDSE to a UNIX File . . . . . . . . .
A Partitioned Concatenation of PDS extents,
PDSEs, and UNIX directories . . . . . .
Status Indicators—BDAM, BPAM, BSAM, and
QSAM . . . . . . . . . . . . . .
Parameter List Passed to DCB Abend Exit
Routine . . . . . . . . . . . . .
Recovery Work Area . . . . . . . . .
Defining an FCB Image for a 3211 . . . .
Parameter List Passed to User Label Exit
Routine . . . . . . . . . . . . .
IECOENTE Macro Parameter List . . . . .
IECOEVSE macro parameter list . . . . .
Direct Access Labeling . . . . . . . .
Initial Volume Label Format . . . . . .
User Header and Trailer Labels on DASD or
Tape . . . . . . . . . . . . . .
Creating a Direct Data Set (Tape-to-Disk)
Adding Records to a Direct Data Set
Updating a Direct Data Set . . . . . . .
Indexed Sequential Data Set Organization
Format of Track Index Entries . . . . . .
Creating an Indexed Sequential Data Set
Sequentially Updating an Indexed Sequential
Data Set . . . . . . . . . . . . .
Directly Updating an Indexed Sequential Data
Set . . . . . . . . . . . . . . .
Directly Updating an Indexed Sequential Data
Set with Variable-Length Records . . . . .
Adding Records to an Indexed Sequential
Data Set . . . . . . . . . . . . .
Deleting Records from an Indexed Sequential
Data Set . . . . . . . . . . . . .
Use of ISAM Processing Programs . . . .
CCSID Conversion Group 1. . . . . . .
CCSID Conversion Group 2. . . . . . .
CCSID Conversion Group 3. . . . . . .
CCSID Conversion Group 4. . . . . . .
CCSID Conversion Group 5. . . . . . .
510
514
521
521
522
523
529
556
569
572
577
579
583
585
592
593
595
602
605
606
612
613
616
625
628
630
632
633
642
665
665
665
665
666
Tables
|
1.
2.
3.
4.
5.
|
|
|
|
|
|
|
|
|
|
|
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
Data management access methods . . . . . 15
Access method services commands. . . . . 17
Data sets supported on read-only devices
24
Data set activity for non-system-managed and
system-managed data sets. . . . . . . . 32
Differences between stripes in sequential and
VSAM data sets . . . . . . . . . . . 46
CSFSERV resource required for data set
encryption . . . . . . . . . . . . . 69
SMS Allocation Processing Based on System
Levels and Allocation Request (z/OS V2R2
with OA50569) . . . . . . . . . . . 71
SMS Allocation Processing Based on System
Levels and Allocation Request (z/OS V2R2
with OA50569) . . . . . . . . . . . 72
SMS Allocation Processing Based on System
Levels and Allocation Request (z/OS V2R1
with OA50569) . . . . . . . . . . . 72
Record definition fields of control intervals
87
Entry-sequenced data set processing . . . . 91
Key-sequenced data set processing . . . . . 94
RRDS processing . . . . . . . . . . . 98
Variable-length RRDS processing . . . . . 99
Comparison of ESDS, KSDS, fixed-length
RRDS, variable-length RRDS, and linear data
sets . . . . . . . . . . . . . . . 99
Adding data to various types of output data
sets . . . . . . . . . . . . . . . 132
Effect of RPL options on data buffers and
positioning . . . . . . . . . . . . 159
Controlling CA reclaim . . . . . . . . 178
SMB access bias guidelines . . . . . . . 184
Relationship between SHAREOPTIONS and
VSAM functions . . . . . . . . . . 216
RLS open rules, for recoverable or
non-recoverable data sets . . . . . . . 242
VSAM user-written exit routines . . . . . 256
Contents of registers at entry to IGW8PNRU
exit routine . . . . . . . . . . . . 258
Contents of registers at entry to EODAD exit
routine . . . . . . . . . . . . . . 259
Contents of registers at entry to
EXCEPTIONEXIT routine . . . . . . . 260
Contents of registers at entry to JRNAD exit
routine . . . . . . . . . . . . . . 261
Contents of parameter list built by VSAM for
the JRNAD exit . . . . . . . . . . . 264
Contents of registers at entry to LERAD exit
routine . . . . . . . . . . . . . . 269
Contents of registers for RLSWAIT exit
routine . . . . . . . . . . . . . . 270
Contents of registers at entry to SYNAD exit
routine . . . . . . . . . . . . . . 271
Conditions when exits to UPAD routines are
taken . . . . . . . . . . . . . . 274
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
69.
70.
© Copyright IBM Corp. 1987, 2017
Contents of registers at entry to UPAD exit
routine . . . . . . . . . . . . . .
Parameter list passed to UPAD routine
Communication with user-securityverification routine. . . . . . . . . .
31-Bit Address Keyword Parameters . . . .
Format of the Header of an Index Record
Segment control codes . . . . . . . .
Tape density (DEN) values . . . . . . .
Optimum and maximum block size
supported. . . . . . . . . . . . .
Rules for setting block sizes for tape data sets
or compressed format data sets . . . . .
Buffering Technique and GET/PUT
processing modes . . . . . . . . . .
Messages for data integrity processing
Different conditions for data integrity
violations . . . . . . . . . . . . .
Types of sequential data sets on DASD –
characteristics and advantages . . . . . .
PDSE and PDS differences . . . . . . .
DE services function summary . . . . . .
Access methods that UNIX files use . . . .
Access permissions for UNIX files and
directories . . . . . . . . . . . .
DCB exit routines . . . . . . . . . .
Data event control block . . . . . . . .
Exception code bits—BISAM . . . . . .
Event control block . . . . . . . . .
Exception code bits—BDAM . . . . . .
Contents of registers at entry to EODAD exit
routine . . . . . . . . . . . . . .
Exception code bits—QISAM . . . . . .
Register contents on entry to SYNAD
routine—BDAM, BPAM, BSAM, and QSAM .
Register contents on entry to SYNAD
routine—BISAM . . . . . . . . . .
Register contents on entry to SYNAD
routine—QISAM . . . . . . . . . .
DCB exit list format and contents . . . . .
Option mask byte settings . . . . . . .
Conditions for which recovery can be
attempted . . . . . . . . . . . . .
System response to block count exit return
code . . . . . . . . . . . . . .
System response to a user label exit routine
return code . . . . . . . . . . . .
Saving and restoring general registers
Requests for indexed sequential data sets
QISAM error conditions . . . . . . . .
BISAM error conditions . . . . . . . .
Register contents for DCB-specified ISAM
SYNAD routine . . . . . . . . . . .
Register contents for AMP-specified ISAM
SYNAD routine . . . . . . . . . . .
ABEND codes issued by the ISAM interface
274
275
276
280
294
309
322
339
341
363
392
393
402
457
477
511
520
550
551
551
553
554
557
558
560
561
561
564
569
570
575
580
583
618
643
644
645
645
646
xv
71.
72.
73.
xvi
DEB fields supported by ISAM interface
DCB fields supported by ISAM interface
Output DISP=NEW,OLD . . . . . .
z/OS DFSMS Using Data Sets
.
646
648
. 667
74.
75.
Output DISP=MOD (IBM V4 tapes only)
Input . . . . . . . . . . . . .
667
. 669
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 673.
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
services commands
z/OS DFSMS Access Method Services Commands describes the access
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 and z/OS DFSMS
Implementing System-Managed Storage describe storage
administration.
Macros
© Copyright IBM Corp. 1987, 2017
z/OS DFSMS Macro Instructions for Data Sets describes the macros
used to process VSAM and non-VSAM data sets.
xvii
Topic
Document
z/OS UNIX System
Services
z/OS UNIX System Services User's Guide describes how to process
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 additional documents:
Document Title
Description
Character Data Representation Architecture
Reference and Registry
Document that includes information about
coded character set identifiers in the
character data representation architecture
repository.
z/OS information
This information explains how z/OS references information in other documents
and on the web.
When possible, this information uses cross document links that go directly to the
topic in reference using shortened versions of the document title. For complete
titles and order numbers of the documents for all products that are part of z/OS,
see z/OS Information Roadmap.
To find the complete z/OS library, go to IBM Knowledge Center
(www.ibm.com/support/knowledgecenter/SSLTBW/welcome).
xviii
z/OS DFSMS Using Data Sets
How to send your comments to IBM
We appreciate your input on this documentation. Please provide us with any
feedback that you have, including comments on the clarity, accuracy, or
completeness of the information.
Use one of the following methods to send your comments:
Important: If your comment regards a technical problem, see instead “If you have
a technical problem.”
v Send an email to [email protected].
v Send an email from the Contact z/OS web page (www.ibm.com/systems/z/os/
zos/webqs.html).
Include the following information:
v Your name and address
v Your email address
v Your phone or fax number
v The publication title and order number:
z/OS DFSMS Using Data Sets
SC23-6855-30
v The topic and page number or URL of the specific information to which your
comment relates
v The text of your comment.
When you send comments to IBM®, you grant IBM a nonexclusive right to use or
distribute the comments in any way appropriate without incurring any obligation
to you.
IBM or any other organizations use the personal information that you supply to
contact you only about the issues that you submit.
If you have a technical problem
Do not use the feedback methods that are listed for sending comments. Instead,
take one or more of the following actions:
v Visit the IBM Support Portal (support.ibm.com).
v Contact your IBM service representative.
v Call IBM technical support.
© Copyright IBM Corp. 1987, 2017
xix
xx
z/OS DFSMS Using Data Sets
Summary of changes
This information includes terminology, maintenance, and editorial changes.
Technical changes or additions to the text and illustrations for the current edition
are indicated by a vertical line to the left of the change.
Summary of changes for z/OS Version 2 Release 3 (V2R3)
The following changes are made for z/OS Version 2 Release 3 (V2R3).
New
v Added information about new support for accessing read-only data sets, in
“Processing data sets on read-only devices” on page 22.
v Added information about new support for z/OS data set encryption, in “Data
Set Encryption” on page 66.
Summary of changes for z/OS Version 2 Release 2 (V2R2)
The following changes are made for z/OS Version 2 Release 2 (V2R2).
New
v Added information on using a non-SMS managed VSAM linear data set with
extended addressability as a zFS version root, in “Using a non-SMS managed
data set for a zFS version root larger than four gigabytes” on page 510.
v Added information on using hiperspace caching for PDSEs, in “Hiperspace
caching for PDSE” on page 503.
Changed
v VSAM information was updated in “Acquiring Buffers” on page 191, “Using
Hiperspace Buffers with LSR” on page 222, and “Deciding the Size of a Virtual
Resource Pool” on page 223.
v Space constraint attributes for a data class may now apply to the secondary
quantity during allocation, as well as the primary quantity, resulting in more
efficient use of space. For more information, refer to “Allocation of Data Sets
with the Space Constraint Relief Attributes” on page 48.
Moved
“Using BSAM, BPAM, and QSAM support for XTIOT, uncaptured UCBs, and
DSAB above the 16 MB line” on page 375 was moved into this information from a
previous edition of DFSMS Using the New Functions.
Deleted
No content was removed from this information.
© Copyright IBM Corp. 1987, 2017
xxi
Summary of changes for z/OS Version 2 Release 1 (V2R1) as updated
March 2014
The following changes are made for z/OS Version 2 Release 1 (V2R1) as updated
March 2014. In this revision, all technical changes for z/OS V2R1 are indicated by
a vertical line to the left of the change.
New
New zEDC compression types are added to “Types of Compression” on page 421
Note: For more information on the zEDC compression enhancements, see z/OS
DFSMS Using the New Functions.
Summary of changes for z/OS Version 2 Release 1 (V2R1) as updated
December 2013
Changes made to z/OS V2R1 as updated December 2013
New
Version 2 PDSEs support multiple levels, or generations, of members. For details,
refer to “PDSE Member Generations” on page 469.
xxii
z/OS DFSMS Using Data Sets
Part 1. All Data Sets
This topic provides information on general topics for all data sets.
© Copyright IBM Corp. 1987, 2017
1
2
z/OS DFSMS Using Data Sets
Chapter 1. Working with Data Sets
This chapter covers the following topics.
Topic
“Data Storage and Management”
“Access Methods” on page 4
“Direct Access Storage Device (DASD) Volumes” on page 8
“Magnetic Tape Volumes” on page 12
“Data Management Macros” on page 15
“Data Set Processing” on page 16
“Distributed Data Management (DDM) Attributes” on page 26
“Virtual I/O for Temporary Data Sets” on page 27
“Data Set Names” on page 27
“Catalogs and Volume Table of Contents” on page 28
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, 2017
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 31. If
you are a storage administrator, also see z/OS DFSMSdfp Storage Administration 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
26.
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 DFSMS Using Data Sets
Working with Data Sets
Related reading: See the following material:
v “Track Format” on page 9
v Appendix C, “Processing Direct Data Sets,” on page 599
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
|
|
|
|
|
Extended-format data sets have an internal storage format that is different from
data sets that are not extended format. The internal storage format for
extended-format data sets provides more usability characteristics, and can have
better performance if the data set is striped. You can choose for an extended-format
data set to be any combination of:
|
v striped
|
v encrypted
|
v compressed format
|
v or none of those.
|
Extended-format data sets must be SMS-managed.
Chapter 1. Working with Data Sets
5
Working with Data Sets
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
information.
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,
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 609.
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, file system, optical storage volume, or tape storage
volume. OAM uses SMS policies to provide information lifecycle management for
these objects. 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
|
|
|
|
|
Extended-format data sets have an internal storage format that is different from
data sets that are not extended format. The internal storage format for
extended-format data sets provides more usability characteristics, and can have
better performance if the data set is striped. You can choose for an extended-format
data set to be any combination of:
|
|
v striped
v encrypted
|
v compressed format
|
v or none of those.
|
Extended-format data sets must be SMS-managed.
6
z/OS DFSMS Using Data Sets
Working with Data Sets
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
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 data set to be in the compressed format or
encrypted 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 z/OS File System (zFS)
v Character special files
v First-in-first-out (FIFO) special files
v Symbolic links
Chapter 1. Working with Data Sets
7
Working with Data Sets
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.
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.
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 591 for information about
direct access labels.
8
z/OS DFSMS Using Data Sets
Working with Data Sets
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 85 and Chapter 20, “Selecting Record
Formats for Non-VSAM Data Sets,” on page 303.
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.
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
Track Descriptor
Record (RO)
Count
Data
...
Block (R1)
Count
Data
Block (Rn)
Count-Key-Data Format
Count
Data
Count
Track Descriptor
Record (RO)
Key
Block (R1)
Data
...
Count
Key
Data
Block (Rn)
Figure 1. DASD Volume Track Formats
Chapter 1. Working with Data Sets
9
Working with Data Sets
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 90.
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.
10
z/OS DFSMS Using Data Sets
Working with Data Sets
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.
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 459 for a description of TTRs for PDSE members and
Chapter 1. Working with Data Sets
11
Working with Data Sets
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 topic 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.
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.
12
z/OS DFSMS Using Data Sets
Working with Data Sets
Related reading: For additional information about using file sequence numbers,
see 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.
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
//C.SYSIN 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
DCBAD
CLOSE
CLOSE FILE
. . .
DCBDCB
DDNAME=DD1,DSORG=PS,EXLST=LSTA,MACRF=PM,LRECL=80,RECFM=FB
LSTA
DS
0F
RJFCB EXIT LIST
DC
AL1(EXLLASTE+EXLRJFCB) CODE FOR JFCB (X’87’)
DC
AL3(JFCBAREA) POINTER TO JFCB AREA
JFCBAREA EQU *
176 bytes for copy of JFCB
* The IEFJFCBN does not define a DSECT. This continues the CSECT.
IEFJFCBN
DEFINE THE JFCB FIELDS
RECORD
DC CL80’RECORD10011’
RECORD AREA
IHAEXLST ,
Define symbols for DCB exit list
Chapter 1. Working with Data Sets
13
Working with Data Sets
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
//C.SYSIN 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
*
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
14
z/OS DFSMS Using Data Sets
Working with Data Sets
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.
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
Basic
Direct
BDAM
Queued
VSAM
ESDS
VSAM
KSDS
VSAM
Chapter 1. Working with Data Sets
15
Working with Data Sets
Table 1. Data management access methods (continued)
Data Set Organization
Basic
Queued
VSAM, DIV1
LDS
Partitioned2
RRDS
VSAM
BPAM, BSAM3
QSAM
4
VSAM
5
Sequential
z/OS UNIX file
BSAM
6
BSAM
QSAM
7
QSAM7
VSAM8
Note:
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.
8. 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
21.
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.
You can use any of the following methods to allocate a data set.
Related reading: For information about these methods, see Chapter 2, “Using the
Storage Management Subsystem,” on page 31.
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.
16
z/OS DFSMS Using Data Sets
Working with 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
Related reading: For information about access method services commands see
z/OS DFSMS Access Method Services Commands.
ALLOCATE Command
You can issue the ALLOCATE command either through access method services or
TSO/E to define VSAM and non-VSAM data sets.
Related reading: For information about TSO commands, see z/OS TSO/E Command
Reference.
Dynamic Allocation
You can allocate VSAM and non-VSAM data sets using the DYNALLOC macro
with the SVC 99 parameter list.
Related reading: For information about dynamic allocation, see z/OS MVS
Programming: Authorized Assembler Services Guide.
JCL
All data sets can be defined directly through JCL.
Related reading: For information about using JCL, see z/OS MVS JCL Reference and
z/OS MVS JCL User's Guide.
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:
Chapter 1. Working with Data Sets
17
Working with Data Sets
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 205 for information about sharing a VSAM data set. See
Chapter 23, “Sharing Non-VSAM Data Sets,” on page 385 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 221.
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 549 and Chapter 16, “Coding VSAM User-Written Exit
Routines,” on page 255.
v Back up and recover data sets. See Chapter 4, “Backing Up and Recovering Data
Sets,” on page 55.
v Maintain data security and integrity. See Chapter 5, “Protecting Data Sets,” on
page 63.
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
31-bit addressing mode to access these areas above 16 MB. See Chapter 17, “Using
31-Bit Addressing Mode with VSAM,” on page 279.
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.
There are only two non-VSAM access method macros that accept a 64-bit virtual
address. The READ and WRITE macros support the data area address being a
64-bit virtual address if the data set is extended format and not compressed
format. Your program must be running in 31-bit mode. You must code the SF64 or
SF64P option on the READ or WRITE macro.
18
z/OS DFSMS Using Data Sets
Working with Data Sets
If the 64-bit address points above the 2 GB bar, then the storage must satisfy one of
these conditions:
v It was obtained by issuing the IARST64 macro with REQUEST=GET. The
maximum length of storage gotten by this means is 64 KB.
v It was obtained by issuing the IARV64 macro with the REQUEST=GETSTOR and
CONTROL=AUTH options. This requires your program to run in supervisor
state or system key. The minimum storage length is 1 MB.
|
|
v It was obtained in a cell pool by issuing the IARCP64 macro with
REQUEST=GET.
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 419 and “Using
Hiperspace Buffers with LSR” on page 222.
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:
//ddname DD DSN=LIBNAME(MEMNAME),...
Chapter 1. Working with Data Sets
19
Working with Data Sets
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 464.
v You can use the STOW macro to add, delete, change, or replace a member name
or alias in the PDS or PDSE directory. You can also use the STOW macro to
delete all the members of a PDS or PDSE. 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 429 and
Chapter 27, “Processing a Partitioned Data Set Extended (PDSE),” on page 455.
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.
v BSAM automatically updates the directory when a member of a PDS or PDSE is
added or deleted.
20
z/OS DFSMS Using Data Sets
Working with Data Sets
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 z/OS 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.
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, but the access method adds metadata to define records if you specify
FILEDATA=RECORD on the DD statement or data class. UNIX programs can
use that metadata to handle record boundaries.
Chapter 1. Working with Data Sets
21
Working with Data Sets
v The access method buffers writes beyond the buffering that your program sees.
This means that after your program issues BSAM WRITE and CHECK, QSAM
PUT with BUFNO=1 or a VSAM PUT, the data probably is not yet on the disk.
If the file is not a FIFO, your program can issue the BSAM or QSAM SYNCDEV
or CLOSE macro to force immediate writing. This interferes with good
performance.
Related Reading: For more information about the following topics, see:
v Chapter 28, “Processing z/OS UNIX Files,” on page 509
v “Simulated VSAM Access to UNIX files” on page 92
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.
Processing data sets on read-only devices
|
|
|
|
|
|
|
|
Read-only devices are devices that do not allow writes. The system programmer
can define one or more DASD volumes with the read-only attribute. To learn more
about how to define a device with the read-only attribute see z/OS HCD Planning.
To process data sets from a read-only volume, certain keywords at data set
allocation and open may be required. These keywords protect applications from
accessing data sets that have different read integrity behavior compared to data
sets on devices that are not read-only.
|
|
|
For more information about assembler program’s access to data on read-only
devices, refer to the CONCURRENTRW keyword on the DCBE macro in z/OS
DFSMS Macro Instructions for Data Sets.
|
|
|
|
Processing considerations and requirements for data sets on
read-only volumes
|
|
|
|
|
|
|
|
Software versus Hardware Sharing
Normally, a job allocates the data set and it states whether it can share
concurrent access to the data set. By specifying a disposition of SHR, the
job indicates that it can tolerate other programs processing the data set at
the same time. Even though access may be shared, the storage subsystem
serializes all of the tracks in the current data set extent. It does this by
delaying a write channel program when a read channel program to the
same extent has already started. For normal (non-read-only) devices, this
Consider the following differences in behavior that apply to data sets on read-only
PPRC secondary volumes, and requirements for accessing them successfully.
22
z/OS DFSMS Using Data Sets
Working with Data Sets
|
|
|
allows the system to guarantee that the data that each channel program
reads will show all of the updates from individual channel programs or
none of those updates.
|
|
|
|
|
|
|
|
|
|
When a data set is accessed from a read-only PPRC secondary device, the
job implicitly shares access with concurrent writes that are mirrored from
the PPRC primary device. When your program causes the access method
to read one or more blocks, the storage controller will delay a request to
update blocks on this track. However, blocks written to other tracks are not
serialized with the channel program that is reading. Your program's
serialization is limited to the blocks read from one track, even though your
program may access blocks spread across many tracks. This means a
program can read blocks that were not written at the same point in time,
which could lead to loss of read data integrity.
|
|
|
|
|
|
|
To ensure an application program can accept the serialization provided by
this read-only device, data set allocation supports the ROACCESS
keyword. For more information, see z/OS MVS JCL Reference. Non-VSAM
OPEN checks the CONCURRENTRW keyword in the optional DCBE
macros to ensure the application programmer has considered the read
integrity provided by a read-only device. See z/OS DFSMS Macro
Instructions for Data Sets.
|
|
|
|
|
|
|
|
|
|
Processing VSAM Data Sets on Peer-to-Peer Remote Copy (PPRC) secondary
devices
VSAM stores records in control intervals. A control interval (CI) is a
continuous area of direct access storage that VSAM uses to store data
records and control information that describes the records. Depending on
the control interval size, the physical blocks for a given CI may cross a
track boundary. Because a read-only secondary device does not provide
multitrack serialization, VSAM prevents an application program from
opening a data set with control interval sizes that allow the CI to cross a
track boundary.
|
|
|
|
|
|
CI size restriction
For VSAM data sets, all CI sizes up to 12 KB are supported; CI sizes 16
KB, 18 KB (for non-Extended Format data sets), 24 KB, and 26 KB are also
supported. This restriction ensures that the physical blocks that make up
the CI are all located on the same track, and prevents a read integrity issue
caused by a PPRC write that modifies a CI that spans a track boundary.
|
|
|
|
|
|
|
|
VSAM OPEN will not require a keyword to open a VSAM data set on a
read-only device as long as they adhere to the CI and SHAREOPTIONS
requirements. This allows many applications that use many CI sizes to
continue to work without modification. However, Device Allocation will
still require keyword ROACCESS=(ALLOW,TRKLOCK).
Does VSAM guarantee that all I/O buffers are consistent with each other?
There are scenarios when VSAM uses multiple I/O buffers (BUFND > 1).
These include:
|
v Spanned records
|
v Read ahead
|
v Sequential writes.
|
|
|
|
|
Without extent serialization, VSAM cannot guarantee all buffers have
consistency. However, if the CI does not cross a track boundary, VSAM can
guarantee the consistency of each individual CI, and therefore guarantee
the consistency of the record, even if it is a spanned record (because VSAM
will notify the caller if the consistency of a spanned record is
Chapter 1. Working with Data Sets
23
Working with Data Sets
compromised, and the caller can revise the request). Restriction: VSAM
only permits an application program to open a data set defined using
SHAREOPTION(2,x) or (3,x). VSAM converts DISP=OLD to SHR(1,3),
which means the user expects only one writer or many readers — and
since VSAM cannot guarantee that, VSAM fails in that case.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Processing linear data sets on PPRC secondary devices
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. On a read-only volume
using the Media Manager I/O Driver, access to a linear data set is not
serialized beyond an individual physical block. (Technically, blocks on the
same track cannot be written while a track is being read, but applications
are not aware of the block-to-track mapping). The application program is
responsible for verifying the integrity of each control interval, which is
composed of one or more physical blocks, accessed from a read-only
volume. The same is true for logical records with a record length greater
than one physical block. The operating system will not prevent an
application from processing a CI or logical record with some blocks that
were not updated at the same time. It is the responsibility of the
application to detect this exception.
|
|
|
|
|
|
|
|
|
|
|
|
|
Processing non-VSAM Data Sets on PPRC secondary devices
Non-VSAM OPEN will require the CONCURRENTRW=(YES,TRKLOCK)
keyword on the DCBE macro to access a data set on a read-only secondary
device. This device will bypass extent collision checking. This means that
another program, on this system or another system, can modify one or
more blocks in the same data set while your program is reading, with one
exception: while your program is reading blocks on a specific track, writes
to this track are delayed. Once your program reads blocks on another
track, updates to blocks on the previous track are allowed to proceed. This
means that your program cannot read multiple blocks spread across
multiple tracks with consistency. For BSAM, QSAM, and EXCP only
specify TRKLOCK if your program can tolerate this level of serialization.
This option has an effect only when the device is defined as read-only.
|
Data sets supported on read-only devices
The following table lists the data sets that are supported on a read-only
device.
|
|
|
Table 3. Data sets supported on read-only devices
|
|
Data set type
|
|
|
|
|
|
|
|
Access method
Sequential (basic, BSAM
large, and
extended format)
|
|
|
|
24
z/OS DFSMS Using Data Sets
Open for
Access allowed on a read-only
device?
INPUT, INOUT,
UPDAT
Yes. Requires JCL DD ROACCESS
parameter or dynamic allocation
text units DALROAC and
DALROA2 - if not specified,
allocation fails. Requires DCBE
parameter CONCURRENT=
(YES,TRKLOCK) - if not specified,
abends with code 213-56.
OUTPUT,
OUTIN,
OUTINX,
EXTEND
No. ABEND with code 213-52.
Working with Data Sets
|
Table 3. Data sets supported on read-only devices (continued)
|
|
Data set type
|
|
|
|
|
|
|
|
Access method
Sequential (basic, QSAM
large, and
extended format)
|
|
|
|
|
|
|
|
|
|
Sequential (basic
and large)
EXCP
|
|
|
Open for
Access allowed on a read-only
device?
INPUT, UPDAT
Yes. Requires JCL DD ROACCESS
parameter or dynamic allocation
text units DALROAC and
DALROA2 - if not specified,
allocation fails. Requires DCBE
parameter CONCURRENT=
(YES,TRKLOCK) - if not specified,
abends with code 213-56.
OUTPUT,
EXTEND
No. ABEND with code 213-52.
INPUT, INOUT,
UPDAT
Yes. Requires JCL DD ROACCESS
parameter or dynamic allocation
text units DALROAC and
DALROA2 - if not specified,
allocation fails. Requires DCBE
parameter CONCURRENTRW=
(YES,TRKLOCK) - if not specified,
abends with code 213-56.
OUTPUT,
OUTIN,
EXTEND
No. ABEND with code 213-52.
|
|
|
|
|
|
|
|
|
|
LDS, KSDS,
ESDS,
RRDS,VRRDS
Base VSAM
INPUT, OUTPUT Yes. Requires JCL DD ROACCESS
parameter or dynamic allocation
text units DALROAC and
DALROA2 - if not specified,
allocation fails. Limited to certain
CONTROLINTERVALSIZE and
SHAREOPTIONS values. IEC161I
(return code 092) RC8 is returned
if the data set attributes are not
compatible.
|
|
KSDS, ESDS,
RRDS, VRRDS
VSAM RLS
Not allowed
No. IEC161I (return code 092) RC8
is returned.
|
|
Direct
BDAM, BSAM,
QSAM, EXCP
Not allowed
No. Abends with code 213-52.
|
|
Sequential (basic
format)
BDAM, BDAM
Create
Not allowed
No. Abends with code 213-52.
|
|
Partitioned (PDS
and PDSE)
BSAM, QSAM,
BPAM
Not allowed
No. Abends with code 213-52.
|
|
|
|
zFS and HFS
UNIX System
Services
Not allowed
No. Mount command fails due to
device allocation error. IEFA181I is
returned.
|
|
|
Summary
An application might need to be modified in order to process data sets on
a read-only device. Here are some scenarios to consider:
|
|
|
|
|
v Loss of ECKD atomicity – On a read-only system, a data set residing on
a secondary device can be accessed while the production system has
allocated the "same" data set OLD on the PPRC primary device. This
means that the application on the read-only system can access the same
set of tracks ("extent") while those same tracks are being written
Chapter 1. Working with Data Sets
25
Working with Data Sets
(mirrored) from the primary device. A channel program that reads
multiple blocks may end up reading blocks of data that were written a
various times. No error will be reported by the access method. The
application program is responsible for detecting this condition.
|
|
|
|
v An application program can get ahead of the writer and read blocks
allocated to the data set that have not yet been written or initialized.
|
|
Limitations and restrictions
v Volume and data set operations from a production site will affect
applications that are accessing data sets on read-only volumes. An
example of a read-only volume is a read-only PPRC secondary volume.
You can access data sets on read-only volumes from a system that is
outside the GRS sysplex. However, there are more things to consider. For
example, GRS serialization is not supported outside the sysplex. Also, a
RESERVE to a PPRC primary volume does not reserve the PPRC
secondary volume.
|
|
|
|
|
|
|
|
|
|
|
|
v A good use case for accessing read-only volumes is sequential data sets.
An example is log recovery files. Another candidate might be data set
access to a single block without regard to other blocks.
|
|
|
|
|
v Access to VSAM data sets has additional considerations. An application
program might reach the end of the data set and not be aware that
additional extents have been added. In this case, additional actions
might be needed. In this case an application program can issue a
VERIFY, ACTION=REFRESH macro.
|
|
v SMS configuration data sets should not be accessed from a read-only
volume
|
|
v Using DFSMSdss to COPY or RESTORE a data set to a (target) volume
that is read-only will cause DFSMSdss to fail.
|
v DFSMShsm ML1 volumes cannot be read-only
|
v DFSMShsm CDSes cannot be accessed from a read-only volume
|
|
v Loading a configuration of PPRC devices to the Hyperswap manager is
rejected if any device is defined with the read-only attribute.
|
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.
26
z/OS DFSMS Using Data Sets
Working with Data Sets
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,
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
Chapter 1. Working with Data Sets
27
Working with Data Sets
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.
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 DEPT58.SMITH.DATA3 is composed of three name segments. The first name on
the left (DEPT58 in that example) 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 118 and “Naming an Alternate Index” on page
134 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 (HLQ.ABCDEFGHI.XYZ)
v A name that contains two successive periods (HLQ..ABC)
v A name that ends with a period (HLQ.ABC.)
v A name that contains a segment that does not start with an alphabetic or
national character (HLQ.123.XYZ)
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 591.
28
z/OS DFSMS Using Data Sets
Working with Data Sets
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)
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 one or more data set control blocks (DSCBs) 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:
Chapter 1. Working with Data Sets
29
Working with Data Sets
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. 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 29. For more
information, see “Hiding Data Set Names” on page 65.
30
z/OS DFSMS Using Data Sets
Chapter 2. Using the Storage Management Subsystem
This topic covers the following subtopics.
Topic
“Using Automatic Class Selection Routines” on page 33
“Allocating Data Sets” on page 34
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 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, 2017
31
Using the Storage Management Subsystem
v SMS must be active when you allocate a new data set to be SMS managed.
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 4 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.
Table 4. 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 exits
ACS
RACF , JCL, IDCAMS, TSO/E,
DYNALLOC
RACF3, data class, JCL, IDCAMS,
TSO/E, DYNALLOC
Access authorization
RACF3
RACF3
Read/write performance, availability
Manual placement, JCL, DFSMSdss1,
DFSMShsm2
Management and storage class
Access method access to UNIX byte
stream
JCL (PATH=) or dynamic allocation
equivalent
JCL (PATH=) or dynamic allocation
equivalent
Backup
DFSMShsm2, DFSMSdss1, utilities
Management class
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
Allocation authorization, definition
3
Access:
Space Management:
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 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
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
32
z/OS DFSMS Using Data Sets
Using the Storage Management Subsystem
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 Commands
(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.
Chapter 2. Using the Storage Management Subsystem
33
Using the Storage Management Subsystem
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 Commands 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.
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.
34
z/OS DFSMS Using Data Sets
Using the Storage Management Subsystem
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 511.
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.
Extended format can also be requested using the DSNTYPE parameter on the JCL
DD statement, with values of EXTREQ (required) or EXTPREF (preferred). The
DSNTYPE specified on a JCL DD statement overrides any DSNTYPE set for the
data class.
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) up to 16,777,215 tracks
Chapter 2. Using the Storage Management Subsystem
35
Using the Storage Management Subsystem
per volume. Large format data sets can be system-managed or not. You can
allocate a large format data set 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.Any VSAM data set that is SMS-managed and
extended format can have the Extended Addressable attribute. The only exception
is for linear data sets which can have the Extended Addressable attribute and be
non SMS-managed.
|
|
|
|
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 Commands (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
//STEP1
//SYSPRINT
//SYSIN
JOB ...
EXEC PGM=IDCAMS,DYNAMNBR=1
DD
SYSOUT=A
DD
*
ALLOC DSNAME(ALX.ALLOCATE.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
ALX.ALLOCATE.EXAMP1.
36
z/OS DFSMS Using Data Sets
Using the Storage Management Subsystem
v NEW specifies the data set being allocated is new.
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
//STEP1
//SYSPRINT
//SYSIN
JOB ...
EXEC PGM=IDCAMS,DYNAMNBR=1
DD
SYSOUT=A
DD
*
ALLOC DSNAME(ALX.ALLOCATE.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
//STEP1
//SYSPRINT
//SYSABEND
//SYSIN
JOB ...
EXEC PGM=IDCAMS
DD
SYSOUT=A
DD
SYSOUT=A
DD
*
ALLOC DSNAME(NONVSAM.EXAMPLE) 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(XMP.ALLOCATE.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
//STEP1
//SYSPRINT
//SYSIN
JOB ...
EXEC PGM=IDCAMS,DYNAMNBR=1
DD
SYSOUT=A
DD
*
ALLOC DSNAME(XMP.ALLOCATE.EXAMP3) Chapter 2. Using the Storage Management Subsystem
37
Using the Storage Management Subsystem
NEW CATALOG SPACE(10,5) TRACKS 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(EX1.DATA) DSORG(PS) SPACE(2,0) TRACKS LRECL(80) RECFM(F,B) NEW
The
The
The
The
The
new data set name: GOLD.EX1.DATA
number of tracks: 2
logical record length: 80
block size: determined by the system
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(EX2.DATA) 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
You can allocate VSAM and non-VSAM data sets using the DYNALLOC macro
with the SVC 99 parameter list.
Note: To allocate a VSAM data set using the DYNALLOC macro with the SVC 99
parameter list, specify text unit 800B - RECORG.
For application programs that require 24–bit UCB addresses, the system creates
24–bit UCB addresses for above 16 MB UCBs. This view is known as a captured
UCB. With step or batch allocation, the system automatically captures an above 16
MB UCB address at allocation and uncaptures the UCB address at deallocation.
However, with dynamic allocation, it is possible not to capture a UCB address if
the affected program can handle above 16 MB UCBs. The major user of uncaptured
UCBs is Db2.
38
z/OS DFSMS Using Data Sets
Using the Storage Management Subsystem
Use the following dynamic allocation options when allocating a VSAM or
non-VSAM data set to use uncaptured UCBs above the 16 MB line and reduce
storage usage:
v XTIOT option (S99TIOEX) - This option requires that your program be APF
authorized, in supervisor state, or in a system key.
v NOCAPTURE option (S99ACUCB) - This option causes the creation of an
XTIOT entry, but it does not require authorization or the coding of the XTIOT
option.
v DSAB-above-the-line option (S99DSABA) - Specify this option to place the data
set association control block (DSAB) above the 16 MB line. You must specify
S99TIOEX if you use this option.
Note: The following non-VSAM access methods support the NOCAPTURE,
XTIOT, and DSAB-above-the-line options of dynamic allocation: BPAM, BSAM, and
QSAM. The following non-VSAM access methods do not support the
NOCAPTURE, XTIOT, and DSAB-above-the-line options of dynamic allocation:
BDAM.
Related reading: See z/OS MVS Programming: Authorized Assembler Services Guide
for more information and for examples of allocating a data set using the
DYNALLOC macro.
Chapter 2. Using the Storage Management Subsystem
39
40
z/OS DFSMS Using Data Sets
Chapter 3. Allocating Space on Direct Access Volumes
This chapter covers the following topics.
Topic
“Specification of Space Requirements”
“Maximum Data Set Size” on page 43
“Primary and Secondary Space Allocation without the Guaranteed Space Attribute” on page
44
“Allocation of Data Sets with the Guaranteed Space Attribute” on page 46
“Allocation of Data Sets with the Space Constraint Relief Attributes” on page 48
“Extension to Another DASD Volume” on page 50
“Multiple Volume Considerations for Sequential Data Sets” on page 50
“Additional Information on Space Allocation” on page 53
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, 2017
41
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 338.
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 preceding 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 following examples.
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:
42
z/OS 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 topic 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 A large format sequential; but cannot occupy more than 16 777 215 tracks on a
single volume.
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 does not enforce this limit when creating the data set but does enforce
it when you open the data set by using the BDAM.
Chapter 3. Allocating Space on Direct Access Volumes
43
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 either:
v A VSAM linear data set (LDS), or
v SMS-managed and 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.
v A system-managed VSAM data set can have up to 255 extents per stripe. This
limit can be removed if the associated data class has extent constraint removal
specified.
v A striped VSAM data set can have 255 extents per stripe in the data component,
the index component will not be striped and thus can only have 255 extents.
v A PDSE can have 123 extents.
v An HFS data set can have 123 extents on each volume.
44
z/OS DFSMS Using Data Sets
Allocating Space on Direct Access 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
primary allocation of space is filled, space is allocated in secondary storage
amounts (if a secondary amount was specified) until the volume is full. The extents
can then continue in this manner to another volume until the additional volumes
are exhausted.
Extents for a striped data set are handled by stripe. See “VSAM Data Striping” on
page 101 for more details.
VIO space allocation is handled differently from other data sets. See “Virtual I/O
for Temporary Data Sets” on page 27.
Multivolume VSAM Data Sets
When a current volume is full, allocation can continue if there are additional
volumes specified for the data set.
When a multivolume VSAM data set with no extended function extends to the
next volume, the initial space allocated on that volume is a primary amount. When
a multivolume VSAM data set with extended format extends to the next volume,
the current value of the data class option, Additional Volume Amount, indicates
whether the initial space allocated on that volume is a primary amount or a
secondary amount. The default is the primary amount. After the initial space
allocated on the volume is used up, space is allocated in secondary amounts. The
previous comments do not pertain to VSAM data that is striped. See “VSAM Data
Striping” on page 101 for details about VSAM data in the striped format.
Special consideration for Secondary Allocation Quantity of Zero:
v For non-striped VSAM data sets, if the secondary allocation quantity is zero, no
secondary extents on the volume can occur. If there are other volumes defined, a
primary allocation will be taken on the next available volume otherwise the
extent will fail.
v For striped VSAM data sets, extensions occur by stripe, so if there is a secondary
quantity of zero, the primary space value is used for the extensions across all
stripes until space is exhausted on the primary and new volumes, or until the
maximum extents for the data set is reached.
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. Striped data sets are
always allocated in tracks, irrespective of the unit of allocation specified on the
define.
Chapter 3. Allocating Space on Direct Access Volumes
45
Allocating Space on Direct Access Volume
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 5 shows how stripes for an extended-format sequential data set are different
from stripes for an extended-format VSAM data set.
Table 5. 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
cannot be extended to another volume.
Each stripe can reside on one or more
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
following blocks on a track in the next stripe.
After the system writes a control interval
(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
methods.
You can use the VSAM access method.
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:
46
z/OS DFSMS Using Data Sets
Allocating Space on Direct Access Volume
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.
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=ENG.MULTIFILE,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.
Chapter 3. Allocating Space on Direct Access Volumes
47
Allocating Space on Direct Access 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.
The attributes are:
v Space Constraint Relief (values are YES or NO). This specifies whether or not to
retry an allocation that was unsuccessful due to space constraints on the volume.
v Reduce Space Up To % (0 - 99%). Used with Space Constraint Relief, this
specifies the amount by which you want to reduce the requested space quantity
when the allocation is retried.
v Dynamic Volume Count (1 - 59 or blank). This is used during allocation
processing to determine the maximum number of volumes a data set can span.
It allows the number of primary volumes to increase, if necessary, without
adding any candidate volumes to the catalog.
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 CREATE
processing, the primary quantity might be reduced for both non-VSAM and VSAM
data sets.
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.
Related reading: For more information about the data class attributes, refer to z/OS
DFSMSdfp Storage Administration.
48
z/OS DFSMS Using Data Sets
Allocating Space on Direct Access Volume
Examples of Dynamic Volume Count When Defining a Data Set
The following examples show the use of volume count (which can be specified
with the attribute for the data class or with a TSO or IDCAMS command, or JCL)
along with the Dynamic Volume Count attribute.
1. Example 1:
Volume count:
Dynamic volume count:
Required volumes:
Volumes in catalog:
6
0
1
1 primary, 5 candidates
2. Example 2:
Volume count:
Dynamic volume count:
Required volumes:
Volumes in catalog:
6
12
1
1 primary, 5 candidates
3. Example 3:
Volume Count:
Dynamic volume count:
Required volumes:
Volumes in catalog:
6
12
7
7 primary, 0 candidates
4. Example 4:
Volume count:
Dynamic volume count:
Required volumes:
Volumes in catalog:
6
12
13
None; request fails
Examples of Dynamic Volume Count When Allocating an
Existing Data Set
The following examples show specific and nonspecific volumes returned to
allocation.
1. Example 5: VSAM KSDS
Specific volume count:
Nonspecific volume count:
Cluster dynamic volume count:
Specific volumes returned to allocation:
Nonspecific volumes returned to allocation:
Total count of volumes returned to allocation:
2
4
20
2
18
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
Specific volumes returned to allocation:
7
Nonspecific volumes returned to allocation:
54
Total count of volumes returned to allocation:
61
Chapter 3. Allocating Space on Direct Access Volumes
49
Allocating Space on Direct Access Volume
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.
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 preceding 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.
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 as follows,
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.
50
z/OS DFSMS Using Data Sets
Allocating Space on Direct Access Volume
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 on all volumes of a
multivolume data set.
Extended Address Volumes
An extended address volume is a volume with more than 65 520 cylinders. An
extended address volume increases the amount of addressable DASD storage per
volume beyond 65 520 cylinders by changing how tracks on ECKD volumes are
addressed.
A track address is a 32-bit number that identifies each track within a volume. The
address is in the format hexadecimal CCCCcccH.
v CCCC is the low order 16-bits of the cylinder number.
v ccc is the high order 12-bits of the cylinder number.
v H is the four-bit track number.
The combination of the 16-bits and 12-bits for the low order and high order
cylinder number represents a 28-bit cylinder number. IBM recommends the use of
the TRKADDR macro for the manipulation of track addresses. See z/OS DFSMSdfp
Advanced Services for more information.
For an extended address volume, the extended addressing space (EAS) is cylinders
whose addresses are equal to or greater than 65,536. The ccc portion is non-zero for
the cylinders of EAS. These cylinder addresses are represented by 28-bit cylinder
numbers.
For compatibility with older programs, the ccc portion is hexadecimal 000 for
tracks in cylinders whose addresses are below 65,536. These cylinder addresses are
represented by 16-bit cylinder numbers. This is the base addressing space on an
extended address volume.
A multi-cylinder unit is a fixed unit of disk space that is larger than a cylinder.
Currently, on an EAV, a multicylinder unit is 21 cylinders and the number of the
first cylinder in each multi-cylinder unit is a multiple of 21.
The cylinder-managed space is space on the volume that is managed only in
multi-cylinder units. Cylinder-managed space begins at cylinder address 65,520.
Each data set occupies an integral multiple of multicylinder units. Space requests
targeted for the cylinder-managed space are rounded up to the next multi-cylinder
unit. The cylinder-managed space only exists on EAV volumes.
Chapter 3. Allocating Space on Direct Access Volumes
51
Allocating Space on Direct Access Volume
The track-managed space is space on a volume that is managed in tracks and
cylinders. Track-managed space ends at cylinder address 65,519. Each data set
occupies an integral multiple of tracks. Track-managed space also exists on all
volumes.
For an extended address volume, the system and storage group break point value
(BPV) helps direct disk space requests to cylinder or track-managed space. The
breakpoint value is expressed in cylinders. When the size of a disk space request is
the breakpoint value or more, the system prefers to use the cylinder-managed
space for that extent. This rule applies to each request for primary or secondary
space for data sets that are eligible for the cylinder-managed space. If
cylinder-managed space is insufficient, the system uses the track-managed space or
uses both types of spaces. When the size of a disk space request is less than the
breakpoint value, the system prefers to use the track-managed space. If space is
insufficient, the system uses the cylinder-managed space or uses both types of
spaces.
Almost all types of data sets are EAS-eligible, including the following:
v SMS and non-SMS managed VSAM data sets (all types), including:
– BCS and VVDS catalog data sets
– VSAM data sets inherited from prior physical migrations or copies
– VSAM temporary data sets
v zFS data sets (they are VSAM).
v Sequential data sets, including extended, basic, and large formats
v PDS and PDSE data sets
v Direct (BDAM) data sets
v Data sets allocated with undefined DSORGs
You can control whether EAS-eligible data sets can reside in cylinder-managed
space by:
v Including or excluding EAVs in particular storage groups.
v For non-SMS managed data sets, controlling the allocation to a volume by
specifying a specific VOLSER or esoteric name.
v Using the EATTR data set attribute keyword to specify that the data set supports
extended attributes (format 8 and 9) and can reside in the EAS of an EAV.
Non-EAS eligible data sets include:
v HFS data sets
v Page data sets
v VTOC and VTOC index data sets
v VSAM data sets with imbed or keyrange attributes that may have been inherited
from prior physical migrations or copies
Only VSAM data sets that are allocated with compatible Control Areas (CA), for
non-striped VSAM, and Minimum Allocation Units (MAU), for striped VSAM, can
reside or be extended in cylinder-managed space. A compatible CA or MAU size
are those that divide evenly into the multi-cylinder unit of value of
cylinder-managed space.
The following CA sizes and MAU are compatible because they divide evenly into
the multi-cylinder unit of 21 cylinders (315 tracks):
v 1, 3, 5, 7, 9, 15 Tracks
52
z/OS DFSMS Using Data Sets
Allocating Space on Direct Access Volume
The system ensures for all new allocations on all volume types that a compatible
CA or MAU is selected.
SMS storage groups with a mix of EAV and non-EAV volumes are supported.
When building the volume candidate list, SMS prefers the following settings:
v volumes based on the data set type
v the size of the space request
v the multicylinder unit size
v the user’s defined break point value
v the free space statistics from both managed spaces on the volume
Generally, for VSAM data set allocation requests that are equal to or larger than
the BPV, SMS prefers EAV volumes. For non-VSAM allocation requests and VSAM
allocation requests that are smaller than the BPV, EAV volumes are not preferred.
See z/OS DFSMSdfp Advanced Services for more information on the VTOC and
INDEX structures of an extended address volumes.
See z/OS DFSMS Using the New Functions for the information about how to set up
and use the EAV.
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 for
information about allocating space for system-managed data sets. See “Allocating
Space for a PDS” on page 433 and “Allocating Space for a PDSE” on page 464 for
information about PDS/PDSE space allocation.
Chapter 3. Allocating Space on Direct Access Volumes
53
54
z/OS DFSMS Using Data Sets
Chapter 4. Backing Up and Recovering Data Sets
This chapter covers the following topics.
Topic
“Using REPRO for Backup and Recovery” on page 56
“Using EXPORT and IMPORT for Backup and Recovery of VSAM Data Sets” on page 57
“Writing a Program for Backup and Recovery” on page 58
“Using Concurrent Copy for Backup and Recovery” on page 59
“Updating a Data Set After Recovery” on page 59
“Synchronizing Catalog and VSAM Data Set Information During Recovery” on page 59
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 DFSMSdfp Storage Administration.
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
requirements and processes of archiving, backing up, and recovering data sets
© Copyright IBM Corp. 1987, 2017
55
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
131.
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 233.
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.
56
z/OS 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.
You must connect all referenced catalogs to the system master catalog.
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.
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.
Chapter 4. Backing Up and Recovering Data Sets
57
Backing Up and Recovering Data Sets
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 233.
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
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 261.
58
z/OS DFSMS Using Data Sets
Backing Up and Recovering Data Sets
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 Administrationy.
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.
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.
Chapter 4. Backing Up and Recovering Data Sets
59
Backing Up and Recovering Data Sets
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.
Besides the VSAM VERIFY macro, you can 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 (without the RECOVER parameter) and the
verification by VSAM OPEN are the same. Neither changes the data in the verified
data set.
If VSAM or RLS processing such as CA reclaim has been interrupted (this may be
indicated by results for the EXAMINE command) you can use the IDCAMS
VERIFY command with the RECOVER parameter to back out or complete the
interrupted process, so that subsequent EXAMINE commands will generate cleaner
output. If you use the IDCAMS VERIFY RECOVER command after CA reclaim
processing has been interrupted, the IDCAMS VERIFY command may also:
v Change the index structure of the data set
v Cause subsequent CA splits to reuse reclaimed empty data CAs for different
records.
The IDCAMS VERIFY RECOVER command requires that the data set be not
opened anywhere else across systems; otherwise, it will fail with an OPEN error.
Although IBM recommends that you use IDCAMS VERIFY RECOVER after a
key-sequenced data set has been closed improperly, if you do not, the next VSAM
or RLS POINT, GET, PUT, or ERASE request that finds the CIs involved in the
interrupted process may back out or complete the process.
The catalog will be updated from the verified information (from VSAM VERIFY or
IDCAMS VERIFY) in the VSAM control blocks when the VSAM data set which
was opened for output is successfully closed. In addition to updating the control
blocks to be used by CLOSE, the IDCAMS VERIFY RECOVER command also
backs out or completes the interrupted VSAM or RLS processing to the data set.
The actual VSAM control-block fields that get updated with the IDCAMS VERIFY
command depend on the type of data set being verified. VSAM control block fields
60
z/OS DFSMS Using Data Sets
Backing Up and Recovering Data Sets
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 IDCAMS VERIFY command or the VSAM VERIFY macro 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 VSAM
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 IDCAMS VERIFY
command. You should issue the IDCAMS 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 214.
For information about the IDCAMS VERIFY command, see VERIFY in z/OS
DFSMS Access Method Services Commands.
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.
Chapter 4. Backing Up and Recovering Data Sets
61
Backing Up and Recovering Data Sets
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 149.
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.
62
z/OS 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
“Data Set Password Protection” on page 75
“User-Security-Verification Routine” on page 76
“Erasure of Residual Data” on page 76
“Authorized Program Facility and Access Method Services” on page 78
“Access Method Services Cryptographic Option” on page 79
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 75.
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.
If a user-security-verification routine (USVR) exists, it is not invoked for
RACF-defined 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. 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.
© Copyright IBM Corp. 1987, 2017
63
Protecting Data Sets
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.
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.
Explicitly bypassing RACF protection. If your program requires the ability to
bypass RACF security checking for a data set, code the BYPASS_AUTH=YES
option on the DCBE macro. This applies when opening a DCB for a DASD
sequential, direct, PDS, or PDSE data set for BSAM, QSAM, BDAM, or BPAM. The
system checks this DCBE option only during open before the open exit is entered
and it remains in effect until the completion of close. Using other mechanisms that
raise the privilege of the entire jobstep or job are not as secure and should be
avoided. Refer to the DCBE BYPASS_AUTH parameter for restrictions when using
this option.
|
|
|
|
|
|
|
|
|
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 a multi-volume data set to
RACF when the data set is created or extended to a new volume.
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.
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).
64
z/OS DFSMS Using Data Sets
Protecting Data Sets
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 STGADMIN.IFG.READVTOC.volser 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 STGADMIN.IFG.READVTOC.volser for
a volume on the VTOC, you can display only data sets for which you have specific
READ access.
Restrictions: The catalog search interface (CSI) treats fully qualified data set names
like generic names. Therefore, if you use the CSI to request a fully-qualified data
set name with name-hiding active, the data set name is hidden unless you have at
least READ access to the data set.
Name hiding will only work if one of the following is true:
v The data set is protected by a generic profile
v The user has created a MODEL profile in the DATASET class that matches the
dsname
v The user has created a discrete profile in the DATASET class that matches the
dsname and has a volser of MIGRAT (this requires using the NOSET option of
ADDSD).
For user tape data sets, name hiding will only work if one of the following is true:
v The TAPEVOL class is active with a TAPEVOL profile defined
Chapter 5. Protecting Data Sets
65
Protecting Data Sets
v SETR TAPEDSN is active with a DATASET profile (or SETR
PROTECTALL(FAIL));
Otherwise the data set has no protection. Anyone can read it, write it, or list it via
LISTCAT.
Neither the CVAF macro or DADSM OBTAIN macro provides the name-hiding
function to calling programs that are APF-authorized or running in supervisor
state or key zero when name-hiding is active. In the name-hiding environment,
these authorized programs can request name hiding by turning on the cv4nmhid
flag in the CVAF parameter list (CVPL) for CVAF requests or by turning on byte 2
bit 3 (mask X'10') in the OBTAIN parameter list for DADSM OBTAIN seek
requests.
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 Encryption
|
Introduction
|
|
|
|
|
|
|
|
|
|
With z/OS data set encryption, you can encrypt data without requiring application
changes. z/OS data set encryption, through SAF controls and RACF® or equivalent
function along with SMS policies, allows you to identify new data sets or groups
of data sets to be encrypted. You can specify encryption key labels to identify
encryption keys to be used to encrypt selected data sets. The specified key label
and encryption key must exist in the ICSF key repository (CKDS). With data set
encryption, you are able to protect data residing on disk from being viewed by
unauthorized users in the clear. Authorization is based on access to the key label
that is associated with the data set and used by the access methods to encrypt and
decrypt the data.
|
|
z/OS data set encryption provides the ability to encrypt the following types of
data sets:
|
|
|
v Sequential extended format data sets, accessed through BSAM and QSAM
v VSAM extended format data sets (KSDS, ESDS, RRDS, VRRDS, LDS), accessed
through base VSAM and VSAM RLS
|
|
Encrypted data sets must be SMS-managed extended format. They also can be
compressed format.
||
Importance of host based compression
|
|
|
|
|
|
It is recommended that clients using host based encryption also exploit host based
compression prior to the encryption of the data. If the data is not compressed prior to the
encryption there can be consequences to other parts of the client infrastructure. For
example, replicated data that is being compressed in the SAN infrastructure by DWDM
technology will no longer be effective trying to compress encrypted data. Without
compressing prior to the encryption of the data, additional bandwidth might be required.
|
|
|
|
|
Another example might be that tape systems can require additional capacity in terms of
disk space, in the case of virtual tape, or tape cartridges. If deduplication of data is
supported, host encryption can prevent deduplication from working. Therefore, where
possible, use compressed format data sets. With encrypted compressed format data sets,
the access methods perform compression before encryption.
|
See Considerations when planning for data set encryption for more information.
66
z/OS DFSMS Using Data Sets
Protecting Data Sets
|
|
|
|
|
|
|
|
To create an encrypted data set, a key label must be supplied on new data set
allocation. The key label must point to an AES-256 bit encryption DATA key within
the ICSF key repository (CKDS) to be used to encrypt or decrypt the data. For each
encrypted data set, its key label is stored in the catalog. The key label is not
sensitive information; it identifies the encryption key, which is sensitive; therefore,
IBM recommends only using secure keys. For more information, see z/OS
Cryptographic Services ICSF System Programmer's Guide.
|
Hardware requirements
|
|
|
Exploitation of this function requires IBM Enterprise z196 or later. It also requires
the following cryptographic hardware features:
v Crypto Express3 Coprocessor or later
|
v Feature 3863, CP Assist for Cryptographic Functions (CPACF)
|
Operating System requirements
|
|
|
v ICSF is installed and configured with a CKDS and AES master key loaded. See “
Considerations regarding ICSF startup and shutdown ” on page 73 for more
information.
|
Coexistence requirements
|
|
|
v On a z/OS V2R2 system with OA50569, you can create encrypted data sets as
well as access encrypted data sets created on a z/OS V2R2 (with OA50569) or
later system.
|
|
|
v On a z/OS V2R1 system with OA50569, you cannot create encrypted data sets.
However, you can access encrypted data sets created on a z/OS V2R2 (with
OA50569) or later system.
|
|
|
|
Note: The minimum software release that can support encrypted data sets is
z/OS V2R1 with OA50569. An attempt to access an encrypted data set on a
lower release will result in loss of access to the data. Ensure that all systems are
at the minimum hardware and software levels before encrypting any data sets.
|
Before enabling this function
|
|
|
|
|
|
|
|
|
|
Because data set encryption has both hardware and software requirements, you
must consider all systems that share data with a system on which you plan to
enable data set encryption before creating an encrypted data set. This includes
backout software levels, backup systems, read-only systems, replication target
systems and disaster recovery systems. Before encrypting data sets other than
those used for testing, be sure that all the systems that must access encrypted data
sets are capable of doing so by meeting the required hardware and software
requirements. In addition to the hardware and software requirements that must be
available on every system that will access the encrypted data sets, all key labels
and encryption keys associated with the encrypted data sets must also be available.
|
|
Take these steps to make data set encryption unavailable to users who are not
explicitly authorized to use it:
|
|
|
v Define the STGADMIN.SMS.ALLOW.DATASET.ENCRYPT profile in the
FACILITY class, and set the universal access to NONE:
RDEFINE FACILITY STGADMIN.SMS.ALLOW.DATASET.ENCRYPT UACC(NONE)
Chapter 5. Protecting Data Sets
67
Protecting Data Sets
|
|
|
|
|
|
v If the FIELD class is active, check for any profile that would allow any user
without SPECIAL attribute access to the DATASET.DFP.DATAKEY. If there are
none, no additional action is needed. If there is any profile that would allow
access to DATASET.DFP.DATAKEY, create a DATASET.DFP.DATAKEY profile in
the FIELD class with a UACC of NONE:
|
|
|
|
Taking the steps above is intended to assure that only authorized users are allowed
to use data set encryption. Such users should be made aware that until the
decryption functions are available on all sharing systems, backup systems, and
disaster recovery systems, access to encrypted data can be lost at any time.
|
Deploying data set encryption
|
The following tasks are necessary to begin using data set encryption.
|
Create key labels and encryption keys
|
|
|
|
|
To create an encrypted data set, a key label must be assigned to the data set. The
key label and its associated AES-256 bit encryption key must exist in the CKDS by
the time the data set is opened. To create keys in the CKDS, refer to z/OS
Cryptographic Services ICSF System Programmer's Guide. IBM recommends the use of
secure keys.
|
Set up CSFKEYS
|
|
To control which users can use which keys, protect resources CSFKEYS class. The
CSFKEYS class controls access to cryptographic keys identified by the key label.
|
To enable the use of ICSF keys:
|
|
|
|
1. Grant the user READ authority to the resource key-label in the CSFKEYS class.
This authority can be granted for all uses of the key-label or only when the use
of the key-label is permitted when using the a CRITERIA value of
DSENCRYPTION for SMS.
RDEFINE FIELD DATASET.DFP.DATAKEY UACC(NONE)
|
|
|
|
|
|
|
|
- if the class has not already been enabled for generics
|
|
|
|
|
|
|
|
|
or
SETROPTS GENERIC(CSFKEYS)
- Define profiles in the CSFKEYS class to protect key labels
RDEFINE
CSFKEYS profile-name UACC(NONE)
ICSF(SYMCPACFWRAP(YES) SYMCPACFRET(YES))
- Give the users (preferably groups) access to the profiles
PERMIT profile-name CLASS(CSFKEYS)
ID(name)
ACCESS(READ)
PERMIT profile-name CLASS(CSFKEYS)
ID(name)
ACCESS(READ)
WHEN(CRITERIA(SMS(DSENCRYPTION)))
2. Define the ICSF information for the key with SYMCPACFWRAP(YES) and
SYMCPACFRET(YES), if it was not specified on the DEFINE
RALTER CSFKEYS profile-name
ICSF(SYMCPACFWRAP(YES)
SYMCPACFRET(YES))
3. Set RACF options
- if the CSFKEYS class is not already active
|
|
SETROPTS CLASSACT(CSFKEYS)
68
z/OS DFSMS Using Data Sets
Protecting Data Sets
|
|
|
|
- if the CSFKEYS class has not already been RACLISTed
SETROPTS RACLIST(CSFKEYS)
- or if the CSFKEYS class has already been RACLISTed
SETROPTS RACLIST(CSFKEYS) REFRESH
|
Set up CSFSERV
|
|
Important: The following setup is required only if CHECKAUTH(YES) is specified
on the ICSF installation options data set. CHECKAUTH(NO) is the default.
|
|
|
Protect the resources CSFSERV class. ICSF controls access to cryptographic services
through the CSFSERV resource class. For more information, see z/OS Cryptographic
Services ICSF Administrator's Guide .
|
|
The following table summarizes the CSFSERV resource required for processing
encrypted data sets.
|
Table 6. CSFSERV resource required for data set encryption
|
Function
ICSF callable service
Resource
|
|
|
|
|
|
CKDS Key Record Read2
CSNBKRR2
CSFKRR2
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If the user does not have sufficient access, open processing will fail. An
informational message ICH408I (which indicates insufficient authorization) might
be issued.
1. Grant the user READ authority to the resource CSFSERV class:
- if the class has not already been enabled for generics
SETROPTS GENERIC(CSFSERV)
- Define profiles in the CSFSERV class to protect key labels
RDEFINE CSFSERV * UACC(NONE)
- Define profile CSFKRR2 if it does not exist
RDEFINE CSFSERV CSFKRR2 UACC(NONE)
- Give the users (preferably groups) access
PERMIT CSFKRR2 CLASS(CSFSERV) ID(groupid) ACCESS(READ)
2. Set RACF options:
- if the CSFSERV class is not already active
SETROPTS CLASSACT(CSFSERV)
- if the CSFSERV class has not already been RACLISTed
SETROPTS RACLIST(CSFSERV)
- or if the CSFSERV class has already been RACLISTed
SETROPTS RACLIST(CSFSERV) REFRESH
|
Create an encrypted data set
|
|
|
To create an encrypted data set, you must assign a key label to the data set when it
is newly allocated (data set create). A key label can be specified through any of the
following methods:
|
v RACF data set profile
|
v JCL, dynamic allocation, TSO ALLOCATE, IDCAMS DEFINE
|
v SMS data class
Chapter 5. Protecting Data Sets
69
Protecting Data Sets
|
|
|
|
|
To specify a key label using the DFP segment in the RACF data set profile, use
keyword DATAKEY(Key-Label). The system will use this key label for extended
format data sets that are created after DATAKEY is added to the data set profile.
Use keyword NODATAKEY to remove a key label, if defined, from the RACF DFP
segment. The key label is ignored for a data set that is not a DASD data set.
|
|
|
|
To specify a key label using JCL, dynamic allocation, and TSO allocate, use JCL
keyword DSKEYLBL='key-label', dynamic allocation text unit DALDKYL, or TSO
allocate DSKEYLBL(label-name). DSKEYLBL is effective only if the new data set is
on DASD. The key label is ignored for a data set that is not a DASD data set.
|
|
See details about the DSKEYLBL(key-label) keyword on the JCL DD statement in
z/OS MVS JCL Reference.
|
|
|
|
To specify a key label using SMS data class, use the Data Set Key Label field on the
ISMF DEFINE/ALTER panel. The system will use this key label for extended
format data sets that are created after the data set key label is added to the data
class. The key label is ignored for a data set that is not a DASD data set.
|
|
See details on using the new Data Set Key Label field in the ISMF panels in z/OS
DFSMS Using the Interactive Storage Management Facility.
|
|
|
|
|
To specify a key label using the IDCAMS DEFINE command for a VSAM
CLUSTER, use the KEYLABEL parameter; for example, KEYLABEL(MYLABEL).
Any alternate index associated with the CLUSTER will also be encrypted and use
the same key label as specified for the CLUSTER. The key label is ignored for a
data set that is not a DASD data set.
|
|
For more information on using IDCAMS DEFINE command for a VSAM
CLUSTER, see z/OS DFSMS Access Method Services Commands.
|
|
|
When a key label is specified on more than one source, the key label is derived
from one of the above sources only on the initial data set allocation (on data set
create). The key label is derived in the following order of precedence:
|
1. From RACF DFP segment DATASET profile.
|
|
2. Explicitly specified on the DD statement, dynamic allocation text unit, TSO
ALLOCATE command, or IDCAMS DEFINE control statement.
|
3. From the data class that applies to the current DD statement.
Note: The REFDD and LIKE JCL DD statement keywords do not cause a key
label from the data set referred to be used when allocating a new data set.
|
|
|
|
|
On successful allocation of an encrypted data set, the following message is issued:
|
Specifying a key label for a non-extended format data set
|
|
|
|
|
|
|
If an encryption key label is specified for a DASD data set that is not extended
format, the key label is ignored and the data set is successfully created as
non-encrypted non-extended format data set. In addition, SMS message IGD17156I
is issued (or if using IDCAMS DEFINE and data set is non-SMS managed, message
IDC3040I is issued) indicating that the key label is ignored. Instead to have the
system fail the allocation, the user must have at least READ authority to the
resource in the FACILITY class: STGADMIN.SMS. FAIL.INVALID.DSNTYPE.ENC
IGD17150I DATA SET dsname IS ELIGIBLE FOR ACCESS METHOD ENCRYPTION
KEY LABEL IS (key_label)
70
z/OS DFSMS Using Data Sets
Protecting Data Sets
|
|
|
If this facility class resource exists and the user has at least read authority, SMS
will fail the allocation and issue message IGD17151I (or if using IDCAMS DEFINE
and non-SMS managed data set request, message IDC3039I is issued).
|
Enable data set encryption
|
|
|
An enablement action is required to allow the creation of encrypted data sets when
the key label is specified through a method outside of the DFP segment in the
RACF data set profile.
|
|
|
|
To allow the system to create encrypted data sets using a key label specified
through a method other than through the DFP segment in the RACF data set
profile, the user must have at least READ authority to the following resource in the
FACILITY class:
|
|
|
STGADMIN.SMS.ALLOW.DATASET.ENCRYPT
|
Note: IBM recommends that you define STGADMIN.* with UACC(NONE).
|
|
|
The system checks the user's authority to access this resource when a data set to be
encrypted is first allocated (that is, created). It is not checked again before
encrypting a data set.
|
Allocation processing
|
|
|
|
|
SMS allocation processing determines if a data set can be allocated as an encrypted
data set. Under certain conditions, you can specify how the allocation should
proceed. The following tables summarize the system behavior during SMS
allocation processing for a new data set based on specific FACILITY class resources
and the user's authorization to the resource.
|
|
|
|
|
On a z/OS V2R2 system (with OA50569) and later, the following table describes
the result of an allocation request for an extended format data set when a key label
has been specified. On a successful allocation, the resulting data set will be an
encrypted extended format data set. Other factors not described in this table (such
as lack of space) might cause the allocation to fail.
|
|
Table 7. SMS Allocation Processing Based on System Levels and Allocation Request (z/OS
V2R2 with OA50569)
|
|
|
FACILITY class
resource
|
Access
|
|
|
Allocation type
|
|
|
Key label from Allocation
DFP segment of continues with
RACF DS profile IGD17150I
Allocation
continues with
IGD17150I
Allocation
continues with
IGD17150I
Allocation
continues with
IGD17150I
|
|
|
|
|
|
Key label from a Allocation fails
source other
with IGD17155I
than DFP
segment of
RACF DS profile
Allocation fails
with IDC3038I
Allocation
continues with
IGD17150I
Allocation
continues with
IGD17150I
STGADMIN.SMS.ALLOW.DATASET.ENCRYPT
Not defined OR not authorized
JCL
IDCAMS
DEFINE
At least authorized for READ
JCL
IDCAMS
DEFINE
Chapter 5. Protecting Data Sets
71
Protecting Data Sets
|
|
|
|
|
|
On a z/OS V2R2 system (with OA50569) and above, the following table describes
the result of an allocation request for a DASD non-extended format data set when
a key label has been specified from any source. On a successful allocation, the
resulting data set will be a non-encrypted non-extended format data set. Other
factors not described in this table (such as lack of space) might cause the allocation
to fail.
|
|
Table 8. SMS Allocation Processing Based on System Levels and Allocation Request (z/OS
V2R2 with OA50569)
|
|
|
FACILITY class
resource
|
Access
|
|
|
Allocation type
|
|
|
SMS mgd
Allocation
continues with
IGD17156I
Allocation
continues with
IGD17156I
Allocation fails
with IGD17151I
Allocation fails
with IGD17151I
non-SMS mgd
Allocation fails
with IGD17156I
Allocation fails
with IDC3040I
Allocation fails
with IGD17151I
Allocation fails
with IDC3039I
|
|
|
|
STGADMIN.SMS. FAIL.INVALID.DSNTYPE.ENC
Not defined OR not authorized
At least authorized for READ
IDCAMS
DEFINE
JCL
JCL
IDCAMS
DEFINE
|
|
|
|
|
|
On a z/OS V2R1 system (with OA50569), the following table describes the result of
an allocation request for a DASD data set (extended format and non-extended
format) when a key label has been specified from any source. On a successful
allocation, the resulting data set will be a non-encrypted data set since you cannot
create new encrypted data sets on a z/OS V2R1 system. Other factors not
described in this table (such as lack of space) might cause the allocation to fail.
|
|
Table 9. SMS Allocation Processing Based on System Levels and Allocation Request (z/OS
V2R1 with OA50569)
|
|
|
FACILITY class
resource
|
Access
|
|
|
Allocation type
|
|
|
Key label
Job fails with
specified on JCL IEFC630I
(DSKEYLBL)
|
|
|
|
|
Key label
specified on
IDCAMS
DEFINE
(KEYLABEL)
|
|
|
|
|
STGADMIN.SMS. FAIL.INVALID.DSNTYPE.ENC
Not defined OR not authorized
JCL
N/A
At least authorized for READ
IDCAMS
DEFINE
JCL
IDCAMS
DEFINE
N/A
Job fails with
IEFC630I
N/A
Allocation fails
with IDC3211I
N/A
Allocation fails
with IDC3211I
Key label from Refer to the following two rows
DFP segment of
RACF DS profile
or from data
class)
|
|
|
SMS mgd
Allocation
continues with
IGD17156I
Allocation
continues with
IDC3040I
Allocation fails
with IGD17154I
Allocation fails
with IDC0017I
|
|
|
non-SMS mgd
Allocation
continues with
IGD17156I
Allocation
continues with
IDC3040I
Allocation fails
with IGD17154I
Allocation fails
with IDC0017I
72
z/OS DFSMS Using Data Sets
Protecting Data Sets
|
|
Accessing encrypted data sets
|
|
|
|
|
|
|
Applications that use standard BSAM, QSAM, and VSAM APIs do not require
changes to access encrypted data sets. The user data transferred between the
application and the access methods is in the unencrypted form. The access method
encrypts the data when writing to DASD and decrypts the data when reading from
DASD. For encrypted compressed format data sets, the access method compresses
the data before encrypting it on output. On input, the access method decrypts the
data before decompressing it.
|
Considerations regarding ICSF startup and shutdown
|
|
|
|
|
|
If you plan to encrypt SMF data sets or other data sets used during z/OS
initialization, you must ensure that ICSF is started early in the IPL process to avoid
delays in z/OS initialization and termination. As such, it is highly recommended
the command S CSF,SUB=MSTR is placed early in the COMMNDxx member to
ensure that there is minimum delay in z/OS initialization. Specifying SUB=MSTR
is necessary to allow ICSF to start before JES.
|
|
|
|
|
|
Furthermore, during z/OS system shutdown, ICSF must be one of the last features
to stop so that dependent functions are not impacted. It is highly recommended
that you shut down ICSF after terminating the JES address space and after
initiating SMF halt processing. Note when ICSF is stopped after SMF is halted, that
there might not be an SMF record cut for the termination of ICSF. (The ability to
start ICSF with SUB=MSTR is available on all supported releases of ICSF.)
|
Considerations regarding backup/migration/replication functions
|
Key label authorization
|
|
|
The following system functions maintain data in the encrypted form. Therefore,
users performing these functions do not require authorization to the key label
associated with the data sets being processed with these functions:
|
v DFSMSdss functions: COPY, DUMP, and RESTORE
|
|
v DFSMShsm functions: migrate/recall, backup/recover, abackup/arecover,
dump/data set restore, FRBACKUP/FRRECOV DSNAME
|
v Track based copy (PPRC, XRC, FlashCopy®, concurrent copy) operations
|
Other considerations
|
|
v DFSMSdss REBLOCK keyword is ignored on COPY and RESTORE functions for
encrypted data sets.
|
|
v DFSMSdss ADRREBLK installation exit will not be called for encrypted data
sets.
|
|
v DFSMSdss does not support VALIDATE processing when backing up encrypted
indexed VSAM data sets. VALIDATE will be ignored.
|
|
|
|
v Backup and migration of encrypted data sets may impact expected savings with
disk or tape device compression. Where possible, convert to compressed format
data sets. When data set level compression requested, access methods handle
compression before encryption for compressed format encrypted data sets.
Chapter 5. Protecting Data Sets
73
Protecting Data Sets
|
|
|
|
|
|
|
|
|
|
Considerations when planning for data set encryption
|
|
|
|
|
|
|
|
|
|
v Encrypted data do not compress. Therefore, encrypted extended format data sets
might not benefit from storage savings when relying on disk and tape device
compression, as well as other areas in the infrastructure that attempt to
compress data. Where possible, consider using compressed format data sets.
When data set level compression is requested along with encryption, access
methods handle compression before encryption for encrypted compressed format
data sets. Refer to Compressed Data for VSAM data sets and Allocating
Compressed-Format Data Sets for sequential data setsin z/OS DFSMS Using Data
Sets for information on allocating compressed format data sets, including
guidelines and restrictions.
|
|
|
|
v When processing encrypted extended format data sets, the access methods may
use additional internal system buffers during read and write processing. For
optimal performance, consider increasing memory to your partition as your use
of encrypted data sets increases.
|
Restrictions for encrypted data sets
|
|
|
v System data sets (such as Catalogs, SMS control data sets, SHCDS, HSM data
sets) must not be encrypted, unless otherwise specified in product
documentation.
|
v Data sets used during IPL must not be encrypted.
|
v Encrypted data sets only supported on 3390 device types.
|
|
v Sequential (non-compressed) data sets with a BLKSIZE of less than 16 bytes
cannot be extended format.
|
|
For potential restrictions associated with other products, consult the corresponding
product documentation.
|
See the following publications for more details on data set encryption support:
|
References:
|
Data Set Encryption for IBM® z/OS® V2.2 Frequently Asked Questions
|
z/OS DFSMS Access Method Services Commands
|
z/OS DFSMSdfp Storage Administration
|
z/OS DFSMSdss Storage Administration
|
z/OS DFSMShsm Storage Administration
|
z/OS Cryptographic Services ICSF Administrator's Guide
|
z/OS Cryptographic Services ICSF System Programmer's Guide
v Encrypted data sets must be extended format. Refer to Extended-Format VSAM
Data Sets and Processing Extended-Format Sequential Data Sets in z/OS DFSMS
Using Data Sets for information on allocating extended format data sets,
including guidelines and restrictions.
v Sequential extended format data sets can be version 1 or 2. When allocating an
encrypted sequential extended format data set, the system creates the data set as
an extended format version 2 data set, regardless of the user's specification for
version number on DSNTYPE or the PS_EXT_VERSION keyword in the
IGDSMSxx member in PARMLIB.
74
z/OS DFSMS Using Data Sets
Protecting Data Sets
|
Data Set Password Protection
You can define data set passwords for non-VSAM data sets, but not for VSAM
data sets. Passwords are ignored for all system-managed data sets, new and
existing. However, passwords can still be defined for system-managed 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.
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.
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
Chapter 5. Protecting Data Sets
75
Protecting Data Sets
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
VSAM lets you protect data by specifying a program that verifies a user's
authorization. “User-Security-Verification Routine” on page 276 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.
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
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 (ICKDSF) 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.
76
z/OS DFSMS Using Data Sets
Protecting Data Sets
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
Prior to z/OS V2R1, EOS issued one channel program to erase one track. This
process repeated until all tracks are erased. If the data set is large, this process
could cause a large number of I/O requests. Starting in V2R1, the system can erase
up to 255 tracks in a single channel program.
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.
Chapter 5. Protecting Data Sets
77
Protecting Data Sets
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 SYS1.LINKLIB, 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.
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
78
z/OS DFSMS Using Data Sets
Protecting Data Sets
VERIFY—When a catalog is to be verified
If the preceding 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.
Access Method Services Cryptographic Option
Although you can provide security for online data by using such facilities as
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.
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. For ICSF, you must have
cryptographic hardware activated in order to use the REPRO ENCIPHER and
REPRO DECIPHER commands. The data remains protected until you use the
REPRO DECIPHER option to decipher it with the correct key.
Related reading: For information on using the REPRO command to encrypt and
decrypt data, see z/OS DFSMS Access Method Services Commands. 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
Chapter 5. Protecting Data Sets
79
Protecting Data Sets
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.
Figure 2 is a graphic representation of the input and output data sets involved in
REPRO ENCIPHER and DECIPHER operations.
Input
Encipher
Source Data Set
(Plaintext)
Any data set
REPRO can copy
into (except
catalogs):
Output
Target Data Set
(Ciphertext)
REPRO
Encipher
VSAM ESDS,
LDS or SAM
Input
Decipher
Target Data Set
(Plaintext)
Source Data Set
(Ciphertext)
VSAM ESDS,
LDS or SAM
Output
REPRO
Decipher
VSAM
ESDS
KSDS
LDS
RRDS
SAM
VSAM
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
80
z/OS DFSMS Using Data Sets
Protecting Data Sets
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.
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
Chapter 5. Protecting Data Sets
81
Protecting Data Sets
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:
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.
82
z/OS DFSMS Using Data Sets
Part 2. VSAM Access to Data Sets and UNIX Files
This topic provides the information of the processing of VSAM data sets.
© Copyright IBM Corp. 1987, 2017
83
84
z/OS DFSMS Using Data Sets
Chapter 6. Organizing VSAM Data Sets
This topic covers the following subtopics.
Topic
“VSAM Data Formats”
“VSAM Data Striping” on page 101
“Selection of VSAM Data Set Types” on page 90
“Extended-Format VSAM Data Sets” on page 100
“Access to Records in a VSAM Data Set” on page 107
“Access to Records through Alternate Indexes” on page 110
“Data Compression” on page 114
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
I/O path
CI
R1
R2
Work
area
R2
R3
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, 2017
85
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 constraint 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 122.
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 169.
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 contains control information consisting of two types of fields: one control
interval definition field (CIDF), and one or more record definition fields (RDFs).
Figure 4. Control interval format
86
z/OS DFSMS Using Data Sets
Organizing VSAM Data Sets
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. Table 10 shows RDFs for records
of the same and different lengths:
Table 10. Record definition fields of control intervals
Record definition fields of control intervals
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
2
Record length 160
160
160
22
3
RDF
3
CIDF
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
130
70
110
140
46
RDF
4
3
RDF
3
RDF
2
RDF
1
CIDF
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
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.
Chapter 6. Organizing VSAM Data Sets
87
Organizing VSAM Data Sets
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
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 106.
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. The system ensures for all new
allocations on all volume types that an extended address volume compatible CA of
1, 3, 5, 7, 9, or 15 tracks are selected. For information about defining an alternate
index, see “Defining Alternate Indexes” on page 133. For information about
optimizing control area size, see “Optimizing Control Area Size” on page 173.
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 5 on page 89, each control interval is 10 240 bytes long.
88
z/OS DFSMS Using Data Sets
Organizing VSAM Data Sets
CI1
R
Free space
CI length
CI2
Control
info
R
CI3
Control
info
FS
R
Free space
Control
info
10240 bytes
Figure 5. Data set with nonspanned records
In Figure 5 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.
Figure 6 contains a data set with the same space requirements as in Figure 5, but
one that permits spanned records.
CI1
R
FS
CI length
Control
info
CI2
R seg 1
CI3
Control
info
R seg 2
CI4
Control
info
R
seg
3
FS
CI5
Control
info
R
FS
Control
info
4096 bytes
Figure 6. 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 6, 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 A spanned record cannot be longer than 255 data control intervals. Each control
interval is called a segment of the spanned record.
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.
Chapter 6. Organizing VSAM Data Sets
89
Organizing VSAM Data Sets
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?
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.
90
z/OS DFSMS Using Data Sets
Organizing VSAM Data Sets
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 7 shows,
records are sequenced by the order of their entry in the data set, rather than by a
key field in the logical record.
R5
R4
R1
R2
R3
Figure 7. 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 85.
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 133. Figure 8 shows the
record lengths and corresponding RBAs for the data set shown in Figure 7.
RBA
Record Length
X'00'
X'62'
X'9A'
X'D6'
X'11C'
R1
R2
R3
R4
R5
98
56
60
70
70
X'162'
Figure 8. Example of RBAs of an entry-sequenced data set
Table 11 lists the operations and types of access for processing entry-sequenced
data sets.
Table 11. 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
records
No
Chapter 6. Organizing VSAM Data Sets
91
Organizing VSAM Data Sets
Table 11. Entry-sequenced data set processing (continued)
Operation
Sequential Access
Direct Access
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
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 21.
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 509 and z/OS DFSMS Macro
Instructions for Data Sets.
Record Processing for UNIX Files
Record boundaries are not maintained within binary files, but the access method
maintains record boundaries when FILEDATA=TEXT or FILEDATA=RECORD is in
effect. 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 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).
When a file is accessed as record-oriented (with FILEDATA=RECORD), your
program does not see the record prefixes. The PUT macro adds a prefix to each
record in the same format as with BSAM or QSAM. A GET macro removes the
prefix. Each record prefix is mapped by the IGGRPFX macro. It is the following
four bytes:
Offset
Length
0
1
1
3
Symbol
RPFX00
RPFXLLL
Description
Reserved.
Length of record that follows this prefix.
If any record in the file consists of zero bytes (that is, the length field in the record
prefix contains zero) or if any record is longer than the length of the buffer, it
results in an error return code for GET.
92
z/OS DFSMS Using Data Sets
Organizing VSAM Data Sets
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. You can avoid this restriction by using
FILEDATA=RECORD. The access method will add metadata in the file to define
record boundaries.
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.
Chapter 6. Organizing VSAM Data Sets
93
Organizing VSAM Data Sets
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 9 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
Part number
654
Invoice number
1598
Unit price
100
Quantity
The key must be:
Unique
In the same position in each record
In the first segment of a spanned record
Figure 9. 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
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 10.
Key Field
654
198
389
771
Figure 10. Inserting records into a key-sequenced data set
Table 12 lists the operations and types of access for processing key-sequenced data
sets.
Table 12. Key-sequenced data set processing
94
Operation
Sequential Access
Direct or Skip-Sequential
Access
Loading the data set
Yes
No
Adding records
Yes (records must be written
in key sequence)
Yes (records are added
randomly by key)
Retrieving records
Yes (records are returned in
key sequence)
Yes (by key)
Updating records
Yes
Yes
Deleting records
Yes
Yes
z/OS DFSMS Using Data Sets
Organizing VSAM Data Sets
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 174.
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
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.
The last empty control interval within the control area is not CI reclaimed. 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.When CA reclaim is
not enabled, a KSDS may have many empty control areas and may 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. 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. If the
record keys are always getting higher, no new records will qualify for insertion
into those empty control areas. The result is a data set in which a majority of the
space is occupied by empty control intervals.
One option a user has to reclaim this space is to reorganize 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. However, such data set reorganization is
time consuming. To minimize the need for reorganizing data sets, use the CA
reclaim function. With CA reclaim, empty CA space is reclaimed automatically and
CA split processing uses control areas that have been reclaimed instead of using
space at the end of the data and index. For more information, refer to “Reclaiming
CA Space for a KSDS” on page 177.
Chapter 6. Organizing VSAM Data Sets
95
Organizing VSAM Data Sets
Insertion of a Logical Record in a CI
Figure 11 shows how CI free space is used to insert and delete a logical record in a
KSDS or variable-length RRDS.
Figure 11. Inserting a Logical Record into a CI
Two logical records are stored in the first control interval shown in Figure 11. 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.
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.
96
z/OS DFSMS Using Data Sets
Organizing VSAM Data Sets
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.
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 12 on page 98 shows the structure of a fixed-length RRDS after
adding a few records. Each slot has a relative record number and an RDF. Table 13
on page 98 shows the access options available for RRDS processing.
Chapter 6. Organizing VSAM Data Sets
97
Organizing VSAM Data Sets
Figure 12. Fixed-length relative-record data set
Table 13 lists the operations and types of access for processing fixed-length RRDSs.
Table 13. RRDS processing
Operation
Sequential Access
Direct or Skip- Sequential
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)
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
98
z/OS DFSMS Using Data Sets
Organizing VSAM Data Sets
aside as free space when the data set is initially loaded. “Insertion of a Logical
Record in a CI” on page 96 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 14 shows the operations available for
key-sequenced data sets and direct or skip-sequential access.
Table 14. Variable-length RRDS processing
Direct or Skip- Sequential
Access
Operation
Sequential Access
Loading the data set
Yes, in ascending relative
record number order
No
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 15 summarizes what each data set format offers.
Table 15. Comparison of ESDS, KSDS, fixed-length RRDS, variable-length RRDS, and linear data sets
Variable-Length
RRDS
ESDS
KSDS
Fixed-Length RRDS
Linear Data Sets
Records are in order
as they are entered
Records are in
collating sequence by
key field
Records are in relative Records are in relative No processing at
record number order record number order record level
Direct access by RBA
Direct access by key
or by RBA
Direct access by
relative record
number
Direct access by
relative record
number
Access with
data-in-virtual (DIV)
Alternate indexes
permitted1
Alternate indexes
permitted
No alternate indexes
permitted
No alternate indexes
permitted
No alternate indexes
permitted
A record's RBA
cannot change
A record's RBA can
change
A record's relative
A record's relative
No processing at
record number cannot record number cannot record level
change
change
Space at the end of
the data set is used
for adding records
Free space is used for Empty slots in the
inserting and
data set are used for
lengthening records
adding records
Free space is used for No processing at
inserting and
record level
lengthening records
A record cannot be
deleted, but you can
reuse its space for a
record of the same
length1
Space given up by a
deleted or shortened
record becomes free
space
A slot given up by a
deleted record can be
reused
Space given up by a
deleted or shortened
record becomes free
space
No processing at
record level
Spanned records
permitted
Spanned records
permitted
No spanned records
No spanned records
No spanned records
Extended format
permitted1
Extended format or
compression
permitted
Extended format
permitted
Extended format
permitted
Extended format
permitted
Chapter 6. Organizing VSAM Data Sets
99
Organizing VSAM Data Sets
Table 15. Comparison of ESDS, KSDS, fixed-length RRDS, variable-length RRDS, and linear data sets (continued)
ESDS
KSDS
Fixed-Length RRDS
Variable-Length
RRDS
Linear Data Sets
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.
v Data set encryption. Encryption protects sensitive data in the data set.
|
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.
Certain types of key-sequenced data set types are excluded. The following data
sets cannot have an extended format:
v Other system data sets
v Temporary data sets
Note: The maximum number of paging slots for each page space is 16M. Page
spaces regardless of their size have the extended format and extended addressable
attributes assigned to them whether they are on an SMS managed volume or a
non-SMS managed volume.
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 13 on page 101 shows the percentage
increase in space as indicated. Other control intervals do not result in an increase
in needed space.
100
z/OS DFSMS Using Data Sets
Organizing VSAM Data Sets
- 3390 Direct Access Device
Control Interval Size
512
1536
18432
Additional Space Required
2.1%
4.5%
12.5%
- 3380 Direct Access Device
Control Interval Size
512
1024
Additional Space Required
2.2%
3.2%
Figure 13. 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.
Note: The maximum number of paging slots for each page space is 16M. Page
spaces regardless of their size have the extended format and extended
addressable attributes assigned to them whether they are on an SMS managed
volume or a non-SMS managed volume.
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)
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.
Chapter 6. Organizing VSAM Data Sets
101
Organizing VSAM Data Sets
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 14 illustrates primary and secondary space allocations on multiple volumes
for a striped VSAM data set.
Layer 1:
VOLA - single primary allocation
Stripe 1
Stripe 2
Stripe 3
VOLA
VOLB
VOLC
VOLB - single primary allocation
VOLC - single primary allocation
Layer 2:
VOLD
VOLA - single secondary allocation
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 14. Primary and Secondary Space Allocations for Striped Data Sets
Figure 15 on page 103 shows examples of the CIs within a control area (CA) on
multiple volumes for a four-stripe VSAM data set.
102
z/OS DFSMS Using Data Sets
Organizing VSAM Data Sets
Figure 15. 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 multi-layering. VSAM supports multi-layering. Figure 16 on
page 104 shows an example of the concept of layering with a four-stripe data set.
Chapter 6. Organizing VSAM Data Sets
103
Organizing VSAM Data Sets
Figure 16. 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 the primary amount is not divided
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. The
system might have to perform additional rounding of space for each stripe if one
or more extended address volumes have been selected. This situation might
happen when cylinder-managed space has been selected which might cause the
requested space amount of that stripe to be rounded to the next multi-cylinder
unit. The remaining stripes space amount is adjusted to match to ensure all stripes
contain the same amount of space. This only occurs after attempts by the system to
allocate the exact amount for each stripe does not succeed.
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 topic 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.
104
z/OS DFSMS Using Data Sets
Organizing VSAM Data Sets
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 (if there is one), using the primary-space amount. For
striped VSAM data sets, extensions occur by stripe, so if there is a secondary
quantity of zero, the primary space value is used for the extensions across all
stripes until space is exhausted on the primary and new volumes, or until the
maximum extents for the data set is reached.
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 must be enforced if the data set
might 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. Though the
maximum CA size for a non-striped VSAM is a cylinder, such is not necessarily the
case for a striped data set. Traditionally that would have meant that the maximum
CA size, based on 3390 geometry, would be 15 tracks. That changes with striped
VSAM data sets in that the maximum CA size now has to accommodate the
maximum stripe count (16), and so the maximum CA now becomes 16 tracks.
Further complicating the issue is the fact that CA sizes must now be compatible
with extended addressable volumes. Consequently, the CA size divided by the
stripe count must be divisible into the multi-cylinder unit of 21 cylinders (315
tracks) -- 1, 3, 5, 7, 9 or 15 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 area size of one track with a
resulting primary and secondary allocation quantity of 1 track.
v For a striped data set which is also non-spanned, with a striped count maximum
of 16, the control area size is then 16 tracks with a resulting primary and
secondary quantity of 16 tracks.
For another example, take the specification of TRACKS(16 4): for non-striped,
traditional VSAM, a control area size of 16 tracks is not allowed, so the allocation
of primary and secondary are adjusted upward to 20 tracks with a secondary of 5,
Chapter 6. Organizing VSAM Data Sets
105
Organizing VSAM Data Sets
and a CA size of 5 tracks per CA -- the CA size being compatible with
multi-cylinder units. For a striped data set which is also non-spanned, with a stripe
count of 3, the CA size is dictated by the smaller of the primary and secondary
allocation. The system would arrive at a CA size of 4 in this instance. However
that CA size is not divisible by the number of stripes, so it is adjusted upwards to
6 tracks per CA. Because there are 3 stripes, the allocation amount per volume is 2
tracks. But since 2 tracks is not compatible with extended addressable volumes, it
must be adjusted downward. The net result is a CA size of 3 tracks . The primary
allocation must be a multiple of the CA size, so it is adjusted up to 18, and the
secondary allocation also must be adjusted to a multiple of the CA size. The
primary allocation would be 18 tracks, and the secondary allocation would be
increased to 6 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.
The calculations are different for a striped data set that allows spanned records.
The CA size for such a data set does not have to be evenly divisible into the multi
cylinder unit of 21 cylinders (315 tracks). Because of this, a striped data set that
allows spanned records is always allocated in the track managed space of each
volume at define time. However, if such a data set does have a computed CA size
that is EAV compatible (1, 3, 5, 7, 9 or 15 tracks), then it can extend into the
cylinder managed portion of EAV volumes.
In case of a three-striped dataset with is spanned, the CA size would be first
dictated by the smaller of the primary and secondary allocation. We would arrive
at a CA size of 4 in this instance. However, that CA size is not divisible by the
number of stripes, so it is adjusted upwards to 6 tracks per CA. Because there are 3
stripes, the allocation amount per volume is 2 tracks. Even though 2 is not
compatible with extended addressable volumes, for striped data sets with spanned
records, we do not adjust it downward. The CA size remains at 6. The primary
allocation must be a multiple of the CA size, so it is adjusted to 18, and the
secondary allocation would be increased to 6 tracks. This data set is allocated in
the track managed space of the volume at define time.
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 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
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).
106
z/OS DFSMS Using Data Sets
Organizing VSAM Data Sets
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
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 195.
Chapter 6. Organizing VSAM Data Sets
107
Organizing VSAM Data Sets
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 91.
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
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.
108
z/OS DFSMS Using Data Sets
Organizing VSAM Data Sets
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.
To update a linear data set using VSAM, you must use control interval access, and
must have control authority. To read a linear data set with VSAM, you must use
control interval access, and must have read authority. For more information, see
Chapter 11, “Processing Control Intervals,” on page 195, especially “Access to a
Control Interval” on page 196. See also the DEFINE CLUSTER topic in z/OS
DFSMS Access Method Services Commands for available options and associated
restrictions for the LINEAR parameter.
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
Chapter 6. Organizing VSAM Data Sets
109
Organizing VSAM Data Sets
records, the search begins from the pointer, rather than from the beginning of the
data set. Records must be retrieved in ascending sequence.
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 133.
110
z/OS DFSMS Using Data Sets
Organizing VSAM Data Sets
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
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 17 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 17. Alternate Index Structure for a Key-Sequenced Data Set
Chapter 6. Organizing VSAM Data Sets
111
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 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 18 on page 113 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.
112
z/OS DFSMS Using Data Sets
Organizing VSAM Data Sets
a
Index
H
D FRED TOM
R
b
c
H
D BEN 400 BILL 000 FRED 140 540 940
R
Alternate
Index
Control
info
d
Data
H
D MIKE 12 TOM 10
R
X'00'
RBA
36
Base
Cluster
Free space
e
X'400'
21
X'800'
41
X'140'
BILL
23
X'540'
BEN
23
X'940'
TOM
41
X'280'
FRED 10
TOM
Free space
Control
info
X'7C0'
MIKE
X'A80'
39 FRED 54
Control
info
X'3C0'
X'680'
FRED 12
Free space
54
Free space
Control
info
X'BC0'
TOM
Free space
Control
info
Note: RBAs are always written as full word binary integers.
Figure 18. Alternate Index Structure for an Entry-Sequenced Data Set
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.
Chapter 6. Organizing VSAM Data Sets
113
Organizing VSAM Data Sets
A search for a given alternate key reads all the base cluster records containing this
alternate key. For example, Figure 17 on page 111 and Figure 18 on page 113 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 133. For information about defining a path, see “Defining a
Path” on page 136.
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
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
v Compression processing can negatively impact CPU and elapsed times.
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
114
z/OS DFSMS Using Data Sets
Organizing VSAM Data Sets
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
115
116
z/OS DFSMS Using Data Sets
Chapter 7. Defining VSAM Data Sets
This chapter covers the following topics.
Topic
“Using Cluster Names for Data and Index Components” on page 118
“Defining a Data Set with Access Method Services” on page 118
“Defining a Data Set with JCL” on page 127
“Loading a VSAM Data Set” on page 128
“Copying and Merging Data Sets” on page 131
“Defining Alternate Indexes” on page 133
“Defining a Page Space” on page 137
“Checking for Problems in Catalogs and Data Sets” on page 138
“Deleting Data Sets” on page 139
This topic explains how to define VSAM data sets. Other topics 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 141.
v For examples of defining VSAM data sets, see z/OS DFSMS Access Method
Services Commands.
v For information about defining a data set using RLS, see “Locking” on page 243.
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, 2017
117
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.
118
z/OS DFSMS Using Data Sets
Defining VSAM Data Sets
Cluster name: SALES.REGION2.CLUSTER
Generated data name = SALES.REGION2.DATA
Generated index name = SALES.REGION2.INDEX
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: DEPT64.ASSET.INFO
Generated data name = DEPT64.ASSET.INFO.DATA
Generated index name = DEPT64.ASSET.INFO.INDEX
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: DEPTABCD.RESOURCE.REGION66.DATA1234.STUFF
Generated data name = DEPTABCD.RESOURCE.REGION66.DATA1234.STUFF.D
Generated index name = DEPTABCD.RESOURCE.REGION66.DATA1234.STUFF.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: DIV012.GROUP16.DEPT98.DAILYLOG.DEC1988.BACK
Generated data name = DIV012.GROUP16.DEPT98.DAILYLOG.TY7RESNO
Generated index name = DIV012.GROUP16.DEPT98.DAILYLOG.YIIQHNTR
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 Commands 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
119
Defining VSAM Data Sets
DSNAME(&CLUSTER)
See “Examples of Defining Temporary VSAM Data Sets” on page 143 for
information about using the ALLOCATE command to define a temporary
system-managed VSAM data set. See “Temporary VSAM Data Sets” on page 283
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:
120
z/OS 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 131.
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 180.
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 169.
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 129.
Chapter 7. Defining VSAM Data Sets
121
Defining VSAM Data Sets
VOLUMES parameter for the index component—Specifies whether to place
the cluster's index on a separate volume from data.
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.
v
Security and Integrity Parameters
The following access method services parameters provide security and integrity
information. See Chapter 5, “Protecting Data Sets,” on page 63 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 Commands.
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 255
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 76 and “Generic and Discrete Profiles for VSAM
Data Sets” on page 64.
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 192 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.
122
z/OS DFSMS Using Data Sets
Defining VSAM Data Sets
v The storage group to which these volumes belong is in the list of storage groups
selected by the ACS routines for this allocation.
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 173 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. For data sets whose ending high used RBA is in track managed
space, 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. For data sets whose ending high
used RBA is in cylinder-managed space, all space after the high used RBA is
released on an MCU boundary up to the high allocated RBA. If the high used RBA
is not on an MCU boundary, the high used amount is rounded to the next MCU
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 unless they are linear data sets designated for zFS.
For extended format data sets, partial release can release unused space across
multiple volumes, from the high used RBA (or next CA/MCU boundary) to the
high allocated RBA. Partial release requires that the primary volumes in the data
set be in ascending order by RBA. For example, the first volume could have RBAs
1 to 1000, the next 1001 to 2000, and so on. If the primary volumes appear out of
order, partial release issues an error message and releases no 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.
Chapter 7. Defining VSAM Data Sets
123
Defining VSAM Data Sets
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
On an extended address volume, partial release processing performed by the
system for a non-striped VSAM data set ensures that point where unused space is
to be released from is on a multi-cylinder unit boundary. Additionally, for a striped
VSAM data set the system ensures that the point where unused space is to be
released from for all stripes results in stripes of the same size. In either case, the
system cannot release some or all of the unused space from the end of the data set.
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
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 173 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 126 demonstrates how to calculate the size of a data set.
See “Using Index Options” on page 192 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.
124
z/OS DFSMS Using Data Sets
Defining VSAM Data Sets
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 if Extent
Constraint Removal is specified in the Data Class. The theoretical limit is then 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.
Note: 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 must be enforced if the
data set might be shared with a pre-V1R7 system.
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.
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.
Chapter 7. Defining VSAM Data Sets
125
Defining VSAM Data Sets
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
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 x 15) = 495.
6. Number of loaded control intervals per control area (495 - 10% x 495) = 446.
7. Number of loaded records per cylinder (4 x 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 × 15) is the number of
physical blocks per track multiplied by the number of data tracks per cylinder.
126
z/OS DFSMS Using Data Sets
Defining VSAM Data Sets
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
Commands 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 Commands to determine which
values or attributes you can alter for a particular data set type.
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 100). 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 281 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.
Chapter 7. Defining VSAM Data Sets
127
Defining VSAM Data Sets
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.
Using REPRO to Copy a VSAM Data Set
The REPRO command lets you retrieve records from a 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 data sets need not be cataloged.
Sequential data sets that are system managed must be cataloged.
If a 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, and/or the output data set is sequential. The
following table shows the key parameters:
Parameters
User Can Supply
Default if Not Supplied
RECFM
F, FB, V, VB, VS, VBS
U
BLKSIZE
Block size
Determined by system if RECFM is
not U and LRECL is specified
LRECL
Logical record length
BLKSIZE for F or FB BLKSIZE-4 for
V, VB, VS, VBS
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.
128
z/OS DFSMS Using Data Sets
Defining VSAM Data Sets
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 want to prevent the system from choosing a block size that
is over a certain value, you can code BLKSZLIM on the DD statement.
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 format-V 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.
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 154.
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.
Chapter 7. Defining VSAM Data Sets
129
Defining VSAM Data Sets
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.
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 255.
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 preformat 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
130
z/OS DFSMS Using Data Sets
Defining VSAM Data Sets
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
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 233.
Chapter 7. Defining VSAM Data Sets
131
Defining VSAM Data Sets
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.
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 128.
Table 16 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 16. Adding data to various types of output data sets
Type of Data Set
Empty
Nonempty
Entry sequenced
Loads new data set in
sequential order.
Adds records in sequential order to the end of the data
set.
Sequential
Loads new data set in
sequential order.
Adds records in sequential order to the end of the data
set.
Key sequenced
Loads new data set in key
sequence and builds an
index.
Merges records by key and updates the index. Unless the
REPLACE option is specified, records whose key
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
relative record sequence,
beginning with relative
record number 1.
132
z/OS DFSMS Using Data Sets
Records from another fixed-length or variable-length
RRDS are merged, keeping their old record numbers.
Unless the REPLACE option is specified, a new record
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.
Defining VSAM Data Sets
Table 16. Adding data to various types of output data sets (continued)
Type of Data Set
Empty
Nonempty
Variable-length RRDS
Loads a new data set in
relative record sequence,
beginning with relative
record number 1.
Records from another fixed-length or variable-length
RRDS are merged, keeping their old record numbers.
Unless the REPLACE option is specified, a new record
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.
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 'SYS1.VVDS.Vvolser'), 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 110 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
Chapter 7. Defining VSAM Data Sets
133
Defining VSAM Data Sets
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
118.
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
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 Commands 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.
134
z/OS DFSMS Using Data Sets
Defining VSAM Data Sets
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 120.
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
example, you would not be able to support as many nonunique keys as you would
if the maximum RECORDSIZE value were 5000. The maximum number of prime
keys that a single alternate index logical record can contain is 32767.
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 Commands.
Chapter 7. Defining VSAM Data Sets
135
Defining VSAM Data Sets
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 195.
You can define a maximum of 255 alternate indexes in a base cluster with the
UPGRADE attribute.
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.
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,
136
z/OS DFSMS Using Data Sets
Defining VSAM Data Sets
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.
Related reading: See z/OS DFSMS Access Method Services Commands 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 maximum size equal to 16 777 215 slots (records).
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.
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 RACF-protected if the page space is RACF-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 SYS1.PARMLIB. To be used as a page space,
it must be defined in a master catalog.
Related reading:
v For information about using the DEFINE PAGESPACE parameter to define the
page size, see z/OS DFSMS Access Method Services Commands.
Chapter 7. Defining VSAM Data Sets
137
Defining VSAM Data Sets
v For details on specifying information for a data set, especially for
system-managed data sets, see “Specifying Cluster Information” on page 120
and “Using Access Method Services Parameters” on page 120.
v For information about how VSAM handles duplicate data sets, see “Duplicate
Data Set Names” on page 119.
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 131.
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 249.
Note: If a VSAM data set was allocated in a JCL job but not opened, and another
job deleted and redefined the same VSAM data set, then the first job will not be
able to open the data set. An IDCAMS DELETE NOSCRATCH command does not
serialize on SYSDSN/dsname resource when deleting and redefining the data set.
Because the allocation is pointing to a specific UCB, if the PATH is deleted and
redefined on another UCB, the subsequent OPEN fails because the new UCB may
not match the original UCB in the TIOT entry.
Related reading: For more information about VERIFY, see “Using VERIFY to
Process Improperly Closed Data Sets” on page 60. 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.
138
z/OS DFSMS Using Data Sets
Defining VSAM Data Sets
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.
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 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 78 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 Commands, 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.
Chapter 7. Defining VSAM Data Sets
139
Defining VSAM Data Sets
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.
140
z/OS DFSMS Using Data Sets
Chapter 8. Defining and Manipulating VSAM Data Sets:
Examples
This chapter covers the following topics.
Topic
“Example of Defining a VSAM Data Set”
“Examples of Defining Temporary VSAM Data Sets” on page 143
“Examples of Defining Alternate Indexes and Paths” on page 144
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 Commands 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.
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
//STEP1
//SYSPRINT
//SYSIN
JOB ...
EXEC PGM=IDCAMS
DD SYSOUT=*
DD *
DEFINE USERCATALOG (NAME (USERCATX) ICFCATALOG CYLINDERS(15 5) VOLUMES(VSER05)) DATA (CYLINDERS(3 1))
IF LASTCC = 0 THEN DEFINE CLUSTER(NAME (EXAMPL1.KSDS) VOLUMES(VSER05)) DATA
(KILOBYTES (50 5))
/*
//STEP2
EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//AMSDUMP DD SYSOUT=*
//INDSET4 DD DSNAME=SOURCE.DATA,DISP=OLD,
//
VOL=SER=VSER02,UNIT=3380
//SYSIN
DD *
REPRO INFILE(INDSET4) OUTDATASET(EXAMPL1.KSDS)
IF LASTCC = 0 THEN © Copyright IBM Corp. 1987, 2017
141
Defining and Manipulating VSAM Data Sets: Examples
LISTCAT ENTRIES(EXAMPL1.KSDS)
IF LASTCC = 0 THEN PRINT INDATASET(EXAMPL1.KSDS)
/*
The following access method services commands are used in this example:
Command
DEFINE USERCATALOG
DEFINE CLUSTER
REPRO
LISTCAT
PRINT
Purpose
Create the catalog
Define the data set
Load the data set
List the catalog entry
Print the data set
See Chapter 18, “Using Job Control Language for VSAM,” on page 281 for
examples of creating VSAM data sets through JCL. See z/OS DFSMS Access Method
Services Commands for more details and examples of these or other access method
services commands.
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.
Parameter
Purpose
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
EXAMPL1.KSDS. The command's parameters are:
142
Parameters
Purpose
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.
z/OS DFSMS Using Data Sets
Defining and Manipulating VSAM Data Sets: Examples
Parameters
Purpose
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
EXAMPL1.KSDS from an existing data set called SOURCE.DATA (that is described
by the INDSET4 DD statement). The command's parameters are:
Parameter
Purpose
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.
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.
Command
Purpose
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
286 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 284.
Example 1: Defining a Temporary VSAM Data Set Using
ALLOCATE
//ALLOC
//STEP1
//SYSPRINT
//SYSIN
JOB
EXEC
DD
DD
...
PGM=IDCAMS
SYSOUT=A
*
ALLOC DSNAME(&CLUSTER) Chapter 8. Defining and Manipulating VSAM Data Sets: Examples
143
Defining and Manipulating VSAM Data Sets: Examples
NEW
RECORG(ES) SPACE(1,10) AVGREC(M)
LRECL(256) STORCLAS(TEMP)
/*
The command's parameters are:
Parameter
Purpose
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.
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
//STEP1
//SYSPRINT
//SYSIN
JOB ...
EXEC PGM=IDCAMS
DD
SYSOUT=A
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 topic, 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
144
z/OS DFSMS Using Data Sets
Defining and Manipulating VSAM Data Sets: Examples
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.
Commands
The first DEFINE command defines a VSAM alternate index over the base cluster
EXAMPL1.KSDS.
Parameter
Purpose
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
UPDATEPW
Specifies the master and update passwords, respectively, for the
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
(EXAMPL1.AIX).
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.
Parameter
Purpose
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.
Chapter 8. Defining and Manipulating VSAM Data Sets: Examples
145
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.
Parameter
Purpose
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 updateor 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.
146
z/OS DFSMS Using Data Sets
Chapter 9. Processing VSAM Data Sets
This topic covers the following subtopics.
Topic
“Creating an Access Method Control Block” on page 148
“Creating an Exit List” on page 148
“Opening a Data Set” on page 149
“Creating a Request Parameter List” on page 150
“Manipulating the Contents of Control Blocks” on page 152
“Requesting Access to a Data Set” on page 153
“Closing Data Sets” on page 163
“Operating in SRB or Cross-Memory Mode” on page 164
“Using VSAM Macros in Programs” on page 165
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 221.)
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, 2017
147
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 161.
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 233.
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 152 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).
148
z/OS 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 33 on page 275.
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 152.
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
149
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 195.
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 63.
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 152.
When you define your request, specify only the processing options appropriate for
that particular request. Parameters not required for a request are ignored. For
150
z/OS 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 157.
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. While a synchronous or asynchronous
request using an RPL is in progress, the application must not modify that RPL,
and the RPL must not be used by another request. 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 162.
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 195.
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.)
Chapter 9. Processing VSAM Data Sets
151
Processing VSAM Data Sets
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.
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.
152
z/OS DFSMS Using Data Sets
Processing VSAM Data Sets
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.
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.
When modifying any field in a RPL, you must first make sure there is no active or
inactive process that is still connected to the RPL. Inactive processes that are still
connected to their RPLs include sequential, skip-sequential and POINT processes.
You can disconnect the RPL from any process using the ENDREQ macro.
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
Chapter 9. Processing VSAM Data Sets
153
Processing VSAM Data Sets
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
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.
154
z/OS DFSMS Using Data Sets
Processing VSAM Data Sets
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 205.
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).
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.
Chapter 9. Processing VSAM Data Sets
155
Processing VSAM Data Sets
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.
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. With shared resources, you must always use a POINT
macro (or GET with RPLOPTCD=(DIR,NSP)) to establish position. A sequential
GET macro can then retrieve the record. With non-shared resources, VSAM will
implicitly position to the first record in the data set for keyed sequential access,
RPLOPTCD=(KEY,SEQ) on the first use of any string. Any subsequent use of the
string, without successfully establishing position, will result in either an
unintended record or a positioning logic error.
Since it may not be obvious to your program whether or not a given string is used
for the first time, and to keep your options open for using LSR or SMB, it is a
good programming practice to always explicitly position instead of relying on the
implicit positioning that you get with non-shared resources.
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.
156
z/OS DFSMS Using Data Sets
Processing VSAM Data Sets
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.
When using POINT with shared buffering, it is important to ensure that either a
GET DIR,NUP or an ENDREQ eventually follows to release positioning or a hang
might occur with other requests needing the buffers that the POINT is holding.
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
Chapter 9. Processing VSAM Data Sets
157
Processing VSAM Data Sets
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.
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.
158
z/OS DFSMS Using Data Sets
Processing VSAM Data Sets
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 17 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 17. Effect of RPL options on data buffers and positioning
RPL Options
Retained
SEQ
*
SKP
*
DIR NSP
*
DIR (no NSP)
Released
*
DIR LOC
*
UPD (with GET)
*
any (with POINT)
*
Note:
1. A sequential GET request which was positioned on the last record of a buffer
will release that buffer and position to the next buffer (control interval) to
return the next sequential record.
2. The ENDREQ macro releases data buffers and, if any, shared resources or RLS,
index buffer, 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.
Chapter 9. Processing VSAM Data Sets
159
Processing VSAM Data Sets
4. Use the ENDREQ macro to end requests that hold position before reusing the
RPL, to avoid unpredictable results. The RPL that you ENDREQ must be the
same RPL that was used to issue the initial request.
5. The POINT request, regardless of the RPL options, will always hold position
because it only positions and does not return a record. A sequential GET
following the POINT will retrieve the record; a direct GET establishes its own
position and may or may not retrieve the record to which POINT was
positioned. The request following a POINT will either keep position or release
it based on Table 17 on page 159.
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
160
z/OS 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 if the data set is not an extended-addressable data set. For an
extended-addressable data set, the RBA of the record will be in the lower six bytes
of the field RPLRBAR.
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.
Chapter 9. Processing VSAM Data Sets
161
Processing VSAM Data Sets
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.
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
162
z/OS DFSMS Using Data Sets
Processing VSAM Data Sets
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.
Once the request is completed, CHECK releases control to the next instruction in
your program, and frees up the RPL for use by another request.
Ending a Request
Suppose you determine that you do not want to complete a request that you
initiated. For example, suppose you determine during the processing immediately
following a GET that you do not want the record you just requested. You can use
the ENDREQ macro to cancel the request. Using the ENDREQ macro has the
following advantages:
v Avoids checking an unwanted asynchronous request.
v Writes any unwritten data or index buffers in use by the string.
v Cancels the VSAM positioning on the data set for the RPL.
Recommendation: If you issue the ENDREQ macro, it is important that you check
the ENDREQ return code to make sure it completes successfully. If an
asynchronous request does not complete ENDREQ successfully, you must issue the
CHECK macro. The data set cannot be closed until all asynchronous requests
successfully complete either ENDREQ or CHECK. ENDREQ waits for the target
RPL to post, so it should not be issued in an attempt to end a hung request.
Closing Data Sets
The CLOSE macro disconnects your program from a data set. It causes VSAM to
take the following actions:
v Write any unwritten data or index records whose contents have changed.
v Update the catalog entry for the data set if necessary (if the location of the
end-of-file indicator has changed, for example).
v Write SMF records if SMF is being used.
v Restore control blocks to the status they had before the data set was opened.
v Release virtual storage obtained during OPEN processing for additional VSAM
control blocks and VSAM routines.
v If partial release was specified at open time, release all space after the high-used
RBA (on a CA boundary of non-EAV data sets, or on an MCU boundary for EAV
data sets) up to the high-allocated RBA.
If a record management error occurs while CLOSE is flushing buffers, the data set's
catalog information is not updated. The catalog cannot properly reflect the data
set's status and the index cannot accurately reflect some of the data records. If the
program enters an abnormal termination routine (ABEND), all open data sets are
closed. The VSAM CLOSE invoked by ABEND does not update the data set's
catalog information, it does not complete outstanding I/O requests, and buffers are
not flushed. The catalog cannot properly reflect the cluster's status, and the index
cannot accurately reference some of the data records. Use the access method
services VERIFY command to correct catalog information. The use of VERIFY is
described in “Using VERIFY to Process Improperly Closed Data Sets” on page 60.
When processing asynchronous VSAM requests, all strings must be quiesced by
issuing the CHECK macro or the ENDREQ macro before issuing CLOSE or CLOSE
TYPE=T (temporary CLOSE).
Chapter 9. Processing VSAM Data Sets
163
Processing VSAM Data Sets
CLOSE TYPE=T causes VSAM to complete any outstanding I/O operations,
update the catalog if necessary, and write any required SMF records. Processing
can continue after a temporary CLOSE without issuing an OPEN macro.
If a VSAM data set is closed and CLOSE TYPE=T is not specified, you must
reopen the data set before performing any additional processing on it.
When you issue a temporary or a permanent CLOSE macro, VSAM updates the
data set's catalog records. If your program ends with an abnormal end (ABEND)
without closing a VSAM data set the data set's catalog records are not updated,
and contain inaccurate statistics.
It is the user's responsibility to ensure that shared DD statements are not
dynamically deallocated until all ACBs that share these DD statements are closed.
For more information about dynamic allocation, see z/OS MVS JCL User's Guide.
Restriction: The following close options are ignored for VSAM data sets:
v FREE=CLOSE JCL parameter
v FREE=CLOSE requested through dynamic allocation, DALCLOSE
Operating in SRB or Cross-Memory Mode
VSAM is the only access method that operates in service request block (SRB) or
cross-memory mode. The SRB or cross-memory mode enables you to use structures
in other address spaces to increase the amount of space available. SRB and
cross-memory modes are supervisor modes of operation reserved for authorized
users. Cross-memory is a complex concept, and there are several warnings and
restrictions associated with it. See z/OS MVS Programming: Authorized Assembler
Services Guide.
|
|
|
|
|
In VSAM you can only operate in cross-memory mode for synchronous
supervisor-state requests with shared resources or improved control interval (ICI)
access. In cross-memory mode, each of the following situations results in a logical
error: an attempt to invoke VSAM asynchronously, in problem state, SRB mode,
non-shared resources (NSR) without ICI.
|
|
You can operate in SRB mode only for synchronous supervisor-state requests while
not in cross-memory mode.
VSAM does not synchronize cross-memory mode requests. For non-ICI processing,
the RPL must specify WAITX, and a UPAD exit (user processing exit routine) must
be provided in an exit list to handle the wait and post processing for cross-memory
requests; otherwise a VSAM error code is returned.
For cross-memory mode requests, VSAM does not do wait processing when a
UPAD for wait returns to VSAM. For non-cross-memory task mode, however, if
the UPAD taken for wait returns with ECB not posted, VSAM issues a WAIT
supervisor call instruction (SVC). For either mode, when a UPAD is taken for post
processing returns, VSAM assumes the ECB has been marked complete and does
not do post processing.
ICI in cross-memory mode assumes (without checking) the request is synchronous.
UPAD is not required. If UPAD routine is not provided, I/O wait and post
164
z/OS DFSMS Using Data Sets
Processing VSAM Data Sets
processing is done by suspend and resume. There is no resource wait/post
processing for ICI. See “Improved Control Interval Access” on page 202 for
information about ICI.
SRB mode does not require UPAD. If a UPAD is provided for an SRB mode
request, it is taken only for I/O wait and resource wait processing.
In cross-memory or SRB mode, record management cannot issue any supervisor
call instructions (SVCs). Whenever VSAM cannot avoid issuing an SVC, it sets an
RPL return code to indicate that you must change processing mode so that you are
running under a task control block (TCB) in the address space in which the data
set was opened. You cannot be in cross-memory mode. Then reissue the request to
permit the SVC to be issued by VSAM. The requirement for VSAM to issue an
SVC is kept to a minimum. Areas identified as requiring a TCB not in
cross-memory mode are EXCEPTIONEXIT, loaded exits, EOV (end-of-volume),
dynamic string addition, and alternate index processing.
If a logical error or an end-of-data condition occurs during cross-memory or SRB
processing, VSAM attempts to enter the LERAD (logical error) or EODAD
(end-of-data-set) exit routine. If the routine must be loaded, it cannot be taken
because loading involves an SVC; VSAM sets the RPL feedback to indicate “invalid
TCB”. If an I/O error occurs during cross-memory or SRB processing and an
EXCEPTIONEXIT or loaded SYNAD (physical error exit) routine is specified, these
routines cannot be taken; the RPL feedback indicates an I/O error condition.
See Chapter 16, “Coding VSAM User-Written Exit Routines,” on page 255 for more
information.
Using VSAM Macros in Programs
At this point it is important to see how all of these macros work together in a
program. Figure 19 on page 166 shows the relationship between JCL and the
VSAM macros in a program.
Chapter 9. Processing VSAM Data Sets
165
Processing VSAM Data Sets
//ddname DD DSNAME=dsname,DISP=(OLD|SHR)
(label)
OPEN
(label)
GET|PUT
(label)
RPL
(address[,(options)], . . . .)
RPL=address
[ACB=address]
[,OPTCD= [DIR|SEQ|SKP]
[ . . . . . . . . . . . .])]
.........
(label)
ACB
...........
[,DDNAME=ddname]
[,BUFND=number]
[,BUFNI=number]
[,BUFSP=number]
[,MACRF=([DIR][,SEQ][,SKP]
[,IN][,OUT]
[,NRS ][,RST]
[,STRNO=number]
[,PASSWD=address]
[,EXLST=address]
........
(label)
EXLST
[JRNAD=(address[A|N[,L])]
[SYNAD=(address[A|N[,L])]
.........
Figure 19. VSAM Macro Relationships
Figure 20 on page 167 is a skeleton program that shows the relationship of VSAM
macros to each other and to the rest of the program.
166
z/OS DFSMS Using Data Sets
Processing VSAM Data Sets
START CSECT
SAVE(14,12)
.
B
INIT
Branch around file specs
MASACB
ACB
DDNAME=MASDS,AM=VSAM,
MACRF=(KEY,SEQ,OUT),
EXLST=EXITS,
RMODE31=ALL
File specs
MASRPL
RPL
ACB=MASACB,
OPTCD=(KEY,SEQ,NUP,MVE,SYN),
AREA=WA,
AREALEN=80,
RECLEN=80
EXITS
EXLST LERAD=LOGER,
JRNAD=JOURN
TRANDCB DCB
INIT
EOTRF
LOGER
JOURN
WA
Standard entry code
X
X
X
X
X
DDNAME=TRANDS,
DSORG=PS,
MACRF=GM,
EODAD=EOTRF,
LRECL=80,
BLKSIZE=80,
RECFM=F
.
.
OPEN (MASACB,,TRANDCB)
.
GET
TRANDCB,WA
.
PUT
RPL=MASRPL
.
CLOSE (MASACB,,TRANDCB)
.
RETURN (14,12)
Exit routines
.
.
.
DS
CL80
END
X
X
X
X
X
X
X
X
X
Program initialization
Connect data sets
Processing loop
Disconnect data sets
Return to calling routine
Work area
Figure 20. Skeleton VSAM Program
Chapter 9. Processing VSAM Data Sets
167
Processing VSAM Data Sets
168
z/OS DFSMS Using Data Sets
Chapter 10. Optimizing VSAM Performance
This topic covers the following subtopics, describing many of the options and
factors that influence or determine the performance of both VSAM and the
operating system.
Topic
“Optimizing Control Interval Size”
“Optimizing Control Area Size” on page 173
“Optimizing Free Space Distribution” on page 174
“Using Index Options” on page 192
“Obtaining Diagnostic Information” on page 193
“Migrating from the Mass Storage System” on page 193
“Using Hiperbatch” on page 193
Most of the options are specified in the access method services DEFINE command
when a data set is defined. Sometimes options can be specified in the ACB and
GENCB macros and in the DD AMP parameter.
Optimizing Control Interval Size
You can let VSAM select the size of a control interval for a data set, you can
request a particular control interval size in the DEFINE command, or you can
specify data class in DEFINE and use the CISIZE attribute assigned by your
storage administrator. You can improve VSAM's performance by specifying a
control interval size in the DEFINE command, depending on the particular storage
and access requirements for your data set. See “Control Intervals” on page 86 for
information about the structure and contents of control intervals.
Control interval size affects record processing speed and storage requirements in
the following ways:
v Buffer space. Data sets with large control interval sizes require more buffer
space in virtual storage. For information about how much buffer space is
required, see “Determining I/O Buffer Space for Nonshared Resource” on page
180.
v I/O operations. Data sets with large control interval sizes require fewer I/O
operations to bring a given number of records into virtual storage; fewer index
records must be read. It is best to use large control interval sizes for sequential
and skip-sequential access. Large control intervals are not beneficial for keyed
direct processing of a key-sequenced data set or variable-length RRDS.
v
Free space. Free space is used more efficiently (fewer control interval splits and
less wasted space) as control interval size increases relative to data record size.
For more information about efficient use of free space, see “Optimizing Free
Space Distribution” on page 174.
Control Interval Size Limitations
When you request a control interval size, you must consider the length of your
records and whether the SPANNED parameter has been specified.
© Copyright IBM Corp. 1987, 2017
169
Optimizing VSAM Performance
The valid control interval sizes and block sizes for the data or index component
are from 512 to 8192 bytes in increments of 512 bytes, and from 8 KB to 32 KB in
increments of 2 KB. When you choose a CI size that is not a multiple of 512 or
2048, VSAM chooses the next higher multiple. For a linear data set, the size
specified is rounded up to 4096 if specified as 4096 or less. It is rounded to the
next higher multiple of 4096 if specified as greater than 4096.
Example: 2050 is increased to 2560.
The block size of the index component is always equal to the control interval size.
However, the block size for the data component and index components might
differ.
Example: Valid control interval sizes are 512, 1024, 1536, 2048, 3584, 4096, ... 8192,
10 240, and 12 288, and so on.
Related reading: For more information, see the description of the
CONTROLINTERVALSIZE parameter of the DEFINE CLUSTER command in z/OS
DFSMS Access Method Services Commands.
Unless the data set was defined with the SPANNED attribute, the control interval
must be large enough to hold a data record of the maximum size specified in the
RECORDSIZE parameter. Because the minimum amount of control information in
a control interval is 7 bytes, a control interval is normally at least 7 bytes larger
than the largest record in the component. For compressed data sets, a control
interval is at least 10 bytes larger than the largest record after it is compressed.
This allows for the control information and record prefix. Since the length of a
particular record is hard to predict and since the records might not compress, it is
best to assume that the largest record is not compressed. If the control interval size
you specify is not large enough to hold the maximum size record, VSAM increases
the control interval size to a multiple of the minimum physical block size. The
control interval size VSAM provides is large enough to contain the record plus the
overhead.
For a variable-length RRDS, a control interval is at least 11 bytes larger than the
largest record.
The use of the SPANNED parameter removes this constraint by permitting data
records to be continued across control intervals. The maximum record size is then
equal to the number of control intervals per control area multiplied by control
interval size minus 10. The use of the SPANNED parameter places certain
restrictions on the processing options that can be used with a data set. For
example, records of a data set with the SPANNED parameter cannot be read or
written in locate mode. For more information about spanned records see “Spanned
Records” on page 88.
Physical Block Size and Track Capacity
Figure 21 on page 171 shows the relationship between control interval size,
physical block size, and track capacity that is not in extended format.
170
z/OS DFSMS Using Data Sets
Optimizing VSAM Performance
CI1
PB
CI2
PB
PB
PB
Track 1
CI3
PB
PB
Track 2
CI4
PB
PB
Track 3
CI6
CI5
PB
PB
PB
PB
Track 4
PB - Physical block
Figure 21. Control Interval Size, Physical Track Size, and Track Capacity
The information about a track is divided into physical blocks. Control interval size
must be a whole number of physical blocks. Control intervals can span tracks.
However, poor performance results if a control interval spans a cylinder boundary,
because the read/write head must move between cylinders.
The physical block size is always selected by VSAM. VSAM chooses the largest
physical block size that exactly divides into the control interval size. The block size
is also based on device characteristics.
Track Allocations versus Cylinder Allocations
All space specifications except cylinders are converted to the appropriate number
of tracks. Usually, cylinder allocations provide better performance than track
allocations. Performance also depends on the control interval size, buffer size, the
number of buffers, and index options.
Data Control Interval Size
You can either specify a data control interval size or default to a system-calculated
control-interval size. If you do not specify a size, the system calculates a default
value that best uses the space on the track for the average record size of spanned
records or the maximum record size of nonspanned records.
If a CONTROLINTERVALSIZE value is specified on the cluster level, this value
propagates to the component level at which no CONTROLINTERVALSIZE value
has been specified.
Normally, a 4096-byte data control interval is reasonably good regardless of the
DASD device used, processing patterns, or the processor. A linear data set requires
a control interval size of 4096 to 32768 bytes in increments of 4096 bytes. However,
there are some special considerations that might affect this choice:
v If you have very large control intervals, more pages are required to be fixed
during I/O operations. This could adversely affect the operation of the system.
v Small records in a data control interval can result in a large amount of control
information. Often free space cannot be used.
v The type of processing you use can also affect your choice of control interval
size:
– Direct processing. When direct processing is predominant, a small control
interval is preferable, because you are only retrieving one record at a time.
Select the smallest data control interval that uses a reasonable amount of
space.
– Sequential processing. When sequential processing is predominant, larger data
control intervals can be good choices. For example, given a 16 KB data buffer
space, it is better to read two 8 KB control intervals with one I/O operation
than four 4 KB control intervals with two I/O operations.
Chapter 10. Optimizing VSAM Performance
171
Optimizing VSAM Performance
– Mixed processing. If the processing is a mixture of direct and sequential, a
small data control interval with multiple buffers for sequential processing can
be a good choice.
If you specify free space for a key-sequenced data set or variable-length RRDS, the
system determines the number of bytes to be reserved for free space. For example,
if control interval size is 4096, and the percentage of free space in a control interval
has been defined as 20%, 819 bytes are reserved. Free space calculations drop the
fractional value and use only the whole number.
To find out what values are actually set in a defined data set, issue the access
method services LISTCAT command.
Index Control Interval Size
For a key-sequenced data set, either specify an index control interval size or
default to a system-calculated size. If you do not specify a size, VSAM calculates
the CISIZE value based on the expected key-compression ratio of 3:1 and the
number of data CIs per control area in the data set. After VSAM determines the
number of CIs in a control area, it estimates whether the user-specified size is large
enough for all the CIs in a control area. (See “How VSAM Adjusts Control Interval
Size.”) If the size is too small, the system increases the size of the index control
interval to VSAM's minimum acceptable size. If the specified size is larger than the
minimum size that VSAM calculated, the system uses specified size.
You might need a larger CI than the size that VSAM calculated, depending on the
allocation unit, the data CI size, the key length, and the key content as it affects
compression. (It is rare to have the entire key represented in the index, because of
key compression.) If the keys for the data set do not compress according to the
estimated ratio (3:1), the index CI size that VSAM calculated might be too small,
resulting in the inability to address CIs in one or more CAs. This results in
allocated space that is unusable in the data set. After the first define (DEFINE), a
catalog listing (LISTCAT) shows the number of control intervals in a control area
and the key length of the data set.
You can use the number of control intervals and the key length to estimate the size
of index record necessary to avoid a control area split, which occurs when the
index control interval size is too small. To make a general estimate of the index
control interval size needed, multiply one half of the key length (KEYLEN) by the
number of data control intervals per control area (DATA CI/CA):
(KEYLEN/2) * DATA CI/CA ≤ INDEX CISIZE
The use of a 2:1 ratio rather than 3:1, which VSAM uses, allows for some of the
additional overhead factors in the actual algorithm for determining the CI size.
How VSAM Adjusts Control Interval Size
The control interval sizes you specify when the data set is defined are not
necessarily the ones that appear in the catalog. VSAM makes adjustments, if
possible, so that control interval size conforms to proper size limits, minimum
buffer space, adequate index-to-data size, and record size. VSAM makes the
following adjustments when your data set is defined.
1. Specifies data and index control interval size. After VSAM determines the
number of control intervals in a control area, it estimates whether one index
record is large enough to handle all control intervals in the control area. If not,
172
z/OS DFSMS Using Data Sets
Optimizing VSAM Performance
the size of the index control interval is increased, if possible. If the size cannot
be increased, VSAM decreases the number of control intervals in the control
area.
2. Specifies maximum record size as 2560 and data control interval size as 2560,
and have no spanned records. VSAM adjusts the data control interval size to
3072 to permit space for control information in the data control interval.
3. Specifies buffer space as 4K, index control interval size as 512, and data control
interval size as 2K. VSAM decreases the data control interval to 1536. Buffer
space must include space for two data control intervals and one index control
interval at DEFINE time. For more information about buffer space requirements
see “Determining I/O Buffer Space for Nonshared Resource” on page 180.
Optimizing Control Area Size
You cannot explicitly specify control-area size. Generally, the primary and
secondary space allocation amounts determine the control-area size:
v If either the primary or secondary allocation is smaller than one cylinder, the
smaller value is used as the control-area size. If RECORDS is specified, the
allocation is rounded up to full tracks.
v If both primary and secondary allocations are equal to or larger than one
cylinder, the control-area size is one cylinder, the maximum size for a control
area.
The following examples show how the control-area size is generally determined by
the primary and secondary allocation amount. The index control-interval size and
buffer space can also affect the control-area size. The available control area sizes
are 1, 3, 5, 7, 9 and 15 tracks. The following examples are based on the assumption
that the index CI size is large enough to handle all the data CIs in the CA. The
buffer space is large enough not to affect the CI sizes:
v CYLINDERS(5,10)—Results in a 1-cylinder control-area size.
v KILOBYTES(100,50)—The system determines the control area based on 50 KB,
resulting in a 1-track control-area size.
v RECORDS(2000,5)—Assuming 10 records would fit on a track, results in a
1-track control-area size.
v TRACKS(100,3)—Results in a 3-track control-area size.
v TRACKS(3,100)—Results in a 3-track control-area size.
A spanned record cannot be larger than the size of a control area minus the size of
the control information (10 bytes per control interval). Therefore, do not specify a
primary or secondary allocation that is not large enough to contain the largest
spanned record.
Note: If space is allocated in kilobytes, megabytes, or records, the system sets the
control area size equal to multiples of the minimum number of tracks or cylinders
required to contain the specified kilobytes, megabytes, or records. Space is not
assigned in units of bytes or records.
If the control area is smaller than a cylinder, the size of the control area is an
integral multiple of tracks, and the control area can span cylinders. However, a
control area can never span an extent of a data set, which is always composed of a
whole number of control areas. The available control area sizes are 1, 3,5, 7, 9 and
15 tracks. 16 tracks is also a valid control area size if the number of stripes is equal
to 16. For requests where either the primary or secondary allocation amount is
smaller than one cylinder, the system might adjust the primary and secondary
Chapter 10. Optimizing VSAM Performance
173
Optimizing VSAM Performance
quantity. The system might also select a CA that is different than what is selected
from a prior release. For example, a TRK(24,4) request results in a control area of 5
tracks, a primary and secondary amounts of 25, and 5 tracks respectively. For more
information about allocating space for a data set, see “Allocating Space for VSAM
Data Sets” on page 122.
Advantages of a Large Control Area Size
Control area size has significant performance implications. One-cylinder control
areas have the following advantages:
v There is a smaller probability of control area splits.
v The index is more consolidated. One index record addresses all the control
intervals in a control area. If the control area is large, fewer index records and
index levels are required. For sequential access, a large control area decreases the
number of reads of index records.
v There are fewer sequence set records. The sequence set record for a control area
is always read for you. Fewer records means less time spent reading them.
v If the sequence set of the index is imbedded on the first track of the control area,
it is replicated to reduce the rotational delay inherent when reading from the
device.
v If you have allocated enough buffers, a large control area lets you read more
buffers into storage at one time. A large control area is useful if you are
accessing records sequentially.
Disadvantages of a Large Control Area Size
The following disadvantages of a one-cylinder control area must also be
considered:
v If there is a control area split, more data is moved.
v During sequential I/O, a large control area might use more real storage and
more buffers.
Optimizing Free Space Distribution
With the DEFINE command, either specify the percentage of free space in each
control interval and the percentage of free control intervals per control area or
specify data class and use the FREESPACE attribute assigned through the ACS
routines established by your storage administrator.
Free space improves performance by reducing the likelihood of control interval
and control area splits. This, in turn, reduces the likelihood of VSAM moving a set
of records to a different cylinder away from other records in the key sequence.
When there is a direct insert or a mass sequential insert that does not result in a
split, VSAM inserts the records into available free space.
The amount of free space you need depends on the number and location of records
to be inserted, lengthened, or deleted. Too much free space can result in:
v Increased number of index levels, that affects run times for direct processing.
v More direct access storage required to contain the data set.
v More I/O operations required to sequentially process the same number of
records.
Too little free space can result in an excessive number of control interval and
control area splits. These splits are time consuming, and have the following
additional effects:
174
z/OS DFSMS Using Data Sets
Optimizing VSAM Performance
v More time is required for sequential processing because the data set is not in
physical sequence.
v More seek time is required during processing because of control area splits.
Use LISTCAT or the ACB JRNAD exit to monitor control area splits. See “JRNAD
Exit Routine to Journalize Transactions” on page 261.
When splits become frequent, reorganize the data set using REPRO or EXPORT.
Reorganization creates a smaller, more efficient data set with fewer control
intervals. However, reorganizing a data set is time consuming. To reduce the need
for reorganizing data sets, use the CA reclaim function. With CA reclaim, empty
CA space is reclaimed automatically and CA split processing uses control areas
that have been reclaimed instead of using space at the end of the data and index.
See “Reclaiming CA Space for a KSDS” on page 177 for more information.
Figure 22 shows how free space is determined for a control interval.
R1
Byte number
R2
R3
R4
500 1000
FREESPACE(20 10)
CONTROLINTERVALSIZE(4096)
RECORDSIZE(500 500)
R5
Control
info
R6
2500
3267
Free space threshold
Figure 22. Determining Free Space
For this data set, each control interval is 4096 bytes. In each control interval, 10
bytes are reserved for control information. Because control interval free space is
specified as 20%, 819 bytes are reserved as free space. (4096 × .20 = 819). Round
down. The free space threshold is 3267 bytes. The space between the threshold and
the control information is reserved as free space.
Because the records loaded in the data set are 500-byte records, there is not enough
space for another record between byte 3000 and the free space threshold at byte
3267. These 267 bytes of unused space are also used as free space. This leaves 1086
bytes of free space; enough to insert two 500-byte records. Only 86 bytes are left
unusable.
When you specify free space, ensure that the percentages of free space you specify
yield full records and full control intervals with a minimum amount of unusable
space.
Selecting the Optimal Percentage of Free Space
Determine the amount of control interval free space based on the percentage of
record additions expected, and their distribution:
No additions. If no records will be added and if record sizes will not be changed,
there is no need for free space.
Few additions. If few records will be added to the data set, consider a free space
specification of (0 0). When records are added, new control areas are created to
provide room for additional insertions.
Chapter 10. Optimizing VSAM Performance
175
Optimizing VSAM Performance
If the few records to be added are fairly evenly distributed, control interval free
space should be equal to the percentage of records to be added. (FSPC (nn 0),
where nn equals the percentage of records to be added.)
Evenly distributed additions. If new records will be evenly distributed throughout
the data set, control area free space should equal the percentage of records to be
added to the data set after the data set is loaded. (FSPC (0 nn), where nn equals
the percentage of records to be added.)
Unevenly distributed additions. If new records will be unevenly distributed
throughout the data set, specify a small amount of free space. Additional splits,
after the first, in that part of the data set with the most growth will produce
control intervals with only a small amount of unneeded free space.
Mass insertion. If you are inserting a group of sequential records, take full
advantage of mass insertion by using the ALTER command to change free space to
(0 0) after the data set is loaded. For more information about mass insertion see
“Inserting and Adding Records” on page 154.
Additions to a specific part of the data set. If new records will be added to only a
specific part of the data set, load those parts where additions will not occur with a
free space of (0 0). Then, alter the specification to (n n) and load those parts of the
data set that will receive additions. The example in “Altering the Free Space
Specification When Loading a Data Set” demonstrates this.
Altering the Free Space Specification When Loading a Data
Set
The following example uses the ALTER command to change the FREESPACE
specification when loading a data set.
Assume that a large key-sequenced data set is to contain records with keys from 1
through 300 000. It is expected to have no inserts in key range 1 through 100 000,
some inserts in key range 100 001 through 200 000, and heavy inserts in key range
200 001 through 300 000.
An ideal data structure at loading time would be:
Key Range
1 through 100 000
100 001 through 200 000
200 001 through 300 000
Free Space
None
5% control area
5% control interval and 20% control area
You can build this data structure as follows:
1. DEFINE CLUSTER and do one of the following:
v Omit the FREESPACE parameter
v Specify FREESPACE (0 0)
v Specify DATACLAS and use the FREESPACE attribute assigned through the
automatic class selection routines established by your storage administrator.
2. Load records 1 through 100 000 with REPRO or any user program using a
sequential insertion technique.
3. CLOSE the data set.
176
z/OS DFSMS Using Data Sets
Optimizing VSAM Performance
4. Change the FREESPACE value of the cluster with the access method services
command ALTER clustername FREESPACE (0 5). Explicit specification of
FREESPACE overrides the data class attribute assigned by your storage
administrator.
5. Load records 100 001 through 200 000 with REPRO or any user program using
a sequential insertion technique.
6. CLOSE the data set.
7. Change the FREESPACE value of the cluster with the access method services
command ALTER clustername FREESPACE (5 20).
8. Load records 200 001 through 300 000 with REPRO or any user program using
a sequential insertion technique.
This procedure has the following advantages:
v It prevents wasting space. For example, if FREESPACE (0 10) were defined for
the whole data set, the free space in the first key range would all be wasted.
v It minimizes control interval and control area splits. If FREESPACE (0 0) were
defined for the whole data set, there would be a very large number of control
interval and control area splits for the first inserts.
Reclaiming CA Space for a KSDS
Erasing records from a KSDS may result in space for empty CAs that is not
reclaimed. Over time, this can produce DASD space that is fragmented and
performance that is degraded due to an index structure that is unnecessarily
complicated by the empty CAs. To reclaim the empty CA space and streamline the
index structure, you can reorganize the KSDS. To reduce the need for reorganizing
a KSDS, you can cause empty CA space on DASD to be reclaimed automatically, so
that it may be reused at a later time when a CA split is required. The CAs that
have been reclaimed are available to be used for new records without any
processing to obtain new space. A CA split that reuses a reclaimed CA will not
change the high-used RBA.
CA reclaim provides for improved DASD space usage, but it requires additional
I/O to keep track of the reclaimed CAs so that they can be reused. The cost of this
I/O may not be justified if there are no or very few CA splits to reuse empty CAs.
To determine if CA reclaim is desirable for a data set, use the EXAMINE DATASET
command, which shows the number of empty CAs in a KSDS with message
IDC01728I. For more information about the EXAMINE DATASET command, see
“EXAMINE Command” on page 249. For a description of message IDC01728I, see
z/OS MVS System Messages, Vol 6 (GOS-IEA).
Requirements for CA Reclaim Eligibility
The minimum z/OS level for CA reclaim is z/OS V1R12. Only VSAM KSDSs are
eligible for CA reclaim processing. They may be catalog data sets, AIX and base
clusters or temporary data sets. They may be SMS managed or not SMS managed
and may be processed by VSAM or VSAM RLS. They may be created with or
without a data class. They must not have been defined with the IMBED option.
CA reclaim cannot reclaim space for:
v Partially empty CAs
v Empty CAs that already existed when CA reclaim was enabled
v CAs with RBA 0
v CAs with the highest key of the KSDS
Chapter 10. Optimizing VSAM Performance
177
Optimizing VSAM Performance
v Data sets processed with GSR.
Enabling and Disabling CA Reclaim
CA reclaim is disabled at the system level by default. To enable CA reclaim at the
system level, use the IGDSMSxx member of PARMLIB or the SETSMS command.
Then, to enable or disable CA reclaim for data sets when they are defined, you can
use a CA reclaim attribute in the data class, which you set with ISMF. The attribute
is set to Yes, to enable CA reclaim, by default. To disable or enable CA reclaim for
individual data sets, use the IDCAMS ALTER command. For a summary, see
Table 18.
Table 18. Controlling CA reclaim
Control for...
Use...
Default
System
“PARMLIB member
IGDSMSxx” or “SETSMS
command” on page 179
Disabled
Existing data sets
-
Enabled, once CA reclaim is
enabled for the system
New data sets created in “ISMF” on page 179, to set
a data class
the CA reclaim attribute for
the data class
Yes (enabled), but the attribute is
ignored if CA reclaim is not
enabled at the system level
Individual data sets
-
“IDCAMS ALTER” on page
179
CA reclaim is in effect for a data set only if all of the following are true:
v The data set is eligible for CA reclaim, as defined in “Requirements for CA
Reclaim Eligibility” on page 177.
v Either the IGDSMSxx member of PARMLIB specifies CA_RECLAIM(DATACLAS
or DATACLASS), or a SETSMS CA_RECLAIM(DATACLAS or DATACLASS)
command is issued.
v When the data set was defined, the CA reclaim attribute for the data class was,
or defaulted to, Yes, or an ALTER RECLAIMCA command is issued for the data
set.
Note: The CA reclaim attribute in data classes defined prior to z/OS V1R12,
when CA reclaim was introduced, defaults to Yes.
PARMLIB member IGDSMSxx
In PARMLIB member IGDSMSxx, you specify the setting for the system as follows:
CA_RECLAIM (NONE | {DATACLAS | DATACLASS})
where
NONE
Disables CA reclaim for the system, regardless of the value for the CA reclaim
attribute in data class or catalog entries. This is the default. Not specifying
CA_RECLAIM has the same effect as specifying CA_RECLAIM(NONE).
DATACLAS or DATACLASS
Enables CA reclaim for the system. CA reclaim is in effect for all eligible data
sets for which CA reclaim is not disabled with the data class attribute or the
ALTER command. You can use the CA Reclaim attribute in each data class to
enable or disable CA reclaim for new data sets as they are defined.
178
z/OS DFSMS Using Data Sets
Optimizing VSAM Performance
SETSMS command
Use the SETSMS command to immediately enable or disable CA reclaim for the
system. SETSMS overrides the value in IGDSMSxx. To retain the setting you
specified with the command, remember to update IGDSMSxx prior to the next IPL.
The command is:
SETSMS CA_RECLAIM (NONE | {DATACLAS | DATACLASS})
where
NONE
Disables CA reclaim for the system, regardless of the value for the CA reclaim
attribute in data class or catalog entries.
DATACLAS or DATACLASS
Enables CA reclaim for the system. CA reclaim is in effect for all eligible data
sets for which CA reclaim is not disabled with the data class attribute or the
ALTER command. You can use the CA Reclaim attribute in each data class to
enable or disable CA reclaim for new data sets as they are defined.
SETSMS has no default for CA_RECLAIM. For more information, see the
description of the SETSMS command in z/OS MVS System Commands.
ISMF
Using ISMF, you can specify the CA reclaim attribute for each data class. This
attribute is copied to a data set's catalog entry when the data set is defined. The
default value for the attribute is to enable CA reclaim.
As with other data class attributes, CA Reclaim is set at the time the data set is
defined. If you later change the value of the CA reclaim attribute for the data class,
the change does not affect data sets that have already been defined. The new value
is used for any data sets that are subsequently defined with that data class.
The CA reclaim attribute for the data class is always saved, but is used only if CA
reclaim is enabled in the IGDSMSxx member of PARMLIB or with the SETSMS
command.
For more information, see Defining data class attributes in z/OS DFSMSdfp Storage
Administration.
IDCAMS ALTER
The IDCAMS ALTER command allows you to change the attribute for CA reclaim
for a KSDS after it is defined. You might use this command to disable CA reclaim
for specific data sets after enabling CA reclaim for the system. The command will
take effect at the first OPEN following the CLOSE of all open ACBs against the
data-set control block structure. The related parameters on the ALTER command
are:
RECLAIMCA | NORECLAIMCA
where
RECLAIMCA
Enables CA reclaim for the data set. For CA reclaim to be in effect for the data
set, CA reclaim must also be in effect for the system, either with PARMLIB
member IGDSMSxx or a SETSMS command.
Chapter 10. Optimizing VSAM Performance
179
Optimizing VSAM Performance
NORECLAIMCA
Disables CA reclaim for the data set.
ALTER has no default values. For more information, see the topic about ALTER in
z/OS DFSMS Access Method Services Commands.
The LISTCAT command, in the CLUSTER section, describes the cataloged CA
reclaim attribute for the KSDS. It does not reflect the setting in the IGDSMSxx
member of PARMLIB or the SETSMS command.
In the INDEX section, LISTCAT displays the number of CAs reclaimed, in the
REC-DELETED field, and the number of reclaimed CAs that have been reused
since the KSDS was created, in the REC-INSERTED field. The REC-TOTAL field is
the total number of index records for all index levels, including those that were
reused and are hence in the active index structure, and those that were reclaimed.
Tip
To enable CA reclaim for the majority of data sets, and disable it for just a few
data sets, you could perform the following:
1. Disable CA reclaim for the appropriate data sets by using the ALTER command
with NORECLAIMCA or by defining data sets with a data class for which the
CA reclaim attribute causes CA reclaim to be disabled.
2. Enable CA reclaim for the system either by issuing the SETSMS command or
by modifying PARMLIB member IGDSMSxx and then performing an IPL.
Determining I/O Buffer Space for Nonshared Resource
I/O buffers are used by VSAM to read and write control intervals from DASD to
virtual storage. For a key-sequenced data set or variable-length RRDS, VSAM
requires a minimum of three buffers, two for data control intervals and one for an
index control interval. (One of the data buffers is used only for formatting control
areas and splitting control intervals and control areas.) The VSAM default is
enough space for these three buffers. Only data buffers are needed for
entry-sequenced, fixed-length RRDSs or for linear data sets.
To increase performance, there are parameters to override the VSAM default
values. There are five places where these parameters can be specified:
v BUFFERSPACE, specified in the access method services DEFINE command. This
is the least amount of storage ever provided for I/O buffers.
v BUFSP, BUFNI, and BUFND, specified in the VSAM ACB macro. This is the
maximum amount of storage to be used for a data set's I/O buffers. If the value
specified in the ACB macro is greater than the value specified in DEFINE, the
ACB value overrides the DEFINE value.
v BUFSP, BUFNI, and BUFND, specified in the JCL DD AMP parameter. This is
the maximum amount of storage to be used for a data set's I/O buffers. A value
specified in JCL overrides DEFINE and ACB values if it is greater than the value
specified in DEFINE.
v ACCBIAS specified in the JCL DD AMP parameter. Record access bias has six
specifications:
Parameter
SYSTEM
USER
180
z/OS DFSMS Using Data Sets
Purpose
Force system-managed buffering and let the system determine the buffering
technique based on the ACB MACRF and storage-class specification.
Bypass system-managed buffering.
Optimizing VSAM Performance
Parameter
SO
SW
DO
DW
Purpose
System-managed
System-managed
System-managed
System-managed
buffering
buffering
buffering
buffering
with sequential optimization.
weighted for sequential processing.
with direct optimization.
weighted for direct optimization.
v Record Access Bias specified in the ISMF data class panels. The data class
keyword Record Access Bias has the same six mutually exclusive specifications as
the JCL AMP ACCBIAS shown previously.
VSAM must always have sufficient space available to process the data set as
directed by the specified processing options.
Obtaining Buffers Above 16 MB
To increase the storage area available below 16 MB for your application program,
request VSAM data buffers and VSAM control blocks from virtual storage above
16 MB. To do this, specify the RMODE31 parameter on the ACB macro. See
Chapter 17, “Using 31-Bit Addressing Mode with VSAM,” on page 279.
Optionally, specify RMODE31 in your JCL DD AMP parameter to let the user
override any RMODE31 values specified when the ACB was created. If you do not
specify RMODE31 in the JCL AMP parameter and the ACCBIAS value is the
SYSTEM, then the default value for RMODE31 is BUFF. If the VSAM buffers are
above the 16 MB line and you attempt to access them directly (as in locate mode),
your program must run in 31-bit addressing mode.
If your program must run in 24-bit addressing mode and you need to access
VSAM buffers directly, code RMODE31=NONE in the JCL AMP parameter.
Note: If you are opening multiple ACBS for the same data set and they are
connecting to the same control block structure, the attributes defined in the first
opened ACB will apply. See Chapter 12, “Sharing VSAM Data Sets,” on page 205.
Virtual Storage Constraint Relief
Use the LOCANY parameter on the Hardware Configuration Definition (HCD)
panel to define unit control blocks (UCBs) either above or below the 16 MB line.
Each device attached to the system has one or more UCBs associated with it. To
conserve common virtual storage below the 16 MB line, you can define a UCB for
a device above 16 MB.
Related reading: For more information, see z/OS HCD User's Guide.
Dynamic Allocation Options for Reducing Storage Usage
Related reading: For information on dynamic allocation options for reducing
storage usage with VSAM, see “Allocating Data Sets with Dynamic Allocation” on
page 38 and z/OS MVS Programming: Authorized Assembler Services Guide.
Tuning for System-Managed Buffering
VSAM can use system-managed buffering (SMB) to determine the number of
buffers and the type of buffer management to use for VSAM data sets.
To indicate that VSAM is to use SMB, specify one of the following options:
v Specify the ACCBIAS subparameter of the JCL DD statement AMP parameter
and an appropriate value for record access bias.
Chapter 10. Optimizing VSAM Performance
181
Optimizing VSAM Performance
v Specify Record Access Bias in the data class and an application processing
option in the ACB.
For system-managed buffering (SMB), the data set must use both of the following
options:
v System Management Subsystem (SMS) storage
v Extended format (DSNTYPE=ext in the data class)
JCL takes precedence over the specification in the data class. You must specify
NSR. SMB either weights or optimizes buffer handling toward sequential or direct
processing.
To optimize your extended format data sets, use the ACCBIAS subparameter of the
AMP parameter along with related subparameters SMBVSP, SMBDFR, and
SMBHWT. You can also use these subparameters with Record Access
Bias=SYSTEM in the data class. These subparameters are only for Direct Optimized
processing.
Processing Techniques
The information in this topic is for planning purposes only. It is not absolute or
exact regarding storage requirements. You should use it only as a guideline for
estimating storage requirements. Individual observations might vary depending on
specific implementations and processing.
System-managed buffering (SMB), a feature of DFSMSdfp, supports batch
application processing. SMB takes the following actions:
1. It changes the defaults for processing VSAM data sets. This enables the system
to take better advantage of current and future hardware technology.
2. It initiates a buffering technique to improve application performance. The
technique is one that the application program does not specify.
You can choose or specify any of the four processing techniques that SMB
implements:
v Direct Optimized (DO)
v Sequential Optimized (SO)
v Direct Weighted (DW)
v Sequential Weighted (SW)
Direct Optimized (DO). The DO processing technique optimizes for totally
random record access. This is appropriate for applications that access records in a
data set in totally random order. This technique overrides the user specification for
nonshared resources (NSR) buffering with a local shared resources (LSR)
implementation of buffering.
The following three options, SMBVSP, SMBDFR, and SMBHWT, are only for
processing with the Direct Optimized technique.
v
SMBVSP. This option specifies the amount of virtual storage to obtain for
buffers when a data set is opened. You can specify the virtual buffer size in
kilobytes, from 1K to 2048000K, or in megabytes, from 1M to 2048M. The
SMBVSP parameter can be used to restrict the size of the pool that is built for
the data component.
You can also use SMBVSP to increase the storage amount used for both data
buffer space and index buffer space. VSAM chooses a maximum number of
index buffers, either based on 20% of the SMBVSP value that you specify, or the
182
z/OS DFSMS Using Data Sets
Optimizing VSAM Performance
current data set size. You can use SMBVSP to improve performance when too
few index buffers were allocated for a data set that grows from small to large,
without being closed and reopened over time.
v SMBDFR. This option specifies the deferred write processing. By using
SMBDFR, you can defer writing buffers to the medium until either of the
following situations occur:
– The buffer is required for a different request.
– The data set is closed.
CLOSE TYPE=T does not write the buffers to the medium when the system uses
LSR processing for direct optimization. Defaults for deferred write processing
depend upon the SHAREOPTIONS values that you specify when you define the
data set. The default for SHAREOPTIONS (1,3) and (2,3) is deferred writing. The
default for SHAREOPTIONS (3,3), (4,3), and (x, 4) is non-deferred writing. If you
specify a value for SMBDFR, this value always takes precedence over any
defaults.
v
SMBHWT. This option specifies the range of the decimal value for buffers. You
can specify a whole decimal value from 1-99 for allocating the Hiperspace
buffers. The allocation is based on a multiple of the number of virtual buffers
that have been allocated.
Note:
1. You can specify SMBDFR and SMBHWT through the JCL AMP parameter. See
z/OS MVS JCL Reference for details.
2. You can specify SMBVSP through the ISMF data class. See z/OS DFSMS Using
the Interactive Storage Management Facility for details.
Sequential Optimized (SO). The SO technique optimizes processing for record
access that is in sequential order. This is appropriate for backup and for
applications that read the entire data set or a large percentage of the records in
sequential order.
Direct Weighted (DW). The majority is direct processing; some is sequential. DW
processing provides the minimum read-ahead buffers for sequential retrieval and
the maximum index buffers for direct requests.
Sequential Weighted (SW). The majority is sequential processing; some is direct.
This technique uses read-ahead buffers for sequential requests and provides
additional index buffers for direct requests. The read-ahead will not be as large as
the amount of data transferred with SO.
To implement SMB, an application program must specify nonshared resources
(NSR) buffering, ACB MACRF=(NSR). The system does not apply SMB when any
VSAM data set is opened with a request for any other buffering option,
MACRF=(LSR|GSR|UBF|RLS).
The basis for the default technique is the application specification for ACB
MACRF=(DIR,SEQ,SKP) Also, specification of the following values in the
associated storage class (SC) influence the default technique:
v Direct millisecond response
v Direct bias
v Sequential millisecond response
v Sequential bias
Chapter 10. Optimizing VSAM Performance
183
Optimizing VSAM Performance
You can specify the technique externally by using the ACCBIAS subparameter of
the AMP= parameter. The system invokes the function only during data set OPEN
processing. After SMB makes the initial decisions during that process, it has no
further involvement.
Table 19 is a guideline showing what access bias SMB chooses for certain
parameter specifications.
Table 19. SMB access bias guidelines
BIAS Selection based on ACB MACRF= and Storage Class MSR/BIAS
MACRF Options MSR/BIAS Value Specified in Storage Class
SEQ
DIR
Both
None
DIR
DW
DO
DO
DO
SEQ - default
SO
SW
SO
SO
SKP
DW
DW
DW
DW
(SEQ,SKP)
SO
SW
SW
SW
(DIR,SEQ) or
(DIR,SKP) or
(DIR,SEQ,SKP)
SW
DW
DW
DW
Abbreviations used in this table:
v DO = Direct Optimized
v DW = Direct Weighted
v SO = Sequential Optimized
v SW = Sequential Weighted.
Note: This table can only be used as guideline to show what Access Bias SMB will
choose when ACCBIAS=SYSTEM is specified in JCL AMP parameter, or when
RECORD_ACCESS_BIAS=SYSTEM is specified in Dataclass. There are exceptions
in determining the actual Access Bias. Other factors that can influence the decision
are amount of storage available, whether it is AIX® or Base component, and if DSN
or DDN sharing is in effect.
In the case where ACCBIAS=DO is specifically asked for on JCL AMP parameter,
SMB may default to DW if there is not enough storage. To avoid this situation,
there are two techniques:
1. Allocate more storage for the job.
2. Specify SMBVSP=xx on JCL to limit the amount of storage SMB will use for
DO. For details of how to use SMBVSP, see the related topic.
If you request SMB and specify JCL AMP MSG = SMBBIAS, VSAM Open issues
message IEC161I 001 to indicate which Access Bias is chosen by SMB. The
following output is an example of message IEC161I 001
184
J E S 2
J O B
16.59.12
16.59.12
16.59.12
16.59.12
16.59.24
547
JOB00019
JOB00019
JOB00019
JOB00019
JOB00019
z/OS DFSMS Using Data Sets
L O G --
S Y S T E M 3 0 9 0
-- N O D E S J P L 3 7 2
---- WEDNESDAY, 26 APR 2006 ---IRR010I USERID IBMUSER IS ASSIGNED TO THIS JOB.
ICH70001I IBMUSER LAST ACCESS AT 16:57:04 ON WEDNESDAY, APRIL 26, 2006
$HASP373 OPENCLOS STARTED - INIT 1
- CLASS A - SYS 3090
IEC161I 001(DW)- 255,OPENCLOS,TESTIT,DD1,,,IBMUSER.TEST.BASE1,, 547
IEC161I SYS1.MVSRES.MASTCAT
Optimizing VSAM Performance
Internal Processing Techniques
In addition, two internal techniques support data set creation and load-mode
processing. A user cannot specify these techniques, which the system invokes
internally if the data set is in load mode (HURBA=0) and if the following items
specify the SYSTEM keyword:
v RECORD ACCESS BIAS for the related data class
v ACCBIAS in the AMP= parameter of the data set JCL
The two techniques are Create Optimized (CO) and Create Recovery Optimized
(CR).
Create Optimized (CO): Maximum buffers to optimize load performance if you
specify SPEED in the data definition.
Create Recovery Optimized (CR): Maximum buffers to optimize load performance
if you specify RECOVERY in the data definition.
Processing Guidelines and Restrictions
The following guidelines and restrictions relate to processing with each technique.
Direct Optimized (DO) Guidelines. DO could result in a requirement for the most
additional processor virtual storage. This results in the creation of a local shared
resources (LSR) pool for each data set opened with this technique in a single
application program. The size of the data set is a major factor in the processor
virtual storage requirement for buffering. The size of the pool is based on the
actual data set size at the time the pool is created. This means that the processor
virtual storage requirement increases with each OPEN after records have been
added and the data set has been extended beyond its previous size.
For each data set, a separate pool is built for both data and index components if
applicable. There is no capability to share a single pool by multiple data sets.
However, DSN sharing and DDN sharing is supported. The index pool is sized to
accommodate all records in the index component. The data pool is sized to
accommodate approximately 20% of the user records in the data set. As discussed
previously, this size can change based on data set growth. A maximum pool size
for the data component is identified. These buffers are acquired above the 16 MB
line unless overridden by the use of the RMODE31 parameter.
You can use the SMBVSP parameter to restrict the size of the pool that is built for
the data component or to expand the size of the pool for the index records. The
SMBHWT parameter can be used to provide buffering in Hiperspace in
combination with virtual buffers for the data component. The value of this
parameter is used as a multiplier of the virtual buffer space for Hiperspace buffers.
This can reduce the size required for an application region, but does have
implications related to processor cycle requirements. That is, all application
requests must orient to a virtual buffer address. If the required data is in a
Hiperspace buffer, the data must be moved to a virtual buffer after “stealing” a
virtual buffer and moving that buffer to a least recently used (LRU) Hiperspace
buffer.
If the optimum amount of storage required for this option is not available, SMB
will reduce the number of buffers and retry the request. For data, SMB will make
two attempts, with a reduced amount and a minimum amount. For an index, SMB
reduces the amount of storage only once, to minimum amount. If all attempts fail,
the DW technique is used. The system issues an IEC161I message to advise that
Chapter 10. Optimizing VSAM Performance
185
Optimizing VSAM Performance
this has happened. In addition, SMF type-64 records indicate whether a reduced or
minimum amount of resource is being used for a data pool and whether DW is
used. For more information, see z/OS MVS System Management Facilities (SMF).
Restrictions on the Use of Direct Optimized (DO). The Direct Optimized (DO)
technique is elected if the ACB only specifies the MACRF=(DIR) option for
accessing the data set. If either SEQ|SKP are specified, either in combination with
DIR or independently, DO is not selected. The selection can be overridden by the
user specification of ACCBIAS=DO on the AMP=parameter of the associated DD
statement.
There are some restrictions for the use of the Direct Optimized (DO) technique:
1. The application must position the data set to the beginning for any sequential
processing. This assumes the first retrieval will be set to that point of the data
set.
2. Applications that use multiple strings can hang if the position is held while
other requests process. An example of this is an application that has one
request doing sequential GETs while another request does PUTs.
Sequential Optimized (SO) Guidelines. This technique provides the most efficient
buffers for sequential application processing such as data set backup. The size of
the data set is not a factor in the processor virtual storage that is required for
buffering. The buffering implementation (NSR) specified by the application will not
be changed for this technique. Approximately 500K of processor virtual storage for
buffers, defaulted to above 16 MB, is required for this technique.
Direct Weighted (DW) Guidelines. This technique is applicable for applications in
which the requests to the records in a VSAM data set are random for the majority
of the accesses. In addition, it might also give some sequential performance
improvement above VSAM defaults.
The size of the data set is a minor factor in the storage that is required for
buffering. This technique does not change the buffering implementation that the
application specified (NSR). This technique requires approximately 100K of
processor storage for buffers, with a default of 16 MB.
Sequential Weighted (SW) Guidelines. This technique is applicable for
applications where the requests to the records in a VSAM data set are sequential
for the majority of the accesses. In addition, this technique might give some direct
performance improvement over VSAM defaults.
The size of the data set is a minor factor in the amount of processor virtual storage
that buffering requires. This technique does not change the buffering
implementation that the application specified (NSR). This technique requires
approximately 100K of processor virtual storage for buffers, with the default above
16 MB.
Create Optimized (CO) Guidelines. This is the most efficient technique, as far as
physical I/Os to the data component, for loading a VSAM data set. It only applies
when the data set is in initial load status and when defined with the SPEED
option. The system invokes it internally, with no user control other than the
specification of RECORD ACCESS BIAS in the data class or an AMP=(ACCBIAS=)
value of SYSTEM.
186
z/OS DFSMS Using Data Sets
Optimizing VSAM Performance
The size of the data set is not a factor in the amount of storage that buffering
requires. This technique does not change the buffering implementation that the
application specified (NSR). This technique requires a maximum of approximately
2 MB of processor virtual storage for buffers, with the default above 16 MB.
Create Recovery Optimized (CR) Guidelines. The system uses this technique
when a data set defined with the RECOVERY option is in initial load status. The
system invokes CR internally, with no user control other than the specification of
RECORD ACCESS BIAS in the data class or an AMP=(ACCBIAS=) value of
SYSTEM.
The size of the data set is not a factor in the amount of storage that buffering
requires. This technique does not change the buffering implementation that the
application specified (NSR). This technique requires a maximum of approximately
1 MB of processor virtual storage for buffers, with the default above 16 MB.
To determine the final SMB processing technique and additional resource-handling
information related to SMB, examine SMF type 64 records. This is mainly for
diagnostic purposes because SMF type 64 records are gathered during the CLOSE
processing of a data set. For more information on SMF records, see z/OS MVS
System Management Facilities (SMF).
General Considerations for the Use of SMB
The following factors affect storage requirements for SMB buffers:
v Number of VSAM data sets opened for SMB within a single application program
v Chosen or specified technique
v Data set size for some techniques
The storage for buffers for SMB techniques is obtained above 16 MB. If the
application runs as AMODE=RMODE=24 and issues locate-mode requests (RPL
OPTCD=(,LOC)), the AMP= parameter must specify RMODE31=NONE for data
sets that use SMB.
SMB might not be the answer to all application program buffering requirements.
The main purpose of SMB is to improve performance buffering options for batch
application processing, beyond the options that the standard defaults provide. In
the case of many large data sets and apparently random access to records, it might
be better to implement a technique within the application program to share a
common resource pool. The application program designer might know the access
technique for the data set, but SMB cannot predict it. In such applications, it would
be better to let the application program designer define the size and number of
buffers for each pool. This is not unlike the requirements of high-performance
database systems.
Allocating Buffers for Concurrent Data Set Positioning
To calculate the number of buffers you need, you must determine the number of
strings you will use. A string is a request to a VSAM data set requiring data set
positioning. If different concurrent accesses to the same data set are necessary,
multiple strings are used. If multiple strings are used, each string requires
exclusive control of an index I/O buffer. Therefore, the value specified for the
STRNO parameter (in the ACB or GENCB macro, or AMP parameter) is the
minimum number of index I/O buffers required when requests that require
concurrent positioning are issued.
Chapter 10. Optimizing VSAM Performance
187
Optimizing VSAM Performance
Allocating Buffers for Direct Access
For a key-sequenced data set or variable-length RRDS, increase performance for
direct processing by increasing the number of index buffers. Direct processing
always requires a top-down search through the index. Many data buffers do not
increase performance, because only one data buffer is used for each access.
Data Buffers for Direct Access
Because VSAM does not read ahead buffers for direct processing, only the
minimum number of data buffers are needed. Only one data buffer is used for
each access. If you specify more data buffers than the minimum, this has little
beneficial effect.
The one case where extra buffers can provide a benefit is for chained I/O for
spanned records. For more information, see “Acquiring Buffers” on page 191.
When processing a data set directly, VSAM reads only one data control interval at
a time. For output processing (PUT for update), VSAM immediately writes the
updated control interval, if OPTCD=NSP is not specified in the RPL macro.
Index Buffers for Direct Access
If the number of I/O buffers provided for index records is greater than the number
of requests that require concurrent positioning (STRNO), one buffer is used for the
highest-level index record. Any additional buffers are used, as required, for other
index-set index records. With direct access, you should provide at least enough
index buffers to be equal to the value of the STRNO parameter of the ACB, plus
one if you want VSAM to keep the highest-level index record always resident.
Unused index buffers do not degrade performance, so you should always specify
an adequate number. For optimum performance, the number of index buffers
should at least equal the number of high-level index set control intervals plus one
per string to contain the entire high-level index set and one sequence set control
interval per string in virtual storage.
VSAM reads index buffers one at a time, and if you use shared resources, keep
your entire index set in storage. Index buffers are loaded when the index is
referred to. When many index buffers are provided, index buffers are not reused
until a requested index control interval is not in storage. Note that additional index
buffers is not used for more than one sequence set buffer per string unless shared
resource pools are used. For large data sets, specify the number of index buffers
equal to the number of index levels.
VSAM keeps as many index-set records as the buffer space allows in virtual
storage. Ideally, the index would be small enough to permit the entire index set to
remain in virtual storage. Because the characteristics of the data set cannot allow a
small index, you should be aware of how an index I/O buffers is used to
determine how many to provide.
Example of Buffer Allocation for Direct Access
The following example (see Figure 23 on page 189), demonstrates how buffers are
scheduled for direct access. Assume the following:
v Two strings
v Three-level index structure as shown
v Three data buffers (one for each string, and one for splits)
v Four index buffers (one for highest level of index, one for second level, and one
for each string)
188
z/OS DFSMS Using Data Sets
Optimizing VSAM Performance
Figure 23. Scheduling Buffers for Direct Access
The following requests happen.
Request 1. A control interval from CA2 is requested by string 1.
v The highest level index set, IS1, is read into an index buffer. IS1 remains in this
buffer for all requests.
v IS1 points to IS2, that is read into a second index buffer.
v IS2 points to the sequence set, SS2, that is read into an index buffer for string 1.
v SS2 points to a control interval in CA2. This control interval is read into a data
buffer for string 1.
Request 2. A control interval from CA3 is requested by string 2.
v IS1 and IS2 remain in their respective buffers.
v SS3 is read into an index buffer for string 2.
v SS3 points to a control interval in CA3. This control interval is read into a data
buffer for string 2.
Request 3. The first control interval in CA6 is requested by string 1.
v IS1 remains in its buffer.
v Since IS1 now points to IS3, IS3 is read into the second index buffer, replacing
IS2.
Chapter 10. Optimizing VSAM Performance
189
Optimizing VSAM Performance
v SS6 is read into an index buffer for string 1.
v SS6 points to the first control interval in CA6. This control interval is read into a
data buffer for string 1.
Request 4. The first control interval in CA6 is now requested by string 2.
v IS1 and IS3 remain in their respective buffers.
v SS6 is read into an index buffer for string 2.
v SS6 points to the first control interval in CA6. This control interval is read into a
data buffer for string 2.
v If the string 1 request for this control interval was a GET for update, the control
interval would be held in exclusive control, and string 2 would not be able to
access it.
Suggested number of buffers for direct processing:
Index buffers
Minimum = STRNO
Maximum = Number of Index Set Records + STRNO
Data buffers
STRNO + 1
Allocating Buffers for Sequential Access
When you are accessing data sequentially, increase performance by increasing the
number of data buffers. When there are multiple data buffers, VSAM uses a
read-ahead function to read the next data control intervals into buffers before they
are needed. Having only one index I/O buffer does not hinder performance,
because VSAM gets to the next control interval by using the horizontal pointers in
sequence set records rather than the vertical pointers in the index set. Extra index
buffers have little effect during sequential processing.
Suggested number of buffers for initial load mode processing:
Index buffers = 3
Data buffers = 2 * (number of Data CI/CA)
For straight sequential processing environments, start with four data buffers per
string. One buffer is used only for formatting control areas and splitting control
intervals and control areas. The other three are used to support the read-ahead
function, so that sequential control intervals are placed in buffers before any
records from the control interval are requested. By specifying enough data buffers,
you can access the same amount of data per I/O operation with small data control
intervals as with large data control intervals.
When SHAREOPTIONS 4 is specified for the data set, the read-ahead function can
be ineffective because the buffers are refreshed when each control interval is read.
Therefore, for SHAREOPTIONS 4, keeping data buffers at a minimum can actually
improve performance.
If you experience a performance problem waiting for input from the device, you
should specify more data buffers to improve your job's run time. More data buffers
let you do more read-ahead processing. An excessive number of buffers, however,
can cause performance problems, because of excessive paging.
For mixed processing situations (sequential and direct), start with two data buffers
per string and increase BUFND to three per string, if paging is not a problem.
190
z/OS DFSMS Using Data Sets
Optimizing VSAM Performance
When processing the data set sequentially, VSAM reads ahead as buffers become
available. For output processing (PUT for update), VSAM does not immediately
write the updated control interval from the buffer unless a control interval split is
required. The POINT macro does not cause read-ahead processing unless RPL
OPTCD=SEQ is specified; POINT positions the data set for subsequent sequential
retrieval.
Suggested number of buffers for sequential access:
Index buffers = STRNO
Data buffers = 3 + STRNO (minimum)
Allocating Buffers for a Path
Processing data sets using a path can increase the number of buffers that need to
be allocated, since buffers are needed for the alternate index, the base cluster, and
any alternate indexes in the upgrade set.
The BUFSP, BUFND, BUFNI, and STRNO parameters apply only to the path's
alternate index when the base cluster is opened for processing with its alternate
index. The minimum number of buffers are allocated to the base cluster unless the
cluster's BUFFERSPACE value (specified in the DEFINE command) or BSTRNO
value (specified in the ACB macro) permits more buffers. VSAM assumes direct
processing and extra buffers are allocated between data and index components
accordingly.
Two data buffers and one index buffer are always allocated for each alternate
index in the upgrade set. If the path's alternate index is a member of the upgrade
set, the minimum buffer increase for each allocation is one for data buffers and one
for index buffers. Buffers are allocated to the alternate index as though it were a
key-sequenced data set. When a path is opened for output and the path alternate
index is in the upgrade set, specify ACB MACRF=DSN and the path alternate
index shares buffers with the upgrade alternate index.
VSAM alternate indexes have spanned records by default. They can benefit from
having extra buffers allocated, to allow for chained I/O of the spanned records.
For more information, see “Acquiring Buffers.”
Acquiring Buffers
Data and index buffers are acquired and allocated when the data set is opened.
VSAM allocates buffers based on parameters in effect when the program opens the
data set. Parameters that influence the buffer allocation are in the program's ACB:
MACRF=(IN|OUT, SEQ|SKP, DIR), STRNO=n, BUFSP=n, BUFND=n, and
BUFNI=n. Other parameters that influence buffer allocation are in the DD
statement's AMP specification for BUFSP, BUFND, and BUFNI, and the
BUFFERSPACE value in the data set's catalog record.
If you open a data set whose ACB includes MACRF=(SEQ,DIR), buffers are
allocated according to the rules for sequential processing. If the RPL is modified
later in the program, the buffers allocated when the data set was opened do not
change.
For spanned records with NSR, if there are enough extra buffers defined for the
data set, VSAM attempts to write all segments of the entire spanned record out to
DASD with one single I/O (chained I/O), to improve integrity and I/O
performance. If there are not enough extra buffers available, VSAM writes each
spanned record segment separately. When segments are written separately, the
Chapter 10. Optimizing VSAM Performance
191
Optimizing VSAM Performance
record might be left in an inconsistent state if the process is interrupted before
completion. VSAM provides chained I/O for spanned records during PUT,
UPD/INSERT, and ERASE operations, with NSR processing. If you update or erase
VSAM data sets with spanned records, defining enough extra data buffers to allow
completion in a single chained I/O can reduce the risk of inconsistent results. This
chaining of I/O for all segments of the spanned record applies to VSAM alternate
indexes which are spanned by default.
Data and index buffer allocation (BUFND and BUFNI) can be specified only by the
user with access to modify the ACB parameters, or through the AMP parameter of
the DD statement. Any program can be assigned additional buffer space by
modifying the data set's BUFFERSPACE value, or by specifying a larger BUFSP
value with the AMP parameter in the data set's DD statement.
When a buffer's contents are written, the buffer's space is not released. The control
interval remains in storage until overwritten with a new control interval; if your
program refers to that control interval, VSAM does not have to reread it. VSAM
checks to see if the desired control interval is in storage, when your program
processes records in a limited key range, you might increase throughput by
providing extra data buffers. Buffer space is released when the data set is closed.
Recommendation: Try to have data available just before it is to be used. If data is
read into buffers too far ahead of its use in the program, it can be paged out. More
data or index buffers than necessary might cause excessive paging or excessive
internal processing. There is an optimum point at which more buffers will not
help.
Using Index Options
The following options influence performance when using the index of a
key-sequenced data set or variable-length RRDS. Each option improves
performance, but some require that you provide additional virtual storage or
auxiliary storage space. The options are:
v Specifying enough virtual storage to contain all index-set records (if you are
using shared resources).
v Ensuring that the index control interval is large enough to contain the key of
each control interval in the control area.
v Placing the index and the data set on separate volumes.
Increasing Virtual Storage for Index Set Records
To retrieve a record from a key-sequenced data set or variable-length RRDS, or
store a record using keyed access, VSAM needs to examine the index of that data
set. Before your processing program begins to process the data set, it must specify
the amount of virtual storage it is providing for VSAM to buffer index records. The
minimum is enough space for one I/O buffer for index records, but a serious
performance problem would occur if an index record were continually deleted
from virtual storage to make room for another, and retrieved again later when it is
required. Ample buffer space for index records can improve performance.
You ensure virtual storage for index-set records by specifying enough virtual
storage for index I/O buffers when you begin to process a key-sequenced data set
or variable-length RRDS. VSAM keeps as many index-set records in virtual storage
as possible. Whenever an index record must be retrieved to locate a data record,
VSAM makes room for it by deleting the index record that VSAM judges to be
least useful under the prevailing circumstances. It is generally the index record that
192
z/OS DFSMS Using Data Sets
Optimizing VSAM Performance
belongs to the lowest index level or that has been used the least. VSAM does not
keep more than one sequence set index record per string unless shared resource
pools are used.
Avoiding Control Area Splits
The second option you might consider is to ensure that the index-set control
interval is large enough to contain the key of each control interval in the control
area. This reduces the number of control area splits. This option also keeps to a
minimum the number of index levels required, thereby reducing search time and
improving performance. However, this option can increase rotational delay and
data transfer time for the index-set control intervals. It also increases virtual
storage requirements for index records.
Putting the Index and Data on Separate Volumes
This information applies to non-SMS-managed volumes. With SMS-managed
volumes, SMS selects the volumes. When a key-sequenced data set or
variable-length RRDS is defined, the entire index or the high-level index set alone
can be placed on a volume separate from the data, either on the same or on a
different type of device.
Using different volumes lets VSAM gain access to an index and to data at the same
time. Also, the smaller amount of space required for an index makes it economical
to use a faster storage device for it.
A performance improvement due to separate volumes generally requires
asynchronous processing or multitasking with multiple strings.
Obtaining Diagnostic Information
For information about the generalized trace facility (GTF) and other VSAM
diagnostic aids, see z/OS DFSMSdfp Diagnosis. The trace is very useful for trying to
determine what VSAM is being asked to do.
Migrating from the Mass Storage System
Because MSS is no longer supported, you need to migrate the data off MSS. If you
issue the ACQRANGE, CNVTAD, or MNTACQ macros, you receive a return code
of 0 and a reason code of 20, that means these macros are no longer supported.
Using Hiperbatch
Hiperbatch is a VSAM extension designed to improve performance in specific
situations. It uses the data lookaside facility (DLF) services in MVS to provide an
alternate fast path method of making data available to many batch jobs. Through
Hiperbatch, applications can take advantage of the performance benefits of MVS
without changing existing application programs or the JCL used to run them. For
more information about using Hiperbatch, see MVS Hiperbatch Guide.
Note: Effective with DFSMS in z/OS 1.3 and above, VSAM clusters defined as
extended format or extended addressable may use Hiperbatch.
Chapter 10. Optimizing VSAM Performance
193
Optimizing VSAM Performance
194
z/OS DFSMS Using Data Sets
Chapter 11. Processing Control Intervals
This topic covers the following subtopics.
Topic
“Access to a Control Interval” on page 196
“Structure of Control Information” on page 197
“User Buffering” on page 202
“Improved Control Interval Access” on page 202
“Control Blocks in Common (CBIC) Option” on page 203
Control interval access gives you access to the contents of a control interval; keyed
access and addressed access give you access to individual data records.
Restriction: You cannot use control interval access to access a compressed data set.
The data set can be opened for control interval access to permit VERIFY and
VERIFY REFRESH processing only.
With control interval access, you have the option of letting VSAM manage I/O
buffers or managing them yourself (user buffering). Unless you specify user
buffering, VSAM buffers obtained at OPEN time are used for reading or writing
the control intervals. With keyed and addressed access, VSAM always manages
I/O buffers. If you select user buffering, you have the further option of using
improved control interval access, which provides faster processing than normal
control interval access. With user buffering, only control interval processing is
permitted. See “Improved Control Interval Access” on page 202.
Control interval access permits greater flexibility in processing entry-sequenced
data sets. With control interval access, change the RBAs of records in a control
interval and delete records by modifying the RDFs and the CIDF.
When using control interval processing, you are responsible for maintaining
alternate indexes. If you have specified keyed or addressed access (ACB
MACRF={KEY|ADR},...) and control interval access, then those requests for keyed
or addressed access (RPL OPTCD={ KEY|ADR},...) cause VSAM to upgrade the
alternate indexes. Those requests specifying control interval access will not
upgrade the alternate indexes. You are responsible for upgrading them. Upgrading
an alternate index is described in “Maintaining Alternate Indexes” on page 136.
Restriction: You should not update key-sequenced data sets or variable-length
RRDSs with control interval access. You cannot use control interval access with
compressed format data sets. When you process control intervals, you are
responsible for how your processing affects indexes, RDFs, and CIDFs. Bypassing
use of the control information in the CIDF and RDFs can make the control interval
unusable for record level processing. For instance, key-sequenced data sets depend
on the accuracy of their indexes and the RDFs and the CIDF in each control
interval.
© Copyright IBM Corp. 1987, 2017
195
Processing Control Intervals
Access to a Control Interval
Control interval access is specified entirely by the ACB MACRF parameter and the
RPL (or GENCB) OPTCD parameter. To prepare for opening a data set for control
interval access with VSAM managing I/O buffers, specify:
ACB
MACRF=(CNV,...),...
With NUB (no user buffering) and NCI (normal control interval access), specify in
the MACRF parameter that the data set is to be opened for keyed and addressed
access, and for control interval access. For example, MACRF=(CNV, KEY, SKP, DIR,
SEQ, NUB, NCI, OUT) is a valid combination of subparameters.
You define a particular request for control interval access by coding:
RPL
OPTCD=(CNV,...),...
Usually, control interval access with no user buffering has the same freedoms and
limitations as keyed and addressed access have. Control interval access can be
synchronous or asynchronous, can have the contents of a control interval moved to
your work area (OPTCD=MVE) or left in VSAM's I/O buffer (OPTCD=LOC), and
can be defined by a chain of request parameter lists (except with OPTCD=LOC
specified). A sequential GET without user buffering adds additional, existing
buffers for the RPL to allow for read-ahead processing.
Except for ERASE, all the request macros (GET, PUT, POINT, CHECK, and
ENDREQ) can be used for normal control interval access. To update the contents of
a control interval, you must (with no user buffering) previously have retrieved the
contents for update. You cannot alter the contents of a control interval with
OPTCD=LOC specified.
Both direct and sequential access can be used with control interval access, but skip
sequential access may not. That is, specify OPTCD=(CNV,DIR) or (CNV,SEQ), but
not OPTCD=(CNV,SKP).
With sequential access, VSAM takes an EODAD exit when you try to retrieve the
control interval whose CIDF is filled with 0s or, if there is no such control interval,
when you try to retrieve a control interval beyond the last one. A control interval
with such a CIDF contains no data or unused space, and is used to represent the
software end-of-file. However, VSAM control interval processing does not prevent
you from using a direct GET or a POINT and a sequential GET to retrieve the
software end-of-file. The search argument for a direct request with control interval
access is the RBA of the control interval whose contents are desired.
The RPL (or GENCB) parameters AREA and AREALEN have the same use for
control interval access related to OPTCD=MVE or LOC as they do for keyed and
addressed access. With OPTCD=MVE, AREA gives the address of the area into
which VSAM moves the contents of a control interval. With OPTCD=LOC, AREA
gives the address of the area into which VSAM puts the address of the I/O buffer
containing the contents of the control interval.
You can load an entry-sequenced data set with control interval access. If you open
an empty entry-sequenced data set, VSAM lets you use only sequential storage.
That is, issue only PUTs, with OPTCD=(CNV,SEQ,NUP). PUT with OPTCD=NUP
stores information in the next available control interval (at the end of the data set).
196
z/OS DFSMS Using Data Sets
Processing Control Intervals
You cannot load or extend a data set with improved control interval access. VSAM
also prohibits you from extending a fixed-length or variable-length RRDS through
normal control interval access.
Update the contents of a control interval in one of two ways:
v Retrieve the contents with OPTCD=UPD and store them back. In this case, the
RBA of the control interval is specified during the GET for the control interval.
v Without retrieving the contents, store new contents in the control interval with
OPTCD=UPD. (You must specify UBF for user buffering.) Because no GET (or a
GET with OPTCD=NUP) precedes the PUT, you have to specify the RBA of the
control interval as the argument addressed by the RPL.
Structure of Control Information
With keyed access and addressed access, VSAM maintains the control information
in a control interval. With control interval access, you are responsible for that
information.
Note: A linear data set has no control information imbedded in the control
interval. All of the bytes in the control interval are data bytes; there are no CIDFs
or RDFs.
Figure 24 shows the relative positions of data, unused space, and control
information in a control interval.
Figure 24. General Format of a Control Interval
For more information about the structure of a control interval, see “Control
Intervals” on page 86.
Control information consists of a CIDF (control interval definition field) and, for a
control interval containing at least one record, record slot, or record segment, one
or more RDFs (record definition fields). The CIDF and RDFs are ordered from right
to left. The format of the CIDF is the same even if the control interval size contains
multiple smaller physical records.
CIDF—Control Interval Definition Field
The CIDF is a 4-byte field that contains two 2-byte binary numbers.
Offset Length
Description
0(0)
The displacement from the beginning of the control interval to the
beginning of the unused space, or, if there is no unused space, to the
beginning of the control information. The displacement is equal to
the length of the data (records, record slots, or record segment). In a
control interval without data, the number is 0.
2
Chapter 11. Processing Control Intervals
197
Processing Control Intervals
Offset Length
Description
2(2)
2
The length of the unused space. This number is equal to the length
of the control interval, minus the length of the control information,
minus the 2-byte value at CIDF+0. In a control interval without data
(records, record slots, or record segment), the number is the length
of the control interval, minus 4 (the length of the CIDF; there are no
RDFs). In a control interval without unused space, the number is 0.
2(2)
1... ....
Busy flag; set when the control interval is being split; reset when the
split is complete.
In an entry-sequenced data set, when there are unused control intervals beyond the
last one that contains data, the first of the unused control intervals contains a CIDF
filled with 0s. In a key-sequenced data set or an RRDS, the first control interval in
the first unused control area (if any) contains a CIDF filled with 0s. A CIDF filled
with 0s represents the software end-of-file.
RDF—Record Definition Field
The RBAs of records or relative record numbers of slots in a control interval ascend
from left to right. RDFs from right to left describe these records or slots or a
segment of a spanned record. RDFs describe records one way for key-sequenced
data sets, entry-sequenced data sets, and variable-length RRDSs, and another way
for fixed-length RRDSs.
In a key-sequenced or entry-sequenced data set, records might vary in length and
can span control intervals. In a variable-length RRDS, records vary in length but do
not span control intervals.
v A nonspanned record with no other records of the same length next to it is
described by a single RDF that gives the length of the record.
v Two or more consecutive nonspanned records of the same length are described
by a pair of RDFs. The RDF on the right gives the length of each record, and the
RDF on the left gives the number of consecutive records of the same length.
v Each segment of a spanned record (one segment per control interval) is
described by a pair of RDFs. The RDF on the right gives the length of the
segment, and the RDF on the left gives its update number. (The update number
in each segment is incremented by one each time a spanned record is updated.
A difference among update numbers within a spanned record means a possible
error in the record.)
In a fixed-length RRDS, records do not vary in length or span control intervals.
Each record slot is described by a single RDF that gives its length and indicates if
it contains a record.
An RDF is a 3-byte field that contains a 1-byte control field and a 2-byte binary
number, as the following table shows.
198
Length and
Offset Bit Pattern
Description
0(0)
1
Control Field.
x... ..xx
Reserved.
.x.. ....
Indicates whether there is (1) or is not (0) a paired RDF to the left of
this RDF.
z/OS DFSMS Using Data Sets
Processing Control Intervals
Length and
Offset Bit Pattern
..xx ....
.... x...
1(1)
Description
Indicates whether the record spans control intervals:
00
No.
01
Yes; this is the first segment.
10
Yes; this is the last segment.
11
Yes; this is an intermediate segment.
Indicates what the 2-byte binary number gives:
0
The length of the record, segment, or slot described by this
RDF.
1
The number of consecutive nonspanned records of the same
length, or the update number of the segment of a spanned
record.
.... .x..
For a fixed-length RRDS, indicates whether the slot described by this
RDF does (0) or does not (1) contain a record.
2
Binary number:
v When bit 4 of byte 0 is 0, gives the length of the record, segment,
or slot described by this RDF.
v When bit 4 of byte 0 is 1 and bits 2 and 3 of byte 0 are 0, gives
the number of consecutive records of the same length.
v When bit 4 of byte 0 is 1 and bits 2 and 3 of byte 0 are not 0,
gives the update number of the segment described by this RDF.
Control field values for nonspanned key-sequenced,
entry-sequenced, and variable-length relative record data sets
In a key-sequenced, entry-sequenced data set, or variable-length RRDS with
nonspanned records, the possible hexadecimal values in the control field of an RDF
follow.
Left RDF
X'08'
Right RDF
Description
X'00'
The RDF at X'00' gives the length of a single
nonspanned record.
X'40'
The right RDF gives the length of each of two or
more consecutive nonspanned records of the same
length. The left RDF gives the number of consecutive
nonspanned records of the same length.
Figure 25 on page 200 shows the contents of the CIDF and RDFs of a 512-byte
control interval containing nonspanned records of different lengths.
Chapter 11. Processing Control Intervals
199
Processing Control Intervals
Length
a
a
R1
R3
R2
R5
R4
X’00’
2a
R5
3a
496-8a
2a
RDF3
RDF4
X’00’
3a
a
12
FREE SPACE
RDF2
X’08’
RDFs
4
C
I
D
F
CIDF
RDF1
3
X’40’
a
8a
4968a
R1 through R3
R4
a = Unit of length
Figure 25. Format of Control Information for Nonspanned Records
The four RDFs and the CIDF comprise 16 bytes of control information as follows:
v RDF4 describes the fifth record.
v RDF3 describes the fourth record.
v RDF2 and RDF1 describe the first three records.
v The first 2-byte field in the CIDF gives the total length of the five records-8a,
which is the displacement from the beginning of the control interval to the free
space.
v The second 2-byte field gives the length of the free space, which is the length of
the control interval minus the total length of the records and the control
information-512 minus 8a minus 16, or 496 minus 8a.
Control field values for spanned key-sequenced and
entry-sequenced data sets
A control interval that contains the record segment of a spanned record contains no
other data; it always has two RDFs. The possible hexadecimal values in their
control fields follow.
200
Left RDF
Right RDF
Description
X'18'
X'50'
The right RDF gives the length of the first segment of
a spanned record. The left RDF gives the update
number of the segment.
X'28'
X'60'
The right RDF gives the length of the last segment of
a spanned record. The left RDF gives the update
number of the segment.
X'38'
X'70'
The right RDF gives the length of an intermediate
segment of a spanned record. The left RDF gives the
update number of the segment.
z/OS DFSMS Using Data Sets
Processing Control Intervals
Figure 26 shows contents of the CIDF and RDFs for a spanned record with a length
of 1306 bytes.
Figure 26. Format of Control Information for Spanned Records
There are three 512-byte control intervals that contain the segments of the record.
The number “n” in RDF2 is the update number. Only the control interval that
contains the last segment of a spanned record can have free space. Each of the
other segments uses all but the last 10 bytes of a control interval.
In a key-sequenced data set, the control intervals might not be contiguous or in the
same order as the segments (for example, the RBA of the second segment can be
lower than the RBA of the first segment).
All the segments of a spanned record must be in the same control area. When a
control area does not have enough control intervals available for a spanned record,
the entire record is stored in a new control area.
Control Field Values for Fixed-Length Relative-Record Data Sets
In a fixed-length RRDS, the possible hexadecimal values in the control field of an
RDF are:
X'04'
The RDF at X'04' gives the length of an empty slot.
X'00'
The RDF at X'00' gives the length of a slot that contains a record.
Every control interval in a fixed-length RRDS contains the same number of slots
and the same number of RDFs; one for each slot. The first slot is described by the
rightmost RDF. The second slot is described by the next RDF to the left, and so on.
Chapter 11. Processing Control Intervals
201
Processing Control Intervals
User Buffering
With control interval access, you have the option of user buffering. If you use the
user buffering option, you need to provide buffers in your own area of storage for
use by VSAM.
User buffering is required for improved control interval access (ICI).
With ACB MACRF=(CNV,UBF) specified (control interval access with user
buffering), the work area specified by the RPL (or GENCB) AREA parameter is, in
effect, the I/O buffer. VSAM transmits the contents of a control interval directly
between the work area and direct access storage. If ACB MACRF specifies UBF,
only one CI may be read or written.
User buffering without ICI does not require a GET UPD to precede a PUT UPD or
ERASE.
If you specify user buffering, you cannot specify KEY or ADR in the MACRF
parameter; you can only specify CNV. That is, you cannot intermix keyed and
addressed requests with requests for control interval access.
OPTCD=LOC is inconsistent with user buffering and is not permitted.
Improved Control Interval Access
Improved control interval access (ICI) is faster than normal control interval access;
however, you can only have one control interval scheduled at a time. Improved
control interval access works well for direct processing.
To use ICI, you have to specify user buffering (UBF), which provides the option of
specifying improved control interval access:
ACB
MACRF=(CNV,UBF,ICI,...),...
You cannot load or extend a data set using ICI. Improved control interval
processing is not permitted for extended format data sets.
A processing program can achieve the best performance with improved control
interval access by combining it with SRB dispatching. SRB dispatching is described
in z/OS MVS Programming: Authorized Assembler Services Guide and “Operating in
SRB or Cross-Memory Mode” on page 164.
Opening an Object for Improved Control Interval Access
Improved control interval processing is faster because functions have been
removed from the path. However, improved control interval processing causes
several restrictions:
v The object must not be empty.
v The object must not be compressed.
v The object must be one of the following:
– An entry-sequenced, fixed-length, or variable-length RRDS cluster.
– The data component of an entry-sequenced, key-sequenced, linear,
fixed-length, or variable-length RRDS cluster.
– The index component of a key-sequenced cluster (index records must not be
replicated).
202
z/OS DFSMS Using Data Sets
Processing Control Intervals
v Control intervals must be the same size as physical records. When you use the
access method services DEFINE command to define the object, specify control
interval size equal to a physical record size used for the device on which the
object is stored. VSAM uses physical record sizes of (n x 512) and (n x 2048),
where n is a positive integer from 1 to 16. The physical record size is always
equal to the control interval size for an index component.
Processing a Data Set with Improved Control Interval Access
To process a data set with improved control interval access, a request must be:
v Defined by a single RPL (VSAM ignores the NXTRPL parameter).
v A direct GET, GET for update, or PUT for update (no POINT, no processing
empty data sets). A RRDS with slots formatted is considered not to be empty,
even if no slot contains a record.
v Synchronous (no CHECK, no ENDREQ).
To release exclusive control after a GET for update, you must issue a PUT for
update, a GET without update, or a GET for update for a different control interval.
With improved control interval access, the following assumptions are in effect for
VSAM (with no checking):
v An RPL whose ACB has MACRF=ICI has OPTCD=(CNV, DIR, SYN).
v A PUT is for update (RPL OPTCD=UPD).
v Your buffer length (specified in RPL AREALEN=number) is correct.
Because VSAM does not check these parameters, you should debug your program
with ACB MACRF=NCI, then change to ICI.
With improved control interval access, VSAM does not take JRNAD exits and does
not keep statistics (which are normally available through SHOWCB).
Fixing Control Blocks and Buffers in Real Storage
With improved control interval access, you can specify that control blocks are to be
fixed in real storage (ACB MACRF=(CFX,...)). If you so specify, your I/O buffers
must also be fixed in real storage. Having your control blocks fixed in real storage,
but not your I/O buffers, can cause physical errors or unpredictable results. If you
specify MACRF=CFX without ICI, VSAM ignores CFX. NFX is the default; it
indicates that buffers are not fixed in real storage, except for an I/O operation. A
program must be authorized to fix pages in real storage, either in supervisor state
with protection key 0 - 7, or link-edited with authorization. (The authorized
program facility (APF) is described in z/OS MVS Programming: Authorized Assembler
Services Guide). An unauthorized request is ignored.
You can use 64-bit real storage for all VSAM data sets, whether they are
extended-format data sets. You can obtain buffer storage from any real address
location available to the processor. The location can have a real address greater
than 2 gigabytes or can be in 31-bit real storage with a real address less than 2
gigabytes.
Control Blocks in Common (CBIC) Option
When you are using improved control interval processing, the CBIC option lets
you have multiple address spaces that address the same data and use the same
control block structure. The VSAM control blocks associated with a VSAM data set
are placed into the common service area (CSA). The control block structure and
Chapter 11. Processing Control Intervals
203
Processing Control Intervals
VSAM I/O operations are essentially the same whether the CBIC option is
invoked, except for the location of the control block structure. The user-related
control blocks are generated in the protect key (0 - 7). The system-related control
blocks are generated in protect key 0. The VSAM control block structure generated
when the CBIC option is invoked retains normal interfaces to the address space
that opened the VSAM data set (for example, the DEB is chained to the address
space's TCB).
The CBIC option is invoked when a VSAM data set is opened. To invoke the CBIC
option, you set the CBIC flag (located at offset X'33' (ACBINFL2) in the ACB, bit 2
(ACBCBIC)) to one. When your program opens the ACB with the CBIC option set,
your program must be in supervisor state with a protect key from 0 to 7.
Otherwise, VSAM will not open the data set.
The following restrictions apply to using the CBIC option:
v The CBIC option must be used only when the ICI option is also specified.
v You cannot also specify LSR or GSR.
v You cannot use the following types of data sets with the CBIC option: catalogs,
catalog recovery areas, swap data sets, or system data sets.
v If an address space has opened a VSAM data set with the CBIC option, your
program cannot take a checkpoint for that address space.
If another address space accesses the data set's control block structure in the
CSA through VSAM record management, the following conditions should be
observed:
v An OPEN macro should not be issued against the data set.
v The ACB of the user who opened the data set with the CBIC option must be
used.
v CLOSE and temporary CLOSE cannot be issued for the data set (only the user
who opened the data set with the CBIC option can close the data set).
v The address space accessing the data set control block structure must have the
same storage protect key as the user who opened the data set with the CBIC
option.
v User exit routines should be accessible from all address spaces accessing the data
set with the CBIC option.
204
z/OS DFSMS Using Data Sets
Chapter 12. Sharing VSAM Data Sets
This topic explains how to share data sets within a single system and among
multiple systems. It also describes considerations for sharing VSAM data sets for
NSR or LSR/GSR access. For considerations about sharing VSAM data sets for RLS
access, see Chapter 14, “Using VSAM Record-Level Sharing,” on page 233.
This topic covers the following subtopics.
Topic
“Subtask Sharing” on page 206
“Cross-Region Sharing” on page 211
“Cross-System Sharing” on page 214
“Control Block Update Facility (CBUF)” on page 215
“Techniques of Data Sharing” on page 217
You can share data sets between:
v Different jobs in a single operating system
v Multiple ACBs in a task or different subtasks
v One ACB in a task or different subtasks
v Different operating systems. To share between different operating systems safely,
you need global resource serialization or an equivalent product to implement
VSAM SHAREOPTIONS, record-level sharing access, and OPEN/CLOSE/EOV
serialization. Failure to use GRS or an equivalent can result in both data set and
VTOC/VVDS corruption and other unpredictable results. See z/OS MVS
Planning: Global Resource Serialization.
When you define VSAM data sets, you can specify how the data is to be shared
within a single system or among multiple systems that can have access to your
data and share the same direct access devices. Before you define the level of
sharing for a data set, you must evaluate the consequences of reading incorrect
data (a loss of read integrity) and writing incorrect data (a loss of write
integrity)—situations can result when one or more of the data set's users do not
adhere to guidelines recommended for accessing shared data sets.
The extent to which you want your data sets to be shared depends on the
application. If your requirements are similar to those of a catalog, where there can
be many users on more than one system, more than one user should be permitted
to read and update the data set simultaneously. At the other end of the spectrum is
an application where high security and data integrity require that only one user at
a time have access to the data.
When your program issues a GET request, VSAM reads an entire control interval
into virtual storage (or obtains a copy of the data from a control interval already in
virtual storage). If your program modifies the control interval's data, VSAM
ensures within a single control block structure that you have exclusive use of the
information in the control interval until it is written back to the data set. If the data
set is accessed by more than one program at a time, and more than one control
block structure contains buffers for the data set's control intervals, VSAM cannot
© Copyright IBM Corp. 1987, 2017
205
Sharing VSAM Data Sets
ensure that your program has exclusive use of the data. You must obtain exclusive
control yourself, using facilities such as ENQ/RESERVE and DEQ.
Two ways to establish the extent of data set sharing are the data set disposition
specified in the JCL and the share options specified in the access method services
DEFINE or ALTER command. If the VSAM data set cannot be shared because of
the disposition specified in the JCL, a scheduler allocation failure occurs. If your
program attempts to open a data set that is in use and the share options specified
do not permit concurrent use of the data, the open fails, and a return code is set in
the ACB error field.
During load mode processing, you cannot share data sets. Share options are
overridden during load mode processing. When a shared data set is opened for
create or reset processing, your program has exclusive control of the data set
within your operating system.
You can use ENQ/DEQ to issue VSAM requests, but not to serialize the system
resources that VSAM uses.
Subtask Sharing
Subtask sharing is the ability to perform multiple OPENs to the same data set
within a task or from different subtasks in a single address space and still share a
single control block structure. Subtask sharing allows many logical views of the
data set while maintaining a single control block structure. With a single control
block structure, you can ensure that you have exclusive control of the buffer when
updating a data set.
If you share multiple control block structures within a task or address space,
VSAM treats this like cross-address space sharing. You must adhere to the
guidelines and restrictions specified in “Cross-Region Sharing” on page 211.
Building a Single Control Block Structure
To share successfully within a task or between subtasks, you should ensure that
VSAM builds a single control block structure for the data set. This control block
structure includes blocks for control information and input/output buffers. All
subtasks access the data set through this single control block structure,
independent of the SHAREOPTION or DISP specifications. The three methods of
achieving a single control block structure for a VSAM data set while processing
multiple concurrent requests are:
v A single access method control block (ACB) and a STRNO>1
v Data definition name (ddname) sharing, with multiple ACBs (all from the same
data set) pointing to a single DD statement. This is the default. For example:
//DD1
DD
DSN=ABC
OPEN ACB1,DDN=DD1
OPEN ACB2,DDN=DD1
v Data set name sharing, with multiple ACBs pointing to multiple DD statements
with different ddnames. The data set names are related with an ACB open
specification (MACRF=DSN). For example:
//DD1
//DD2
DD
DD
DSN=ABC
DSN=ABC
OPEN ACB1,DDN=DD1,MACRF=DSN
OPEN ACB2,DDN=DD2,MACRF=DSN
206
z/OS DFSMS Using Data Sets
Sharing VSAM Data Sets
Multiple ACBs must be in the same address space, and they must be opening to
the same base cluster. The connection occurs independently of the path selected to
the base cluster. If the ATTACH macro is used to create a new task that will be
processing a shared data set, let the ATTACH keyword SZERO to default to YES or
code SZERO=YES. This causes subpool 0 to be shared with the subtasks. For more
information about the ATTACH macro see z/OS MVS Programming: Authorized
Assembler Services Reference ALE-DYN. This also applies to when you are sharing
one ACB in a task or different subtasks. To ensure correct processing in the shared
environment, all VSAM requests should be issued in the same key as the job step
TCB key.
Resolving Exclusive Control Conflicts
In this environment with a single control block, VSAM record management
serializes updates to any single control interval and provides read and write
integrity. When a control interval is not available for the type of user processing
requested (shared or exclusive), VSAM record management returns a logical error
code with an exclusive control error indicated in the RPL feedback code. When this
occurs, you must decide whether to retry later or to free the resource causing the
conflict. See Figure 27 on page 208 for a diagram of exclusive control conflict
feedback and results of different user requests.
Chapter 12. Sharing VSAM Data Sets
207
Sharing VSAM Data Sets
Figure 27. Exclusive Control Conflict Resolution
By default, if an exclusive control conflict is encountered, VSAM defers the request
until the resource becomes available. You can change this by using the VSAM
avoid LSR error control wait function. By using the NLW subparameter of the
MACRF parameter for the ACB macro, instead of deferring the request, VSAM
returns the exclusive control return code 20 (X'14') to the application program. The
application program can then determine the next action.
Alternatively, you can do this by changing the GENCB ACB macro in the
application program.
To test to see if the new function is in effect, the TESTCB ACB macro can be coded
into the application program.
The application program must be altered to handle the exclusive control error
return code. Register 15 will contain 8 and the RPLERRCD field will contain 20
(X'14'). The address of the RPL that owns the resource is placed in the first word in
the RPL error message area. The VSAM avoid LSR exclusive control wait option
cannot be changed after OPEN.
208
z/OS DFSMS Using Data Sets
Sharing VSAM Data Sets
Preventing Deadlock in Exclusive Control of Shared
Resources
Contention for VSAM data (the contents of a control interval) can lead to
deadlocks, in which a processing program is prevented from continuing because its
request for data cannot be satisfied. A and B can engage as contenders in four
distinct ways:
1. A wants exclusive control, but B has exclusive control. VSAM refuses A's
request: A must either do without the data or retry the request.
2. A wants exclusive control, but B is only willing to share. VSAM queues A's
request (without notifying A of a wait) and gives A use of the data when B
releases it.
3. A wants to share, but B has exclusive control. VSAM refuses A's request: A
must either do without the data or retry the request.
4. A wants to share, and B is willing to share. VSAM gives A use of the data,
along with B.
VSAM's action in a contention for data rests on two assumptions:
v If a processing program has exclusive control of the data, it can update or delete
it.
v If a processing program is updating or deleting the data, it has exclusive control.
(The use of MRKBFR, MARK=OUT provides an exception to this assumption. A
processing program can update the contents of a control interval without
exclusive control of them.)
In ways 1 and 3 shown previously, B is responsible for giving up exclusive control
of a control interval through an ENDREQ, a MRKBFR with MARK=RLS, or a
request for access to a different control interval. (The RPL that defines the
ENDREQ, MRKBFR, or request is the one used to acquire exclusive control
originally.)
Data Set Name Sharing
Data set name sharing is established by the ACB option (MACRF=DSN). To
understand DSN sharing, you must understand a sphere and the base of the
sphere and how they function.
Spheres. A sphere is a VSAM cluster and its associated data sets. The cluster is
originally defined with the access method services ALLOCATE command, the
DEFINE CLUSTER command, or through JCL. The most common use of the sphere
is to open a single cluster. The base of the sphere is the cluster itself. When
opening a path (which is the relationship between an alternate index and base
cluster) the base of the sphere is again the base cluster. Opening the alternate index
as a data set results in the alternate index becoming the base of the sphere. In
Figure 28 on page 210, DSN is specified for each ACB, and output processing is
specified.
Chapter 12. Sharing VSAM Data Sets
209
Sharing VSAM Data Sets
CLUSTER.REAL.PATH
CLUSTER.REAL.AIX (UPGRADE)
CLUSTER.REAL
CLUSTER.ALIAS
Figure 28. Relationship Between the Base Cluster and the Alternate Index
Connected Spheres. VSAM connects an ACB to an existing control block structure
for data set name sharing only when the base of the sphere is the same for both
ACBs. The following three OPEN statements show how information is added to a
single control block structure, permitting data set name sharing.
1. OPEN ACB=(CLUSTER.REAL)
v Builds control block structure for CLUSTER.REAL
v Builds control block structure for CLUSTER.REAL.AIX
2. OPEN ACB=(CLUSTER.REAL.PATH)
v Adds to existing structure for CLUSTER.REAL
v Adds to existing structure for CLUSTER.REAL.AIX
3. OPEN ACB=(CLUSTER.ALIAS)
Adds to existing structure for CLUSTER.REAL
If you add a fourth statement, the base of the sphere changes, and multiple control
block structures are created for the alternate index CLUSTER.REAL.AIX:
4.
OPEN ACB=(CLUSTER.REAL.AIX)
v Does not add to existing structure as the base of the sphere is not the same.
v SHAREOPTIONS are enforced for CLUSTER.REAL.AIX since multiple control block
structures exist.
Consistent Processing Options
To be compatible, both the new ACB and the existing control block structure must
be consistent in their specification of the following processing options.
v The data set specification must be consistent in both the ACB and the existing
control block structure. This means that an index of a key-sequenced data set
that is opened as an entry-sequenced data set, does not share the same control
block structure as the key-sequenced data set opened as a key-sequenced data
set.
v The MACRF options DFR, UBF, ICI, CBIC, LSR, and GSR must be consistent. For
example, if the new ACB and the existing structure both specify MACRF=DFR,
the connection is made. If the new ACB specifies MACRF=DFR and the existing
structure specifies MACRF=DFR,UBF, no connection is made.
If compatibility cannot be established, OPEN tries (within the limitations of the
share options specified when the data set was defined) to build a new control
block structure. If it cannot, OPEN fails.
210
z/OS DFSMS Using Data Sets
Sharing VSAM Data Sets
Shared Subtasks
When processing multiple subtasks sharing a single control block, concurrent GET
and PUT requests are allowed. A control interval is protected for write operations
using an exclusive control facility provided in VSAM record management. Other
PUT requests to the same control interval are not allowed and a logical error is
returned to the user issuing the request macro. Depending on the selected buffer
option, nonshared (NSR) or shared (LSR/GSR) resources, GET requests to the same
control interval as that being updated can or cannot be allowed. Figure 27 on page
208 illustrates the exclusive control facility.
When a subtask issues OPEN to an ACB that will share a control block structure
that can have been previously used, issue the POINT macro to obtain the position
for the data set. In this case, it should not be assumed that positioning is at the
beginning of the data set.
Cross-Region Sharing
The extent of data set sharing within one operating system depends on the data set
disposition and the cross-region share option specified when you define the data
set. Independent job steps or subtasks in an MVS system or multiple systems with
global resource serialization (GRS) can access a VSAM data set simultaneously. For
more information about GRS see z/OS MVS Planning: Global Resource Serialization.
To share a data set, each user must specify DISP=SHR in the data set's DD
statement.
Cross-Region Share Options
The level of cross-region sharing permitted by VSAM is established (when the data
set is defined) with the SHAREOPTIONS value:
v Cross-region SHAREOPTIONS 1: The data set can be shared by any number of
VSAM control blocks for read processing, or the data set can be accessed by only
one VSAM control block for read and write (OUTPUT) processing. With this
option, VSAM ensures complete data integrity for the data set. This setting does
not permit any type of non-RLS access when the data set is already open for
RLS processing.
v Cross-region SHAREOPTIONS 2: If the data set has not already been opened for
record-level sharing (RLS) processing, the data set can be accessed by any
number of non-RLS users for read processing and it can also be accessed by one
non-RLS user for write processing. With this option, VSAM ensures write
integrity by obtaining exclusive control for a control interval when it is to be
updated.
If the data set has already been opened for RLS processing, non-RLS accesses for
read are allowed. VSAM provides full read and write integrity to its RLS users,
but it is the non-RLS user's responsibility to ensure read integrity.
If you require read integrity, it is your responsibility to use the ENQ and DEQ
macros appropriately to provide read integrity for the data the program obtains.
For information about using ENQ and DEQ see z/OS MVS Programming:
Authorized Assembler Services Reference ALE-DYN and z/OS MVS Programming:
Authorized Assembler Services Reference EDT-IXG.
v Cross-region SHAREOPTIONS 3: The data set can be fully shared by any
number of users. With this option, each user is responsible for maintaining both
read and write integrity for the data the program accesses. This setting does not
allow any type of non-RLS access when the data set is already open for RLS
processing.
Chapter 12. Sharing VSAM Data Sets
211
Sharing VSAM Data Sets
This option requires that the user's program use ENQ/DEQ to maintain data
integrity while sharing the data set, including the OPEN and CLOSE processing.
User programs that ignore the write integrity guidelines can cause VSAM
program checks, lost or inaccessible records, uncorrectable data set failures, and
other unpredictable results. This option places responsibility on each user
sharing the data set.
v Cross-region SHAREOPTIONS 4: The data set can be fully shared by any
number of users, and buffers used for direct processing are refreshed for each
request. This setting does not allow any type of non-RLS access when the data
set is already open for RLS processing. With this option, as in SHAREOPTIONS
3, each user is responsible for maintaining both read and write integrity for the
data the program accesses. See the description of SHAREOPTIONS 3 for
ENQ/DEQ and warning information that applies equally to SHAREOPTIONS 4.
With options 3 and 4 you are responsible for maintaining both read and write
integrity for the data the program accesses. These options require your program to
use ENQ/DEQ to maintain data integrity while sharing the data set, including the
OPEN and CLOSE processing. User programs that ignore the write integrity
guidelines can cause VSAM program checks, lost or inaccessible records,
uncorrectable data set failures, and other unpredictable results. These options place
heavy responsibility on each user sharing the data set.
When your program requires that no updating from another control block structure
occur before it completes processing of the requested data record, your program
can issue an ENQ to obtain exclusive use of the VSAM data set. If your program
completes processing, it can relinquish control of the data set with a DEQ. If your
program is only reading data and not updating, it is probably a good practice to
serialize the updates and have the readers wait while the update is occurring. If
your program is updating, after the update has completed the ENQ/DEQ bracket,
the reader must determine the required operations for control block refresh and
buffer invalidation based on a communication mechanism or assume that
everything is down-level and refresh each request.
The extent of cross-region sharing is affected by using DISP=SHR or DISP=OLD in
the DD statement. If the data set's DD statement specifies DISP=OLD, only the
dsname associated with the DD statement is exclusively controlled. In this case,
only the cluster name is reserved for the OPEN routine's exclusive use. You can
include DD statements with DISP=OLD for each of the cluster's components to
reserve them as well. Doing this ensures that all resources needed to open the data
set will be exclusively reserved before your task is initiated.
Protecting the cluster name with DISP processing and the components by VSAM
OPEN SHAREOPTIONS is the normally accepted procedure. When a shared data
set is opened with DISP=OLD, or is opened for reset processing (IDCAMS REUSE
command), or is empty, the data set is processed using SHAREOPTIONS 1 rules.
Scheduler disposition processing is the same for VSAM and non-VSAM data sets.
This is the first level of share protection.
Read Integrity During Cross-Region Sharing
You are responsible for ensuring read integrity when the data set is opened for
sharing with cross-region SHAREOPTIONS 2, 3, and 4. When your program issues
a GET request, VSAM obtains a copy of the control interval containing the
requested data record. Another program sharing the data set can also obtain a
copy of the same control interval, and can update the data and write the control
212
z/OS DFSMS Using Data Sets
Sharing VSAM Data Sets
interval back into the data set. When this occurs, your program has lost read
integrity. The control interval copy in your program's buffer is no longer the
current copy.
The following should be considered when you are providing read integrity:
v Establish ENQ/DEQ procedures for all requests, read and write.
v Decide how to determine and invalidate buffers (index and/or data) that are
possibly down-level.
v Do not permit secondary allocation for an entry-sequenced data set or for a
fixed-length or variable-length RRDS. If you do allow secondary allocation you
should provide a communication mechanism to the read-only tasks that the
extents are increased, force a CLOSE, then issue another OPEN. Providing a
buffer refresh mechanism for index I/O will accommodate secondary allocations
for a key-sequenced data set.
v With an entry-sequenced data set or a fixed-length or variable-length RRDS, you
must also use the VERIFY macro before the GET macro to update possible
down-level control blocks.
v Generally, the loss of read integrity results in down-level data records and
erroneous no-record-found conditions.
Invalidating Index Buffers
To invalidate index buffers, you could perform the following steps:
1. In the ACB, specify:
STRNO>1.
MACRF=NSR to indicate nonshared resources.
Let the value for BUFNI default to the minimum.
2. Ensure that your index is a multilevel index.
3. Ensure that all requests are for positioning by specifying the following:
GET RPL OPTCD=DIR
POINT
PUT RPL OPTCD=NUP
Invalidating Data Buffers
To invalidate data buffers, ensure that all requests are for positioning by specifying
one of the following:
v GET/PUT RPL OPTCD=(DIR,NSP) followed by ENDREQ
v POINT GET/PUT RPL OPTCD=SEQ followed by ENDREQ
Write Integrity During Cross-Region Sharing
You are responsible for ensuring write integrity if a data set is opened with
cross-region SHAREOPTIONS 3 or 4.
When an application program issues a “direct” or “skip-sequential”
PUT-for-update or no-update, (RPL OPTCD=DIR|SKP), the updated control
interval is written to direct access storage when you obtain control following a
synchronous request (RPL OPTCD=SYN) or following the CHECK macro from an
asynchronous request (RPL OPTCD=ASY). To force direct access I/O for a
sequential PUT (RPL OPTCD=SEQ), the application program must issue an
ENDREQ or MRKBFR TYPE=OUT.
Chapter 12. Sharing VSAM Data Sets
213
Sharing VSAM Data Sets
Whenever an ENDREQ is issued, the return code in register 15 should be checked
to determine if there is an error. If there is an error, normal check processing
should be performed to complete the request.
The considerations that apply to read integrity also apply to write integrity. The
serialization for read could be done as a shared ENQ and for write as an exclusive
ENQ. You must ensure that all I/O is performed to DASD before dropping the
serialization mechanism (usually the DEQ).
Cross-System Sharing
These share options allow you to specify SHAREOPTION 1 or 2 sharing rules with
SHAREOPTION 3 or 4 record management processing. Use either of the following
share options when you define a data set that must be accessed or updated by
more than one operating system simultaneously:
v Cross-system SHAREOPTION 3. The data set can be fully shared. With this
option, the access method uses the control block update facility (CBUF) to help.
With this option, as in cross-region SHAREOPTIONS 3, each user is responsible
for maintaining both read and write integrity for the data the program accesses.
User programs that ignore write integrity guidelines can cause VSAM program
checks, uncorrectable data set failures, and other unpredictable results. This
option places heavy responsibility on each user sharing the data set. The
RESERVE and DEQ macros are required with this option to maintain data set
integrity.
v Cross-system SHAREOPTION 4. The data set can be fully shared, and buffers
used for direct processing are refreshed for each request.
This option requires that you use the RESERVE and DEQ macros to maintain
data integrity while sharing the data set. Output processing is limited to update
and/or add processing that does not change either the high-used RBA or the
RBA of the high key data control interval if DISP=SHR is specified. For
information about using RESERVE and DEQ, see z/OS MVS Programming:
Authorized Assembler Services Reference ALE-DYN and z/OS MVS Programming:
Authorized Assembler Services Reference LLA-SDU.
System-managed volumes and catalogs that contain system-managed data sets
must not be shared with non-system-managed systems. When sharing data sets in
a cross-region or cross-system environment, run the VSAM VERIFY macro before
you open a data set. VERIFY locates the current end of the data set and updates
internal control blocks. When the data set closes successfully, the system updates
the catalog with the information that VERIFY determined. This information and its
effects cannot be evident to all systems sharing the data set. If run as the first step
of a job stream, VERIFY causes an update to the end-of-file information in the
catalog.
To ensure data integrity in a shared environment, VSAM provides users of
SHAREOPTIONS 4 (both cross-region and cross-system) with the following
assistance:
v Each PUT request results in the appropriate buffer being written immediately
into the VSAM object's direct access device space. VSAM writes out the buffer in
the user's address space that contains the new or updated data record.
v Each GET request results in all the user's input buffers being refreshed. The
contents of each data and index buffer used by the user's program is retrieved
from the VSAM object's direct access device.
214
z/OS DFSMS Using Data Sets
Sharing VSAM Data Sets
When the data set is shared under cross-system SHAREOPTIONS 4, regardless of
cross-region requests, VSAM does not allow changes to high-used and high-key
RBAs. In addition, VSAM provides assistance to the application to aid in
preserving the integrity of the data:
v Control area splits and the addition of a new high-key record for a new control
interval that results from a control interval split are not allowed; VSAM returns
a logical error to the user's program if this condition should occur.
v The data and sequence-set control interval buffers are marked nonvalid
following I/O operation to a direct access storage device.
Job steps of two or more systems can gain access to the same data set regardless of
the disposition specified in each step's JCL. To get exclusive control of a volume, a
task in one system must issue a RESERVE macro. For other methods of obtaining
exclusive control using global resource serialization (GRS) see z/OS MVS Planning:
Global Resource Serialization.
Control Block Update Facility (CBUF)
Whenever a data set is opened with DISP=SHR, cross-region SHAREOPTION 3 or
4, and cross-system SHAREOPTION 3, VSAM record management maintains a
copy of the critical control block data in common storage. The control block data in
the common storage area is available to each program (each memory) sharing the
data set. The common storage area is available only to regions within your
operating system. Communicating this information to another operating system is
your responsibility.
CBUF eliminates the restriction that prohibits control area splits under cross-region
SHAREOPTION 4. Therefore, you do not need to restrict code to prevent control
area splits, or allow for the control area split error condition. The restriction to
prohibit control area splits for cross-systems SHAREOPTION 4 still exists.
CBUF processing is not provided if the data set has cross-system SHAREOPTION
4, but does not reside on shared DASD when it is opened. That is, the data set is
still processed as a cross-system SHAREOPTION 4 data set on shared DASD.
When a key-sequenced data set or variable-length RRDS has cross-system
SHAREOPTION 4, control area splits are prevented. Also, split of the control
interval containing the high key of a key range (or data set) is prevented. With
control interval access, adding a new control interval is prevented.
Cross-system sharing can be accomplished by sending the VSAM shared
information (VSI) blocks to the other host at the conclusion of each output request.
Generally, the VSIs will not have changed and only a check occurs.
If you use SHAREOPTION 3, you must continue to provide read/write integrity.
Although VSAM ensures that SHAREOPTION 3 and 4 users will have correct
control block information if serialization is done correctly, the SHAREOPTION 3
user will not get the buffer invalidation that will occur with SHAREOPTION 4.
When improved control interval processing is specified with SHAREOPTION 3 or
4, the data set can be opened. However, if another control block structure extends
the data set, the control block structure using improved control interval processing
will not be updated unless it is closed and reopened.
Chapter 12. Sharing VSAM Data Sets
215
Sharing VSAM Data Sets
Table 20 shows how the SHAREOPTIONS specified in the catalog and the
disposition specified on the DD statement interact to affect the type of processing.
Table 20. Relationship between SHAREOPTIONS and VSAM functions
(CR CS) when DISP=SHR1
Functions Provided
(3 3)
CBUF
(3 4)
Data and sequence set buffers invalidated. CA split
not allowed.
(4 3)
Data and index component buffers invalidated.
CBUF.
(4 4)
Data and sequence set buffers invalidated. CA split
not allowed.
Legend:
CA = Control area
CR = Cross-region
CS = Cross-system
CBUF = Control block update facility
Buffer invalidated = Invalidation of buffers is automatic
Note:
1. When DISP=OLD is specified or the data set is in create or reset mode (regardless of the
disposition specified), the share options specified in the catalog are ignored. The data set
is processed under the rules for SHAREOPTIONS(1 3). OPEN ensures that the user has
exclusive control of the data set within a single system. If the data set can be shared
between systems, VSAM does nothing to ensure that another system is not accessing the
data set concurrently. With cross-system sharing, the user must ensure that another
system is not accessing the data set before specifying DISP=OLD.
Considerations for CBUF Processing
If your program shares a data set defined with SHAREOPTIONS(3 3) or
SHAREOPTIONS(4 3), you should note that:
v In a shared environment, VSAM does not allow you to process the data set in an
initial load or reset mode (create). VSAM forces your data set to be processed as
though it were defined with SHAREOPTIONS(1 3).
v A user program cannot share a system data set (for example, the master catalog,
page space data sets, SYS1. data sets, duplex data sets, and swap data sets).
v The user's program must serialize all VSAM requests against the data set, using
ENQ/DEQ (or a similar function).
v The user's program must insure that all VSAM resources are acquired and
released within ENQ/DEQ protocol to:
– Force VSAM to write sequential update and insert requests.
– Release VSAM's positioning within the data set.
v VSAM invalidates data and index buffers used with cross-region or cross-system
SHAREOPTIONS 4 data sets, but does not invalidate buffers used with
SHAREOPTIONS 3 data sets. When a buffer is marked nonvalid, it is identified
as a buffer that VSAM must refresh (read in a fresh copy of the control interval
from DASD) before your program can use the buffer's contents.
v Programs that use GSR and LSR can invalidate and force writing of buffers
using the MRKBFR and WRTBFR macros.
v Because programs in many regions can share the same data set, an error that
occurs in one region can affect programs in other regions that share the same
216
z/OS DFSMS Using Data Sets
Sharing VSAM Data Sets
data set. If a logical error (register 15=8) or physical error (register 15=12) is
detected, any control block changes made before the error was detected will be
propagated to the shared information in common storage.
v When a VSAM data set requires additional space, VSAM end-of-volume
processing acquires new extents for the data set, updates the VSAM control
block structure for the data set with the new extent information, and updates the
critical control block data in common storage so that this new space is accessible
by all regions that use the data set. If the occurrence of an abend or unexpected
error prevents this space allocation from being completed, all regions are
prevented from further extending the data set. To obtain additional space, you
must close the VSAM data set in all regions, then reopen it.
v To correct the control blocks of a data set after an abnormal termination (abend),
issue the VERIFY macro to update them. VERIFY does not modify the data set.
You must determine what recovery action is required, if any. A subsequent
CLOSE updates the catalog record. The system bypasses the update to the data
set's catalog record after an abnormal termination.
v Implicit VERIFY is invoked by the open-for-output indicator in the catalog.
When a data set is opened and the open-for-output indicator is already on,
CLOSE processing resets the indicator only if the data set was just opened for
output; otherwise it leaves the bit on.
v Data sets shared in a cross-region or cross-system environment should either use
the access method services VERIFY command or issue the VERIFY macro from
within the application program.
v Because programs in many regions can share the same data set, an error in one
region can affect programs in other regions that share the data set. If a logical
error (register 15=8) or physical error (register 15=12) occurs, control block
changes made before the error was detected propagate to the shared information
control block in common storage. When this condition occurs, that data set can
place incorrect information in the catalog. Check the affected data set by using
the appropriate diagnostic tool (such as EXAMINE) to determine if the data set
has been corrupted. If the data set is damaged, use an appropriate utility, such
as REPRO, to recover the data set.
Checkpoints for Shared Data Sets
If you issue a checkpoint or if a restart occurs, none of the VSAM data sets open in
your region at that time can be using CBUF processing. If you issue checkpoints,
you should open the VSAM data sets that are eligible for CBUF processing with a
disposition of OLD, or CLOSE them before the checkpoint. Note that, if an
alternate index was using CBUF processing, the associated base cluster and any
other paths open over that base cluster must also be closed before the checkpoint,
even if they are not using CBUF processing.
Techniques of Data Sharing
This topic describes the different techniques of data sharing.
Cross-Region Sharing
To maintain write integrity for the data set, your program must ensure that there is
no conflicting activity against the data set until your program completes updating
the control interval. Conflicting activity can be divided into two categories:
1. A data set that is totally preformatted and the only write activity is
update-in-place.
Chapter 12. Sharing VSAM Data Sets
217
Sharing VSAM Data Sets
In this case, the sharing problem is simplified by the fact that data cannot
change its position in the data set. The lock that must be held for any write
operation (GET/PUT RPL OPTCD=UPD) is the unit of transfer that is the control
interval. It is your responsibility to associate a lock with this unit of transfer;
the record key is not sufficient unless only a single logical record resides in a
control interval.
The following is an example of the required procedures:
a. Issue a GET for the RPL that has the parameters
OPTCD=(SYN,KEY,UPD,DIR),ARG=MYKEY.
b. Determine the RBA of the control interval (RELCI) where the record resides.
This is based on the RBA field supplied in the RPL. For
extended-addressible data sets, this would be the lower six bytes of the field
RPLRBAR; for non-extended-addressable data sets, it would beRPLDDDD.
RELCI=CISIZE * integer-part-of (RPLDDDD / CISIZE)
c. Enqueue MYDATA.DSNAME.RELCI (the calculated value).
d. Issue an ENDREQ.
e. Issue a GET for the RPL that has the parameters
OPTCD=(SYN,KEY,UPD,DIR),ARG=MYKEY. This action will do I/O and get a
refreshed copy of the buffer.
f. Determine the RBA of the control interval (RELCI) where the record resides.
This is based on the RBA field supplied in the RPL. For
extended-addressable data sets, this would be the lower six bytes of the field
RPLRBAR; for non-extended-addressable data sets, it would beRPLDDDD. .
RELCI = CISIZE * integer-part-of (RPLDDDD / CISIZE)
Compare the calculated values. If they are equal, you are assured the control
interval has not moved. If they are not equal, dequeue resource from step
“c” and start over at step “a”.
g. Issue a PUT for the RPL that has the parameters OPTCD=(SYN,KEY,DIR,UPD).
This does not hold position in the buffer. You can do one of the following:
v Issue a GET for the RPL that has the parameters
OPTCD=(SYN,KEY,UPD,DIR),ARG=MYKEY. This will acquire position of the
buffer.
v Issue a PUT for the RPL that has the parameters
OPTCD=(SYN,KEY,DIR,NSP). This does hold position in the buffer.
h. Issue an ENDREQ. This forces I/O to DASD, will drop the position, and
cause data buffer invalidation.
i. Dequeue MYDATA.DSNAME.RELCI.
2. A data set in which record additions and updates with length changes are
permitted.
In this case, the minimum locking unit is a control area to accommodate control
interval splits. A higher level lock must be held during operations involving a
control area split. The split activity must be serialized at a data set level. To
perform a multilevel locking procedure, you must be prepared to use the
information provided during VSAM JRNAD processing in your program. This
user exit is responsible for determining the level of data movement and
obtaining the appropriate locks.
Higher concurrency can be achieved by a hierarchy of locks. Based on the
particular condition, one or more of the locking hierarchies must be obtained.
218
z/OS DFSMS Using Data Sets
Sharing VSAM Data Sets
Lock
Control Interval
Control Area
Data Set
Condition
Updating a record in place or adding a record to a control interval
without causing a split.
Adding a record or updating a record with a length change, causing a
control interval split, but not a control area split.
Adding a record or updating a record with a length change, causing a
control area split.
The following is a basic procedure to provide the necessary protection. Note
that, with this procedure, all updates are locked at the at the data set level:
SHAREOPTION = (4 3)
Enqueue MYDATA.DSNAME
CBUF processing
Shared for read only;
exclusive for write
Issue VSAM request macros
...
Dequeue MYDATA.DSNAME
In any sharing situation, it is a general rule that all resources be obtained and
released between the locking protocol. All positioning must be released by
using all direct requests or by issuing the ENDREQ macro before ending the
procedure with the DEQ.
Cross-System Sharing
With cross-system SHAREOPTIONS 3, you have the added responsibility of
passing the VSAM shared information (VSI) and invalidating data and/or index
buffers. This can be done by using an informational control record as the low key
or first record in the data set. The following information is required to accomplish
the necessary index record invalidation:
1. Number of data control interval splits and index updates for sequence set
invalidation
2. Number of data control area splits for index set invalidation
All data buffers should always be invalidated. See “Techniques of Data Sharing”
on page 217 for the required procedures for invalidating buffers. To perform
selective buffer invalidation, an internal knowledge of the VSAM control blocks is
required.
Your program must serialize the following types of requests (precede the request
with an ENQ and, when the request completes, issue a DEQ):
v All PUT requests.
v POINT, GET-direct-NSP, GET-skip, and GET-for-update requests that are
followed by a PUT-insert, PUT-update, or ERASE request.
v VERIFY requests. When VERIFY is run by VSAM, your program must have
exclusive control of the data set.
v Sequential GET requests.
User Access to VSAM Shared Information
You can code the following instructions to get the length and address of the data
to be sent to another processor:
v Load ACB address into register RY.
v To locate the VSI for a data component:
Chapter 12. Sharing VSAM Data Sets
219
Sharing VSAM Data Sets
L
L
L
LH
LA
RX,04(,RY)
1,52(,RX)
1,68(,1)
0,62(,1)
1,62(,1)
Put AMBL address into register RX
Get data AMB address
Get VSI address
Load data length
Point to data to be communicated
v To locate the VSI information for an index component of a key-sequenced data
set:
L
L
L
LH
LA
RX,04(,RY)
1,56(,RX)
1,68(,1)
0,62(,1)
1,62(,1)
Put AMBL address into register RX
Get index AMB address
Get VSI address
Load data length
Point to data to be communicated
Similarly, the location of the VSI on the receiving processor can be located. The VSI
level number must be incremented in the receiving VSI to inform the receiving
processor that the VSI has changed. To update the level number, assuming the
address of the VSI is in register 1:
LA
AL
ST
0,1
0,64(,1)
0,64(,1)
Place increment into register 0
Add level number to increment
Save new level number
All processing of the VSI must be protected by using ENQ/DEQ to prevent
simultaneous updates to the transmitted data. To alter the VSI a user must run in
KEY0 AUTHORIZED.
If the data set can be shared between z/OS operating systems, a user's program in
another system can concurrently access the data set. Before you open the data set
specifying DISP=OLD, it is your responsibility to protect across systems with
ENQ/DEQ using the UCB option. This protection is available with GRS or
equivalent functions.
220
z/OS DFSMS Using Data Sets
Chapter 13. Sharing Resources Among VSAM Data Sets
This topic covers the following subtopics.
Topic
“Provision of a Resource Pool”
“Management of I/O Buffers for Shared Resources” on page 226
“Restrictions and Guidelines for Shared Resources” on page 230
This topic is intended to help you share resources among your VSAM data sets.
VSAM has a set of macros that lets you share I/O buffers and I/O-related control
blocks among many VSAM data sets. In VSAM, an I/O buffer is a virtual storage
area from which the contents of a control interval are read and written. Sharing
these resources optimizes their use, reducing the requirement for virtual storage
and therefore reducing paging of virtual storage.
Sharing these resources is not the same as sharing a data set itself (that is, sharing
among different tasks that independently open it). Data set sharing can be done
with or without sharing I/O buffers and I/O-related control blocks. For
information about data set sharing see Chapter 12, “Sharing VSAM Data Sets,” on
page 205.
There are also macros that let you manage I/O buffers for shared resources.
Sharing resources does not improve sequential processing. VSAM does not
automatically position itself at the beginning of a data set opened for sequential
access, because placeholders belong to the resource pool, not to individual data
sets. When you share resources for sequential access, positioning at the beginning
of a data set has to be specified explicitly with the POINT macro or the direct GET
macro with RPL OPTCD=NSP. You may not use a resource pool to load records
into an empty data set.
Provision of a Resource Pool
To share resources, follow this procedure to provide a resource pool:
1. Use the BLDVRP macro to build a resource pool.
2. Code a MACRF parameter in the ACB and use OPEN to connect your data sets
to the resource pool.
3. After you have closed all the data sets, use the DLVRP macro to delete the
resource pool.
Building a Resource Pool: BLDVRP
Issuing BLDVRP causes VSAM to share the I/O buffers and I/O-related control
blocks of data sets whose ACBs indicate the corresponding option for shared
resources. Control blocks are shared automatically; you may control the sharing of
buffers.
When you issue BLDVRP, you specify for the resource pool the size and number of
virtual address space buffers for each virtual buffer pool.
© Copyright IBM Corp. 1987, 2017
221
Sharing Resources Among VSAM Data Sets
Using Hiperspace Buffers with LSR
If you are using local shared resources (LSR), you can specify multiple 4-KB
Hiperspace buffers for each buffer pool in the resource pool. The size of the
Hiperspace buffers must be equal to the CISIZE of the data sets being used.
The use of Hiperspace buffers can reduce the amount of I/O to a direct access
storage device (DASD) by caching data in central storage. The data in a Hiperspace
buffer is preserved unless there is a central storage shortage and the central storage
that backs the Hiperspace buffer is reclaimed by the system. VSAM invalidates a
Hiperspace buffer when it is copied to a virtual address space buffer and,
conversely, invalidates a virtual address space buffer when it is copied to a
Hiperspace buffer. Therefore at most there is only one copy of the control interval
in virtual address space and Hiperspace. When a modified virtual address space
buffer is reclaimed, it is copied to Hiperspace and to DASD.
For the data pool or the separate index pool at OPEN time, a data set is assigned
the one buffer pool with buffers of the appropriate size—either the exact control
interval size requested, or the next larger size available.
You may have both a global resource pool and one or more local resource pools.
Tasks in an address space that have a local resource pool may use either the global
resource pool, under the restrictions described below, or the local resource pool.
There may be multiple buffer pools based on buffer size for each resource pool.
To share resources locally, a task in the address space issues BLDVRP TYPE=LSR,
DATA|INDEX. To share resources globally, a system task issues BLDVRP
TYPE=GSR. The program that issues BLDVRP TYPE=GSR must be in supervisor
state with key 0 - 7.
You can share resources locally or globally, with the following restrictions:
v LSR (local shared resources). You can build up to 255 data resource pools and
255 index resource pools in one address space. Each resource pool must be built
individually. The data pool must exist before the index pool with the same share
pool identification can be built. The parameter lists for these multiple LSR pools
can reside above or below 16 MB. The BLDVRP macro RMODE31 parameter
indicates where VSAM is to obtain virtual storage when the LSR pool control
blocks and data buffers are built.
These resource pools are built with the BLDVRP macro TYPE=LSR and
DATA|INDEX specifications. Specifying MACRF=LSR on the ACB or
GENCB-ACB macros causes the data set to use the LSR pools built by the
BLDVRP macro. The DLVRP macro processes both the data and index resource
pools.
If a BLDVRP-built resource pool is too small such that a VSAM request cannot
find an available buffer, and if it is suitable for the mode of the application
(including buffers already residing above 16 MB), VSAM may dynamically add
buffers to the resource pool so that the request can complete without an error.
v GSR (global shared resources). All address spaces for a given protection key in
the system share one resource pool. Only one resource pool can be built for each
of the protection keys 0 - 7. With GSR, an access method control block and all
related request parameter lists, exit lists, data areas, and extent control blocks
must be in the common area of virtual storage with a protection key the same as
the resource pool. To get storage in the common area with that protection key,
issue the GETMAIN macro while in that key, for storage in subpool 241. If you
need to share a data set among address spaces, multiple systems, or both,
consider using record-level sharing (RLS) instead of GSR.
222
z/OS DFSMS Using Data Sets
Sharing Resources Among VSAM Data Sets
The separate index resource pools are not supported for GSR.
The Hiperspace buffers (specified in the BLDVRP macro) are not supported for
GSR.
Generate ACBs, RPLs, and EXLSTs with the GENCB macro: code the WAREA
and LENGTH parameters. The program that issues macros related to that global
resource pool must be in supervisor state with the same key. (The macros are
BLDVRP, CHECK, CLOSE, DLVRP, ENDREQ, ERASE, GENCB, GET, GETIX,
MODCB, MRKBFR, OPEN, POINT, PUT, PUTIX, SCHBFR, SHOWCB, TESTCB,
and WRTBFR. The SHOWCAT macro is not related to a resource pool, because a
program can issue this macro independently of an opened data set.)
Deciding the Size of a Virtual Resource Pool
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. To specify the BUFFERS, KEYLEN, and STRNO parameters of the BLDVRP
macro, you must know the size of the control intervals, data records (if spanned),
and key fields in the components that will use the resource pool. You must also
know how the components are processed. You can use the SHOWCAT and
SHOWCB macros, or the access method services LISTCAT command to get this
information.
For example, to find the control interval size using SHOWCB: open the data set for
nonshared resources processing, issue SHOWCB, close the ACB, issue BLDVRP,
open the ACB for LSR or GSR.
Tip: Because Hiperspace buffers are in expanded storage, you do not need to
consider their size and number when you calculate the size of the virtual resource
pool.
For each VSAM cluster that will share the virtual resource pool you are building,
follow this procedure:
1. Determine the number of concurrent requests you expect to process. The
number of concurrent requests represents STRNO for the cluster.
2. Specify BUFFERS=(SIZE(STRNO+1)) for the data component of the cluster.
v If the cluster is a key-sequenced cluster and the index CISZ (control interval
size) is the same as the data CISZ, change the specification to
BUFFERS=(SIZE(2 X STRNO)+1).
v If the index CISZ is not the same as the data component CISZ, specify
BUFFERS=(dataCISZ(STRNO+1),indexCISZ(STRNO)).
Following this procedure provides the minimum number of buffers needed to
support concurrently active STRNO strings. An additional string is not
dynamically added to a shared resource pool. The calculation can be repeated for
each cluster which will share the resource pool, including associated alternate
index clusters and clusters in the associated alternate index upgrade sets.
For each cluster component having a different CISZ, add another
‘,SIZE(NUMBER)’ range to the ‘BUFFERS=’ specification. Note that the data
component and index component buffers may be created as one set of buffers, or,
by use of the ‘TYPE=’ statement, may be created in separate index and data buffer
sets.
Additional buffers may be added to enhance performance of applications requiring
read access to data sets by reducing I/O requirements. You should also consider
Chapter 13. Sharing Resources Among VSAM Data Sets
223
Sharing Resources Among VSAM Data Sets
the need for cross-region or cross-system sharing of the data sets where modified
data buffers must be written frequently to enhance read and update integrity.
Many buffers is not usually an advantage in such environments. In some
applications where a resource pool is shared by multiple data sets and not all data
set strings are active concurrently, less than the recommended number of buffers
may produce satisfactory results.
For LSR buffering, if the user specified number of buffers is inadequate to process
a request and DBA is allowed, VSAM will attempt to add additional buffers
dynamically to the resource pool (Dynamic Buffer Addition, DBA) to avoid the 'out
of buffers' logical error, reason code 152(X'98'). DBA is allowed for LSR only, for
task mode requests and if DBA=NO was not specified on the BLDVRP.
Displaying Information about an Unopened Data Set
The SHOWCAT macro lets you get information about a component before its
cluster or alternate index is opened. The program that is to issue BLDVRP can
issue SHOWCAT on all the components to find out the sizes of control intervals,
records, and keys. This information lets the program calculate values for the
BUFFERS and KEYLEN parameters of BLDVRP.
A program need not be in supervisor state with protection key 0 - 7 to issue
SHOWCAT, even though it must be in supervisor state and in protection key 0 - 7
to issue BLDVRP TYPE=GSR.
The SHOWCAT macro is described in z/OS DFSMS Macro Instructions for Data Sets.
Displaying Statistics about a Buffer Pool
You can use the SHOWCB macro to obtain statistics about the use of buffer pools.
These statistics help you determine how to improve both a previous definition of a
resource pool and the mix of data sets that use it. The statistics are available
through an ACB that describes an open data set that is using the buffer pool. They
reflect the use of the buffer pool from the time it was built to the time SHOWCB is
issued. All but one of the statistics are for a single buffer pool. To get statistics for
the whole resource pool, issue SHOWCB for each of its buffer pools.
The statistics cannot be used to redefine the resource pool while it is in use. You
have to make adjustments the next time you build it.
The use of SHOWCB to display an ACB is described in “Manipulating the
Contents of Control Blocks” on page 152. If the ACB has MACRF=GSR, the
program that issues SHOWCB must be in supervisor state with protection key 0 7. A program check can occur if SHOWCB is issued by a program that is not in
supervisor state with the same protection key as the resource pool.
For buffer pool statistics, the keywords described as follows are specified in
FIELDS. These fields may be displayed only after the data set described by the
ACB is opened. Each field requires one fullword in the display work area:
Field
BFRFND
BUFNOL
BUFRDS
BUFUSE
224
z/OS DFSMS Using Data Sets
Description
The number of requests for retrieval that could be satisfied without an
I/O operation (the data was found in a buffer).
The number of I/O buffers allocated for the data component or index
component during BLDVRP or SMB for LSR processing.
The number of reads to bring data into a buffer.
The number of I/O buffers actually in use for the data component or
index component at the time the SHOWCB macro issued.
Sharing Resources Among VSAM Data Sets
Field
NUIW
STRMAX
UIW
Description
The number of nonuser-initiated writes (that VSAM was forced to do
because no buffers were available for reading the contents of a control
interval).
The maximum number of placeholders currently active for the resource
pool (for all the buffer pools in it).
The number of user-initiated writes (PUTs not deferred or WRTBFRs, see
“Deferring Write Requests” on page 226).
Connecting a Data Set to a Resource Pool: OPEN
You cause a data set to use a resource pool built by BLDVRP by specifying LSR or
GSR in the MACRF parameter of the data set's ACB before you open the data set.
ACB
MACRF=({NSR|LSR|GSR},...),...
NSR, the default, indicates the data set does not use shared resources. LSR
indicates it uses the local resource pool. GSR indicates it uses the global resource
pool.
If the VSAM control blocks and data buffers reside above 16 MB, RMODE31=ALL
must be specified in the ACB before OPEN is issued. If the OPEN parameter list or
the VSAM ACB resides above 16 MB, the MODE=31 parameter of the OPEN macro
must also be coded.
When an ACB indicates LSR or GSR, VSAM ignores its BSTRNO, BUFNI, BUFND,
BUFSP, and STRNO parameters because VSAM will use the existing resource pool
for the resources associated with these parameters.
To connect LSR pools with a SHRPOOL identification number other than
SHRPOOL=0, you must use the SHRPOOL parameter of the ACB macro to indicate
which LSR pool you are connecting.
If more than one ACB is opened for LSR processing of the same data set, the LSR
pool identified by the SHRPOOL parameter for the first ACB will be used for all
subsequent ACBs.
For a data set described by an ACB with MACRF=GSR, the ACB and all related
RPLs, EXLSTs, ECBs, and data areas must be in the common area of virtual storage
with the same protection key as the resource pool.
Deleting a Resource Pool Using the DLVRP Macro
After all data sets using a resource pool are closed, delete the resource pool by
issuing the DLVRP (delete VSAM resource pool) macro. Failure to delete a local
resource pool causes virtual storage to be lost until the end of the job step or
TSO/E session. This loss is protected with a global resource pool. If the address
space that issued BLDVRP terminates without having issued DLVRP, the system
deletes the global resource pool when its use count is 0.
To delete an LSR pool with a SHRPOOL identification number other than
SHRPOOL=0, you must use the SHRPOOL parameter to indicate which resource
pool you are deleting. If both a data resource pool and an index resource pool
have the same SHRPOOL number, both will be deleted.
If the DLVRP parameter list is to reside above 16 MB, the MODE=31 parameter
must be coded.
Chapter 13. Sharing Resources Among VSAM Data Sets
225
Sharing Resources Among VSAM Data Sets
Management of I/O Buffers for Shared Resources
Managing I/O buffers includes:
v Deferring writes for direct PUT requests, which reduces the number of I/O
operations.
v Writing buffers that have been modified by related requests.
v Locating buffers that contain the contents of specified control intervals.
v Marking a buffer to be written without issuing a PUT.
v When your program accesses an nonvalid buffer, VSAM refreshes the buffer
(that is, reads in a fresh copy of the control interval) before making its contents
available to your program.
Managing I/O buffers should enable you to speed up direct processing of VSAM
data sets that are accessed randomly. You probably will not be able to speed up
sequential processing or processing of a data set whose activity is consistently
heavy.
Deferring Write Requests
VSAM automatically defers writes for sequential PUT requests. It normally writes
out the contents of a buffer immediately for direct PUT requests. With shared
resources, you can cause writes for direct PUT requests to be deferred. Buffers are
finally written out when:
v You issue the WRTBFR macro.
v VSAM needs a buffer to satisfy a GET request.
v A data set using a buffer pool is closed. (Temporary CLOSE is ineffective against
a data set that is sharing buffers, and ENDREQ does not cause buffers in a
resource pool to be written.)
Deferring writes saves I/O operations when subsequent requests can be satisfied
by the data in the buffer pool. If you are going to update control intervals more
than once, data processing performance will be improved by deferring writes.
You indicate that writes are to be deferred by coding MACRF=DFR in the ACB,
along with MACRF=LSR or GSR.
ACB
MACRF=({LSR|GSR},{DFR|NDF},...),...
The DFR option is incompatible with SHAREOPTIONS 4. (SHAREOPTIONS is a
parameter of the DEFINE command of access method services. It is described in
z/OS DFSMS Access Method Services Commands.) A request to open a data set with
SHAREOPTIONS 4 for deferred writes is rejected.
VSAM notifies the processing program when an unmodified buffer has been found
for the current request and there will be no more unmodified buffers into which to
read the contents of a control interval for the next request. (VSAM will be forced to
write a buffer to make a buffer available for the next I/O request.) VSAM sets
register 15 to 0 and puts 12 (X'0C') in the feedback field of the RPL that defines the
PUT request detecting the condition.
VSAM also notifies the processing program when there are no buffers available to
be assigned to a placeholder for a request. This is a logical error (register 15
contains 8 unless an exit is taken to a LERAD routine). The feedback field in the
RPL contains 152 (X'98'). You may retry the request; it gets a buffer if one is freed.
226
z/OS DFSMS Using Data Sets
Sharing Resources Among VSAM Data Sets
Relating Deferred Requests by Transaction ID
You can relate action requests (GET, PUT, and so forth) according to transaction by
specifying the same ID in the RPLs that define the requests.
The purpose of relating the requests that belong to a transaction is to enable
WRTBFR to cause all the modified buffers used for a transaction to be written.
When the WRTBFR request is complete, the transaction is physically complete.
RPL
TRANSID=number,...
TRANSID specifies a number from 0 to 31. The number 0, which is the default,
indicates that requests defined by the RPL are not associated with other requests. A
number from 1 to 31 relates the requests defined by this RPL to the requests
defined by other RPLs with the same transaction ID.
You can find out what transaction ID an RPL has by issuing SHOWCB or TESTCB.
SHOWCB
FIELDS=([TRANSID],...),...
TRANSID requires one fullword in the display work area.
TESTCB
TRANSID=number,...
If the ACB to which the RPL is related has MACRF=GSR, the program issuing
SHOWCB or TESTCB must be in supervisor state with the same protection key as
the resource pool. With MACRF=GSR specified in the ACB to which the RPL is
related, a program check can occur if SHOWCB or TESTCB is issued by a program
that is not in supervisor state with protection key 0 - 7. For more information
about using SHOWCB and TESTCB see “Manipulating the Contents of Control
Blocks” on page 152.
Writing Buffers Whose Writing is Deferred: WRTBFR
If any PUTs to a data set using a shared resource pool are deferred, you can use
the WRTBFR (write buffer) macro to write:
v All modified unwritten index and data buffers for a given data set (which causes
all Hiperspace buffers for the data set to be invalidated)
v All modified unwritten index and data buffers in the resource pool
v The least recently used modified buffers in each buffer pool of the resource pool
v All buffers modified by requests with the same transaction ID
v A buffer, identified by an RBA value, that has been modified and has a use
count of zero
You can specify the DFR option in an ACB without using WRTBFR to write
buffers. A buffer is written when VSAM needs one to satisfy a GET request, or all
modified buffers are written when the last of the data sets that uses them is closed.
Besides using WRTBFR to write buffers whose writing is deferred, you can use it
to write buffers that are marked for output with the MRKBFR macro, which is
described in “Marking a Buffer for Output: MRKBFR” on page 229.
Using WRTBFR can improve performance, if you schedule WRTBFR to overlap
other processing.
VSAM notifies the processing program when there are no more unmodified buffers
into which to read the contents of a control interval. (VSAM would be forced to
Chapter 13. Sharing Resources Among VSAM Data Sets
227
Sharing Resources Among VSAM Data Sets
write buffers when another GET request required an I/O operation.) VSAM sets
register 15 to 0 and puts 12 (X'0C') in the feedback field of the RPL that defines the
PUT request that detects the condition.
VSAM also notifies the processing program when there are no buffers available to
which to assign a placeholder for a request. This is a logical error (register 15
contains 8 unless an exit is taken to a LERAD routine); the feedback field in the
RPL contains 152 (X'98'). You may retry the request; it gets a buffer if one is freed.
When sharing the data set with a user in another region, your program might
want to write the contents of a specified buffer without writing all other modified
buffers. Your program issues the WRTBFR macro to search your buffer pool for a
buffer containing the specified RBA. If found, the buffer is examined to verify that
it is modified and has a use count of zero. If so, VSAM writes the contents of the
buffer into the data set.
Recommendation: Before you use WRTBFR TYPE=CHK|TRN|DRBA, be sure to
release all buffers. See “Processing Multiple Strings” on page 160 for information
about releasing buffers. If one of the buffers is not released, VSAM defers
processing until the buffer is released.
Handling Exits to Physical Error Analysis Routines
With deferred writes of buffers, a processing program continues after its PUT
request has been completed, even though the buffer has not been written. The
processing program is not synchronized with a physical error that occurs when the
buffer is finally written. A processing program that uses MRKBFR MARK=OUT is
also not synchronized with a physical error. An EXCEPTION or a SYNAD routine
must be supplied to analyze the error.
The ddname field of the physical error message identifies the data set that was
using the buffer, but, because the buffer might have been released, its contents
might be unavailable. You can provide a JRNAD exit routine to record the contents
of buffers for I/O errors. It can be coordinated with a physical error analysis
routine to handle I/O errors for buffers whose writing has been deferred. If a
JRNAD exit routine is used to cancel I/O errors during a transaction, the physical
error analysis routine will get only the last error return code. See “SYNAD Exit
Routine to Analyze Physical Errors” on page 271 and “JRNAD Exit Routine to
Journalize Transactions” on page 261 for information about the SYNAD and
JRNAD routines.
Using the JRNAD Exit with Shared Resources
VSAM takes the JRNAD exit for the following reasons when the exit is associated
with a data set whose ACB has MACRF=LSR or GSR:
v A data or index control interval buffer has been modified and is about to be
written.
v A physical error occurred. VSAM takes the JRNAD exit first—your routine can
direct VSAM to bypass the error and continue processing or to terminate the
request that occasioned the error and proceed with error processing.
v A control interval or a control area is about to be split for a key-sequenced data
set or variable-length RRDS. Your routine can cancel the request for the split and
leave VSAM. An example of using the JRNAD exit for this purpose is given in
“JRNAD Exit Routine to Journalize Transactions” on page 261.
228
z/OS DFSMS Using Data Sets
Sharing Resources Among VSAM Data Sets
See “JRNAD Exit Routine to Journalize Transactions” on page 261 for information
describing the contents of the registers when VSAM exits to the JRNAD routine,
and the fields in the parameter list pointed to by register 1.
Accessing a Control Interval with Shared Resources
Control interval access is not permitted with shared resources.
Locating an RBA in a Buffer Pool: SCHBFR
When a resource pool is built, the buffers in each buffer pool are numbered from 1
through the number of buffers in each buffer pool. At a given time, several buffers
in a buffer pool may hold the contents of control intervals for a particular data set.
These buffers may or may not contain RBAs of interest to your processing
program. The SCHBFR macro lets you find out. Specify in the ARG parameter of
the RPL that defines SCHBFR the address of an 8-byte field that contains the first
and last control interval RBAs of the range you are interested in.
Note: For compressed format data sets, the RBA of the compressed record is
unpredictable. The RBA of another record or the address of the next record in the
buffer cannot be determined using the length of the current record or the length of
the record provided to VSAM.
The buffer pool to be searched is the one used by the data component defined by
the ACB to which your RPL is related. If the ACB names a path, VSAM searches
the buffer pool used by the data component of the alternate index. (If the path is
defined over a base cluster alone, VSAM searches the buffer pool used by the data
component of the base cluster.) VSAM begins its search at the buffer you specify
and continues until it finds a buffer that contains an RBA in the range or until the
highest numbered buffer is searched.
For the first buffer that satisfies the search, VSAM returns its address
(OPTCD=LOC) or its contents (OPTCD=MVE) in the work area whose address is
specified in the AREA parameter of the RPL and returns its number in register 0. If
the search fails, Register 0 is returned with the user specified buffer number and a
one-byte SCHBFR code of X'0D'. To find the next buffer that contains an RBA in
the range, issue SCHBFR again and specify the number of the next buffer after the
first one that satisfied the search. You continue until VSAM indicates it found no
buffer that contains an RBA in the range or until you reach the end of the pool.
Finding a buffer that contains a desired RBA does not get you exclusive control of
the buffer. You may get exclusive control only by issuing GET for update. SCHBFR
does not return the location or the contents of a buffer that is already under the
exclusive control of another request.
Marking a Buffer for Output: MRKBFR
You locate a buffer that contains the RBA you are interested in by issuing a
SCHBFR macro, a read-only GET, or a GET for update. When you issue GET for
update, you get exclusive control of the buffer. Whether you have exclusive control
or not, you can mark the buffer for output by issuing the MRKBFR macro with
MARK=OUT, then change the buffer's contents. Without exclusive control, you
should not change the control information in the CIDF or RDFs (do not change the
record lengths).
MRKBFR MARK=OUT, indicates that the buffer's contents are modified. You must
modify the contents of the buffer itself, not a copy. Therefore, when you issue
SCHBFR or GET to locate the buffer, you must specify RPL OPTCD=LOC. (If you
Chapter 13. Sharing Resources Among VSAM Data Sets
229
Sharing Resources Among VSAM Data Sets
use OPTCD=MVE, you get a copy of the buffer but do not learn its location.) The
buffer is written when a WRTBFR is issued or when VSAM is forced to write a
buffer to satisfy a GET request.
If you are sharing a buffer or have exclusive control of it, you can release it from
shared status or exclusive control with MRKBFR MARK=RLS. If the buffer was
marked for output, MRKBFR with MARK=RLS does not nullify it; the buffer is
eventually written. Sequential positioning is lost. MRKBFR with MARK=RLS is
similar to the ENDREQ macro.
Restrictions and Guidelines for Shared Resources
Restrictions for using the LSR and GSR options are:
v Empty data sets cannot be processed (that is, loaded).
v Multiple LSR pools in an address space are obtained by using the SHRPOOL
parameter of the BLDVRP macro to identify each LSR pool.
v Control interval access cannot be used (ACB MACRF=CNV and ACB
MACRF=ICI).
v Control blocks in common (CBIC) cannot be used.
v User buffering is not allowed (ACB MACRF=UBF).
v Writes for data sets with SHAREOPTIONS 4 cannot be deferred (ACB
MACRF=DFR).
v Request parameter lists for MRKBFR, SCHBFR, and WRTBFR cannot be chained
(the NXTRPL parameter of the RPL macro is ignored).
v For sequential access, positioning at the beginning of a data set must be explicit:
with a POINT macro or a direct GET macro with RPL OPTCD=NSP.
v Temporary CLOSE and ENDREQ do not cause buffers to be written if
MACRF=DFR was specified in the associated ACB.
v Address spaces that use Hiperspace buffering (LSR only) should be made
nonswappable. Otherwise, the expanded storage (and, therefore, the Hiperspace
buffers) will be discarded when the address space is swapped out.
v With GSR, an ACB and all related RPLs, EXLSTs, data areas, and ECBs must be
stored in the common area of virtual storage with protection key 0 - 7; all VSAM
requests related to the global resource pool may be issued only by a program in
supervisor state with protection key 0 - 7 (the same as the resource pool).
v Checkpoints cannot be taken for data sets whose resources are shared in a global
resource pool. When a program in an address space that opened a data set
whose ACB has MACRF=GSR issues the CHKPT macro, 8 is returned in register
15. If a program in another address space issues the CHKPT macro, the
checkpoint is taken, but only for data sets that are not using the global resource
pool.
Checkpoint/restart can be used with data sets whose resources are shared in a
local resource pool, but the restart program does not reposition for processing at
the point where the checkpoint occurred—processing is restarted at a data set's
highest used RBA. See z/OS DFSMSdfp Checkpoint/Restart for information about
restarting the processing of VSAM data.
v If a physical I/O error is found while writing a control interval to the direct
access device, the buffer remains in the resource pool. The write-required flag
(BUFCMW) and associated mod bits (BUFCMDBT) are turned off, and the BUFC
is flagged in error (BUFCER2=ON). The buffer is not replaced in the pool, and
230
z/OS DFSMS Using Data Sets
Sharing Resources Among VSAM Data Sets
buffer writing is not attempted. To release this buffer for reuse, a WRTBFR
macro with TYPE=DS can be issued or the data set can be closed (CLOSE issues
the WRTBFR macro).
v When you use the BLDVRP macro to build a shared resource pool, some of the
VSAM control blocks are placed in a system subpool and others in subpool 0.
When a task ends, the system frees subpool 0 unless it is shared with another
task. The system does not free the system subpool until the job step ends. Then,
if another task attempts to use the resource pool, an abend might occur when
VSAM attempts to access the freed control blocks. This problem does not occur
if the two tasks share subpool 0. Code in the ATTACH macro the SZERO=YES
parameter, or the SHSPL or SHSPV parameters. SZERO=YES is the default.
v GSR is not permitted for compressed data sets.
Chapter 13. Sharing Resources Among VSAM Data Sets
231
Sharing Resources Among VSAM Data Sets
232
z/OS DFSMS Using Data Sets
Chapter 14. Using VSAM Record-Level Sharing
This topic describes how to set up the resources that you need for using VSAM
record-level sharing (RLS) and DFSMS Transactional VSAM (DFSMStvs). This topic
covers the following subtopics.
Topic
“Controlling Access to VSAM Data Sets”
“Accessing Data Sets Using DFSMStvs and VSAM Record-Level Sharing”
“Specifying Read Integrity” on page 247
“Specifying a Timeout Value for Lock Requests” on page 247
“Index Trap” on page 248
Controlling Access to VSAM Data Sets
You can specify the following options to control DFSMStvs access to VSAM data
sets:
v VSAM record-level sharing (VSAM RLS)
v Read integrity options
v Timeout value for lock requests
If a VSAM data set is recoverable, DFSMStvs can open the data for input within a
transaction. A recoverable VSAM data set is defined with the LOG(UNDO) or
LOG(ALL) attribute. For more information about using recoverable VSAM data
sets, see z/OS DFSMStvs Planning and Operating Guide.
Accessing Data Sets Using DFSMStvs and VSAM Record-Level
Sharing
This topic describes the use of VSAM data sets for DFSMStvs.
VSAM record-level sharing (RLS) is an access option for VSAM data sets that
allows transactional (such as Customer Information Control System (CICS) and
DFSMStvs), and non-transactional applications to concurrently access data. This
option provides multisystem sharing of VSAM data sets across a z/OS Parallel
Sysplex®. VSAM RLS exploits the data sharing technology of the coupling facility
(CF) including a CF-based lock manager and a CF cache manager. VSAM RLS uses
the CF-based lock manager and the CF cache manager in its implementation of
record-level sharing.
Note: VSAM RLS requires that the data sets be System Managed Storage (SMS)
data sets. To be eligible for RLS, a data set that is not already SMS-managed must
be converted to SMS.
RLS is a mode of access to VSAM data sets. RLS is an access option interpreted at
open time. Select the option by specifying a new JCL parameter (RLS) or by
specifying MACRF=RLS in the ACB. The RLS MACRF option is mutually exclusive
with the MACRF NSR (nonshared resources), LSR (local shared resources), and
GSR (global shared resources) options. This topic uses the term non-RLS access to
distinguish between RLS access and NSR, LSR, and GRS access.
© Copyright IBM Corp. 1987, 2017
233
Using VSAM Record-Level Sharing
Access method services do not use RLS when performing an IDCAMS EXPORT,
IMPORT, PRINT, or REPRO command. If the RLS keyword is specified in the DD
statement of a data set to be opened by access method services, the keyword is
ignored and the data set is opened and accessed in non-RLS mode. See “Using
Non-RLS Access to VSAM Data Sets” on page 241 for more information about
non-RLS access.
RLS access is supported for KSDS, ESDS, RRDS, and VRRDS data sets, and for
VSAM alternate indexes.
The VSAM RLS functions are provided by the SMSVSAM server. This server
resides in a system address space. The address space is created and the server is
started at MVS IPL time. VSAM internally performs cross-address space accesses
and linkages between requestor address spaces and the SMSVSAM server address
space.
The SMSVSAM server owns two data spaces. One data space is called the
SMSVSAM data space. It contains some VSAM RLS control blocks and a
system-wide buffer pool. VSAM RLS uses the other data space, called MMFSTUFF,
to collect activity monitoring information that is used to produce SMF records.
VSAM provides the cross-address space access and linkage between the requestor
address spaces and the SMSVSAM address and data spaces. See Figure 29.
CICS AOR
address space
CICS AOR
address space
Batch job
address space
OPEN
OPEN
OPEN
ACB
ACB
ACB
MACRF=RLS
MACRF=RLS
MACRF=RLS
GET/PUT
GET/PUT
GET/PUT
VSAM RLS
Data space Data space
(SMSVSAM)
address space RLS buffer RLS activity
pool
Monitoring
information
RLS internal
control blocks
Figure 29. VSAM RLS address and data spaces and requestor address spaces
VSAM RLS data buffers occupy the largest share of the SMSVSAM data-space
storage. In some cases, storage limits on the data buffers may create performance
slowdowns in high-volume transaction environments. To avoid any storage limits
and potentially enhance performance, VSAM RLS offers the option to move RLS
data buffers into 64-bit addressable virtual storage. This option can be activated by
assigning VSAM data sets to a data class with ISMF that specifies
RlsAboveTheBar(YES). IBM recommends that you use this option, especially for
applications with a high rate of critical CICS transactions. For details on setting up
and using this option, see “Using 64-Bit Addressable Data Buffers” on page 239
Record-Level Sharing CF Caching
VSAM record-level sharing allows multiple levels of CF caching for DFSMS cache
structures that are defined in the active storage management subsystem (SMS)
configuration.
VSAM RLS has multiple levels of CF caching. The value of the SMS DATACLAS
RLS CF Cache Value keyword determines the level of CF caching.
234
z/OS DFSMS Using Data Sets
Using VSAM Record-Level Sharing
All active systems in a sysplex must have the greater than 4K CF caching feature
before the function is enabled.
To set up RLS CF caching, use the following values:
v ALL or UPDATESONLY or NONE or DIRONLY for the SMS DATACLAS RLS
CF Cache Value keyword
To allow greater than 4K caching of DFSMS VSAM data sets open for RLS
processing, you need to make the following changes:
– You can change the value of the SMS DATACLAS RLS CF Cache Value
keyword if you do not want caching of all VSAM RLS data:
ALL
Indicates that RLS is to cache VSAM index and data components in
the coupling facility. ALL is the default.
NONE
Indicates that RLS is to cache only the VSAM index data. The data
components are not to be placed in the cache structure.
UPDATESONLY
Indicates that RLS is to place only WRITE requests in the cache
structure.
DIRONLY
indicates that RLS will not cache data or index part of the VSAM data
set in the coupling facility cache structure. In this case, RLS will use
the XCF cache structure to keep track of data that resides in
permanent storage (DASD) and local storage but data or index CIs
are not stored in the cache structure itself.
– VSAM honors the RLS CF Cache Value keyword only when you specify
RLS_MaxCfFeatureLevel(A) and all systems in the sysplex can run the greater
than 4K caching code.
To determine the code level on each system in the sysplex and whether the
RLS CF Cache Value keyword is honored, use the D SMS,SMSVSAM, D
SMS,SMSVSAM,ALL, and D SMS,CFCACHE() operator commands. When
DFSMS cache structures connect to the system, VSAM RLS issues an IGW500I
message to indicate that greater than 4K caching is active. The cache
structures connect to the system through the first instance of a data set
opened on each system.
v You can specify the following values for the RLS_MaxCfFeatureLevel keyword:
– A—This value allows greater than 4K caching if all active VSAM RLS
instances in the sysplex have the correct level of code.
– Z—This is the default value if you do not specify RLS_MaxCfFeatureLevel in
the active SMS configuration. Greater than 4K caching is not allowed.
v RLS_MaxCfFeatureLevel keyword in the SETSMS command
v RLS_MaxCfFeatureLevel keyword in the SET SMSxx command
v RLS_MaxCfCacheFeatureLevel in the D SMS,OPTIONS command
VSAM Record-Level Sharing Multiple Lock Structure
VSAM record-level sharing has multiple lock structures that are defined in the
active storage management subsystem (SMS) configuration. You can define the
multiple, secondary lock structures by using the parameter, Lock Set, in the SMS
Storage Class definition. Using the lock set attribute, you can define an additional
Coupling Facility DFSMS Lock Structure to be associated with a single SMS
storage Class. DFSMS allows up to 256 Lock Sets and lock structures to be defined.
Chapter 14. Using VSAM Record-Level Sharing
235
Using VSAM Record-Level Sharing
Each Lock Set can contain a single lock structure name. However, the maximum
number of lock structures that can be connected is between 10 and 14, depending
on the MAXCAD value of IEASYSxx.
When an application opens a VSAM data set, RLS processing determines which
lock structure to use by checking the storage class defined for the data set. If the
storage class specifies a secondary lock structure, RLS processing uses the
secondary lock structure for serializing access to records in the data set. Otherwise,
RLS processing uses IGWLOCK00 for all record locking.
A secondary lock structure connection persists beyond data set closure. It is
disconnected only when you restart the SMSVSAM address spaces that use the
lock structure, or you delete the lock structure itself through the command VARY
SMS,SMSVSAM,FORCEDELETELOCKSTRUCTURE. See z/OS MVS System
Commands for details.
A failed persistent connection can exist even when the SMSVSAM address space
has been terminated. the lock structure can be deleted using the VARY
SMS,SMSVSAM,FORCEDELETELOCKSTRUCTURE command.
Note:
1. VSAM RLS does not support record locks for a single VSAM sphere to be
placed in multiple lock structures.
Using VSAM RLS with CICS
The CICS file-control component is a transactional file system built on top of
VSAM. CICS file control provides transactional function such as commit, rollback,
and forward recovery logging functions for recoverable data sets. Prior to VSAM
RLS, CICS file control performs its own record-level locking. The VSAM data sets
are accessed through a single CICS.
Users of multiple CICS regions have a file owning region (FOR) where the local
file definitions reside. The access to the data set from the FOR is through the local
file definition. Local data sets are accessed by the CICS application-owning region
(AOR) submitting requests directly to VSAM. The remote definition contains
information on the region and local filename. Sharing of data sets among regions
or systems is achieved by having a remote file definition in any other region that
wants to access the data set. If you are not using VSAM RLS, sharing is achieved
by having remote definitions for the local file in any region that wants to share it.
Figure 30 on page 237 shows the AOR, FOR, and VSAM request flow prior to
VSAM RLS.
236
z/OS DFSMS Using Data Sets
Using VSAM Record-Level Sharing
CICS
AOR
CICS
AOR
CICS
AOR
CICS
AOR
VSAM
VSAM
CICS
FOR
VSAM
MVS 1
MVS n
Figure 30. CICS VSAM non-RLS access
The CICS AOR's function ships VSAM requests to access a specific data set to the
CICS FOR that owns the file that is associated with that data set. This distributed
access form of data sharing has existed in CICS for some time.
With VSAM RLS, multiple CICS AORs can directly share access to a VSAM data
set without CICS function shipping. With VSAM RLS, CICS continues to provide
the transactional functions. The transactional functions are not provided by VSAM
RLS itself. VSAM RLS provides CF-based record-level locking and CF data caching.
Figure 31 shows a CICS configuration with VSAM RLS.
CICS
AOR
CICS
AOR
CICS
AOR
CICS
AOR
VSAM RLS
instance 1
VSAM RLS
instance n
SMSVSAM
address space
SMSVSAM
address space
MVS 1
MVS n
Coupling facility (CF)
Figure 31. CICS VSAM RLS
VSAM RLS is a multisystem server. The CICS AORs access the shared data sets by
submitting requests directly to the VSAM RLS server. The server uses the CF to
serialize access at the record level.
Chapter 14. Using VSAM Record-Level Sharing
237
Using VSAM Record-Level Sharing
Related reading: For an overview of CICS, and for more information about using
CICS to recover data sets, see CICS Transaction Server for z/OS
(www.ibm.com/support/knowledgecenter/SSGMGV/welcome.html).
Recoverable and Nonrecoverable Data Sets
CICS file control supports recoverable or nonrecoverable data sets. DFSMStvs
supports only recoverable data sets; it allows batch update of recoverable VSAM
data sets, even while CICS is processing the data sets. A data set definition
includes a LOG attribute that denotes whether the data set is recoverable. The
attribute options are specified as follows:
v LOG(NONE)—nonrecoverable
Specifies the data set as nonrecoverable. CICS does not perform any logging of
changes for a data set that has this attribute. Neither rollback nor forward
recovery is provided.
v LOG(UNDO)—recoverable
Specifies the data set as commit or rollback recoverable. CICS and DFSMStvs log
the before (UNDO) images of changes to the data set and backs out the changes
if the application requests rollback or if the transaction terminates abnormally.
v LOG(ALL)—recoverable
Specifies the data set as both commit or rollback recoverable and forward
recoverable. In addition to the logging and recovery functions provided for
LOG(UNDO), CICS logs the after image of changes (REDO record) to the data
set. The redo log records are used by forward recovery programs or products
such as CICS VSAM Recovery (CICSVR) to reconstruct the data set in the event
of hardware or software damage to the data set.
Attention: Specifying LOG(NONE) is different from not specifying LOG at all. If
you do not specify LOG, RLS cannot access the data set.
You can specify VSAM recoverable data set control attributes in IDCAMS (access
method services) DEFINE and ALTER commands. In the data class, you can
specify LOG along with the BWO and LOGSTREAMID parameters. If you want to
be able to back up a data set while it is open, you should define them using the
IDCAMS BWO(TYPECICS) parameter. Only a CICS application or DFSMStvs can
open a recoverable data set for output because VSAM RLS does not provide the
logging and other transactional functions required for writing to a recoverable data
set.
When a data set is opened in a non-RLS access mode (NSR, LSR, or GSR), the
recoverable attributes of the data set do not apply and are ignored. The recoverable
data set rules have no impact on existing programs that do not use RLS access.
CICS Transactional Recovery for VSAM Recoverable Data Sets
The transactional services of CICS provide an ideal environment for data sharing.
Exclusive locks held by VSAM RLS on the modified records cause
read-with-integrity and write requests to these records by other transactions to
wait. After the modifying transaction commits or rolls back, the locks are released
and other transactions can access the records.
The CICS rollback (backout) function removes changes made to the recoverable
data sets by a transaction. When a transaction terminates abnormally, CICS
implicitly performs a rollback.
The commit and rollback functions protect an individual transaction from changes
that other transactions make to a recoverable data set or other recoverable
238
z/OS DFSMS Using Data Sets
Using VSAM Record-Level Sharing
resource. This lets the transaction logic focus on the function it is providing and
not have to be concerned with data recovery or cleanup in the event of problems
or failures.
Non-CICS Use of VSAM RLS
When VSAM RLS is used outside of CICS or DFSMStvs, the applications do not
have the transactional recovery environment. In most cases, this makes read/write
data sharing not feasible.
A non-CICS application other than DFSMStvs is permitted to open a recoverable
data set in RLS mode only for input. VSAM RLS provides the necessary
record-level locking to provide read-with-integrity (if requested) for the non-CICS
application. This functionality lets multiple CICS applications have the data set
open for read and write RLS access. CICS provides the necessary transactional
recovery for the writes to the recoverable data set. Concurrently, non-CICS
applications outside DFSMStvs can have the data set open for read RLS access.
Using 64-Bit Addressable Data Buffers
For each system in a sysplex, the SMSVSAM address space contains all the VSAM
RLS data buffers. By default, the data buffers are contained below the 2-gigabyte
virtual storage bar in a data space. To avoid possible buffer space constraints and
potentially improve performance for high-transaction applications, you can
optionally specify that data sets and indexes be assigned to RLS buffers with 64-bit
virtual addresses, above the 2-gigabyte bar. This 64-bit virtual buffering option is
provided by a combination of data class keyword and settings in the IGDSMSxx
member of SYS1.PARMLIB.
To provide 64-bit data buffering for a data set with VSAM RLS, all the following
must be true:
v The system must be at level z/OS 1.7 or higher.
v The data set or index must belong to a data class with the attribute “RLS Above
the 2-GB Bar” set to Yes.
v The active IGDSMSxx member of SYS1.PARMLIB must have the keyword
RlsAboveTheBarMaxPoolsize set to a number between 500 megabytes or 2
terabytes for the system.
In addition, to enhance performance for each named system, whether or not the
buffers are above the 2-gigabyte bar, you can set the keyword RlsFixedPoolSize in
IGDSMSxx to specify the amount of total real storage to be permanently fixed to
be used as data buffers.
Setting a Data Class for 64-bit data buffering
The ISMF data class attribute “RLS Above the 2-GB Bar”is one of the three
required conditions in determining whether the buffers for a VSAM data set will
be above or below the 2-GB bar; the default is below the bar. To make the data
class eligible for using the RLS buffers above the bar, specify Yes for “RLS Above
the 2-GB Bar” on the Data Class Define or Alter panels. Then assign the VSAM
data set to the data class.
Setting IGDSMSxx PARMLIB values for VSAM RLS data buffering
Use the following keywords in SYS1.PARMLIB member IGDSMSxx to specify the
amount and placement of data buffer space for use by VSAM RLS:
Chapter 14. Using VSAM Record-Level Sharing
239
Using VSAM Record-Level Sharing
RlsAboveTheBarMaxPoolSize(sysname1,value1;sysname2,value2;...) or
(ALL,value)
Specifies the total size of the buffer pool, in megabytes, to reside above the
2-megabyte bar on each named system or all systems. The system programmer
can specify different values for individual systems in the sysplex, or one value
that applies to all the systems in the sysplex. Valid values are 0 (the default), or
values between 500 megabytes and 2000000 megabytes (2 terabytes).
RlsFixedPoolSize(sysname1,value1;sysname2,value2;...) or (ALL,value)
Specifies the total real storage, in megabytes (above or below the 2-gigabyte
bar) to be permanently fixed or “pinned” for the use of VSAM RLS data
buffers. The default is 0. The system programmer can specify different values
for individual systems in the sysplex, or one value that applies to all the
systems in the sysplex. If the specified amount is 80% or more of the available
real storage, the amount is capped at 80% and a write-to-operator (WTO)
message is issued to warn of the limit being reached.
To help determine the amount of real storage to use for VSAM RLS buffering,
you can check SMF record Type 42, subtype 19, for the hit ratio for VSAM RLS
buffers. A large number of misses indicates a need for more real storage to be
pinned for the use of VSAM RLS.
Note: If you have relatively small auxiliary storage size, permanently
page-fixing buffers by the RlsFixedPoolSize keyword may require installing
additional auxiliary storage. That is because the equivalent number of pages
will likely be stolen to auxiliary storage to compensate for the decrease in real
storage available for paging due to the permanent page fix.
These values can be changed later by using the SET SMS=xx command with these
keywords specified in the IGDSMSxx member, or by using the SETSMS command
with the specific keywords to be changed.
As usual, the changed parameters in IGDSMSxx cannot take effect until SET
SMS=xx has been issued.
Other than modifying the IGDSMSxx PARMLIB member, the
RlsAboveTheBarMaxPoolSize and RlsFixedPoolSize values can also be changed
with the SETSMS command.
Note: The changes with SETSMS and SET SMS=xx do not take effect immediately.
If the data set has been opened on a system, the SETSMS and SET SMS changes to
RlsAboveTheBarMaxPoolSize and RlsFixedPoolSize do not take effect on that
system until the SMSVSAM address space is recycled. If the data set has not been
opened on that system, the SETSMS and SET SMS changes to the two keywords
will take effect when the data set is opened the first time on the system, without
the need to recycle SMSVSAM.
For more information about specifying IGDSMSxx parameters, see z/OS MVS
Initialization and Tuning Reference. For more information about checking SMF
records, see z/OS MVS System Management Facilities (SMF). See z/OS MVS System
Commands for detailed information on the SET SMS and SETSMS commands.
Read Sharing of Recoverable Data Sets
A non-CICS application outside DFSMStvs is permitted to open a recoverable data
set in RLS mode only for input. VSAM RLS provides the necessary record-level
locking to provide read-with-integrity (if requested) for the non-CICS application.
240
z/OS DFSMS Using Data Sets
Using VSAM Record-Level Sharing
This support lets multiple CICS applications have the data set open for read/write
RLS access. CICS provides the necessary transactional recovery for the writes to
the recoverable data set. Concurrently, non-CICS applications outside DFSMStvs
can have the data set open for read RLS access. VSAM provides the necessary
locking. Because the non-CICS application is not permitted to write to the data set,
transactional recovery is not required.
Read-Sharing Integrity across KSDS CI and CA Splits
VSAM with non-RLS access does not ensure read integrity across splits for
non-RLS access to a data set with cross-region share options 2, 3, and 4. If read
integrity is required, the application must ensure it. When KSDS CI and CA splits
move records from one CI to another CI, there is no way the writer can invalidate
the data and index buffers for the reader. This can result in the reader not seeing
some records that were moved.
VSAM RLS can ensure read integrity across splits. It uses the cross-invalidate
function of the CF to invalidate copies of data and index CI in buffer pools other
than the writer's buffer pool. This ensures that all RLS readers, DFSMStvs, CICS,
and non-CICS outside DFSMStvs, are able to see any records moved by a
concurrent CI or CA split. On each GET request, VSAM RLS tests validity of the
buffers and when invalid, the buffers are refreshed from the CF or DASD.
Read and Write Sharing of Nonrecoverable Data Sets
Nonrecoverable data sets are not part of transactional recovery. Commit and
rollback logging do not apply to these data sets. Because transactional recovery is
not required, VSAM RLS permits read and write sharing of nonrecoverable data
sets concurrently by DFSMStvs, CICS, and non-CICS applications. Any application
can open the data set for output in RLS mode.
VSAM RLS provides record locking and buffer coherency across the CICS and
non-CICS read/write sharers of nonrecoverable data sets. However, the record lock
on a new or changed record is released as soon as the buffer that contains the
change has been written to the CF cache and DASD. This differs from the case in
which a DFSMStvs or CICS transaction modifies VSAM RLS recoverable data sets
and the corresponding locks on the added and changed records remain held until
the end of the transaction.
For sequential and skip-sequential processing, VSAM RLS does not write a
modified control interval (CI) until the processing moves to another CI or an
ENDREQ is issued by the application. If an application or the VSAM RLS server
ends abnormally, these buffered changes are lost. To help provide data integrity,
the locks for those sequential records are not released until the records are written.
While VSAM RLS permits read and write sharing of nonrecoverable data sets
across DFSMStvs and CICS and non-CICS applications, most applications are not
designed to tolerate this sharing. The absence of transactional recovery requires
very careful design of the data and the application.
Using Non-RLS Access to VSAM Data Sets
RLS access does not change the format of the data in the VSAM data sets. The data
sets are compatible for non-RLS access. If the data set has been defined with a
cross-region share option of 2, a non-RLS open for input is permitted while the
data set is open for RLS processing; but a non-RLS open for output fails. If the
data set is already open for non-RLS output, an open for RLS fails. Therefore, at
Chapter 14. Using VSAM Record-Level Sharing
241
Using VSAM Record-Level Sharing
any time, a data set can be open for non-RLS write access or open for RLS
access.To open a data set specifying RLS-in-use for non-RLS access, SMSVSAM
must be active on the system issuing the non-RLS open.
CICS and VSAM RLS provide a quiesce function to assist in the process of
switching a data set from CICS RLS usage to non-RLS usage.
After an RPL has been used for non-RLS access, the RPL might have residual
settings for that non-RLS request. If that RPL is used again for an RLS request,
whether or not for the same data set, be sure to clear the RPL settings and set the
fields for the RLS request; otherwise there might be ABENDs or unpredictable
results. Should the RLS RPL is used again for non-RLS access, the same would be
true. It might be safer and easier to use separate RPLs for RLS and non-RLS
requests.
RLS Access Rules
The following table illustrates RLS access rules, showing the possible scenarios for
opening data sets with and without RLS. In Table 21, OPEN1 represents an initial
successful open and OPEN2 represents the options for a subsequent open of the
same data set, with or without RLS.
Table 21. RLS open rules, for recoverable or non-recoverable data sets
OPEN1 Did—>
OPEN2 Wants:
RLS
Non-RLS Input with Non-RLS Output, or
SHR(2 x)
Input without SHR(2
x)
RLS
See note below
OK
NO
Non-RLS Input with
SHR(2 x)
OK
OK
SHAREOPTIONS
rules
Non-RLS Output, or
Input without SHR(2
x)
NO
SHAREOPTIONS
rules
SHAREOPTIONS
rules
Note: For non-recoverable data sets, either transactional (CICS or DFSMStvs) RLS
or non-transactional (non-CICS and non-DFSMStvs) RLS is acceptable. For
recoverable data sets:
v Transactional RLS can share with: any transactional RLS accesses, and input-only
non-transactional RLS accesses (non-transactional RLS cannot update recoverable
data sets)
v Non-transactional RLS can share with any non-transactional RLS as long as they
do not update the recoverable data sets.
For example, if OPEN1 already successfully opened the data set to be accessed
with RLS, the subsequent OPEN2 attempting to open it for non-RLS output would
fail, regardless of whether or not the data set is recoverable. With the same
OPEN1, if the data set is recoverable, OPEN2 can open it for non-transactional
(that is, non-commit protocol) RLS input-only access.
Comparing RLS Access and Non-RLS Access
This topic describes the differences between RLS access and non-RLS access.
Share Options
For non-RLS access, VSAM uses the share options settings to determine the type of
sharing permitted. If you set the cross-region share option to 2, a non-RLS open for
242
z/OS DFSMS Using Data Sets
Using VSAM Record-Level Sharing
input is permitted while the data set is already open for RLS access. VSAM
provides full read and write integrity for the RLS users, but does not provide read
integrity for the non-RLS user. A non-RLS open for output is not permitted when
already opened for RLS.
VSAM RLS provides full read and write sharing for multiple users; it does not use
share options settings to determine levels of sharing. When an RLS open is
requested and the data set is already open for non-RLS input, VSAM does check
the cross-region setting. If it is 2, then the RLS open is permitted. The open fails for
any other share option or if the data set has been opened for non-RLS output.
Locking
Non-RLS provides local locking (within the scope of a single buffer pool) of the
VSAM control interval. Locking contention can result in an “exclusive control
conflict” error response to a VSAM record management request.
VSAM RLS uses a DFSMS lock manager to provide a system-managed duplexing
rebuild process. The locking granularity is at the VSAM record level. When
contention occurs on a VSAM record, the request that encountered the contention
waits for the contention to be removed. The DFSMS lock manager provides
deadlock detection. When a lock request is in deadlock, VSAM rejects the request.
This results in the VSAM record management request completing with a deadlock
error response.
When you request a user-managed rebuild for a lock structure, the validity check
function determines if there is enough space for the rebuild process to complete. If
there is not enough space, the system rejects the request and displays an
informational message.
When you request an alter operation for a lock structure, the validity check
function determines if there is enough space for the alter process to complete. If
there is not enough space, the system displays a warning message that includes the
size recommendation.
VSAM RLS supports a timeout value that you can specify through the RPL, in the
PARMLIB, or in the JCL. Recoverable regions, such as CICS, use this parameter to
ensure that a transaction does not wait indefinitely for a lock to become available.
VSAM RLS uses a timeout function of the DFSMS lock manager.
When an ESDS is used with VSAM RLS, to serialize the processing of ESDS
records, an exclusive, sysplex-wide data-set level “add to end” lock is held each
time a record is added to the end of the data set. Reading and updating of existing
records do not acquire the lock. Non-RLS VSAM does not need such serialization
overhead because it does not serialize ESDS record additions across the sysplex.
Recommendation: Carefully design your use of ESDS with RLS; otherwise, you
might see performance differences between accessing ESDSs with and without
RLS.
Retaining locks: VSAM RLS uses share and exclusive record locks to control
access to the shared data. An exclusive lock is used to ensure that a single user is
updating a specific record. The exclusive lock causes any read-with-integrity
request for the record by another user (CICS transaction or non-CICS application)
to wait until the update is finished and the lock released.
Chapter 14. Using VSAM Record-Level Sharing
243
Using VSAM Record-Level Sharing
Failure conditions can delay completion of an update to a recoverable data set.
This occurs when a CICS transaction enters in-doubt status. This means CICS can
neither rollback nor commit the transaction. Therefore, the recoverable records
modified by the transaction must remain locked. Failure of a CICS AOR also
causes the current transaction's updates to recoverable data sets not to complete.
They cannot complete until the AOR is restarted.
When a transaction enters in-doubt, sysplex failure, MVS failure, failure of an
instance of the SMSVSAM Address Space, or a CICS AOR terminates, any
exclusive locks on records of recoverable data sets held by the transaction must
remain held. However, other users waiting for these locks should not continue to
wait. The outage is likely to be longer than the user would want to wait. When
these conditions occur, VSAM RLS converts these exclusive record locks into
retained locks.
Both exclusive and retained locks are not available to other users. When another
user encounters lock contention with an exclusive lock, the user's lock request
waits. When another user encounters lock contention with a retained lock, the lock
request is immediately rejected with “retained lock” error response. This results in
the VSAM record management request that produced the lock request failing with
“retained lock” error response.
If you close a data set in the middle of a transaction or unit of recovery and it is
the last close for this data set on this system, then RLS converts the locks from
active to retained.
Supporting non-RLS access while retained locks exist: Retained locks are created
when a failure occurs. The locks need to remain until completion of the
corresponding recovery. The retained locks only have meaning for RLS access.
Lock requests issued by RLS access requests can encounter the retained locks.
Non-RLS access does not perform record locking and therefore would not
encounter the retained locks.
To ensure integrity of a recoverable data set, VSAM does not permit non-RLS
update access to the data set while retained locks exist for that data set. There can
be situations where an installation must execute some non-CICS applications that
require non-RLS update access to the data set. VSAM RLS provides an IDCAMS
command (SHCDS PERMITNONRLSUPDATE) that can be used to set the status of
a data set to enable non-RLS update access to a recoverable data set while retained
locks exist. This command does not release the retained locks. If this function is
used, VSAM remembers its usage and informs the CICSs that hold the retained
locks when they later open the data set with RLS.
If you use the SHCDS PERMITNONRLSUPDATE command, neither CICS nor
DFSMStvs has any idea whether or not it is safe to proceed with pending
backouts. Because of this, you must supply exits that DFSMStvs and CICS call, and
each exit must tell the resource manager whether or not to go ahead with the
backout. For more information, see the description of the batch override exit in
“IGW8PNRU Routine for Batch Override” on page 258.
VSAM Options Not Used by RLS
RLS does not support the following options and capabilities:
v Linear data sets
v Addressed access to a KSDS
v Control interval (CNV or ICI) to any VSAM data set type
244
z/OS DFSMS Using Data Sets
Using VSAM Record-Level Sharing
v User buffering (UBF)
v Clusters that have been defined with the IMBED option
v Key Range data sets
v Temporary data sets
v GETIX and PUTIX requests
v MVS Checkpoint/Restart facility
v ACBSDS (system data set) specification
v Hiperbatch
v VVDS, the JRNAD exit, and any JCL AMP= parameters in JCL
v Data that is stored in z/OS UNIX System Services
In addition, VSAM RLS has the following restrictions:
v You cannot specify RLS access when accessing a VSAM data set using the ISAM
interface to VSAM.
v You cannot open individual components of a VSAM cluster for RLS access.
v You cannot specify a direct open of an alternate index for RLS access, but you
can specify RLS open of an alternate index path.
v RLS open does not implicitly position to the beginning of the data set. For
sequential or skip-sequential processing, specify a POINT or GET DIR, NSP
request to establish a position in the data set.
v RLS does not support a request that is issued while the caller is executing in any
of the following modes: cross-memory mode, SRB mode, or under an FRR. See
“Requesting VSAM RLS Run-Mode” for a complete list of mode requirements.
v RLS does not support UNIX files.
Requesting VSAM RLS Run-Mode
When a program issues a VSAM RLS request (OPEN, CLOSE, or Record
Management request), the program must be running in the following run mode,
with the listed constraints:
v Task mode (not SRB mode)
v Address space control=primary
v Home address space=primary address space=secondary address space
v No functional recovery routine (FRR) can be in effect, but an ESTAE might be.
The VSAM RLS record management request task must be the same task that
opened the ACB, or the task that opened the ACB must be in the task hierarchy.
That is, the record management task was attached by the task that opened the
ACB, or by a task that was attached by the task that opened the ACB.
Using VSAM RLS Read Integrity Options
VSAM RLS provides three levels of read integrity as follows:
1. NRI—no read integrity
This tells VSAM RLS not to obtain a record lock on the record accessed by a
GET or POINT request. This avoids the overhead of record locking. This is
sometimes referred to as dirty read because the reader might see an
uncommitted change made by another transaction.
Even with this option specified, VSAM RLS still performs buffer validity
checking and buffer refresh when the buffer is invalid. Thus, a sequential
Chapter 14. Using VSAM Record-Level Sharing
245
Using VSAM Record-Level Sharing
reader of a KSDS does not miss records that are moved to new control intervals
by control interval (CI) and control area (CA) splits.
There are situations where VSAM RLS temporarily obtains a shared lock on the
record even though NRI is specified. This situation happens when the read
encounters an inconsistency within the VSAM data set while attempting to
access the record. An example of this is path access through an alternate index
to a record for which a concurrent alternate index upgrade is being performed.
The path access sees an inconsistency between the alternate index and base
cluster. This would normally result in an error response return code 8 and
reason code 144. Before giving this response to the NRI request, VSAM RLS
obtains a shared lock on the base cluster record that was pointed to by the
alternate index. This ensures that if the record was being modified, the change
and corresponding alternate index upgrade completes. The record lock is
released. VSAM retries the access. The retry should find the record correctly.
This internal record locking may encounter locking errors such as deadlock or
timeout. Your applications must be prepared to accept locking error return
codes that may be returned on GET or POINT NRI requests. Normally such
errors will not occur.
2. CR—consistent read
This tells VSAM RLS to obtain a SHARE lock on the record accessed by a GET
or POINT request. It ensures the reader does not see an uncommitted change
made by another transaction. Instead, the GET/POINT waits for the change to
be committed or backed out and the EXCLUSIVE lock on the record to be
released.
3. CRE—consistent read explicit
This is the same as CR, except VSAM RLS keeps the SHARE lock on the record
until end-of-transaction. This option is only available to CICS or DFSMStvs
transactions. VSAM does not understand end-of-transaction for non-CICS or
non-DFSMStvs usage.
This capability is often referred to as REPEATABLE READ.
The record locks obtained by the VSAM RLS GET requests with CRE option
inhibit update or erase of the records by other concurrently executing
transactions. However, the CRE requests do not inhibit the insert of other
records by other transactions. The following cases need to be considered when
using this function.
a. If a GET DIR (direct) or SKP (skip sequential) request with CRE option
receives a “record not found” response, VSAM RLS does not retain a lock
on the nonexistent record. The record could be inserted by another
transaction.
b. A sequence of GET SEQ (sequential) requests with CRE option results in a
lock being held on each record that was returned. However, no additional
locks are held that would inhibit the insert of new records in between the
records locked by the GET CRE sequential processing. If the application
were to re-execute the previously executed sequence of GET SEQ,CRE
requests, it would see any newly inserted records. Within the transactional
recovery community, these records are referred to as “phantom” records.
The VSAM RLS CRE function does not inhibit phantom records.
Using VSAM RLS with ESDS
Using VSAM RLS with ESDSs provides greater scalability and availability over
non-RLS VSAM. However, in comparison with non-RLS VSAM, using VSAM RLS
with ESDSs might result in performance degradation in certain operating
environments.
246
z/OS DFSMS Using Data Sets
Using VSAM Record-Level Sharing
To serialize the adding of ESDS records across the sysplex, VSAM RLS obtains an
“add-to-end” lock exclusively for every record added to the end of the data set. If
applications frequently add records to the same ESDS, the requests are serially
processed and therefore, performance degradation might be experienced.
In comparison, non-RLS VSAM has a different set of functions and does not
require serializing ESDS record additions across the sysplex. If an ESDS is shared
among threads, carefully design your use of ESDS with RLS to lessen any possible
impact to performance, as compared to the use of ESDSs with non-RLS VSAM.
Note: For VSAM RLS, the system obtains a global data-set-level lock only for
adding an ESDS record to the data set, not for reading or updating existing ESDS
records. Therefore, GET requests and PUT updates on other records for the data
sets do not obtain the “add-to-end” lock. Those updates can be processed while
another thread holds the “add-to-end” lock.
How long the RLS “add-to-end” lock is held depends on whether the data set is
recoverable and on the type of PUT request that adds the record. If the data set is
recoverable, RLS does not implicitly release the lock. The lock is explicitly released
by ENDREQ, IDAEADD, or IDALKREL. For nonrecoverable data sets, the PUT
SEQ command releases the lock after writing a few buffers, whereas the PUT DIR
command releases the lock at the end of the request.
Specifying Read Integrity
You can use one of the following subparameters of the RLS parameter to specify a
read integrity option for a VSAM data set.
NRI
Specifies no read integrity (NRI). The application can read all records.
CR Specifies consistent read (CR). This subparameter requests that VSAM obtain a
SHARE lock on each record that the application reads.
CRE
Specifies consistent read explicit (CRE). This subparameter requests
serialization of the record access with update or erase of the record by another
unit of recovery.
CRE gives DFSMStvs access to VSAM data sets open for input or output. CR or
NRI gives DFSMStvs access to VSAM recoverable data sets only for output.
Related reading:
v For information about how to use these read integrity options for DFSMStvs
access, see z/OS DFSMStvs Planning and Operating Guide.
v For complete descriptions of these subparameters, see the description of the RLS
parameter in z/OS MVS JCL Reference.
Specifying a Timeout Value for Lock Requests
You can use the RLSTMOUT parameter of the JCL EXEC statement to specify a
timeout value for lock requests. A VSAM RLS or DFSMStvs request waits the
specified number of seconds for a required lock before the request times out and is
assumed to be in deadlock.
For information about the RLSTMOUT parameter, see the description of the EXEC
statement in z/OS MVS JCL Reference.
Chapter 14. Using VSAM Record-Level Sharing
247
Using VSAM Record-Level Sharing
Related reading :
v For information about avoiding deadlocks and additional information about
specifying a timeout value, see z/OS DFSMStvs Planning and Operating Guide.
v z/OS MVS Initialization and Tuning Guide.
Index Trap
For VSAM RLS, there is an index trap that checks each index record before writing
it.The trap detects the following index corruptions:
v High-used greater than high-allocated
v Duplicate or invalid index pointer
v Out-of-sequence index record
v Invalid section entry
v Invalid key length.
For more information about the VSAM RLS index trap for system programmers,
see z/OS DFSMSdfp Diagnosis.
248
z/OS DFSMS Using Data Sets
Chapter 15. Checking VSAM Key-Sequenced Data Set
Clusters for Structural Errors
This chapter covers the following topics.
Topic
“EXAMINE Command”
“How to Run EXAMINE” on page 250
“Samples of Output from EXAMINE Runs” on page 252
This chapter describes how the service aid, EXAMINE, is used to analyze a
key-sequenced data set (KSDS) cluster for structural errors.
EXAMINE Command
EXAMINE is an access method services command that lets users analyze and
collect information on the structural consistency of key-sequenced data set clusters.
This service aid consists of two tests: INDEXTEST and DATATEST.
INDEXTEST examines the index component of the key-sequenced data set cluster
by cross-checking vertical and horizontal pointers contained within the index
control intervals, and by performing analysis of the index information. It is the
default test of EXAMINE.
DATATEST evaluates the data component of the key-sequenced data set cluster by
sequentially reading all data control intervals, including free space control
intervals. Tests are then carried out to ensure record and control interval integrity,
free space conditions, spanned record update capacity, and the integrity of internal
VSAM pointers contained within the control interval.
For a description of the EXAMINE command syntax, see z/OS DFSMS Access
Method Services Commands.
Types of Data Sets
EXAMINE can test the following types of data sets:
v Key-sequenced data set
v Catalog
EXAMINE Users
EXAMINE end users fall into two categories:
1. Application Programmer/Data Set Owner. These users want to know of any
structural inconsistencies in their data sets, and they are directed to
corresponding recovery methods that IBM supports by the appropriate
summary messages. The users' primary focus is the condition of their data sets;
therefore, they should use the ERRORLIMIT(0) parameter of EXAMINE to
suppress printing of detailed error messages.
2. System Programmer/Support Personnel. System programmers or support
personnel need the information from detailed error messages to document or
fix a problem with a certain data set.
© Copyright IBM Corp. 1987, 2017
249
Checking VSAM Key-Sequenced Data Set Clusters for Structural Errors
Users must have master level access to a catalog or control level access to a data
set to examine it. Master level access to the master catalog is also sufficient to
examine a user catalog.
How to Run EXAMINE
During an EXAMINE run, the following considerations for sharing data sets apply:
v No users should be open to the data set while EXAMINE runs.
v EXAMINE issues the message “IDC01723I ERRORS MAY BE DUE TO
CONCURRENT ACCESS” if it detects any errors; the data set might have been
open for output during testing. This message does not necessarily indicate that
the reported errors are because of concurrent access.
v When you run EXAMINE against a catalog, concurrent access might have
occurred without the message being issued. Because system access to the catalog
can be difficult to stop, you should not run jobs that would cause an update to
the catalog.
For further considerations for data set sharing, see Chapter 12, “Sharing VSAM
Data Sets,” on page 205.
Before using EXAMINE with a catalog or data set that has been closed improperly
(as a result of a CANCEL, ABEND or system error), use the VERIFY RECOVER
command. See “Using VERIFY to Process Improperly Closed Data Sets” on page 60
for more information.
Deciding to Run INDEXTEST, DATATEST, or Both Tests
INDEXTEST reads the entire index component of the KSDS cluster.
DATATEST reads the sequence set from the index component and the entire data
component of the KSDS cluster. So, it should take considerably more time and
more system resources than INDEXTEST.
If you are using EXAMINE to document an error in the data component, run both
tests. If you are using EXAMINE to document an error in the index component, it
is usually not necessary to run DATATEST.
If you are using EXAMINE to confirm a data set's integrity, your decision to run
one or both tests depends on the time and resources available.
Skipping DATATEST on Major INDEXTEST Errors
If you decide to run both tests (INDEXTEST and DATATEST), INDEXTEST runs
first. If INDEXTEST finds major structural errors, DATATEST does not run, even
though you requested it. This gives you a chance to review the output from
INDEXTEST and to decide whether you need to run DATATEST.
If you want to run DATATEST unconditionally, you must specify the
NOINDEXTEST parameter in the EXAMINE command to bypass INDEXTEST.
Examining a User Catalog
You must have master-level access for either the user catalog being examined or
for the master catalog. If you have master-level access for the master catalog, the
self-describing records in the user catalog will not be read during open. If you
have master-level access only for the user catalog being examined, the catalog
self-describing records will be read during open.
250
z/OS DFSMS Using Data Sets
Checking VSAM Key-Sequenced Data Set Clusters for Structural Errors
If the master catalog is protected by RACF or an equivalent product and you do
not have alter authority for the catalog, a message can be issued indicating an
authorization failure when the check indicated previously is made. This is normal,
and, if you have master level access to the catalog being examined, the
examination can continue.
Recommendation: When you analyze a catalog, use the VERIFY command before
you use the EXAMINE command.
Understanding Message Hierarchy
Messages describing errors or inconsistencies are generated during EXAMINE
processing as that condition is detected. The detection of an error condition can
result in the generation of many messages. There are five distinct types of
EXAMINE error messages:
1. Status and Statistical Messages. This type of message tells you the status of
the EXAMINE operation, such as the beginning and completion of each test. It
provides general statistical data, such as the number of data records, the
percentage of free space in data control intervals (CIs), and the number of
deleted CIs. The four status messages are IDC01700I, IDC01701I, IDC01709I,
and IDC01724I. The five statistical messages are IDC01708I, IDC01710I,
IDC01711I, IDC01712I, and IDC01722I.
2. Supportive (Informational) Messages. Supportive messages (all remaining
IDC0-type messages) issued by EXAMINE clarify individual data set structural
errors and provide additional information pertinent to an error.
3. Individual Data Set Structural Error Messages. The identification of an error is
always reported by an individual data set structural error (IDC1-type) message
that can be immediately followed by one or more supportive messages.
4. Summary Error Messages. One or more summary error (IDC2-type) messages
are generated at the completion of either INDEXTEST or DATATEST to
categorize all individual data set structural error (IDC1-type) messages
displayed during the examination. The summary error message represents the
final analysis of the errors found, and the user should follow the course of
recovery action as prescribed by the documentation.
5. Function-Not-Performed Messages. Function-not-performed messages (all of
the IDC3-type messages) indicate that the function you requested cannot be
successfully performed by EXAMINE. In each case, the test operation
terminates before the function completes.
Function-not-performed messages are issued for a variety of reasons, some of
that follows:
v A nonvalid request (such as an attempt to examine an entry-sequenced data
set (ESDS))
v A physical I/O error in a data set
v A system condition (such as insufficient storage)
v A system error (such as an OBTAIN DSCB failed)
v An error found during INDEXTEST (see “Skipping DATATEST on Major
INDEXTEST Errors” on page 250).
Controlling Message Printout
Use the ERRORLIMIT parameter in the EXAMINE command to suppress
supportive and individual data set structural error messages during an EXAMINE
run. This parameter indicates the number of these error messages to print. When
EXAMINE reaches this number of errors, it stops issuing error messages but
Chapter 15. Checking VSAM Key-Sequenced Data Set Clusters for Structural Errors
251
Checking VSAM Key-Sequenced Data Set Clusters for Structural Errors
continues to scan the data set. ERRORLIMIT (0) means that none of these messages
will be printed. When you do not specify the ERRORLIMIT parameter (the default
condition), all supportive and individual data set structural error messages are
printed. Note that the status and statistical messages, summary messages, and
function-not-performed messages are not under the control of ERRORLIMIT, and
print regardless of the ERRORLIMIT settings. The ERRORLIMIT parameter is used
separately by INDEXTEST and DATATEST. For more information about using this
parameter see z/OS DFSMS Access Method Services Commands.
Samples of Output from EXAMINE Runs
This topic shows examples of output from EXAMINE runs.
INDEXTEST and DATATEST Tests of an Error-Free Data Set
In this run, INDEXTEST and DATATEST are both run successfully against an
error-free data set. The first four messages tell us the status of the two EXAMINE
tests, that performed with no errors detected. The next five messages then
summarize component statistics as revealed by the DATATEST.
IDCAMS SYSTEM SERVICES
EXAMINE NAME(EXAMINE.KD05) INDEXTEST DATATEST
IDC01700I
IDC01724I
IDC01701I
IDC01709I
INDEXTEST BEGINS
INDEXTEST COMPLETES NO ERRORS DETECTED
DATATEST BEGINS
DATATEST COMPLETES NO ERRORS DETECTED
IDC01708I
IDC01710I
IDC01711I
IDC01712I
IDC01722I
45 CONTROL INTERVALS ENCOUNTERED
DATA COMPONENT CONTAINS 1000 RECORDS
DATA COMPONENT CONTAINS 0 DELETED CONTROL INTERVALS
MAXIMUM LENGTH DATA RECORD CONTAINS 255 BYTES
65 PERCENT FREE SPACE
IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0
INDEXTEST and DATATEST Tests of a Data Set with a
Structural Error
The user intended to run both tests, INDEXTEST and DATATEST, but INDEXTEST
found an error in the sequence set. From the messages, we learn the following:
v A structural problem was found in the index component of the KSDS cluster.
v The current index level is 1 (that is the sequence set).
v The index control interval (beginning at the relative byte address of decimal
23552) where it found the error is displayed.
v The error is located at offset hexadecimal 10 into the control interval.
Because of this severe INDEXTEST error, DATATEST did not run in this particular
case.
252
z/OS DFSMS Using Data Sets
Checking VSAM Key-Sequenced Data Set Clusters for Structural Errors
IDCAMS SYSTEM SERVICES
EXAMINE NAME(EXAMINE.KD99) INDEXTEST DATATEST
IDC01700I INDEXTEST BEGINS
IDC11701I STRUCTURAL PROBLEM FOUND IN INDEX
IDC01707I CURRENT INDEX LEVEL IS 1
IDC01720I INDEX CONTROL INTERVAL DISPLAY AT RBA 23552 FOLLOWS
000000 01F90301 00000000 00005E00 00000000 02000021 010701BC 2D2C2B2A
000020 25000000 00000000 00000000 00000000 00000000 00000000 00000000
000040 00000000 00000000 00000000 00000000 00000000 00000000 00000000
000060 00000000 00000000 00000000 00000000 00000000 00000000 00000000
000080 00000000 00000000 00000000 00000000 00000000 00000000 00000000
0000A0 00000000 00000000 00000000 00000000 00000000 00000000 00000000
0000C0 00000000 00000000 00000000 00000000 00000000 00000000 00000000
0000E0 00000000 00000000 00000000 00000000 00000000 00000000 00000000
000100 00000000 0000F226 01240007 F7F12502 23F82601 22F72601 21F42601
000120 1FF6F025 021E001B F525011D F626011C F526011B F226011A F5F12502
000140 18001CF4 F7250217 F4260116 F3260115 F4F02502 14260013 F6260112
000160 250211F2 260110F3 F125020F F826010E F726010D F426010C 001CF2F3
000180 F025020A 260009F6 260108F5 260107F2 26010600 40F0F0F0 F0F0F0F0
0001A0 F0F0F0F0 F0F0F0F0 F0F0F0F0 F0F0F0F0 F0F0F0F0 F0F0F0F0 F0F0F1F1
0001C0 260104F7 260103F4 260102F3 260101F0 F0F0F0F0 F0F0F0F0 F0F0F0F0
0001E0 F0F0F0F0 F0F0F0F0 F0F0F0F0 F0F0F0F0 F0F0F0F0 F0F0F027 000001F9
IDC01714I ERROR LOCATED AT OFFSET 00000010
IDC21701I MAJOR ERRORS FOUND BY INDEXTEST
IDC31705I DATATEST NOT PERFORMED DUE TO SEVERE INDEXTEST ERRORS
IDC3003I FUNCTION TERMINATED. CONDITION CODE IS 12
29282726
00000000
00000000
00000000
00000000
00000000
00000000
00000000
20F32601
19F82601
001BF3F5
25020BF2
F0F0F0F0
002705F8
F0F0F0F0
01F90000
X.9........;.....................X
X................................X
X................................X
X................................X
X................................X
X................................X
X................................X
X................................X
X......2.....71...8...7...4...3..X
X.60.....5...6...5...2...51...8..X
X...47...4...3...40......6.....35X
X...2...31...8...7...4.....23...2X
X0......6...5...2.... 00000000000X
X0000000000000000000000000011...8X
X...7...4...3...00000000000000000X
X0000000000000000000000.....9.9..X
IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 12
INDEXTEST and DATATEST Tests of a Data Set with a
Duplicate Key Error
The user intended to run both tests, INDEXTEST and DATATEST. INDEXTEST
began and completed successfully. DATATEST looked at the data component of the
KSDS cluster and found a “duplicate key” error.
EXAMINE then displayed the prior key (11), the data control interval at relative
byte address decimal 512, and the offset address hexadecimal 9F into the control
interval where the duplicate key was found.
Chapter 15. Checking VSAM Key-Sequenced Data Set Clusters for Structural Errors
253
Checking VSAM Key-Sequenced Data Set Clusters for Structural Errors
IDCAMS SYSTEM SERVICES
EXAMINE NAME(EXAMINE.KD99) INDEXTEST DATATEST
IDC01700I INDEXTEST BEGINS
IDC01724I INDEXTEST COMPLETE NO ERRORS DETECTED
IDCC17OLI DATATEST COMPLETE
IDC11741I DUPLICATE CONSECUTIVE KEYS FOUND
IDC01717I DATA KEYS FOLLOW
000000 FOFOFOFO FOFOFOFO FOFOFOFO FOFOFOFO FOFOFOFO FOFOFOFO FOFOFOFO FOFOFOFO X00000000000000000000000000000000X
000020 FOFOFOFO FOFOF1F1
X00000011
X
DIC01713I DATA CONTROL INTERVAL DISPLAY AT RBA 512 FOLLOWS
000000 00000000 0000D0C1 AB33F0F0 F0F0F0F0 F0F0F0F0 F0F0F0F0
000020 F0F0F0F0 F0F0F0F0 F0F0F0F0 F0F0F0F0 F1F1C3C3 C3C3C3C3
000040 C3C3C3C3 C3C3C3C3 C3C3C3C3 C3C3C3C3 C3C3C3C3 C3C3C3C3
000060 C3C3C3C3 C3C3C3C3 C3C3C3C3 C3C3C3C3 C3C3C3C3 C3C3C3C3
000080 C3C3C3C3 C3C3C3C3 C3C3C3C3 C3C3C3C3 C3C3C3C3 C3000000
0000A0 F0F0F0F0 F0F0F0F0 F0F0F0F0 0F0F0F0F FOFOFOFO FOFOFOFO
0000C0 F0F0F0F0 FOF1F1C4 C4C4C4C4 C4C4C4C4 C4C4C4C4 C4C4C4C4
0000E0 C4C4C4C4 C4C4C4C4 C4C4C4C4 C4C4C4C4 C4C4C4C4 00000000
000100 F0F0F0F0 FOFOFOFO F0F0F0F0 OFOFOFOF F0F0F0F0 FOFOFOFO
000120 FOFOFOFO F3F1C1C1 C1C1C100 00000000 00000000 00000000
000140 00000000 00000000 00000000 00000000 00000000 00000000
000160 00000000 00000000 00000000 00000000 00000000 00000000
000180 00000000 00000000 00000000 00000000 00000000 00000000
0001A0 00000000 00000000 00000000 00000000 00000000 00000000
0001C0 00000000 00000000 00000000 00000000 00000000 00000000
0001E0 00000000 00000000 00000000 00000000 00000000 00370000
IDC01714I ERROR LOCATED AT OFFSET 00000C9F
IDC21703I MAJOR ERRORS FOUND BY DATATEST
IDC0001I FUNCTION COMPLETED. HIGHEST CONDITION CODE WAS 8
F0F0F0F0
C3C3C3C3
C3C3C3C3
C3C3C3C3
0000006E
FOFOFOFO
C4C4C4C4
000055E2
FOFOFOFO
00000000
00000000
00000000
00000000
00000000
00000000
5F000095
IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 8
254
z/OS DFSMS Using Data Sets
F0F0F0F0
C3C3C3C3
C3C3C3C3
C3C3C3C3
E065DEF0
FOFOFOF0
C4C4C4C4
0706F0F0
FOFOFOFO
00000000
00000000
00000000
00000000
00000000
00000000
012B00C8
X.......A..0000000000000000000000X
X000000000000000011CCCCCCCCCCCCCCX
XCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCX
XCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCX
XCCCCCCCCCCCCCCCCCCCCC......>...0X
X00000000000000000000000000000000X
X0000011DDDDDDDDDDDDDDDDDDDDDDDDDX
XDDDDDDDDDDDDDDDDDDDD.......S..00X
X00000000000000000000000000000000X
X000031AAAAA.....................X
X................................X
X................................X
X................................X
X................................X
X................................X
X........................-......HX
Chapter 16. Coding VSAM User-Written Exit Routines
This topic covers general guidelines for coding VSAM user-written exit routines
and specific information about coding the following routines.
Topic
“Guidelines for Coding Exit Routines”
“EODAD Exit Routine to Process End of Data” on page 259
“EXCEPTIONEXIT Exit Routine” on page 260
“JRNAD Exit Routine to Journalize Transactions” on page 261
“LERAD Exit Routine to Analyze Logical Errors” on page 269
“RLSWAIT Exit Routine” on page 270
“SYNAD Exit Routine to Analyze Physical Errors” on page 271
“UPAD Exit Routine for User Processing” on page 273
“User-Security-Verification Routine” on page 276
Guidelines for Coding Exit Routines
You can supply VSAM exit routines to do the following tasks:
v Analyze logical errors
v Analyze physical errors
v Perform end-of-data processing
v Record transactions made against a data set
v Perform special user processing
v Perform wait user processing
v Perform user-security verification.
VSAM user-written exit routines are identified by macro parameters in access
methods services commands.
You can use the EXLST VSAM macro to create an exit list. EXLST parameters
EODAD, JRNAD, LERAD, SYNAD and UPAD are used to specify the addresses of
your user-written routines. Only the exits marked active are executed.
You can use access methods services commands to specify the addresses of
user-written routines to perform exception processing and user-security verification
processing.
Related reading:
v For information about the EXLST macro, see z/OS DFSMS Macro Instructions for
Data Sets.
v For information about exits from access methods services commands, see z/OS
DFSMS Access Method Services Commands.
Table 22 on page 256 shows the exit locations available from VSAM.
© Copyright IBM Corp. 1987, 2017
255
Coding VSAM User-Written Exit Routines
Table 22. VSAM user-written exit routines
Exit routine
When available
Where specified
Batch override
After you issue an IDCAMS SHCDS
PERMITNONRLSUPDATE command
while backout work was owed
IGW8PNRU exit in LINKLIB or
LPALIB
End-of-data-set
When no more sequential records or
blocks are available
EODAD parameter of the EXLST
macro
Exception exit
After an uncorrectable input/output
error
EXCEPTIONEXIT parameter in access
methods services commands
Journalize transactions against a data
set
After an input/output completion or JRNAD parameter of the EXLST
error, change to buffer contents,
macro
shared or nonshared request, program
issues GET, PUT, ERASE, shift in data
in a control interval
Analyze logical errors
After an uncorrectable logical error
LERAD parameter of the EXLST
macro
Wait
For non-cross-memory mode callers
using RLS
RLSWAIT parameter of the EXLST
macro
Error analysis
After an uncorrectable input/output
error
SYNAD parameter of the EXLST
macro
User processing
WAIT for I/O completion or for a
serially reusable request
UPAD parameter of the EXLST macro
User security verification
When opening a VSAM data set
AUTHORIZATION parameter in
access methods services commands
Programming Guidelines
Usually, you should observe these guidelines in coding a routine:
v Code your routine reentrant.
v Save and restore registers (see individual routines for other requirements).
v Be aware of registers used by the VSAM request macros.
v Be aware of the addressing mode (24-bit or 31-bit) in which your exit routine
will receive control.
v Determine if VSAM or your program should load the exit routine.
A user exit that is loaded by VSAM is invoked in the addressing mode specified
when the module was link edited. A user exit that is not loaded by VSAM receives
control in the same addressing mode as the issuer of the VSAM
record-management, OPEN, or CLOSE request that causes the exit to be taken. It is
the user's responsibility to ensure that the exit is written for the correct addressing
mode.
Your exit routine can be loaded within your program or by using JOBLIB or
STEPLIB with the DD statement to point to the library location of your exit
routine.
Related reading: When you code VSAM user exit routines, you should have
available z/OS DFSMS Macro Instructions for Data Sets and z/OS DFSMS Access
Method Services Commands and be familiar with their contents.
256
z/OS DFSMS Using Data Sets
Coding VSAM User-Written Exit Routines
Multiple Request Parameter Lists or Data Sets
If the exit routine is used by a program that is doing asynchronous processing with
multiple request parameter lists (RPL) or if the exit routine is used by more than
one data set, you must code the exit routine so that it can handle an entry made
before the previous entry's processing is completed. Saving and restoring registers
in the exit routine, or by other routines called by the exit routine, is best
accomplished by coding the exit routine reentrant. Another way of doing this is to
develop a technique for associating a unique save area with each RPL.
If the LERAD, EODAD, or SYNAD exit routine reuses the RPL passed to it, you
should be aware of these factors:
v The exit routine is called again if the request issuing the reused RPL results in
the same exception condition that caused the exit routine to be entered
originally.
v The original feedback code is replaced with the feedback code that indicates the
status of the latest request issued against the RPL. If the exit routine returns to
VSAM, VSAM (when it returns to the user's program) sets register 15 to also
indicate the status of the latest request.
v JRNAD, UPAD, and exception exits are extensions of VSAM and, therefore, must
return to VSAM in the same processing mode in which they were entered (that
is, cross-memory, SRB, or task mode).
Return to a Main Program
Six exit routines can be entered when your main program issues a VSAM request
macro (GET, PUT, POINT, and ERASE) and the macro has not completed: LERAD,
SYNAD, EODAD, UPAD, RLSWAIT or the EXCEPTIONEXIT routine. Entering the
LERAD, SYNAD, EODAD, or EXCEPTIONEXIT indicates that the macro failed to
complete successfully. When your exit routine completes its processing, it can
return to your main program in one of two ways:
v The exit routine can return to VSAM (by the return address in register 14).
VSAM then returns to your program at the instruction following the VSAM
request macro that failed to complete successfully. This is the easier way to
return to your program.
If your error recovery and correction process needs to reissue the failing VSAM
macro against the RPL to retry the failing request or to correct it:
– Your exit routine can correct the RPL (using MODCB), then set a switch to
indicate to your main program that the RPL is now ready to retry. When your
exit routine completes processing, it can return to VSAM (via register 14),
which returns to your main program. Your main program can then test the
switch and reissue the VSAM macro and RPL.
– Your exit routine can issue a GENCB macro to build an RPL, and then copy
the RPL (for the failing VSAM macro) into the newly built RPL. At this point,
your exit routine can issue VSAM macros against the newly built RPL. When
your exit routine completes processing, it can return to VSAM (using register
14), which returns to your main program.
v The exit routine can determine the appropriate return point in your program,
then branch directly to that point. Note that when VSAM enters your exit
routine, none of the registers contains the address of the instruction following
the failing macro.
You are required to use this method to return to your program if, during the
error recovery and correction process, your exit routine issued a GET, PUT,
POINT, or ERASE macro that refers to the RPL referred to by the failing VSAM
macro. (That is, the RPL has been reissued by the exit routine.) In this case,
Chapter 16. Coding VSAM User-Written Exit Routines
257
Coding VSAM User-Written Exit Routines
VSAM has lost track of its reentry point to your main program. If the exit
routine returns to VSAM, VSAM issues an error return code.
IGW8PNRU Routine for Batch Override
To prevent damage to a data set, DFSMStvs defers the decision whether to back
out a specific record to an installation exit, the batch override exit. Transaction
VSAM calls this optional exit when it backs out a unit of recovery (UR) that
involves a data set that might have been impacted by the IDCAMS SHCDS
PERMITNONRLSUPDATE command. The exit is called once for each affected
undo log record for the data set.
The purpose of this exit is to return to DFSMStvs with an indication of whether or
not the backout should be applied. The input is an undo log record (mapped by
IGWUNLR) and a data set name. The output is a Boolean response of whether or
not to do the backout, returned in register 15:
v 0 (zero) means do not back out this record.
v 4 means back out this record.
The exit is given control in the following environment:
v INTERRUPTS enabled
v STATE and KEY problem program state, key 8
v ASC Mode P=H=S, RLS address space
v AMODE, RMODE: No restrictions
v LOCKS: None held
v The exit is reentrant
Register Contents
Table 23 gives the contents of the registers when VSAM exits to the IGW8PNRU
routine.
Table 23. Contents of registers at entry to IGW8PNRU exit routine
Register
Contents
0
Not applicable.
1
Address of IGWUNLR (in key 8 storage).
Address of an area to be used as an autodata area (in key 8 storage).
3
Length of the autodata area.
4-13
Unpredictable. Register 13, by convention, contains the address of your
processing program's 72-byte save area, which must not be used as a save
area by the IGW8PNRU routine if it returns control to VSAM.
14
Return address to VSAM.
15
Entry address to the IGW8PNRU routine.
Programming Considerations
The following programming considerations apply to the batch override exit:
v The name of this exit must be IGW8PNRU.
v The exit must be loadable from any system that might do peer recovery for
another system.
258
z/OS DFSMS Using Data Sets
Coding VSAM User-Written Exit Routines
v The IGW8PNRU module is loaded by DFSMStvs and, therefore, must reside in
LINKLIB or LPALIB. If the load fails, DFSMStvs issues a message.
v If it does not find the batch override exit, DFSMStvs shunts any UR with a
pending backout for a data set that was accessed through
PERMITNONRLSUPDATE.
v If your installation needs to fix a code error or enhance the function of the exit,
you need to restart DFSMStvs to enable the new exit.
v The exit can issue SVC instructions.
DFSMStvs establishes an ESTAE recovery environment before calling the exit to
protect the RLS address space from failures in the exit. If the exit fails or an
attempt to invoke it fails, the UR is shunted. A dump is taken, and the exit is
disabled until the next DFSMStvs restart, but the server is not recycled. If the exit
abnormally ended, it might result in a dump with a title like this:
DUMP
TITLE=COMPID=?????,CSECT=????????+FFFF,DATE=????????,MAINT
ID=????????,ABND=0C4,RC=00000000,RSN=00000004
If this happens, investigate why the exit abended.
Recommendation: It is possible for this exit to perform other processing, but IBM
strongly recommends that the exit not attempt to update any recoverable resources.
When your IGW8PNRU routine completes processing, return to your main
program as described in “Return to a Main Program” on page 257.
EODAD Exit Routine to Process End of Data
VSAM exits to an EODAD routine when an attempt is made to sequentially
retrieve or point to a record beyond the last record in the data set (one with the
highest key for keyed access and the one with the highest RBA for addressed
access). VSAM does not take the exit for direct requests that specify a record
beyond the end. If the EODAD exit is not used, the condition is considered a
logical error (FDBK code X'04') and can be handled by the LERAD routine, if one
is supplied. See “LERAD Exit Routine to Analyze Logical Errors” on page 269.
Register Contents
Table 24 gives the contents of the registers when VSAM exits to the EODAD
routine.
Table 24. Contents of registers at entry to EODAD exit routine
Register
Contents
0
Unpredictable.
1
Address of the RPL that defines the request that occasioned VSAM's
reaching the end of the data set. The register must contain this address if
you return to VSAM.
2-13
Unpredictable. Register 13, by convention, contains the address of your
processing program's 72-byte save area, which must not be used as a save
area by the EODAD routine if it returns control to VSAM.
14
Return address to VSAM.
15
Entry address to the EODAD routine.
Chapter 16. Coding VSAM User-Written Exit Routines
259
Coding VSAM User-Written Exit Routines
Programming Considerations
The typical actions of an EODAD routine are to:
v Examine RPL for information you need, for example, type of data set
v Issue completion messages
v Close the data set
v Terminate processing without returning to VSAM.
If the routine returns to VSAM and another GET request is issued for access to the
data set, VSAM exits to the LERAD routine.
If a processing program retrieves records sequentially with a request defined by a
chain of RPLs, the EODAD routine must determine whether the end of the data set
was reached for the first RPL in the chain. If not, then one or more records have
been retrieved but not yet processed by the processing program.
The type of data set whose end was reached can be determined by examining the
RPL for the address of the access method control block that connects the program
to the data set and testing its attribute characteristics.
If the exit routine issues GENCB, MODCB, SHOWCB, or TESTCB and returns to
VSAM, it must provide a save area and restore registers 13 and 14, which are used
by these macros.
When your EODAD routine completes processing, return to your main program as
described in “Return to a Main Program” on page 257.
EXCEPTIONEXIT Exit Routine
You can provide an exception exit routine to monitor I/O errors associated with a
data set. You specify the name of your routine via the access method services
DEFINE command using the EXCEPTIONEXIT parameter to specify the name of
your user-written exit routine.
Register Contents
Table 25 gives the contents of the registers when VSAM exits to the
EXCEPTIONEXIT routine.
Table 25. Contents of registers at entry to EXCEPTIONEXIT routine
Register
Contents
0
Unpredictable.
1
Address of the RPL that contains a feedback return code and the address of
a message area, if any.
2-13
Unpredictable. Register 13, by convention, contains the address of your
processing program's 72-byte save area, which must not be used by the
routine if it returns control to VSAM.
14
Return address to VSAM.
15
Entry address to the exception exit routine.
Programming Considerations
Define a RACF FACILITY class profile with the resource name of
IDA.VSAMEXIT.xxxxxxxx where xxxxxxxx is the EXITNAME parameter value of
EXCEPTIONEXIT. You must give users at least READ authority to the facility class
resource name in order to invoke the exit.
260
z/OS DFSMS Using Data Sets
Coding VSAM User-Written Exit Routines
The exception exit is taken for the same errors as a SYNAD exit. If you have both
an active SYNAD routine and an EXCEPTIONEXIT routine, the exception exit
routine is processed first.
The exception exit is associated with the attributes of the data set (specified by the
DEFINE) and is loaded on every call. Your exit must reside in the LINKLIB and
the exit cannot be called when VSAM is in cross-memory mode.
When your exception exit routine completes processing, return to your main
program as described in “Return to a Main Program” on page 257.
Related reading: For information about how exception exits are established,
changed, or nullified, see z/OS DFSMS Access Method Services Commands.
JRNAD Exit Routine to Journalize Transactions
A JRNAD exit routine can be provided to record transactions against a data set, to
keep track of changes in the RBAs of records, and to monitor control interval
splits. It is only available for VSAM shared resource buffering. When using the
JRNAD exit routine with compressed data sets, all RBAs and data length values
returned represent compressed data. For shared resources, you can use a JRNAD
exit routine to deny a request for a control interval split. VSAM takes the JRNAD
exit each time one of the following occurs:
v The processing program issues a GET, PUT, or ERASE
v Data is shifted right or left in a control interval or is moved to another control
interval to accommodate a records being deleted, inserted, shortened, or
lengthened
v An I/O error occurs
v An I/O completion occurs
v A shared or nonshared request is received
v The buffer contents are to be changed.
Restriction: The JRNAD exit is not supported by RLS.
Register Contents
Table 26 gives the contents of the registers when VSAM exits to the JRNAD
routine.
Table 26. Contents of registers at entry to JRNAD exit routine
Register
Contents
0
Byte 0—the subpool ID token created by a BLDVRP request. Bytes 2 3—the relative buffer number, that is, the buffer array index within a buffer
pool.
1
Address of a parameter list built by VSAM.
2-3
Unpredictable.
4
Address of buffer control block (BUFC).
5-13
Unpredictable.
14
Return address to VSAM.
15
Entry address to the JRNAD routine.
Chapter 16. Coding VSAM User-Written Exit Routines
261
Coding VSAM User-Written Exit Routines
Programming Considerations
If the JRNAD is taken for I/O errors, a journal exit can zero out, or otherwise alter,
the physical-error return code, so that a series of operations can continue to
completion, even though one or more of the operations failed.
The contents of the parameter list built by VSAM, pointed to by register 1, can be
examined by the JRNAD exit routine, which is described in Table 27 on page 264.
If the exit routine issues GENCB, MODCB, SHOWCB, or TESTCB, it must restore
register 14, which is used by these macros, before it returns to VSAM.
If the exit routine uses register 1, it must restore it with the parameter list address
before returning to VSAM. (The routine must return for completion of the request
that caused VSAM to exit.)
The JRNAD exit must be indicated as active before the data set for which the exit
is to be used is opened, and the exit must not be made inactive during processing.
If you define more than one access method control block for a data set and want to
have a JRNAD routine, the first ACB you open for the data set must specify the
exit list that identifies the routine.
When the data set being processed is extended addressable, the JRNAD exits
dealing with RBAs are not taken or are restricted due to the increase in the size of
the field required to provide addressability to RBAs which may be greater than 4
GB. The restrictions are for the entire data set without regard to the specific RBA
value.
Journalizing Transactions
For journalizing transactions (when VSAM exits because of a GET, PUT, or
ERASE), you can use the SHOWCB macro to display information in the request
parameter list about the record that was retrieved, stored, or deleted
(FIELDS=(AREA,KEYLEN,RBA,RECLEN), for example). You can also use the
TESTCB macro to find out whether a GET or a PUT was for update
(OPTCD=UPD).
If your JRNAD routine only journals transactions, it should ignore reason X'0C'
and return to VSAM; conversely, it should ignore reasons X'00', X'04', and X'08' if it
records only RBA changes.
RBA Changes
For recording RBA changes, you must calculate how many records there are in the
data being shifted or moved, so you can keep track of the new RBA for each. If all
the records are the same length, you calculate the number by dividing the record
length into the number of bytes of data being shifted. If record length varies, you
can calculate the number by using a table that not only identifies the records (by
associating a record's key with its RBA), but also gives their length.
You should provide a routine to keep track of RBA changes caused by control
interval and control area splits. RBA changes that occur through keyed access to a
key-sequenced data set must also be recorded if you intend to process the data set
later by direct-addressed access.
Control Interval Splits
Some control interval splits involve data being moved to two new control
intervals, and control area splits normally involve many control intervals' contents
262
z/OS DFSMS Using Data Sets
Coding VSAM User-Written Exit Routines
being moved. In these cases, VSAM exits to the JRNAD routine for each separate
movement of data to a new control interval.
You might also want to use the JRNAD exit to maintain shared or exclusive control
over certain data or index control intervals; and in some cases, in your exit routine
you can reject the request for certain processing of the control intervals. For
example, if you used this exit to maintain information about a data set in a shared
environment, you might reject a request for a control interval or control area split
because the split might adversely affect other users of the data set.
Figure 32 is a skeleton program USERPROG with a user exit routine USEREXIT. It
demonstrates the use of the JRNAD exit routine to cancel a request for a control
interval or control area split.
USERPROG
NOCANCEL
DIRACB
CSECT
SAVE(R14,R12)
Standard entry code
.
.
.
BLDVRP BUFFERS=(512(3)), Build resource pool
X
KEYLEN=4,
X
STRNO=4,
X
TYPE=LSR,
X
SHRPOOL=1,
X
RMODE31=ALL
OPEN (DIRACB)
Logically connect KSDS1
.
.
.
PUT RPL=DIRRPL
This PUT causes the exit routine USEREXIT
to be taken with an exit code X’50’ if
there is a CI or CA split
LTR R15,R15
Check return code from PUT
BZ NOCANCEL
Retcode = 0 if USEREXIT did not cancel
CI/CA split
= 8 if cancel was issued, if
we know a CI or CA split
occurred
.
.
Process the cancel situation
.
.
Process the noncancel situation
.
.
CLOSE (DIRACB)
Disconnect KSDS1
DLVRP TYPE=LSR,SHRPOOL=1 Delete the resource pool
.
.
.
RETURN
Return to caller.
.
.
.
ACB AM=VSAM,
X
DDNAME=KSDS1,
X
BUFND=3,
X
BUFNI=2,
X
MACRF=(KEY,DDN,SEQ,DIR,OUT,LSR),
X
SHRPOOL=1,
X
EXLST=EXITLST
Figure 32. Example of a JRNAD exit Part 1 of 2
Chapter 16. Coding VSAM User-Written Exit Routines
263
Coding VSAM User-Written Exit Routines
*
DIRRPL
RPL AM=VSAM,
ACB=DIRACB,
AREA=DATAREC,
AREALEN=128,
ARG=KEYNO,
KEYLEN=4,
OPTCD=(KEY,DIR,FWD,SYN,NUP,WAITX),
RECLEN=128
*
DATAREC
KEYNO
EXITLST
JRNADDR
USEREXIT
EXIT
X
X
X
X
X
X
X
DC CL128’DATA RECORD TO BE PUT TO KSDS1’
DC F’0’
Search key argument for RPL
EXLST AM=VSAM,JRNAD=(JRNADDR,A,L)
DC CL8’USEREXIT’ Name of user exit routine
END
End of USERPROG
CSECT
On entry to this exit routine, R1 points
to the JRNAD parameter list and R14 points
back to VSAM.
.
.
.
.
.
.
.
.
CLI 20(R1),X’50’
BNE EXIT
MVI 21(R1),X’8C’
.
.
.
.
.
BR R14
END
Nonstandard entry code -- need not save
the registers at caller’s save area and,
since user exit routines are reentrant for
most applications, save R1 and R14 at some
registers only if R1 and R14 are to be
destroyed
USEREXIT called because of CI/CA split?
No. Return to VSAM
Tell VSAM that user wants to cancel split
Nonstandard exit code -- restore R1 and
R14 from save registers
Return to VSAM which returns to USERPROG
if cancel is specified
End of USEREXIT
Figure 33. Example of a JRNAD exit Part 2 of 2
Parameter List
The parameter list built by VSAM contains reason codes to indicate why the exit
was taken, and also locations where you can specify return codes for VSAM to
take or not take an action on returning from your routine. The information
provided in the parameter list varies depending on the reason the exit was taken.
Table 27 shows the contents of the parameter list.
The parameter list will reside in the same area as the VSAM control blocks, either
above or below the 16 MB line. For example, if the VSAM data set was opened
and the ACB stated RMODE31=CB, the exit parameter list will reside above the 16
MB line. To access a parameter list that resides above the 16 MB line, you will
need to use 31-bit addressing.
Table 27. Contents of parameter list built by VSAM for the JRNAD exit
Offset
Bytes
Description
0(X'0')
4
Address of the RPL that defines the request that caused VSAM to exit to the routine.
264
z/OS DFSMS Using Data Sets
Coding VSAM User-Written Exit Routines
Table 27. Contents of parameter list built by VSAM for the JRNAD exit (continued)
Offset
Bytes
Description
4(X'4')
4
Address of a 5-byte field that identifies the data set being processed. This field has the
format:
4 bytes Address of the access method control block specified by the RPL that defines
the request occasioned by the JRNAD exit.
1 byte
8(X'8')
4
Indication of whether the data set is the data (X'01') or the index (X'02')
component.
Variable, depends on the reason indicator at offset 20:
Offset 20
Contents at offset 8
X'0C'
The RBA of the first byte of data that is being shifted or moved.
X'20'
The RBA of the beginning of the control area about to be split.
X'24'
The address of the I/O buffer into which data was going to be read.
X'28'
The address of the I/O buffer from which data was going to be written.
X'2C'
The address of the I/O buffer that contains the control interval contents that
are about to be written.
X'30'
Address of the buffer control block (BUFC) that points to the buffer into which
data is about to be read under exclusive control.
X'34'
Address of BUFC that points to the buffer into which data is about to be read
under shared control.
X'38'
Address of BUFC that points to the buffer which is to be acquired in exclusive
control. The buffer is already in the buffer pool.
X'3C'
Address of the BUFC that points to the buffer which is to be built in the buffer
pool in exclusive control.
X'40'
Address of BUFC which points to the buffer whose exclusive control has just
been released.
X'44'
Address of BUFC which points to the buffer whose contents have been made
invalid.
X'48'
Address of the BUFC which points to the buffer into which the READ
operation has just been completed.
X'4C'
Address of the BUFC which points to the buffer from which the WRITE
operation has just been completed.
X'54' - X'6C'
Starting CI number of the data CA reclaimed.
Chapter 16. Coding VSAM User-Written Exit Routines
265
Coding VSAM User-Written Exit Routines
Table 27. Contents of parameter list built by VSAM for the JRNAD exit (continued)
Offset
Bytes
Description
12(X'C')
4
Variable, depends on the reason indicator at offset 20:
Offset 20
Contents at offset 12
X'0C'
The number of bytes of data that is being shifted or moved (this number does
not include free space, if any, or control information, except for a control area
split, when the entire contents of a control interval are moved to a new control
interval.)
X'20'
Unpredictable.
X'24'
Unpredictable.
X'28'
Bits 0-31 correspond with transaction IDs 0-31. Bits set to 1 indicate that the
buffer that was being written when the error occurred was modified by the
corresponding transactions. You can set additional bits to 1 to tell VSAM to
keep the contents of the buffer until the corresponding transactions have
modified the buffer.
X'2C'
The size of the control interval whose contents are about to be written.
X'30'
Zero.
X'34'
Zero.
X'38'
Zero.
X'3C'
Size of the buffer which is to be built in the buffer pool in exclusive control.
X'48'
Size of the buffer into which the READ operation has just been completed.
X'4C'
Size of the buffer from which the WRITE operation has just been completed.
X'54'
Zero.
X'58'
Byte 0: Highest level of index reclaimed in the current CA reclaim.
Byte 1-3: Total number of data CAs successfully reclaimed since the KSDS was
created.
X'5C'
RPLFDBK code for CA reclaim interruption due to logical or physical error.
X'60'
Zero.
X'64'
Byte 0: Highest level of index reclaimed in the current CA reclaim.
Byte 1-3: Total number of data CAs successfully reclaimed since the KSDS was
created.
266
X'68'
Byte 0: Index level of index CI being reused. Always 1 because this JRNAD
with entry code X'68' is taken only when a sequence-set CI is reused.
X'6C'
Total number of data CAs successfully reused since the KSDS was created.
z/OS DFSMS Using Data Sets
Coding VSAM User-Written Exit Routines
Table 27. Contents of parameter list built by VSAM for the JRNAD exit (continued)
Offset
Bytes
Description
16(X'10')
4
Variable, depends on the reason indicator at offset 20:
Offset 20
Contents at offset 16
X'0C'
The RBA of the first byte to which data is being shifted or moved.
X'20'
The RBA of the last byte in the control area about to be split.
X'24'
The fourth byte contains the physical error code from the RPL FDBK field. You
use this fullword to communicate with VSAM. Setting it to 0 indicates that
VSAM is to ignore the error, bypass error processing, and let the processing
program continue. Leaving it nonzero indicates that VSAM is to continue as
usual: terminate the request that occasioned the error and proceed with error
processing, including exiting to a physical error analysis routine.
X'28'
Same as for X'24'.
X'2C'
The RBA of the control interval whose contents are about to be written.
X'48'
Unpredictable.
X'4C'
Unpredictable.
X'54' - X'6C'
Ending CI number of the data CA reclaimed.
Chapter 16. Coding VSAM User-Written Exit Routines
267
Coding VSAM User-Written Exit Routines
Table 27. Contents of parameter list built by VSAM for the JRNAD exit (continued)
Offset
Bytes
Description
20(X'14')
1
Indication of the reason VSAM exited to the JRNAD routine:
X'00'
GET request.
X'04'
PUT request.
X'08'
ERASE request.
X'0C'
RBA change.
X'10'
Read spanned record segment.
X'14'
Write spanned record segment.
X'18'
Reserved.
X'1C'
Reserved.
The following codes are for shared resources only:
X'20'
Control area split.
X'24'
Input error.
X'28'
Output error.
X'2C'
Buffer write.
X'30'
A data or index control interval is about to be read in exclusive control.
X'34'
A data or index control interval is about to be read in shared status.
X'38'
Acquire exclusive control of a control interval already in the buffer pool.
X'3C'
Build a new control interval for the data set and hold it in exclusive control.
X'40'
Exclusive control of the indicated control interval already has been released.
X'44'
Contents of the indicated control interval have been made invalid.
X'48'
Read completed.
X'4C'
Write completed.
X'50'
Control interval or control area split.
X'54'
Start of CA reclaim.
X'58'
End of CA reclaim.
X'5C'
CA reclaim failed.
X'60'
Start of CA reclaim recovery.
X'64'
End of CA reclaim recovery.
X'68'
Start of CA reuse.
X'6C'
End of CA reuse.
X'70'–X'FF'
Reserved.
21(X'15')
268
1
JRNAD exit code set by the JRNAD exit routine. Indication of action to be taken by
VSAM after resuming control from JRNAD (for shared resources only):
X'80'
Do not write control interval.
X'84'
Treat I/O error as no error.
X'88'
Do not read control interval.
X'8C'
Cancel the request for control interval or control area split.
z/OS DFSMS Using Data Sets
Coding VSAM User-Written Exit Routines
LERAD Exit Routine to Analyze Logical Errors
A LERAD exit routine should examine the feedback field in the request parameter
list to determine what logical error occurred. What the routine does after
determining the error depends on your knowledge of the kinds of things in the
processing program that can cause the error.
VSAM does not call the LERAD exit if the RPL feedback code is 64.
Register Contents
Table 28 gives the contents of the registers when VSAM exits to the LERAD exit
routine.
Table 28. Contents of registers at entry to LERAD exit routine
Register
Contents
0
Unpredictable.
1
Address of the RPL that contains the feedback field the routine should
examine. The register must contain this address if you return to VSAM.
2-13
Unpredictable. Register 13, by convention, contains the address of your
processing program's 72-byte save area, which must not be used as a save
area by the LERAD routine if the routine returns control to VSAM.
14
Return address to VSAM.
15
Entry address to the LERAD routine. The register does not contain the
logical-error indicator.
Programming Considerations
The typical actions of a LERAD routine are:
1. Examine the feedback field in the RPL to determine what error occurred
2. Determine what action to take based on error
3. Close the data set
4. Issue completion messages
5. Terminate processing and exit VSAM or return to VSAM.
If the LERAD exit routine issues GENCB, MODCB, SHOWCB, or TESTCB and
returns to VSAM, it must restore registers 1, 13, and 14, which are used by these
macros. It must also provide two save areas; one, whose address should be loaded
into register 13 before the GENCB, MODCB, SHOWCB, or TESTCB is issued, and
the second, to separately store registers 1, 13, and 14.
If the error cannot be corrected, close the data set and either terminate processing
or return to VSAM.
If a logical error occurs and no LERAD exit routine is provided (or the LERAD exit
is inactive), VSAM returns codes in register 15 and in the feedback field of the RPL
to identify the error.
When your LERAD exit routine completes processing, return to your main
program as described in “Return to a Main Program” on page 257.
Chapter 16. Coding VSAM User-Written Exit Routines
269
Coding VSAM User-Written Exit Routines
RLSWAIT Exit Routine
The RLSWAIT exit is entered at the start of the record management request and
the request is processed asynchronously under a separate VSAM execution unit. If
a UPAD is specified, RLS ignores it.
The exit can do its own wait processing associated with the record management
request that is being asynchronously executed. When the record management
request is complete, VSAM will post the ECB that the user specified in the RPL.
For RLS, the RLSWAIT exit is entered only for a request wait, never for a resourceor I/O- wait or post as with non-RLS VSAM UPAD.
The RLSWAIT exit is optional. It is used by applications that cannot tolerate VSAM
suspending the execution unit that issued the original record management request.
The RLSWAIT exit is required for record management request issued in cross
memory mode.
RLSWAIT should be specified on each ACB which requires the exit. If the exit is
not specified on the ACB via the EXLST, there is no RLSWAIT exit processing for
record management requests associated with that ACB. This differs from non-RLS
VSAM where the UPAD exit is associated with the control block structure so that
all ACBs connected to that structure inherit the exit of the first connector.
To activate RLSWAIT exit processing for a particular record management request,
the RPL must specify OPTCD=(SYN,WAITX). RLSWAIT is ignored if the request is
asynchronous.
Register Contents
Table 29 gives the contents of the registers when RLSWAIT is entered in 31–bit
mode.
Table 29. Contents of registers for RLSWAIT exit routine
Register
Contents
1
Address of the user RPL. If a chain of RPLs was passed on the original
record management request, this is the first RPL in the chain.
12
Reserved and must be the same on exit as on entry.
13
Reserved and must be the same on exit as on entry.
14
Return address. The exit must return to VSAM using this register.
15
Address of the RLSWAIT exit.
The RLSWAIT exit must conform to the following restrictions:
v The exit must return to VSAM using register 14 and it must return with the
same entry environment. That is, under the same execution unit as on entry and
with the same cross-memory environment as on entry.
v The exit must not issue any request using the RPL passed in register 1.
v The exit must be reentrant if multiple record management request that use the
exit can be concurrently outstanding.
Request Environment
VSAM RLS record management requests must be issued in PRIMARY ASC mode
and cannot be issued in home, secondary, or AR ASC mode. The user RPL, EXLST,
270
z/OS DFSMS Using Data Sets
Coding VSAM User-Written Exit Routines
ACB, must be addressable from primary. Open must have been issued from the
same primary address space. VSAM RLS record management request task must be
the same as the task that opened the ACB, or the task that opened the ACB must
be in the task hierarchy (i.e., the record management task was attached by that task
that opened the ACB, or by a task that was attached by the task that opened that
ACB). VSAM RLS record management requests must not be issued in SRB mode,
and must not have functional recovery routine (FRR) in effect.
If the record management request is issued in cross memory mode, then the caller
must be in supervisor state and must specify that an RLSWAIT exit is associated
with the request (RPLWAITX = ON). The request must be synchronous.
The RLSWAIT exit is optional for non-cross memory mode callers.
The RLSWAIT exit, if specified, is entered at the beginning of the request and
VSAM processes the request asynchronously under a separate execution unit.
VSAM RLS does not enter the RLSWAIT exit for post processing.
VSAM assumes that the ECB supplied with the request is addressable form both
home and primary, and that the key of the ECB is the same as the key of the
record management caller.
SYNAD Exit Routine to Analyze Physical Errors
VSAM exits to a SYNAD routine if a physical error occurs when you request
access to data. It also exits to a SYNAD routine when you close a data set if a
physical error occurs while VSAM is writing the contents of a buffer out to
direct-access storage.
Register Contents
Table 30 gives the contents of the registers when VSAM exits to the SYNAD
routine.
Table 30. Contents of registers at entry to SYNAD exit routine
Register
Contents
0
Unpredictable.
1
Address of the RPL that contains a feedback return code and the address of
a message area, if any. If you issued a request macro, the RPL is the one
pointed to by the macro. If you issued an OPEN, CLOSE, or cause an
end-of-volume to be done, the RPL was built by VSAM to process an
internal request. Register 1 must contain this address if the SYNAD routine
returns to VSAM.
2-13
Unpredictable. Register 13, by convention, contains the address of your
processing program's 72-byte save area, which must not be used by the
SYNAD routine if it returns control to VSAM.
14
Return address to VSAM.
15
Entry address to the SYNAD routine.
Programming Considerations
If you are specifying the SYNAD exit as a keyword of the AMP statement, you
must define a RACF FACILITY class profile with the resource name of
IDA.VSAMEXIT.xxxxxxxx where xxxxxxxx is the module name specified on the
SYNAD keyword. You must give users at least READ authority to the facility class
Chapter 16. Coding VSAM User-Written Exit Routines
271
Coding VSAM User-Written Exit Routines
resource name in order to invoke the exit. This is not necessary if the SYNAD exit
is coded on an EXLST within the program.
A SYNAD routine should typically:
v Examine the feedback field in the request parameter list to identify the type of
physical error that occurred.
v Get the address of the message area, if any, from the request parameter list, to
examine the message for detailed information about the error
v Recover data if possible
v Print error messages if uncorrectable error
v Close the data set
v Terminate processing.
The main problem with a physical error is the possible loss of data. You should try
to recover your data before continuing to process. Input operation (ACB
MACRF=IN) errors are generally less serious than output or update operation
(MACRF=OUT) errors, because your request was not attempting to alter the
contents of the data set.
If the routine cannot correct an error, it might print the physical-error message,
close the data set, and terminate the program. If the error occurred while VSAM
was closing the data set, and if another error occurs after the exit routine issues a
CLOSE macro, VSAM doesn't exit to the routine a second time.
If the SYNAD routine returns to VSAM, whether the error was corrected or not,
VSAM drops the request and returns to your processing program at the instruction
following the last executed instruction. Register 15 is reset to indicate that there
was an error, and the feedback field in the RPL identifies it.
Physical errors affect positioning. If a GET was issued that would have positioned
VSAM for a subsequent sequential GET and an error occurs, VSAM is positioned
at the control interval next in key (RPL OPTCD=KEY) or in entry (OPTCD=ADR)
sequence after the control interval involved in the error. The processing program
can therefore ignore the error and proceed with sequential processing. With direct
processing, the likelihood of re-encountering the control interval involved in the
error depends on your application.
If the exit routine issues GENCB, MODCB, SHOWCB, or TESTCB and returns to
VSAM, it must provide a save area and restore registers 13 and 14, which these
macros use.
See “Example of a SYNAD User-Written Exit Routine” on page 273 for the format
of a physical-error message that can be written by the SYNAD routine.
When your SYNAD exit routine completes processing, return to your main
program as described in “Return to a Main Program” on page 257.
If a physical error occurs and no SYNAD routine is provided (or the SYNAD exit
is inactive), VSAM returns codes in register 15 and in the feedback field of the RPL
to identify the error.
Related reading :
v For a description of the SYNAD return codes, see z/OS DFSMS Macro
Instructions for Data Sets.
272
z/OS DFSMS Using Data Sets
Coding VSAM User-Written Exit Routines
Example of a SYNAD User-Written Exit Routine
The example in Figure 34 demonstrates a user-written exit routine. It is a SYNAD
exit routine that examines the FDBK field of the RPL checking for the type of
physical error that caused the exit. After the checking, special processing can be
performed as necessary. The routine returns to VSAM after printing an appropriate
error message on SYSPRINT.
ACB1
ACB
EXLST=EXITS
EXITS
RPL1
EXLST
RPL
SYNAD=PHYERR
ACB=ACB1,
MSGAREA=PERRMSG,
MSGLEN=128
PHYERR
*
USING
*,15
This routine is nonreentrant.
Register 15 is entry address.
.
.
LA
.
.
.
13,SAVE
Save caller’s register
(1, 13, 14).
Point to routine’s save area.
If register 1=address of RPL1,
then error did not occur for a
CLOSE.
SHOWCB RPL=RPL1,
FIELDS=FDBK,
AREA=ERRCODE,
LENGTH=4
*
Show type of physical error.
.
.
.
PUT
.
.
.
BR
.
.
.
ERRCODE DC
PERRMSG DS
PRTDCB,ERRMSG
Examine error, perform special
processing.
Print physical error message.
Restore caller’s registers
(1, 13, 14).
14
Return to VSAM.
F’0’
0XL128
RPL reason code from SHOWCB.
Physical error message.
DS
XL12
Pad for unprintable part.
XL116
Printable format part of message.
PRTDCB
DS
.
.
.
DCB
.....
QSAM DCB.
SAVE
DS
18F
SYNAD routine’s save area.
SAVREG
DS
3F
Save registers 1, 13, 14.
ERRMSG
Figure 34. Example of a SYNAD exit routine
UPAD Exit Routine for User Processing
VSAM calls the UPAD routine only when the request's RPL specifies
OPTCD=(SYN, WAITX) and the ACB specifies MACRF=LSR or MACRF=GSR, or
MACRF=ICI. VSAM CLOSE can also cause a UPAD exit to be taken to post a
record-management request deferred for VSAM internal resource. VSAM takes the
Chapter 16. Coding VSAM User-Written Exit Routines
273
Coding VSAM User-Written Exit Routines
UPAD exit to wait for I/O completion or for a serially reusable resource and the
UPAD can also be taken to do the corresponding post processing subject to
conditions listed in Table 31.
If you are executing in cross-memory mode, you must have a UPAD routine and
RPL must specify WAITX. z/OS MVS Programming: Extended Addressability Guide
describes cross-memory mode. The UPAD routine is optional for
non-cross-memory mode.
Table 31 describes the conditions in which VSAM calls the UPAD routine for
synchronous requests with shared resources. UPAD routine exits are taken only for
synchronous requests with shared resources or improved control interval
processing (ICI).
Table 31. Conditions when exits to UPAD routines are taken
XMM
Sup.
state
UPAD
needed
I/O wait
I/O post
Resource wait
Resource post
Yes
Yes
Yes
UPAD taken
UPAD taken
UPAD taken
UPAD taken
No
Yes
No
UPAD taken if
requested
UPAD not taken UPAD taken if
even if requested requested
UPAD taken if either resource
owner or the deferred request
runs in XM mode
No
No
No
UPAD taken if
requested
UPAD not taken UPAD taken if
even if requested requested
UPAD taken if either resource
owner or the deferred request
runs in XM mode
Note:
v You must be in supervisor state when you are in cross-memory mode or SRB mode.
v RPL WAITX is required if UPAD is required. A UPAD routine can be taken only if RPL specifies WAITX.
v VSAM gives control to the UPAD exit in the same primary address space of the VSAM record management
request. However, VSAM can give control to UPAD with home and secondary ASIDs different from those of the
VSAM record management request because the exit was set up during OPEN.
v When a UPAD exit is taken to do post processing, make sure the ECB is marked posted before returning to VSAM.
VSAM does not check the UPAD return code and does not do post after UPAD has been taken. For
non-cross-memory task mode only, if the UPAD exit taken for wait returns with ECB not posted, VSAM issues a
WAIT SVC.
v The UPAD exit must return to VSAM in the same address space, mode, state, and addressing mode, and under the
same TCB or SRB from which the UPAD exit was called. Registers 1, 13, and 14 must be restored before the UPAD
exit returns to VSAM.
v ICI does not require UPAD for any mode. Resource wait and post processings do not apply to ICI.
RLS ignores the UPAD exit.
Register Contents
Table 32 shows the register contents passed by VSAM when the UPAD exit routine
is entered.
Table 32. Contents of registers at entry to UPAD exit routine
274
Register
Contents
0
Unpredictable.
1
Address of a parameter list built by VSAM.
2-12
Unpredictable.
13
Reserved.
z/OS DFSMS Using Data Sets
Coding VSAM User-Written Exit Routines
Table 32. Contents of registers at entry to UPAD exit routine (continued)
Register
Contents
14
Return address to VSAM.
15
Entry address of the UPAD routine.
Programming Considerations
The UPAD exit routine must be active before the data set is opened. The exit must
not be made inactive during processing. If the UPAD exit is desired and multiple
ACBs are used for processing the data set, the first ACB that is opened must
specify the exit list that identifies the UPAD exit routine.
You can use the UPAD exit to examine the contents of the parameter list built by
VSAM, pointed to by register 1. Table 33 describes this parameter list.
Table 33. Parameter list passed to UPAD routine
Offset
Bytes
Description
0(X'0')
4
Address of user's RPL; address of system-generated RPL if
UPAD is taken for CLOSE processing or for an alternate
index through a path.
4(X'4')
4
Address of a 5-byte data set identifier. The first four bytes
of the identifier are the ACB address. The last byte
identifies the component; data (X'01'), or index (X'02').
8(X'8')
4
Address of the request's ECB.
12(X'0C')
4
Reserved.
12(X'10')
1
UPAD flags:
Bit 0 = ON: Wait for resource
Bit 0 = OFF: Wait for I/O
(Bit 0 is only applicable to UPAD taken for wait
processing.)
Lower 7 bits are reserved.
16(X'11')
4
Reserved.
20(X'14')
1
Reason code:
X'00'
VSAM to do wait processing
X'04'
UPAD to do post processing
X'08'–X'FC' Reserved
If the UPAD exit routine modifies register 14 (for example, by issuing a TESTCB),
the routine must restore register 14 before returning to VSAM. If register 1 is used,
the UPAD exit routine must restore it with the parameter list address before
returning to VSAM.
The UPAD routine must return to VSAM under the same TCB from which it was
called for completion of the request that caused VSAM to exit. The UPAD exit
routine cannot use register 13 as a save area pointer without first obtaining its own
save area.
The UPAD exit routine, when taken before a WAIT during LSR or GSR processing,
might issue other VSAM requests to obtain better processing overlap (similar to
Chapter 16. Coding VSAM User-Written Exit Routines
275
Coding VSAM User-Written Exit Routines
asynchronous processing). However, the UPAD routine must not issue any
synchronous VSAM requests that do not specify WAITX, because a started request
might issue a WAIT for a resource owned by a starting request.
If the UPAD routine starts requests that specify WAITX, the UPAD routine must be
reentrant. After multiple requests have been started, they should be synchronized
by waiting for one ECB out of a group of ECBs to be posted complete rather than
waiting for a specific ECB or for many ECBs to be posted complete. (Posting of
some ECBs in the list might be dependent on the resumption of some of the other
requests that entered the UPAD routine.)
If you are executing in cross-memory mode, you must have a UPAD routine and
RPL must specify WAITX. When waiting or posting of an event is required, the
UPAD routine is given control to do wait or post processing (reason code 0 or 4 in
the UPAD parameter list).
User-Security-Verification Routine
If you use VSAM password protection, you can also have your own routine to
check a requester's authority. Your routine is invoked from OPEN, rather than via
an exit list. VSAM transfers control to your routine, which must reside in
SYS1.LINKLIB, when a requester gives a correct password other than the master
password.
Recommendation: Do not use VSAM password protection. Instead, use RACF or
an equivalent product.
Through the access method services DEFINE command with the
AUTHORIZATION parameter you can identify your user-security-verification
routine (USVR) and associate as many as 256 bytes of your own security
information with each data set to be protected. The user-security-authorization
record (USAR) is made available to the USVR when the routine gets control. You
can restrict access to the data set as you choose. For example, you can require that
the owner of a data set give ID when defining the data set and then permit only
the owner to gain access to the data set.
If the USVR is being used by more than one task at a time, you must code the
USVR reentrant or develop another method for handling simultaneous entries.
When your USVR completes processing, it must return (in register 15) to VSAM
with a return code of 0 for authority granted or not 0 for authority withheld in
register 15. Table 34 gives the contents of the registers when VSAM gives control to
the USVR.
Table 34. Communication with user-security-verification routine
276
Register
Contents
0
Unpredictable.
z/OS DFSMS Using Data Sets
Coding VSAM User-Written Exit Routines
Table 34. Communication with user-security-verification routine (continued)
Register
Contents
1
Address of a parameter list with the following format:
44 bytes
Name of the data set for which authority to process is to be
verified (the name you specified when you defined it with access method
services)
8 bytes
Prompting code (or 0's).
8 bytes
Owner identification (or 0's).
8 bytes
VSAM).
The password that the requester gave (it has been verified by
2 bytes
Length of the user-security-authorization routine (in binary).
–
The user-security-authorization.
2-13
Unpredictable.
14
Return address to VSAM.
15
Entry address to the USVR. When the routine returns to VSAM, it indicates
by the following codes in register 15 if the requester has been authorized to
gain access to the data set:
0
Authority granted.
not 0 Authority withheld.
Chapter 16. Coding VSAM User-Written Exit Routines
277
Coding VSAM User-Written Exit Routines
278
z/OS DFSMS Using Data Sets
Chapter 17. Using 31-Bit Addressing Mode with VSAM
This chapter covers rules, guidelines, and keyword parameters that you need to
know about to implement 31-bit addressing with VSAM.
Topic
“VSAM Options”
VSAM Options
Using VSAM, you can obtain control blocks, buffers, and multiple local shared
resource (LSR) pools above or below 16 MB. However, if your program uses a
24-bit address, it can generate a program check if you attempt to reference control
blocks, buffers, or LSR pools located above 16 MB. With a 24-bit address, you do
not have addressability to the data buffers.
If you specify that control blocks, buffers, or pools can be above the line and
attempt to use locate mode to access records while in 24-bit mode, your program
will program check (ABEND 0C4).
Rule: You cannot specify the location of buffers or control blocks for RLS
processing. RLS ignores the ACB RMODE31= keyword.
When you use 31-bit addresses, observe the following rules:
v All VSAM control blocks that contain addresses must contain valid 31-bit
addresses. If you are using 24-bit or 31-bit addresses, do not use the high-order
byte of a 31-bit address field as a user-defined flag field.
v I/O buffers and control blocks can be obtained either above or below 16 MB in
storage.
– I/O buffers and control blocks can be requested below 16 MB by taking the
ACB, GENCB, MODCB, or BLDVRP macro defaults.
– I/O buffers can be requested above 16 MB and control blocks below 16 MB
by specifying the RMODE31=BUFF parameter on the ACB, GENCB, MODCB,
or BLDVRP macros.
– Control blocks can be requested above 16 MB and buffers below 16 MB by
specifying the RMODE31=CB parameter on the ACB, GENCB, MODCB, or
BLDVRP macros.
– Control blocks and buffers can be requested above 16 MB by specifying the
RMODE31=ALL parameter on the ACB, GENCB, MODCB, or BLDVRP
macros.
– Buffers are obtained in 24-bit addressable storage by specifying the
RMODE31=NONE or CB subparameter on the AMP parameter.
– Control blocks are obtained in 24-bit addressable storage by specifying the
RMODE31=NONE or BUFF subparameter on the AMP parameter.
v The parameter list passed to your UPAD and JRNAD exit routine resides in the
same area specified with the VSAM control blocks. If RMODE31=CB or
RMODE31=ALL is specified, the parameter list resides above 16 MB.
v You must recompile the portion of your program that contains the ACB,
BLDVRP, and DLVRP macro specifications.
© Copyright IBM Corp. 1987, 2017
279
Using 31-Bit Addressing Mode with VSAM
v You specify 31-bit parameters by specifying the AMP=(RMODE31=) parameter
in the JCL.
Table 35 summarizes the 31-bit address keyword parameters and their use in the
applicable VSAM macros.
Table 35. 31-Bit Address Keyword Parameters
MACRO
RMODE31=
MODE=
LOC=
ACB
Virtual storage location of VSAM control blocks
and I/O buffers
INVALID
INVALID
BLDVRP
Virtual storage location of VSAM LSR pool,
VSAM control blocks and I/O buffers
Format of the BLDVRP
parameter list (24-bit or
31-bit format)
INVALID
CLOSE
INVALID
Format of the CLOSE
parameter list (24-bit or
31-bit format)
INVALID
DLVRP
INVALID
Format of the DLVRP
parameter list (24-bit or
31-bit format)
INVALID
GENCB
RMODE31 values to be placed in the ACB that
is being created. When the generated ACB is
opened, the RMODE31 values will then
determine the virtual storage location of VSAM
control blocks and I/O buffers.
INVALID
Location for the virtual
storage obtained by
VSAM for the ACB,
RPL, or EXIT LIST.
MODCB
RMODE31 values to be placed in a specified
ACB
INVALID
INVALID
OPEN
INVALID
Format of the OPEN
parameter list (24-bit or
31-bit format)
INVALID
Related reading:
v See “Obtaining Buffers Above 16 MB” on page 181 for information about
creating and accessing buffers that reside above 16 MB.
v See Chapter 13, “Sharing Resources Among VSAM Data Sets,” on page 221 for
information about building multiple LSR pools in an address space.
v See z/OS MVS JCL Reference for information about specifying 31-bit parameters
using the AMP=(RMODE31=) parameter.
280
z/OS DFSMS Using Data Sets
Chapter 18. Using Job Control Language for VSAM
This topic covers the following subtopics.
Topic
“Using JCL Statements and Keywords”
“Creating VSAM Data Sets with JCL” on page 282
“Retrieving an Existing VSAM Data Set” on page 287
Using JCL Statements and Keywords
All VSAM data sets, except for variable-length RRDSs, can be defined, created, and
retrieved using Job Control Language (JCL). When a JCL DD statement is used to
identify a VSAM data set, the DD statement must contain data set name and
disposition (DISP) keywords. You can add other keywords to the DD statement
when appropriate. “Creating VSAM Data Sets with JCL” on page 282 and
“Retrieving an Existing VSAM Data Set” on page 287 describe the required JCL
keywords. See z/OS MVS JCL Reference for descriptions of all the DD statements.
Data Set Name
The data set name (DSNAME) parameter specifies the name of the data set being
processed. For a new data set, the specified name is assigned to the data set. For
an existing data set, the system uses the name to locate the data set.
Optionally, the DSNAME parameter can be used to specify one of the components
of a VSAM data set. Each VSAM data set is defined as a cluster of one or more
components. Key-sequenced data sets contain a data component and an index
component. Entry-sequenced and linear data sets and fixed-length RRDSs contain
only a data component. Process a variable-length RRDS as a cluster. Each alternate
index contains a data component and an index component. For further information
on specifying a cluster name see “Naming a Cluster” on page 118.
Disposition
The disposition (DISP) parameter describes the status of a data set to the system
and tells the system what to do with the data set after the step or job terminates.
All new system-managed and VSAM data sets are treated as if
DISP=(NEW,CATLG) were specified. They are cataloged at step initiation time.
To protect non-system-managed data sets in a shared environment, specify
DISP=OLD for any data set that can be accessed improperly in a shared
environment. Specifying DISP=OLD permits only one job step to access the data
set. If the data set's share options permit the type of sharing your program
anticipates, you can specify DISP=SHR in the DD statements of separate jobs to
enable two or more job steps to share a data set. With separate DD statements,
several subtasks can share a data set under the same rules as for cross-region
sharing. When separate DD statements are used and one or more subtasks will
perform output processing, the DD statements must specify DISP=SHR. For more
details on sharing data sets see Chapter 12, “Sharing VSAM Data Sets,” on page
205.
© Copyright IBM Corp. 1987, 2017
281
Using Job Control Language for VSAM
Creating VSAM Data Sets with JCL
You can use the JCL DD statement with the RECORG parameter to create a
permanent or temporary VSAM data set. SMS must be active, but the data set does
not have to be system managed. The system catalogs a permanent VSAM data set
when the data set is allocated.
With SMS, you can optionally specify a data class that contains RECORG. If your
storage administrator, through the ACS routines, creates a default data class that
contains RECORG, you have the option of taking this default as well.
The following list contains the keywords, including RECORG, used to allocate a
VSAM data set. See z/OS MVS JCL Reference for a detailed description of these
keywords.
AVGREC—Specifies the scale value of an average record request on the SPACE
keyword. The system applies the scale value to the primary and secondary
quantities specified in the SPACE keyword. The AVGREC keyword is ignored if
the SPACE keyword specifies anything but an average record request.
Possible values for the AVGREC keyword follow:
U—Use a scale of 1
K—Use a scale of 1024
M—Use a scale of 1 048 576
DATACLAS—Is a list of the data set allocation parameters and their default
values. The storage administrator can specify KEYLEN, KEYOFF, LRECL,
LGSTREAM, and RECORG in the DATACLAS definition, but you can override
them.
DSNTYPE—Specifies whether the data set is preferred to be extended format or
must be extended format. These values are relevant to VSAM:
v BASIC. Not extended format.
v EXTPREF. You prefer it to be extended format but if that is not possible, then
non-extended format is requested.
v EXTREQ. Extended format is required. If it is not possible, then fail the request.
EXPDT—Specifies the date up to which a data set cannot be deleted without
specifying the PURGE keyword on the access method services DELETE command.
On and after the expiration date, the data set can be deleted or written over by
another data set.
KEYLEN—Specifies key length.
LGSTREAM—Specifies the log stream used. LOG and BWO parameters can be
derived from the data class.
KEYOFF—Specifies offset to key.
LIKE—Specifies that the properties of an existing cataloged data set should be
used to allocate a new data set. For a list of the properties that can be copied, see
z/OS MVS JCL Reference.
282
z/OS DFSMS Using Data Sets
Using Job Control Language for VSAM
LRECL—Specifies logical record length. Implies a system determined control
interval size.
MGMTCLAS—Specifies the name, 1 to 8 characters, of the management class for a
new system-managed data set. Your storage administrator defines the names of the
management classes you can specify on the MGMTCLAS parameter. After the data
set is allocated, attributes in the management class control the following:
v The migration of the data set, which includes migration criteria from primary
storage to migration storage and from one migration level to another in a
hierarchical migration scheme.
v The backup of the data set, which includes frequency of backup, number of
versions, and retention criteria for backup versions.
RECORG—Specifies the type of data set desired: KS, ES, RR, LS.
KS
ES
RR
LS
= key-sequenced data set
= entry-sequenced data set
= fixed-length relative-record data set
= linear data set
REFDD—Specifies that the properties on the JCL statement and from the data class
of a previous DD statement should be used to allocate a new data set.
RETPD—Specifies the number of days a data set cannot be deleted by specifying
the PURGE keyword on the access method services DELETE command. After the
retention period, the data set can be deleted or written over by another data set.
SECMODEL—Permits specification of the name of a “model” profile that RACF
should use in creating a discrete profile for the data set. For a list of the
information that is copied from the model profile see z/OS MVS JCL Reference.
STORCLAS—Specifies the name, 1 to 8 characters, of the storage class for a new,
system-managed data set.
Your storage administrator defines the names of the storage classes you can specify
on the STORCLAS parameter. A storage class is assigned when you specify
STORCLAS or an ACS routine selects a storage class for the new data set.
Use the storage class to specify the storage service level to be used by SMS for
storage of the data set. The storage class replaces the storage attributes specified on
the UNIT and VOLUME parameter for non-system-managed data sets.
If a guaranteed space storage class is assigned to the data set (cluster) and volume
serial numbers are specified, space is allocated on all specified volumes if the
following conditions are met:
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.
Temporary VSAM Data Sets
A temporary data set is allocated and deleted within a job. Also, temporary VSAM
data sets must reside in storage managed by the Storage Management Subsystem.
SMS manages a data set if you specify a storage class (using the DD STORCLAS
parameter) or if an installation-written automatic class selection (ACS) routine
selects a storage class for the data set.
Chapter 18. Using Job Control Language for VSAM
283
Using Job Control Language for VSAM
Data Set Names
When defining a temporary data set, you can omit the DSNAME. If omitted, the
system will generate a qualified name for the data set. If you specify a DSNAME,
it must begin with & or &&. The DSNAME can be simple or qualified.
&ABC
&XYZ
Allocation
You can allocate VSAM temporary data sets by specifying
RECORG=KS|ES|LS|RR as follows:
v By the RECORG keyword on the DD statement or the dynamic allocation
parameter
v By the data class (if the selected data class has the RECORG attribute)
v By the default data class established by your storage administrator (if the default
data class exists and has the RECORG attribute)
Using temporary data sets avoids the following problems:
v The data set can be defined in a catalog for which you are not authorized.
v The data set can be assigned to an RACF user or group ID for which you are
not authorized. The data set can also be assigned to an ID that is not defined to
RACF, in which case the allocation will fail either if the RACF option that
required protection of all data sets is in effect, or if the data set requires a
discrete RACF profile.
v The allocation can fail because there is already a data set cataloged with that
name. This failure would be likely if there are many jobs using the same data set
names for what were regarded as temporary data sets.
Restrictions for Temporary VSAM Data Sets
The following restrictions apply to the use of temporary VSAM data sets:
v Multivolume temporary VSAM data sets are not permitted.
v You cannot reference a temporary data set once a job is completed.
v The use of VOL=SER and UNIT will not let you refer to a temporary data set
outside the job that created it.
v The EXPDT and RETPD keywords are ignored.
v
A temporary VSAM data set cannot support the RESET option in the ACB.
For additional information on temporary data sets see z/OS MVS JCL Reference and
z/OS MVS Programming: Assembler Services Guide. See “Example 4: Allocate a
Temporary VSAM Data Set” on page 286 for an example of creating a temporary
VSAM data set.
Examples Using JCL to Allocate VSAM Data Sets
The following examples contain allocation information.
Example 1: Allocate a Key-Sequenced Data Set
The following example shows allocating a key-sequenced data set:
//DDNAME
//
//
DD
DSNAME=KSDATA,DISP=(NEW,KEEP),
SPACE=(80,(20,2)),AVGREC=U,RECORG=KS,
KEYLEN=15,KEYOFF=0,LRECL=250
Explanation of Keywords:
v DSNAME specifies the data set name.
284
z/OS DFSMS Using Data Sets
Using Job Control Language for VSAM
v DISP specifies that a new data set is to be allocated in this step and that the data
set is to be kept on the volume if this step terminates normally. If the data set is
not system managed, KEEP is the only normal termination disposition
subparameter permitted for a VSAM data set. Non-system-managed VSAM data
sets should not be passed, cataloged, uncataloged, or deleted.
v SPACE specifies an average record length of 80, a primary space quantity of 20
and a secondary space quantity of 2.
v AVGREC specifies that the primary and secondary space quantity specified on
the SPACE keyword represents the number of records in units (multiplier of 1).
If DATACLAS were specified in this example, AVGREC would override the data
class space allocation.
v RECORG specifies a VSAM key-sequenced data set.
v KEYLEN specifies that the length of the keys used in the data set is 15 bytes. If
DATACLAS were specified in this example, KEYLEN would override the data
class key length allocation.
v KEYOFF specifies an offset of zero of the first byte of the key in each record. If
DATACLAS were specified in this example, KEYOFF would override the data
class key offset allocation.
v LRECL specifies a record length of 250 bytes. If DATACLAS were specified in
this example, LRECL would override the data class record length allocation.
v The system determines an appropriate size for the control interval.
Example 2: Allocate a System-Managed Key-Sequenced Data Set
Using Keywords
The following example shows allocating a system-managed key-sequenced data
set:
//DDNAME
//
//
DD
DSNAME=KSDATA,DISP=(NEW,KEEP),
DATACLAS=STANDARD,STORCLAS=FAST,
MGMTCLAS=STANDARD
Explanation of Keywords:
v DSNAME specifies the data set name.
v DISP specifies that a new data set is to be allocated in this step and that the data
set is to be kept on the volume if this step terminates normally. Because a
system-managed data set is being allocated, all dispositions are valid for VSAM
data sets; however, UNCATLG is ignored.
v DATACLAS specifies a data class for the new data set. If SMS is not active, the
system syntax ignores DATACLAS. SMS also ignores the DATACLAS keyword if
you specify it for an existing data set, or a data set that SMS does not support.
This keyword is optional. If you do not specify DATACLAS for the new data set
and your storage administrator has provided an ACS routine, the ACS routine
can select a data class for the data set.
v STORCLAS specifies a storage class for the new data set. If SMS is not active,
the system syntax ignores STORCLAS. SMS also ignores the STORCLAS
keyword if you specify it for an existing data set.
This 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 for the data set.
v MGMTCLAS specifies a management class for the new data set. If SMS is not
active, the system syntax ignores MGMTCLAS. SMS also ignores the
MGMTCLAS keyword if you specify it for an existing data set.
Chapter 18. Using Job Control Language for VSAM
285
Using Job Control Language for VSAM
This keyword is optional. If you do not specify MGMTCLAS for the new data
set and your storage administrator has provided an ACS routine, the ACS
routine can select a management class for the data set.
Example 3: Allocate a VSAM Data Set Using Keyword Defaults
The following example shows the minimum number of keywords needed to
allocate a permanent VSAM data set through JCL:
//DDNAME
DD
DSNAME=DSVSAM,DISP=(NEW,CATLG)
Explanation of Keywords:
v DSNAME specifies the data set name.
v DISP specifies that a new data set is to be allocated in this step and that the
system is to place an entry pointing to the data set in the system or user catalog.
v DATACLAS, STORCLAS, and MGMTCLAS are not required if your storage
administrator has provided ACS routines that will select the SMS classes for
you, and DATACLAS defines RECORG.
Example 4: Allocate a Temporary VSAM Data Set
The following example shows allocating a temporary VSAM data set:
//VSAM1
//
//
DD
DSN=&CLUSTER,DISP=(NEW,PASS),
RECORG=ES,SPACE=(1,(10)),AVGREC=M,
LRECL=256,STORCLAS=TEMP
Explanation of Keywords:
v DSN specifies the data set name. If you specify a data set name for a temporary
data set, it must begin with & or &&. This keyword is optional, however. If you
do not specify a DSN, the system will generate a qualified data set name for the
temporary data set.
v DISP specifies that a new data set is to be allocated in this step and that the data
set is to be passed for use by a subsequent step in the same job. If KEEP or
CATLG are specified for a temporary data set, the system changes the
disposition to PASS and deletes the data set at job termination.
v RECORG specifies a VSAM entry-sequenced data set.
v SPACE specifies an average record length of 1 and a primary quantity of 10.
v AVGREC specifies that the primary quantity (10) specified on the SPACE
keyword represents the number of records in megabytes (multiplier of 1048576).
v LRECL specifies a record length of 256 bytes.
v STORCLAS specifies a storage class for the temporary data set.
This 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 5: Allocate a Temporary VSAM Data Set Taking All
Defaults
The following example shows the minimum number of keywords required to
allocate a temporary VSAM data set:
//VSAM2
DD
DISP=(NEW,PASS)
If no DSNAME is specified, the system will generate one. If no STORCLAS name
is specified, and your storage administrator has provided an ACS routine, the ACS
routine can select a storage class. The key length for a key-sequenced data set must
be defined in your default DATACLAS. If you do not, this example will fail.
286
z/OS DFSMS Using Data Sets
Using Job Control Language for VSAM
Retrieving an Existing VSAM Data Set
To retrieve an existing VSAM data set, code a DD statement in the form:
//ddname
or
//ddname
DD
DSNAME=dsname,DISP=OLD
DD
DSNAME=dsname,DISP=SHR
If SMS is active, you can pass VSAM data sets within a job. The system replaces
PASS with KEEP for permanent VSAM data sets. When you refer to the data set
later in the job, the system obtains data set information from the catalog. Without
SMS you cannot pass VSAM data sets within a job.
Migration Consideration
If you have existing JCL that allocates a VSAM data set with DISP=(OLD,DELETE),
the system ignores DELETE and keeps the data set if SMS is inactive. If SMS is
active, DELETE is valid and the system deletes the data set.
Keywords Used to Process VSAM Data Sets
Use the following keywords to process VSAM data sets once they have been
retrieved. Use these parameters to process existing VSAM data sets, not to allocate
new VSAM data sets. For information about the JCL parameters used to allocate a
new VSAM data set see “Creating VSAM Data Sets with JCL” on page 282.
AMP is only used with VSAM data sets. The AMP parameter takes effect when the
data set defined by the DD statement is opened.
Note: This is not supported by RLS.
DDNAME lets you postpone defining a data set until later in the job step.
DISP =(SHR|OLD[,PASS]) describes the status of a data set, and tells the system
what to do with the data set after the step or job ends.
DSNAME specifies the name of a data set.
DUMMY specifies that no disposition processing is to be performed on the data
set. It also specifies that no device or external storage space is to be allocated to the
data set.
DYNAM increases by one the control value for dynamically allocated resources
held for reuse.
FREE specifies when the system is to deallocate resources for the data set.
PROTECT tells RACF to protect the data set.
UNIT =(device number|type|group,p|unitcount) places the data set on a specific
device or a group of devices.
VOLUME =(PRIVATE|SER) identifies the volume on which a data set will reside.
With SMS, you do not need the AMP, UNIT, and VOLUMES parameters to retrieve
an existing VSAM data set. With SMS, you can use the DISP subparameters MOD,
NEW, CATLG, KEEP, PASS, and DELETE for VSAM data sets.
Chapter 18. Using Job Control Language for VSAM
287
Using Job Control Language for VSAM
Certain JCL keywords should either not be used, or used only with caution when
processing VSAM data sets. See the VSAM data set topic in z/OS MVS JCL User's
Guide for a list of these keywords. Additional descriptions of these keywords also
appear in z/OS MVS JCL Reference.
288
z/OS DFSMS Using Data Sets
Chapter 19. Processing Indexes of Key-Sequenced Data Sets
This topic covers the following subtopics.
Topic
“Access to a Key-Sequenced Data Set Index”
“Format of an Index Record” on page 293
“Key Compression” on page 297
VSAM lets you access indexes of key-sequenced data sets to help you diagnose
index problems. This can be useful if your index is damaged or if pointers are lost
and you want to know exactly what the index contains. You should not attempt to
duplicate or substitute the index processing done by VSAM during normal access
to data records.
Access to a Key-Sequenced Data Set Index
You can gain access to the index of a key-sequenced data set in one of two ways:
v By opening the cluster and using the GETIX and PUTIX macros
v By opening the index component alone and using the macros for normal data
processing (GET, PUT, and so forth)
Access to an Index with GETIX and PUTIX
To process the index of a key-sequenced data set with GETIX and PUTIX, you
must open the cluster with ACB MACRF=(CNV,...) specified. CNV provides for
control interval access, which you use to gain access to the index component.
Access using GETIX and PUTIX is direct, by control interval: VSAM requires RPL
OPTCD=(CNV,DIR). The search argument for GETIX is the RBA of a control
interval. The increment from the RBA of one control interval to the next is control
interval size for the index.
GETIX can be issued either for update or not for update. VSAM recognizes
OPTCD=NUP or UPD but interprets OPTCD=NSP as NUP.
The contents of a control interval cannot be inserted through PUTIX. VSAM
requires OPTCD=UPD. The contents must previously have been retrieved for
update through GETIX.
RPL OPTCD=MVE or LOC can be specified for GETIX, but only OPTCD=MVE is
valid for PUTIX. If you retrieve with OPTCD=LOC, you must change OPTCD to
MVE to store. With OPTCD=MVE, AREALEN must be at least index control
interval size.
Beyond these restrictions, access to an index through GETIX and PUTIX follows
the rules found in Chapter 11, “Processing Control Intervals,” on page 195.
Access to the Index Component Alone
You can gain addressed or control interval access to the index component of a
key-sequenced cluster by opening the index component alone and using the
© Copyright IBM Corp. 1987, 2017
289
Processing Indexes of Key-Sequenced Data Sets
request macros for normal data processing. To open the index component alone,
specify: DSNAME=indexcomponentname in the DD statement identified in the ACB
(or GENCB) macro.
You can gain access to index records with addressed access and to index control
intervals with control interval access. The use of these two types of access for
processing an index is identical in every respect with their use for processing a
data component.
Processing the index component alone is identical to processing an
entry-sequenced data set. An index itself has no index and thus cannot be
processed by keyed access.
Prime Index
A key-sequenced data set always has an index that relates key values to the
relative locations of the logical records in a data set. This index is called the prime
index. The prime index, or simply index, has two uses:
v Locate the collating position when inserting records
v Locate records for retrieval
When a data set is initially loaded, 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. The index is stored in control intervals. An
index control interval contains pointers to index control intervals in the next lower
level, or one entry for each data control interval in a control area.
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. The highest possible key in a data control interval is one
less than the value of the first key in the next sequential data control interval.
Figure 35 shows that a single index entry, such as 19, contains all the information
necessary to locate a logical record in a data control interval.
Index
CI
Free
CI Ptr
List
19
25
Data CI1
11
15
18
Data CI2
Control
info
20
25
Data CI3
Control
info
Free space
C
I
D
F
Figure 35. Relation of Index Entry to Data Control Interval
Figure 36 on page 291 shows that a single index control interval contains all the
information necessary to locate a record in a single data control area.
290
z/OS DFSMS Using Data Sets
Processing Indexes of Key-Sequenced Data Sets
Index
CI
Free
CI Ptr
list
19
25
b
c
a
Data CI1
11
15
18
Data CI2
Control
info
20
25
Data CI3
Control
info
Free space
C
I
D
F
Data control area
Figure 36. Relation of Index Entry to Data Control Interval
The index contains the following entries:
1. A free control interval pointer list, which indicates available free space control
intervals. Because this control area has a control interval that is reserved as free
space, VSAM places a free space pointer in the index control interval to locate
the free space data control interval.
2. 19, the highest possible key in data control interval 1. This entry points to the
beginning of data control interval 1.
3. 25, the highest possible key in data control interval 2. This entry points to the
beginning of data control interval 2.
Index Levels
A VSAM index can consist of more than one index level. Each level contains a set
of records with entries giving the location of the records in the next lower level.
Figure 37 on page 292 shows the levels of a prime index and shows the
relationship between sequence set index records and control areas. The sequence
set shows both the horizontal pointers used for sequential processing and the
vertical pointers to the data set. Although the values of the keys are actually
compressed in the index, the figure shows the full key values.
Chapter 19. Processing Indexes of Key-Sequenced Data Sets
291
Processing Indexes of Key-Sequenced Data Sets
H
D
R
2799 4200 6705
H
D
R
1333 2383 2799
H
D
R
H
D
R
1021 1051
H
D
R
Index set
Sequence set
Control area 1
1333
4200
1401 2344
1001 1002 1009
FS
Control
info
1052 1060 1080
FS
Control
info
1022 1025 1033
FS
Control
info
2383
Control
area 2
1334 1350 1400
FS
Control
info
1402 1424 1428
FS
Control
info
2345 2342 2363
FS
Control
info
HDR - Header information
Figure 37. Levels of a Prime Index
Sequence Set. The index records at the lowest level are the sequence set. There is
one index sequence set level record for each control area in the data set. This
sequence set record gives the location of data control intervals. An entry in a
sequence set record consists of the highest possible key in a control interval of the
data component, paired with a pointer to that control interval.
Index Set. If there is more than one sequence set level record, VSAM automatically
builds another index level. Each entry in the second level index record points to
one sequence set record. The records in all levels of the index above the sequence
set are called the index set. An entry in an index set record consists of the highest
possible key in an index record in the next lower level, and a pointer to the
beginning of that index record. The highest level of the index always contains only
a single record.
When you access records sequentially, VSAM refers only to the sequence set. It
uses a horizontal pointer to get from one sequence set record to the next record in
collating sequence. When you access records directly (not sequentially), VSAM
follows vertical pointers from the highest level of the index down to the sequence
set to find vertical pointers to data.
VSAM index trap
VSAM has an index trap that checks each index record before writing it. The trap
catches the following common index breakages, but not all others:
292
z/OS DFSMS Using Data Sets
Processing Indexes of Key-Sequenced Data Sets
v High-used greater than high-allocated
v Duplicate or invalid index pointer
v Out-of-sequence index record
v Invalid section entry
v Invalid key length.
For more information about the VSAM index trap for system programmers, see
z/OS DFSMSdfp Diagnosis.
Format of an Index Record
Index records are stored in control intervals the same as data records, except that
only one index record is stored in a control interval, and there is no free space
between the record and the control information. So, there is only one RDF that
contains the flag X'00' and the length of the record (a number equal to the length
of the control interval minus 7). The CIDF also contains the length of the record
(the displacement from the beginning of the control interval to the control
information); its second number is 0 (no free space). The contents of the RDF and
CIDF are the same for every used control interval in an index. The control interval
after the last-used control interval has a CIDF filled with 0s, and is used to
represent the software end-of-file (SEOF).
Index control intervals are not grouped into control areas as are data control
intervals. When a new index record is required, it is stored in a new control
interval at the end of the index data set. As a result, the records of one index level
are not segregated from the records of another level, except when the sequence set
is separate from the index set. The level of each index record is identified by a
field in the index header (see “Header Portion”).
When an index record is replicated on a track, each copy of the record is identical
to the other copies. Replication has no effect on the contents of records.
Figure 38 shows the parts of an index record.
Figure 38. General Format of an Index Record
An index record contains the following parts:
v A 24-byte header containing control information about the record.
v For a sequence-set index record governing a control area that has free control
intervals, there are entries pointing to those free control intervals.
v Unused space, if any.
v A set of index entries used to locate, for an index-set record, control intervals in
the next lower level of the index, or, for a sequence-set record, used control
intervals in the control area governed by the index record.
Header Portion
The first 24 bytes of an index record is the header, which gives control information
about the index record. Table 36 on page 294 shows its format. All lengths and
displacements are in bytes. The discussions in the following two sections amplify
the meaning and use of some of the fields in the header.
Chapter 19. Processing Indexes of Key-Sequenced Data Sets
293
Processing Indexes of Key-Sequenced Data Sets
Table 36. Format of the Header of an Index Record
Field
Offset
Length
Description
IXHLL
0(0)
2
Index record length. The length of the index record is equal to the length of
the control interval minus 7.
IXHFLPLN
2(2)
1
Index entry control information length. This is the length of the last three of
the four fields in an index entry. (The length of the first field is variable.) The
length of the control information is 3, 4, or 5 bytes.
IXHPTLS
3(3)
1
Vertical-pointer-length indicator.
The fourth field in an index entry is a vertical pointer to a control interval.
In an index-set record, the pointer is a binary number that designates a
control interval in the index. The number is calculated by dividing the RBA of
the control interval by the length of the control interval. To permit for a
possibly large index, the pointer is always 3 bytes.
In a sequence-set record, the pointer is a binary number, beginning at 0, and
calculated the same as for index-set record, that designates a control interval
in the data control area governed by the sequence-set record. A
free-control-interval entry is nothing more than a vertical pointer. There are as
many index entries and free-control-interval entries in a sequence-set record
as there are control intervals in a control area. Depending on the number of
control intervals in a control area, the pointer is 1, 2, or 3 bytes.
An IXHPTLS value of X'01' indicates a 1-byte pointer; X'03' indicates a 2-byte
pointer; X'07' indicates a 3-byte pointer.
IXHBRBA
4(4)
4
Base RBA. In an index-set record, this is the beginning RBA of the index. Its
value is 0. The RBA of a control interval in the index is calculated by
multiplying index control interval length times the vertical pointer and
adding the result to the base RBA.
In a sequence-set record, this is the RBA of the control area governed by the
record. The RBA of a control interval in the control area is calculated by
multiplying data control interval length times the vertical pointer and adding
the result to the base RBA. Thus, the first control interval in a control area has
the same RBA as the control area (length times 0, plus base RBA, equals base
RBA).
Exception: For an extended-addressable KSDS, this field is a relative control
interval number instead of a RBA.
IXHBCI
4(4)
4
IXHFINXT
4(4)
4
Doubly defined with IXHBRBA. Set only in an index-set record. It is the CI#
of the next index-set record in the free index-set record LIFO chain. This field
in the first 2nd-level index record (CI #2) has the CI# of the most recently
freed index-set record or, if Flag byte = X'80', the index-set record that was
interrupted during CA reclaim.
IXHHP
8(8)
4
Horizontal-pointer RBA. This is the RBA of the next index record in the same
level as this record. The next index record contains keys next in ascending
sequence after the keys in this record.
Exception: For an extended-addressable KSDS, this field is a relative control
interval number instead of a RBA.
IXHFSNXT
294
12(C)
z/OS DFSMS Using Data Sets
Set in the first 2nd-level index record (CI #2) and the free sequence-set
records. It is the CI# of the next sequence-set record in the free sequence-set
record LIFO chain. This field in the first 2nd-level index record has the CI# of
the most recently freed sequence-set record or, if Flag byte = X’80’, the
sequence-set record that was interrupted during CA reclaim.
Processing Indexes of Key-Sequenced Data Sets
Table 36. Format of the Header of an Index Record (continued)
Field
Offset
Length
Description
IXHLV
16(10)
1
Level number. The sequence set is the first level of an index, and each of its
records has an IXHLV of 1. Records in the next higher level have a 2, and so
on.
17(11)
1
Flag byte
X'80' -- CA reclaim is in progress. Set only in index CI #2.
X'40' -- CA reclaim is committed. Set only in the index record one level
above the vertical chain of index records to be reclaimed.
X'20' -- CA reclaim is pending. Set in all index reccords that will be
reclaimed. This flag stays ON until this index record is reused.
X'10' -- Index record removed from horizontal chain for CA Reclaim. This
flag stays ON until this index record is reused.
X'08' -- Index CI #2 itself is logically in the IXHFINXT chain. This flag is
set only in index CI #2.
X'04' -- IXHHBACK is valid and can be referenced.
IXHFSO
18(12)
2
Displacement to the unused space in the record. In an index-set record, this is
the length of the header (24). There are no free control interval entries.
In a sequence-set record, the displacement is equal to 24, plus the length of
free control interval entries, if any.
IXHLEO
20(14)
2
Displacement to the control information in the last index entry. The last
(leftmost) index entry contains the highest key in the index record. In a
search, if the search-argument key is greater than the highest key in the
preceding index record but less than or equal to the highest key in this index
record, then this index record governs either the index records in the next
lower level that have the range of the search-argument key or the control area
in which a data record having the search-argument key is stored.
IXHSEO
22(16)
2
Displacement to the control information in the last (leftmost) index entry in
the first (rightmost) section. Index entries are divided into sections to simplify
a quick search. Individual entries are not examined until the right section is
located.
IXHHBACK
24(18)
4
Point to the preceding index CI in the horizontal chain. Only set in the
reclaimed index CI.
Free Control Interval Entry Portion
If the control area governed by a sequence-set record has free control intervals, the
sequence-set record has entries pointing to those free control intervals. Each entry
is 1, 2, or 3 bytes long (indicated by IXHPTLS in the header: the same length as the
pointers in the index entries).
The entries come immediately after the header. They are used from right to left.
The rightmost entry is immediately before the unused space (whose displacement
is given in IXHFSO in the header). When a free control interval gets used, its free
entry is converted to zero, the space becomes part of the unused space, and a new
index entry is created in the position determined by ascending key sequence.
Thus, the free control interval entry portion contracts to the left, and the index
entry portion expands to the left. When all the free control intervals in a control
area have been used, the sequence-set record governing the control area no longer
has free control interval entries, and the number of index entries equals the
number of control intervals in the control area. Note that if the index control
interval size was specified with too small a value, it is possible for the unused
Chapter 19. Processing Indexes of Key-Sequenced Data Sets
295
Processing Indexes of Key-Sequenced Data Sets
space to be used up for index entries before all the free control intervals have been
used, resulting in control intervals within a data control area that cannot be used.
Index Entry Portion
The index entry portion of an index record takes up all of the record that is left
over after the header, the free control interval entries, if any, and the unused space.
Figure 39 shows the format of the index entry portion of an index record. To
improve search speed, index entries are grouped into sections, of which there are
approximately as many as the square root of the number of entries. For example, if
there are 100 index entries in an index record, they are grouped into 10 sections of
10 entries each. (The number of sections does not change, even though the number
of index entries increases as free control intervals get used.)
0
Last
Section
3rd
Section
2nd
Section
1st
Section
Index
Entries
Index
Entries
Index
Entries
Index
Entries
Displacement from beginning of this section to
the beginning of the next section.
Figure 39. Format of the Index Entry Portion of an Index Record
The sections, and the entries within a section, are arranged from right to left.
IXHLEO in the header gives the displacement from the beginning of the index
record to the control information in the leftmost index entry. IXHSEO gives the
displacement to the control information in the leftmost index entry in the
rightmost section. You calculate the displacement of the control information of the
rightmost index entry in the index record (the entry with the lowest key) by
subtracting IXHFLPLN from IXHLL in the header (the length of the control
information in an index entry from the length of the record).
Each section is preceded by a 2-byte field that gives the displacement from the
control information in the leftmost index entry in the section to the control
information in the leftmost index entry in the next section (to the left). The last
(leftmost) section's 2-byte field contains 0s.
Figure 40 gives the format of an index entry.
Control information
Compressed key
F
L
F-Number of characters eliminated from the front
L-Number of characters left in key after compression
P-Vertical pointer
Figure 40. Format of an Index Record
296
z/OS DFSMS Using Data Sets
P
Processing Indexes of Key-Sequenced Data Sets
Key Compression
Index entries are variable in length within an index record because VSAM
compresses keys. That is, it eliminates redundant or unnecessary characters from
the front and back of a key to save space. The number of characters that can be
eliminated from a key depends on the relationship between that key and the
preceding and following keys. Note: VSAM index key compression is not related
to MVS data compression or compressed format data sets.
For front compression, VSAM compares a key in the index with the preceding key
in the index and eliminates from the key those leading characters that are the same
as the leading characters in the preceding key. For example, if key 12356 follows
key 12345, the characters 123 are eliminated from 12356 because they are equal to
the first three characters in the preceding key. The lowest key in an index record
has no front compression; there is no preceding key in the index record.
There is an exception for the highest key in a section. For front compression, it is
compared with the highest key in the preceding section, rather than with the
preceding key. The highest key in the rightmost section of an index record has no
front compression; there is no preceding section in the index record.
What is called “rear compression” of keys is actually the process of eliminating the
insignificant values from the end of a key in the index. The values eliminated can
be represented by X'FF'. VSAM compares a key in the index with the following key
in the data and eliminates from the key those characters to the right of the first
character that are unequal to the corresponding character in the following key. For
example, if the key 12345 (in the index) precedes key 12356 (in the data), the
character 5 is eliminated from 12345 because the fourth character in the two keys is
the first unequal pair.
The first of the control information fields gives the number of characters
eliminated from the front of the key, and the second field gives the number of
characters that remain. When the sum of these two numbers is subtracted from the
full key length (available from the catalog when the index is opened), the result is
the number of characters eliminated from the rear. The third field indicates the
control interval that contains a record with the key.
The example in Figure 41 on page 299 gives a list of full keys and shows the
contents of the index entries corresponding to the keys that get into the index (the
highest key in each data control interval). A sequence-set record is assumed, with
vertical pointers 1 byte long. The index entries shown in the figure from top to
bottom are arranged from right to left in the assumed index record.In Figure 41 on
page 299, the first column (Full Key of Data Record) has all the keys of the data
records in the data control intervals (CIs). The second column (Index Entry) shows
the contents of the entries in a sequence-set index CI, each entry in the index CI
representing one data CI. The compressed keys under Index Entry are generated
by front and rear compressions. The front compression is done by comparing the
highest key of a current data CI against the highest key of its preceding data CI;
the rear compression by comparing a high key with the low key of its next data
CI.
In Figure 41 on page 299, data CI high key 12345 has no front compression because
it is the first key in the index record. Data CI high key 12356 has no rear
compression because, in the comparison between 12356 and 12357 (the low key of
the next CI), there are no characters following 6, which is the first character that is
unequal to the corresponding character in the following key. For high key 12359,
Chapter 19. Processing Indexes of Key-Sequenced Data Sets
297
Processing Indexes of Key-Sequenced Data Sets
comparing it against high key 12356 results in front compression of 1235;
comparing with 12370 results in rear compression of 9.
You can always figure out what characters have been eliminated from the front of
a key. You cannot figure out the ones eliminated from the rear. Rear compression,
in effect, establishes the key in the entry as a boundary value instead of an exact
high key. That is, an entry does not give the exact value of the highest key in a
control interval, but gives only enough of the key to distinguish it from the lowest
key in the next control interval. For example, in Figure 41 on page 299 the last
three index keys are 12401, 124, and 134 after rear compression. Data records with
key field between:
v 12402 and 124FF are associated with index key 124.
v 12500 and 134FF are associated with index key 134.
If the last data record in a control interval is deleted, and if the control interval
does not contain the high key for the control area, then the space is reclaimed as
free space. Space reclamation can be suppressed by setting the RPLNOCIR bit,
which has an equated value of X'20', at offset 43 into the RPL.
The last index entry in an index level indicates the highest possible key value. The
convention for expressing this value is to give none of its characters and indicate
that no characters have been eliminated from the front. The last index entry in the
last record in the sequence set looks like this:
In a search, the two 0s signify the highest possible key value in this way:
v The fact that 0 characters have been eliminated from the front implies that the
first character in the key is greater than the first character in the preceding key.
v A length of 0 indicates that no character comparison is required to determine if
the search is successful. That is, when a search finds the last index entry, a hit
has been made.
298
z/OS DFSMS Using Data Sets
Processing Indexes of Key-Sequenced Data Sets
Full Key of
Data Record
Index Entry
Eliminated
From Front
K
12345
1
F
L
P
0
2
3 4
0
4
K
F
3
L
2
P
1
Eliminated
From Rear
None
5
123
none
1235
9
12
none
124
21
1
56
12350
12353
12354
12356
6
5
12357
12358
12359
F
L
P
4
0
2
12370
12373
12380
12385
12390
12401
K
4 0
1
F
3
P
4
F
2
L
3
P
3
12405
12410
12417
L
0
12421
12600
K
13200
13456
3
4
F
L
P
1
2
5
Note: 'Full keys' are the full keys of the data records that reside in data CIs where highest
possible keys are compressed in the corresponding index entries.
Legend:
K-Characters left in key after compression
F-Number of characters eliminated from the front
L-Number of characters left in key after compression
P-Vertical pointer
Figure 41. Example of Key Compression
Index Update Following a Control Interval Split
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.
Figure 42 on page 300 shows how the control interval is split and the index is
updated when a record with a key of 12 is inserted in the control area shown in
Figure 36 on page 291.
Chapter 19. Processing Indexes of Key-Sequenced Data Sets
299
Processing Indexes of Key-Sequenced Data Sets
Index
CI
14
19
d
c
25
Data CI2
Data CI1
11
12
FS
Control
Info
20
25
Data CI3
Control
Info
a
15
18
FS
Control
Info
b
Figure 42. Control Interval Split and Index Update
1. A control interval split occurs in data control interval 1, where a record with
the key of 12 must be inserted.
2. Half the records in data control interval 1 are moved by VSAM to the free
space control interval (data control interval 3).
3. An index entry is inserted in key sequence to point to data control interval 3,
that now contains data records moved from data control interval 1.
4. A new index entry is created for data control interval 1, because after the
control interval split, the highest possible key is 14. Because data control
interval 3 now contains data, the pointer to this control interval is removed
from the free list and associated with the new key entry in the index. Note that
key values in the index are in proper ascending sequence, but the data control
intervals are no longer in physical sequence.
Index Entries for a Spanned Record
In a key-sequenced data set, there is an index entry for each control interval that
contains a segment of a spanned record. All the index entries for a spanned record
are grouped together in the same section. They are ordered from right to left
according to the sequence of segments (first, second, third, and so on).
Only the last (leftmost) index entry for a spanned record contains the key of the
record. The key is compressed according to the rules described above. All the other
index entries for the record look like this:
F
L
P
Y
0
X
Where Y is a binary number equal to the length of the key
(Y indicates that the entire key has been eliminated from the front).
L indicates that 0 characters remain.
X identifies the control interval that contains the segment.
300
z/OS DFSMS Using Data Sets
Part 3. Non-VSAM Access to Data Sets and UNIX Files
This topic provides the information of non-VSAM data sets and UNIX files.
© Copyright IBM Corp. 1987, 2017
301
302
z/OS DFSMS Using Data Sets
Chapter 20. Selecting Record Formats for Non-VSAM Data
Sets
This topic covers the following subtopics.
Topic
“Format Selection”
“Fixed-Length Record Formats” on page 304
“Variable-Length Record Formats” on page 306
“Undefined-Length Record Format” on page 312
“ISO/ANSI Tapes” on page 312
“Record Format—Device Type Considerations” on page 320
This topic discusses record formats of non-VSAM data sets and device type
considerations. Records are stored in one of four formats:
v Fixed length (RECFM=F)
v Variable length (RECFM=V)
v ASCII variable length (RECFM=D)
v Undefined length (RECFM=U)
For information about disk format, see “Direct Access Storage Device (DASD)
Volumes” on page 8.
Format Selection
Before selecting a record format, you should consider:
v The data type (for example, EBCDIC) your program can receive and the type of
output it can produce
v The I/O devices that contain the data set
v The access method you use to read and write the records
v Whether the records can be blocked
Blocking is the process of grouping records into blocks before they are written on a
volume. A block consists of one or more logical records. Each block is written
between consecutive interblock gaps. Blocking conserves storage space on a
volume by reducing the number of interblock gaps in the data set, and increases
processing efficiency by reducing the number of I/O operations required to process
the data set.
If you do not specify a block size, the system generally determines a block size
that is optimum for the device to which your data set is allocated. See
“System-Determined Block Size” on page 338.
You select your record format in the data control block (DCB) using the options in
the DCB macro, the DD statement, dynamic allocation, automatic class selection
routines or the data set label. Before executing your program, you must supply the
operating system with the record format (RECFM) and device-dependent
information in data class, a DCB macro, a DD statement, or a data set label. A
© Copyright IBM Corp. 1987, 2017
303
Selecting Record Formats for Non-VSAM Data Sets
complete description of the DD statement keywords and a glossary of DCB
subparameters is contained in z/OS MVS JCL Reference.
All record formats except U can be blocked. Variable-length records can be
spanned (RECFM=DS or VS). Spanned records can span more than one block.
Fixed-length records (RECFM=F or FB) can be specified as standard (RECFM=FS or
FBS). Standard format means there are no short blocks or unfilled tracks within the
data set, except for the last block or track.
Fixed-Length Record Formats
The size of fixed-length (format-F or -FB) records, shown in Figure 43, is constant
for all records in the data set.
Blocked
records
Block
Block
Record A Record B Record C
Record D Record E Record F
Record
a
b
Data
Optional table reference
character: 1 byte
Optional control
character: 1 byte
Block
Unblocked
Record A
records
Block
Block
Record B
Record C
Record D
Figure 43. Fixed-Length Records
The records can be blocked or unblocked. If the data set contains unblocked
format-F records, one record constitutes one block. If the data set contains blocked
format-F records, the number of records within a block typically is constant for
every block in the data set. The data set can contain truncated (short) blocks. The
system automatically checks the length (except for card readers) on blocked or
unblocked format-F records. Allowances are made for truncated blocks.
Format-F records can be used in any type of data set.
The optional control character (a), used for stacker selection or carriage control, can
be included in each record to be printed or punched. The optional table reference
character (b) is a code to select the font to print the record on a page printer. See
“Using Optional Control Characters” on page 321 and “Table Reference Character”
on page 323.
304
z/OS DFSMS Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
Standard Format
During creation of a sequential data set (to be processed by BSAM or QSAM) with
fixed-length records, the RECFM subparameter of the DCB macro can specify a
standard format (RECFM=FS or FBS). A sequential data set with standard format
records (format-FS or -FBS) sometimes can be read more efficiently than a data set
with format-F or -FB records. This efficiency is possible because the system is able
to determine the address of each record to be read, because each track contains the
same number of blocks.
A standard-format data set must conform to the following specifications:
v All records in the data set are format-F records.
v No block except the last block is truncated. (With BSAM, you must ensure that
this specification is met.) If the last block is truncated, the system writes it where
a full size block would have been written.
v Every track except the last contains the same number of blocks.
v Every track except the last is filled as determined by the track capacity formula
established for the device.
v The data set organization is physically sequential. You cannot use format-FS for
a PDS or PDSE.
Restrictions
If the last block is truncated, you should never extend a standard-format data set
by coding:
v EXTEND or OUTINX on the OPEN macro
v OUTPUT, OUTIN, or INOUT on the OPEN macro with DISP=MOD on the
allocation
v CLOSE LEAVE, TYPE=T, followed by a WRITE
v POINT to after the last block, followed by a WRITE
v CNTRL on tape to after the last block, followed by a WRITE
If the data set becomes extended, it contains a truncated block that is not the last
block. Reading an extended data set with this condition results in a premature
end-of-data condition when the truncated block is read, giving the appearance that
the blocks following this truncated block do not exist.
Standard-format data sets that end in a short block on magnetic tape should not be
read backward because the data set would begin with a truncated block.
A format-F data set will not meet the requirements of a standard-format data set if
you do the following:
v Extend a fixed-length, blocked standard data set when the last block was
truncated.
v Use the POINT macro to prevent BSAM from filling a track other than the last
one. Do not skip a track when writing to a data set.
Standard format should not be used to read records from a data set that was
created using a record format other than standard, because other record formats
might not create the precise format required by standard.
If the characteristics of your data set are altered from the specifications described
previously at any time, the data set should no longer be processed with the
standard format specification.
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
305
Selecting Record Formats for Non-VSAM Data Sets
Variable-Length Record Formats
In a variable-length record data set, each record or record segment can have a
different length. Variable-length records can be used with all types of data sets. The
variable-length record formats are format-V and format-D. They can also be
spanned format (-VS or -DS), blocked format (-VB or -DB), or both format (-VBS
and -DBS). Format-D, -DS, and -DBS records are used for ISO/ANSI tape data sets.
Format-V Records
Figure 44 shows blocked and unblocked variable-length (format-V) records without
spanning. A block in a data set containing unblocked records is in the same format
as a block in a data set containing blocked records. The only difference is that with
blocked records each block can contain multiple records.
Block
Block
LL
LL
BDW
BDW
Record B Record C
Record D Record E Record F
Blocked records
ll
Data
RDW
ll
00
a
b
Optional table reference
character
Optional control character
Reserved: 2 bytes
Record length: 2 bytes
Block
Block
Record
BDW
Record
BDW
Non-extended BDW (block descriptor word)
0
BDW
Figure 44. Nonspanned, Format-V Records
z/OS DFSMS Using Data Sets
Record C
Extended BDW
1
LL 00
Reserved: 2 bytes
Block length: 15 bits
Bit 0 is 0
306
Record B
LLLL
Block length: 31 bits
Bit 0 is 1
Unblocked records
Selecting Record Formats for Non-VSAM Data Sets
The system uses the record or segment length information in blocking and
unblocking. The first four bytes of each record, record segment, or block make up a
descriptor word containing control information. You must allow for these
additional 4 bytes in both your input and output buffers.
Block Descriptor Word (BDW)
A variable-length block consists of a block descriptor word (BDW) followed by one
or more logical records or record segments. The block descriptor word is a 4-byte
field that describes the block. It specifies the 4 byte block length for the BDW plus
the total length of all records or segments within the block.
There are two types of BDW. If bit 0 is zero, it is a nonextended BDW. Bits 1-15
contain the block length. Bits 16-31 are zeroes. The block length can be from 8 to
32 760 bytes. All access methods and device types support nonextended BDWs.
If bit 0 of the BDW is one, the BDW is an extended BDW and BDW bits 1-31
contain the block length. Extended BDWs are currently supported only on tape.
When writing, BSAM applications provide the BDW; for QSAM, the access method
creates the BDW. BSAM accepts an extended BDW if large block interface (LBI)
processing has been selected (DCBESLBI in the DCBE control block is set on) and
the output device is a magnetic tape. If an extended BDW is encountered and you
are not using LBI, or the output device is not magnetic tape, an ABEND 002 is
issued. IBM recommends that the BSAM user not provide an extended BDW
unless the block length is greater than 32 760 because an extended BDW would
prevent SAM reading the data on lower-level DFSMS systems. Other programs
that read the data set may also not support an extended BDW. QSAM creates
extended BDWs only for blocks whose length is greater than 32 760, otherwise the
nonextended format is used. When you read with either BSAM or QSAM, the
access method interrogates the BDW to determine its format.
See “Large Block Interface (LBI)” on page 337.
Record Descriptor Word (RDW)
A variable-length logical record consists of a record descriptor word (RDW)
followed by the data. The record descriptor word is a 4 byte field describing the
record. The first 2 bytes contain the length (LL) of the logical record (including the
4 byte RDW). The length can be from 4 to 32 760. All bits of the third and fourth
bytes must be 0, because other values are used for spanned records.
For output, you must provide the RDW, except in data mode for spanned records
(described under “Controlling Buffers” on page 359). For output in data mode, you
must provide the total data length in the physical record length field (DCBPRECL)
of the DCB.
For input, the operating system provides the RDW, except in data mode. In data
mode, the system passes the record length to your program in the logical record
length field (DCBLRECL) of the DCB.
The optional control character (a) can be specified as the fifth byte of each record.
The first byte of data is a table reference character (b) if OPTCD=J has been
specified. The RDW, the optional control character, and the optional table reference
character are not punched or printed.
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
307
Selecting Record Formats for Non-VSAM Data Sets
Spanned Format-VS Records (Sequential Access Method)
Figure 45 shows how the spanning feature of the queued and basic sequential
access methods lets you create and process variable-length logical records that are
larger than one physical block. It also lets you pack blocks with variable-length
records by splitting the records into segments so that they can be written into more
than one block.
Block
LL
BDW
Last segment First segment
of logical
of logical
record B
record A
Intermediate
segment of
logical record B
BDW
ll
First
segment
of logical
record
ll
ab
Last segment First segment
of logical
of logical
record C
record B
ll
ll
Data
SDW
BDW
Data
SDW
Intermediate
segment
of logical
record
Last
segment
of logical
record
ll
Optional table
reference character
Optional control character
Reserved: 1 byte
Segment control code: 1 byte
Segment length: 2 bytes
SDW
Data
ll
Segment
control code
Segment
control code
ll
Data portion of logical record B
RDW
Logical record
(in user's work area)
ll
ab
Rest of data
portion of
first segment
Data portion
Data portion
of intermediate
of last
segment
segment
Optional table reference character
Optional control character
Reserved: 2 bytes
Record length: 2 bytes
Figure 45. Spanned Format-VS Records (Sequential Access Method)
The format of the BDW is as described in Figure 44 on page 306.
When spanning is specified for blocked records, QSAM attempts to fill all blocks.
For unblocked records, a record larger than the block size is split and written in
two or more blocks. If your program is not using the large block interface, each
block contains only one record or record segment. Thus, the block size can be set
to the best block size for a given device or processing situation. It is not restricted
by the maximum record length of a data set. A record can, therefore, span several
blocks, and can even span volumes.
308
z/OS DFSMS Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
Spanned record blocks can have extended BDWs. See “Block Descriptor Word
(BDW)” on page 307.
When you use unit record devices with spanned records, the system assumes that
it is processing unblocked records and that the block size must be equivalent to the
length of one print line or one card. The system writes records that span blocks
one segment at a time.
Spanned variable-length records cannot be specified for a SYSIN data set.
Restrictions in Processing Spanned Records with QSAM
When spanned records span volumes, reading errors could occur when using
QSAM, if a volume that begins with a middle or last segment is mounted first or if
an FEOV macro is issued followed by another GET. QSAM cannot begin reading
from the middle of the record. The errors include duplicate records, program
checks in the user's program, and nonvalid input from the spanned record data set.
A logical record spanning three or more volumes cannot be processed in update
mode (as described in “Controlling Buffers” on page 359) by QSAM. For blocked
records, a block can contain a combination of records and record segments, but not
multiple segments of the same record unless the program is using LBI. When
records are added to or deleted from a data set, or when the data set is processed
again with different block size or record size parameters, the record segmenting
changes.
When QSAM opens a spanned record data set in UPDAT mode, it uses the logical
record interface (LRI) to assemble all segments of the spanned record into a single,
logical input record, and to disassemble a single logical record into multiple
segments for output data blocks. A record area must be provided by using the
BUILDRCD macro or by specifying BFTEK=A in the DCB.
When you specify BFTEK=A, the open routine provides a record area equal to the
LRECL specification, which should be the maximum length in bytes. (An LRECL=0
is not valid.)
Segment Descriptor Word
Each record segment consists of a segment descriptor word (SDW) followed by the
data. The segment descriptor word, similar to the record descriptor word, is a 4
byte field that describes the segment. The first 2 bytes contain the length (LL) of
the segment, including the 4 byte SDW. The length can be from 5 to 32 756 bytes.
The third byte of the SDW contains the segment control code that specifies the
relative position of the segment in the logical record. The segment control code is
in the rightmost 2 bits of the byte. The segment control codes are shown in
Table 37.
Table 37. Segment control codes
Binary Code
Relative Position of Segment
00
Complete logical record
01
First segment of a multisegment record
10
Last segment of a multisegment record
11
Segment of a multisegment record other than the first or last segment
The remaining bits of the third byte and all of the fourth byte are reserved for
possible future system use and must be 0.
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
309
Selecting Record Formats for Non-VSAM Data Sets
The SDW for the first segment replaces the RDW for the record after the record is
segmented. You or the operating system can build the SDW, depending on which
access method is used.
v In the basic sequential access method, you must create and interpret the spanned
records yourself.
v In the queued sequential access method move mode, complete logical records,
including the RDW, are processed in your work area. GET consolidates segments
into logical records and creates the RDW. PUT forms segments as required and
creates the SDW for each segment.
Data mode is similar to move mode, but allows reference only to the data
portion of the logical record (that is, to one segment) in your work area. The
logical record length is passed to you through the DCBLRECL field of the data
control block.
In locate mode, both GET and PUT process one segment at a time. However, in
locate mode, if you provide your own record area using the BUILDRCD macro,
or if you ask the system to provide a record area by specifying BFTEK=A, then
GET, PUT, and PUTX process one logical record at a time.
Records Longer than 32 756 Bytes
A spanned record (RECFM=VS or RECFM=VBS) can contain logical records of any
length, because it can contain any number of segments. While each segment must
be less than 32 756, the segments concatenated together into the logical record can
be longer than 32 756 bytes. Here are some techniques for processing records
longer than 32 756 bytes.
1. If you use QSAM with BFTEK=A, but do not use the BUILDRCD macro to
create the assembly area, you can create a record of up to 32 756 bytes long.
2. If you use QSAM locate mode and specify LRECL=X in your DCB macro, you
can process logical records that exceed 32 756 bytes. Instead of QSAM
assembling the record segments into one logical record, QSAM will give you
one segment at a time. Then, you must concatenate the segments together into
one logical record.
3. If you use BSAM and specify LRECL=X in your DCB macro, you can process
logical records that exceed 32 756 bytes. You need to concatenate the segments
together into one logical record.
You cannot use BFTEK=A or the BUILDRCD macro when the logical records
exceed 32 756 bytes.
Null Segments
A 1 in bit position 0 of the SDW indicates a null segment. A null segment means
that there are no more segments in the block. Bits 1-7 of the SDW and the
remainder of the block must be binary zeros. A null segment is not an
end-of-logical-record delimiter.
Null segments are not recreated in PDSEs. For more information, see “Processing
PDSE Records” on page 460
Spanned Format-V Records (Basic Direct Access Method)
The spanning feature of BDAM lets you create and process variable-length
unblocked logical records that span tracks. The feature also lets you pack tracks
with variable-length records by splitting the records into segments. Figure 46 on
page 311 shows how these segments can then be written onto more than one track.
310
z/OS DFSMS Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
Track 1
Track 2
Track 3
Block
BDW
LL*
00
LL
First segment
of logical
record
LL*
00
Intermediate
segment of
logical record
LL*
Last segment
of logical
record
00
Block
length:
2 bytes
ll
Reserved:
2 bytes
SDW
First
segment
of logical
record
ll
Data
SDW
Intermediate
segment
of logical
record
ll
ll
Data
SDW
Last
segment
of logical
record
ll
ll
Segment
control
code
Reserved: 1 byte
Segment control code: 1 byte
Segment length: 2 bytes
Data
Segment
control
code
LL
Data portion of logical record B
BDW
Logical record
(in user's work area) LL
00
Data portion
of first
segment
Data portion
of intermediate
segment
Data portion
of last
segment
Reserved: 2 bytes
Block length: 2 bytes
LL* = maximum block size for track
Figure 46. Spanned Format-V Records for Direct Data Sets
When you specify spanned, unblocked record format for the basic direct access
method, and when a complete logical record cannot fit on the track, the system
tries to fill the track with a record segment. Thus, the maximum record length of a
data set is not restricted by track capacity. Segmenting records permits a record to
span several tracks, with each segment of the record on a different track. However,
because the system does not permit a record to span volumes, all segments of a
logical record in a direct data set are on the same volume.
Recommendation: Do not use the basic direct access method (BDAM).
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
311
Selecting Record Formats for Non-VSAM Data Sets
Undefined-Length Record Format
Format-U permits processing of records that do not conform to the F- or V- format.
Figure 47 shows how each block is treated as a record; therefore, any unblocking
that is required must be performed by your program. The optional control
character can be used in the first byte of each record. Because the system does not
do length checking on format-U records, you can design your program to read less
than a complete block into virtual storage. However, for extended format data sets,
since the system writes maximum length records, you must provide an area at
least as large as the block size of the data set. With BSAM the system attempts to
read as much data as indicated by the current value of the BLKSIZE in the DCB or
DCBE. When you are reading an extended format data set, make sure that the DCB
or DCBE BLKSIZE field value is no more than the length of the area you are
reading into. If you supply a short area because you know the next block is short,
BSAM can overlay storage to the length limit set by the current BLKSIZE value.
Figure 47. Undefined-Length Records
For format-U records, you must specify the record length when issuing the WRITE,
PUT, or PUTX macro. No length checking is performed by the system, so no error
indication will be given if the specified length does not match the buffer size or
physical record size.
In update mode, you must issue a GET or READ macro before you issue a PUTX
or WRITE macro to a data set on a direct access storage device. If you change the
record length when issuing the PUTX or WRITE macro, the record will be padded
with zeros or truncated to match the length of the record received when the GET
or READ macro was issued. No error indication will be given.
ISO/ANSI Tapes
ISO/ANSI tape records are written in format-F, format-D, format-S, or format-U.
Character Data Conversion
Data management lets you convert from one character representation to another
when using ISO/ANSI tapes. Conversion occurs according to one of the following
techniques:
312
z/OS DFSMS Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
v Coded Character Set Identifier (CCSID) Conversion. CCSID conversion
provides data management conversion to convert records between one CCSID
which defines the character representation of the data in the records on tape to
another CCSID which defines the character representation of the data in the
records used by the application program. You can request that BSAM or QSAM
perform this type of conversion for ISO/ANSI V4 tapes by supplying a CCSID
in the CCSID parameter of a JOB statement, EXEC statement, or DD statement
as well as through dynamic allocation or TSO ALLOCATE. CCSIDs are ignored
if specified for other than ISO/ANSI V4 tapes.
The CCSID which describes the data residing on the tape is taken from (in order
of precedence):
1. The CCSID supplied on the DD statement, or dynamic allocation, or TSO
ALLOCATE.
2. The CCSID field stored in the tape label.
3. The default (to CCSID of 367 representing 7-bit ASCII) if a CCSID has been
supplied for the application program.
The CCSID that describes the data to use by the application program is taken
from (in order of precedence):
1. The CCSID supplied on the EXEC statement.
2. The CCSID supplied on the JOB statement.
3. The default (to CCSID of 500 representing International EBCDIC) if a CCSID
has been supplied for the tape data.
Data records can contain any character data as defined by the CCSID in which it
was created.
You can prevent access method conversion by supplying a special CCSID of
65535. In this case, data management transfers the data between the tape and the
application program without conversion.
See Appendix F, “Converting Character Sets,” on page 655 for a list of supported
CCSID combinations and “CCSID Decision Tables” on page 666 for a description
of CCSID processing rules.
Restrictions: The following restrictions apply when CCSID conversion is used:
– Only SBCS to SBCS or DBCS to DBCS is supported. For more information
about double byte character sets (DBCS), see Appendix B, “Using the
Double-Byte Character Set (DBCS),” on page 597.
– When converting from one CCSID to another, changes in length for data
records are not supported and will result in an error.
– All data management calls (OPEN, READ/WRITE, GET/PUT, CLOSE) must
be made in the original key of the task (TCBPKF). Key switching is not
supported and results in an error.
– All data management calls must be made in the task in which the DCB was
opened. Subtasking is not supported and will result in an error.
– Supervisor state callers are not supported for any data management calls and
results in an error.
v Default character conversion. Data management provides conversion from
ASCII to EBCDIC on input, and EBCDIC to ASCII for output in any of the
following cases (see “Tables for Default Conversion Codes” on page 670):
– ISO/ANSI V1 and V3 tapes
– ISO/ANSI V4 tapes without CCSID
– Unlabeled tapes with OPTCD=Q
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
313
Selecting Record Formats for Non-VSAM Data Sets
Related reading: For information about conversion routines that the system
supplies for this type of conversion, which converts to and from ASCII 7-bit
code, see z/OS DFSMS Using Magnetic Tapes.
When you convert from ASCII to EBCDIC, if a source character contains a bit in
the high-order position, the 7-bit conversion does not produce an equivalent
character. Instead, it produces a substitute character to note the loss in
conversion. This means, for example, that the system cannot record random
binary data (such as a dump) in ASCII 7-bit code.
The system cannot use CCSID conversion to read or write to an existing data set
that was created using default character conversion, unless DISP=OLD.
When you use CCSIDs, the closest equivalent to default character conversion is
between a CCSID of 367, which represents 7-bit ASCII, and a CCSID of 500,
which represents International EBCDIC.
Format-F Records
For ISO/ANSI tapes, format-F records are the same as described in “Fixed-Length
Record Formats” on page 304, except for control characters, block prefixes, and
circumflex characters.
Control Characters. Control characters, when present, must be ISO/ANSI control
characters. For more information about control characters see z/OS DFSMS Macro
Instructions for Data Sets.
Block Prefixes. Record blocks can contain block prefixes. The block prefix can vary
from 0 to 99 bytes, but the length must be constant for the data set being
processed. For blocked records, the block prefix precedes the first logical record.
For unblocked records, the block prefix precedes each logical record.
Using QSAM and BSAM to read records with block prefixes requires that you
specify the BUFOFF parameter in the DCB. When using QSAM, you do not have
access to the block prefix on input. When using BSAM, you must account for the
block prefix on both input and output. When using either QSAM or BSAM, you
must account for the length of the block prefix in the BLKSIZE and BUFL
parameters of the DCB.
When you use BSAM on output records, the operating system does not recognize a
block prefix. Therefore, if you want a block prefix, it must be part of your record.
Note that you cannot include block prefixes in QSAM output records.
The block prefix can only contain EBCDIC characters that correspond to the 128,
seven-bit ASCII characters. Thus, you must avoid using data types such as binary,
packed decimal, and floating point that cannot always be converted into ASCII.
This is also true when CCSIDs are used when writing to ISO/ANSI V4 tapes.
Related reading: For information about conversion routines supplied by the
system for this type of conversion, which converts to ASCII 7-bit code, see z/OS
DFSMS Using Magnetic Tapes.
Figure 48 on page 315 shows the format of fixed-length records for ISO/ANSI
tapes and where control characters and block prefixes are positioned if they exist.
314
z/OS DFSMS Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
Blocked
Records
Block
Block
Optional
block
prefix
Record A
Record B
Optional
block
prefix
Record C
Record D
Record E
Record F
Record
a
Unblocked
Records
Data
Optional control
character: 1 byte
Block
Block
Optional
block
Record A
prefix
Optional
block
Record B
prefix
Optional
block Record C
pPrefix
Block
Optional
block Record D
prefix
Figure 48. Fixed-Length Records for ISO/ANSI Tapes
Circumflex Characters. The GET routine tests each record (except the first) for all
circumflex characters (X'5E'). If a record completely filled with circumflex
characters is detected, QSAM ignores that record and the rest of the block. A
fixed-length record must not consist of only circumflex characters. This restriction
is necessary because circumflex characters are used to pad out a block of records
when fewer than the maximum number of records are included in a block, and the
block is not truncated.
Format-D Records
Format-D, format-DS, and format-DBS records are used for ISO/ANSI tape data
sets. ISO/ANSI records are the same as format-V records, with three exceptions:
v Block prefix
v Block size
v Control characters.
Block Prefix. A record block can contain a block prefix. To specify a block prefix,
code BUFOFF in the DCB macro. The block prefix can vary in length from 0 to 99
bytes, but its length must remain constant for all records in the data set being
processed. For blocked records, the block prefix precedes the RDW for the first or
only logical record in each block. For unblocked records, the block prefix precedes
the RDW for each logical record.
To specify that the block prefix is to be treated as a BDW by data management for
format-D or format-DS records on output, code BUFOFF=L as a DCB parameter.
Your block prefix must be 4 bytes long, and it must contain the length of the block,
including the block prefix. The maximum length of a format-D or format-DS,
BUFOFF=L block is 9999 because the length (stated in binary numbers by the user)
is converted to a 4 byte ASCII character decimal field on the ISO/ANSI tape when
the block is written. It is converted back to a 2 byte length field in binary followed
by two bytes of zeros when the block is read.
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
315
Selecting Record Formats for Non-VSAM Data Sets
If you use QSAM to write records, data management fills in the block prefix for
you. If you use BSAM to write records, you must fill in the block prefix yourself. If
you are using chained scheduling to read blocked DB or DBS records, you cannot
code BUFOFF=absolute expression in the DCB. Instead, BUFOFF=L is required,
because the access method needs binary RDWs and valid block lengths to unblock
the records.
When you use QSAM, you cannot read the block prefix into your record area on
input. When using BSAM, you must account for the block prefix on both input and
output. When using either QSAM or BSAM, you must account for the length of the
block prefix in the BLKSIZE and BUFL parameters.
When using QSAM to access DB or DBS records, and BUFOFF=0 is specified, the
value of BUFL, if specified, must be increased by 4. If BUFL is not specified, then
BLKSIZE must be increased by 4. This permits a 4 byte QSAM internal processing
area to be included when the system acquires the buffers. These 4 bytes do not
become part of the user's block.
When you use BSAM on output records, the operating system does not recognize
the block prefix. Therefore, if you want a block prefix, it must be part of your
record.
The block prefix can contain only EBCDIC characters that correspond to the 128,
seven-bit ASCII characters. Thus, you must avoid using data types (such as binary,
packed decimal, and floating point), that cannot always be converted into ASCII.
For DB and DBS records, the only time the block prefix can contain binary data is
when you have coded BUFOFF=L, which tells data management that the prefix is
a BDW. Unlike the block prefix, the RDW must always be binary. This is true
whether conversion or no conversion is specified with CCSID for Version 4 tapes.
Block Size. Version 3 tapes have a maximum block size of 2048. This limit can be
overridden by a label validation installation exit. For Version 4 tapes, the
maximum size is 32 760.
If you specify a maximum data set block size of 18 or greater when creating
variable-length blocks, then individual blocks can be shorter than 18 bytes. In those
cases data management pads each one to 18 bytes when the blocks are written
onto an ISO/ANSI tape. The padding character used is the ASCII circumflex
character, which is X'5E'.
Control Characters. Control characters, if present, must be ISO/ANSI control
characters. For more information about control characters see z/OS DFSMS Macro
Instructions for Data Sets.
Figure 49 on page 317 shows the format of nonspanned variable-length records for
ISO/ANSI tapes, where the record descriptor word (RDW) is located, and where
block prefixes and control characters must be placed when they are used.
316
z/OS DFSMS Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
Block
Blocked
records
Optional
block
prefix
Block
Optional
Record D Record E Record F
block
prefix
Record A Record B Record C
ll
RDW
ll
Data
a
Optional control character
Reserved: 2 bytes
Record length: 2 bytes
Block
Unblocked
records
Optional
block
prefix
Record C
Optional
block
prefix
Record D
Block
Optional
block
prefix
Record E
Figure 49. Nonspanned Format-D Records for ISO/ANSI Tapes As Seen by the Program
ISO/ANSI Format-DS and Format-DBS Records
For ISO/ANSI tapes, variable-length spanned records must be specified in the DCB
RECFM parameter as DCB RECFM=DS or DBS. Format-DS and format-DBS
records are similar to format-VS or format-VBS records. The exceptions are
described in “Converting the Segment Descriptor Word” on page 318 and
“Processing Records Longer than 32 760 Bytes” on page 319.
Figure 50 on page 318 shows what spanned variable-length records for ISO/ANSI
tapes look like.
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
317
Selecting Record Formats for Non-VSAM Data Sets
Block
Block
Blocked
First
Last
records Optional segment segment
block
of logical of logical
prefix
record A record B
Optional
block
prefix
Intermediate
segment
of logical
record B
First
segment
of logical
record B
ll
First
Last
Optional
segment segment
block
of logical of logical
prefix
record B record C
l l +1
l l +1
SDW
Block
Data
l l +1
Data
SDW
Intermediate
segment
C0
l l C0
of logical
record B
Reserved: 1 byte
Segment position indicator: 1 byte
Segment length: 2 bytes
Field expansion byte
SDW
Last
segment
of logical
record B
Data
l l C0
ll
RDW (binary)
Logical record
(in LRI record area)
ll
00
Complete logical record data
Last
First segment Intermediate
segment
of
segment
of
of logical
logical
logical
record B
record B
record B
Reserved: 2 bytes (must be zero)
Record length: 2 bytes
lll
RDW (binary)
XLRI format
logical record
(in XLRI record area)
0
lll
Complete logical record data
Last
First segment Intermediate
segment of segment of
of logical
logical
logical
record B
record B
record B
Record length: 3 bytes or 16776192
Reserved: 2 bytes (must be zero)
Figure 50. Spanned Variable-Length (Format-DS) Records for ISO/ANSI Tapes As Seen by the Program
Figure 50 shows the segment descriptor word (SDW), where the record descriptor
word (RDW) is located, and where block prefixes must be placed when they are
used. If you are not using IBM access methods see z/OS DFSMS Macro Instructions
for Data Sets for a description of ISO/ANSI record control words and segment
control words.
Converting the Segment Descriptor Word
There is an additional byte preceding each SDW for DS/DBS records. This
additional byte is required for conversion of the SDW from IBM to ISO/ANSI
format, because the ISO/ANSI SDW (called a segment control word) is five bytes
long. Otherwise, the SDW for DS/DBS records is the same as the SDW for VS/VBS
records. The SDW LL count excludes the additional byte.
318
z/OS DFSMS Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
QSAM or BSAM convert between ISO/ANSI segment control word (SCW) format
and IBM segment descriptor word (SDW) format. On output, the binary SDW LL
value (provided by you when using BSAM and by the access method when using
QSAM), is increased by 1 for the extra byte and converted to four ASCII numeric
characters. Because the binary SDW LL value will result in four numeric
characters, the binary value must not be greater than 9998. The fifth character is
used to designate which segment type (complete logical record, first segment, last
segment, or intermediate segment) is being processed.
On input, the four numeric characters designating the segment length are
converted to two binary SDW LL bytes and decreased by one for the unused byte.
The ISO/ANSI segment control character maps to the DS/DBS SDW control flags.
This conversion leaves an unused byte at the beginning of each SDW. It is set to
X'00'. See z/OS DFSMS Macro Instructions for Data Sets for more details on this
process.
On the tape, the SDW bytes are ASCII numeric characters even if the other bytes in
the record are not ASCII.
Processing Records Longer than 32 760 Bytes
A spanned record (RECFM=VS or RECFM=VBS) can contain logical records of any
length, because it can contain any number of segments. While each segment must
be less than 32 760, the segments concatenated together into the logical record can
be longer than 32 760 bytes. A variable-length ISO/ANSI tape record (RECFM=D)
can be longer than 32 760 bytes. Some techniques for processing records longer
than 32 760 bytes follow.
Processing techniques for Format-D, Format-DS or Format-DBS Records
(ISO/ANSI tapes):
v If you use QSAM or BSAM and specify LRECL=X, you can process records
longer than 32 760 bytes for ISO/ANSI tapes. Note that the maximum block
length for ISO/ANSI tapes is 2048.
v If you use QSAM with XLRI and specify LRECL=nnnnnK or 0K, you can process
records longer than 32 760 bytes for variable-length, spanned ISO/ANSI tapes.
DS/DBS records with a record length of over 32 760 bytes can be processed using
XLRI. (XLRI is supported only in QSAM locate mode for ISO/ANSI tapes.) Using
the LRECL=X for ISO/ANSI causes an 013-D8 ABEND.
To use XLRI, specify LRECL=0K or LRECL=nK in the DCB macro. Specifying
DCBLRECL with the K suffix sets the DCBBFTK bit that indicates that LRECL is
coded in K units and that the DCB is to be processed in XLRI mode.
LRECL=0K in the DCB macro specifies that the LRECL value will come from the
file label or JCL. When LRECL is from the label, the file must be opened as an
input file. The label (HDR2) value for LRECL will be converted to kilobytes and
rounded up when XLRI is in effect. When the ISO/ANSI label value for LRECL is
00 000 to show that the maximum record length can be greater than 99 999, you
must use LRECL=nK in the JCL or in the DCB to specify the maximum record
length.
You can express the LRECL value in JCL in absolute form or with the K notation.
When the DCB specifies XLRI, the system converts absolute values to kilobytes by
rounding up to an integral multiple of 1024. Absolute values are permissible only
from 5 to 32 760.
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
319
Selecting Record Formats for Non-VSAM Data Sets
To show the record area size in the DD statement, code LRECL=nK, or specify a
data class that has the LRECL attribute you need. The value nK can range from 1K
to 16 383K (expressed in 1024 byte multiples). However, depending on the buffer
space available, the value you can specify in most systems will be much smaller
than 16 383K bytes. This value is used to determine the size of the record area
required to contain the largest logical record of the spanned format file.
When you use XLRI, the exact LRECL size is communicated in the three low-order
bytes of the RDW in the record area. This special RDW format exists only in the
record area to communicate the length of the logical record (including the 4 byte
RDW) to be written or read. (See the XLRI format of the RDW in Figure 50 on
page 318.) DCB LRECL shows the 1024 multiple size of the record area (rounded
up to the next nearest kilobyte). The normal DS/DBS SDW format is used at all
other times before conversion.
Processing DS/DBS Tapes with QSAM
When using QSAM, the same application used to process VS/VBS tape files can be
used to process DS/DBS tape files. However, you must ensure that ISO/ANSI
requirements such as block size limitation, tape device, and restriction to EBCDIC
characters that correspond to the 128, seven-bit ASCII characters are met. The
SCW/SDW conversion and buffer positioning is handled by the GET/PUT
routines.
ISO/ANSI Version 4 tapes also permits special characters !*"%&'()+,-./:;<=>?_ and
numeric characters 0 - 9.
Processing DS/DBS Tapes with BSAM
When using BSAM to process a DS/DBS tape file, you must allow for an
additional byte at the beginning of each SDW. The SDW LL must exclude the
additional byte. On input, you must ignore the unused byte preceding each SDW.
On output, you must allocate the additional byte for each SDW.
Format-U Records
Data can only be in format-U for ISO/ANSI Version 1 tapes (ISO 1001-1969 and
ANSI X3.27-1969). These records can be used for input only. They are the same as
the format-U records described in “Undefined-Length Record Format” on page 312
except the control characters must be ISO/ANSI control characters, and block
prefixes can be used.
Format-U records are not supported for Version 3 or Version 4 ISO/ANSI tapes. An
attempt to process a format-U record from a Version 3 or Version 4 tape results in
entering the label validation installation exit.
Record Format—Device Type Considerations
This topic discusses which record formats are acceptable for specific devices.
DASD—Format-F, format-U, format-V
Magnetic tape—Format-D, format-F, format-U, format-V
Printer—Format-F, format-U, format-V
Card reader and punch—Format-F, format-U
SYSIN and SYSOUT—Format-F, format-U, format-V
For more information see Chapter 24, “Spooling and Scheduling Data Sets,” on
page 397.
320
z/OS DFSMS Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
The device-dependent (DEVD) parameter of the DCB macro specifies the type of
device where the data set's volume resides:
Value
DA
TA
PR
RD
PC
Device specified
Direct access storage devices
Magnetic tape
Printer
Card reader
Card punch
Note: Because the DEVD option affects only for the DCB macro expansion, you are
guaranteed the maximum device flexibility by letting it default to DEVD=DA and
not coding any device-dependent parameter.
Using Optional Control Characters
You can specify in the DD statement, the DCB macro, or the data set label that an
optional control character is part of each record in the data set. The 1 byte
character is used to show a carriage control function when the data set is printed
or a stacker bin when the data set is punched. Although the character is a part of
the record in storage, it is never printed or punched. Note that buffer areas must
be large enough to accommodate the character.
If the immediate destination of the data set is a device, such as a disk or tape,
which does not recognize the control character, the system assumes that the control
character is the first byte of the data portion of the record. If the destination of the
data set is a printer or punch and you have not indicated the presence of a control
character, the system regards the control character as the first byte of data. If the
destination of the data set is SYSOUT, the effect of the control characters is
determined at the ultimate destination of the data set. See z/OS DFSMS Macro
Instructions for Data Sets for a list of the control characters.
The presence of a control character is indicated by M or A in the RECFM field of
the data control block. M denotes machine code; A denotes American National
Standards Institute (ANSI) code. If either M or A is specified, the character must be
present in every record; the printer space (PRTSP) or stacker select (STACK) field
of the DCB is ignored.
The optional control character must be in the first byte of format-F and format-U
records, and in the fifth byte of format-V records and format-D records where
BUFOFF=L. If the immediate destination of the data set is a sequential DASD data
set or an IBM standard or ISO/ANSI standard labelled tape, OPEN records the
presence and type of control characters in the data set label. This is so that a
program that copies the data set to a print, punch, or SYSOUT data set can
propagate RECFM and therefore control the type of control character.
Using Direct Access Storage Devices (DASD)
Direct access storage devices accept records of format-F, format-V, or format-U. To
read or write the records with keys, you must specify the key length (KEYLEN). In
addition, the operating system has a standard track format for all direct access
volumes. See “Track Format” on page 9 for a complete description of track format.
Each track contains data information and certain control information, such as the
following information:
v The address of the track
v The address of each record
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
321
Selecting Record Formats for Non-VSAM Data Sets
v The length of each record
v Gaps between areas
Except for a PDSE or compressed format data set, the size of a block cannot exceed
what the system can write on a track. For PDSEs and compressed format data sets,
the access method simulates blocks, and you can select a value for BLKSIZE
without regard to the track length. A compressed format data set is a type of
extended format data set that is stored in a data format that can contain records
that the access method compressed.
Using Magnetic Tape
Format-F, format-V, format-D, and format-U records are acceptable for magnetic
tape. Format-V records are not acceptable on 7-track tape if the data conversion
feature is not available. ASCII records are not acceptable on 7-track tape.
When you create a tape data set with variable-length record format-V or format-D,
the control program pads any data block shorter than 18 bytes. For format-V
records, it pads to the right with binary zeros so that the data block length equals
18 bytes. For format-D (ASCII) records, the padding consists of ASCII circumflex
characters, which are equivalent to X'5E's.
Note that there is no minimum requirement for block size. However, in
nonreturn-to-zero-inverted mode, if a data check occurs on a magnetic tape device,
any record shorter than 12 bytes in a read operation will be treated as a noise
record and lost. No check for noise will be made unless a data check occurs.
Table 38 shows how the tape density (DEN) specifies the recording density in bits
per inch per track.
Table 38. Tape density (DEN) values
DEN
7-Track Tape
9-Track Tape
1
556 (NRZI)
N/A
2
800 (NRZI)
800 (NRZI)1
3
N/A
1600 (PE)2
4
N/A
6250 (GCR)3
Note:
1. NRZI is for nonreturn-to-zero-inverted mode.
2. PE is for phase encoded mode.
3. GCR is for group coded recording mode.
When DEN is not specified, the highest density capable by the unit will be used.
The DEN parameter has no effect on an 18-track or 36-track tape cartridge.
The track recording technique (TRTCH) for 7-track tape can be specified as follows.
322
Value
Meaning
C
Data conversion is to be used. Data conversion makes it possible to write 8 binary
bits of data on 7 tracks. Otherwise, only 6 bits of an 8-bit byte are recorded. The
length field of format-V records contains binary data and is not recorded correctly
without data conversion.
E
Even parity is to be used. If E is omitted, odd parity is assumed.
z/OS DFSMS Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
Value
Meaning
T
BCDIC to EBCDIC conversion is required.
The track recording technique (TRTCH) for magnetic tape drives with Improved
Data Recording Capability can be specified as:
Value
Meaning
COMP
Data is written in compacted format.
NOCOMP
Data is written in standard format.
The system programmer sets the 3480 default for COMP or NOCOMP in the
DEVSUPxx member of SYS1.PARMLIB.
Using a Printer
Records of a data set that you write directly or indirectly to a printer with BSAM
or QSAM can contain control characters. See “Using Optional Control Characters”
on page 321. Independently of whether the records contain control characters, they
can contain table reference characters.
Table Reference Character
The table reference character is a numeric character that corresponds to the order
in which you specified the character arrangement table names with the CHARS
keyword. The system uses the table reference character for selection of a character
arrangement table during printing.
A numeric table reference character (such as 0) selects the font to which the
character corresponds. The characters' number values represent the order in which
you specified the font names with the CHARS parameter. In addition to using
table reference characters that correspond to font names specified in the CHARS
parameter, you can code table reference characters that correspond to font names
specified in the PAGEDEF control structure. With CHARS, valid table reference
characters vary and range between 0 and 3. With PAGEDEF, they range between 0
and 126. The system treats table reference characters with values greater than the
limit as 0 (zero).
Indicate the presence of table reference characters by coding OPTCD=J in the DCB
macro, in the DD statement, or in the dynamic allocation call.
The system processes table reference characters on printers such as the IBM 3800
and IBM 3900 that support the CHARS and PAGEDEF parameters on the DD
statement. If the device is a printer that does not support CHARS or PAGEDEF, the
system discards the table reference character. This is true both for printers that are
allocated directly to the job step and for SYSOUT data sets. This makes it
unnecessary for your program to know whether the printer supports table
reference characters.
If the immediate destination of the data set for which OPTCD=J was specified is
DASD, the system treats the table reference characters as part of the data. The
system also records the OPTCD value in the data set label. If the immediate
destination is tape, the system does not record the OPTCD value in the data set
label.
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
323
Selecting Record Formats for Non-VSAM Data Sets
Record Formats
The printer can accept format-F, format-V, and format-U records. The system does
not print the first 4 bytes (record descriptor word or segment descriptor word) of
format-V records or record segments. For format-V records, at least 1 byte of data
must follow the record or segment descriptor word or the carriage control
character. The system does not print the carriage control character, if you specify it
in the RECFM parameter. The system does not position the printer to channel 1 for
the first record unless you use a carriage control character to specify this position.
Because each line of print corresponds to one record, the record length should not
exceed the length of one line on the printer. For variable-length spanned records,
each line corresponds to one record segment; block size should not exceed the
length of one line on the printer.
If you do not specify carriage control characters, you can specify printer spacing
(PRTSP) as 0, 1, 2, or 3. If you do not specify PRTSP, the system assumes 1.
For all QSAM RECFM=FB printer data sets, the system adjusts the block size in the
DCB to equal the logical record length. The system treats this data set as
RECFM=F. If the system builds the buffers for this data set, the BUFL parameter
determines the buffer length. If you do not specify the BUFL parameter, the system
uses the adjusted block size for the buffer length.
To reuse the DCB with a block size larger than the logical record length, you must
reset DCBBLKSI in the DCB and ensure that the buffers are large enough to
contain the largest block size. To ensure the buffer size, specify the BUFL
parameter before the first open of the data set. Or you can issue the FREEPOOL
macro after each CLOSE macro, so that the system builds a new buffer pool of the
correct size each time it opens the data set.
Using a Card Reader and Punch
Format-F and format-U records are acceptable to both the reader and the punch.
Format-V records are acceptable to the punch only. The device control character, if
specified in the RECFM parameter, is used to select the stacker; it is not punched.
For control character information, see “Using Optional Control Characters” on
page 321. The first 4 bytes (record descriptor word or segment descriptor word) of
format-V records or record segments are not punched. For format-V records, at
least 1 byte of data must follow the record or segment descriptor word or the
carriage control character.
A record size of 80 bytes is called EBCDIC mode (E) and a record size of 160 bytes
is called column binary mode (C). Each punched card corresponds to one physical
record. Therefore, you should restrict the maximum record size to EBCDIC mode
(80 bytes) or column binary mode (160 bytes). When column binary mode is used
for the card punch, BLKSIZE must be 160 unless you are using PUT. Then you can
specify BLKSIZE as 160 or a multiple of 160, and the system handles this as
described under “PUT—Write a Record” on page 371. Specify the read/punch
mode of operation (MODE) parameter as either card image column binary mode
(C) or EBCDIC mode (E). If this information is omitted, E is assumed. The stacker
selection parameter (STACK) can be specified as either 1 or 2 to show which bin is
to receive the card. If STACK is not specified, 1 is assumed.
For all QSAM RECFM=FB card punch data sets, the block size in the DCB is
adjusted by the system to equal the logical record length. This data set is treated as
RECFM=F. If the system builds the buffers for this data set, the buffer length is
324
z/OS DFSMS Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
determined by the BUFL parameter. If the BUFL parameter was not specified, the
adjusted block size is used for the buffer length.
If the DCB is to be reused with a block size larger than the logical record length,
you must reset DCBBLKSI in the DCB and ensure that the buffers are large enough
to contain the largest block size expected. You can ensure the buffer size by
specifying the BUFL parameter before the first time the data set is opened, or by
issuing the FREEPOOL macro after each CLOSE macro so the system will build a
new buffer pool of the correct size each time the data set is opened.
Punch error correction on the IBM 2540 Card Read Punch is not performed.
The IBM 3525 Card Punch accepts only format-F records for print and associated
data sets. Other record formats are permitted for the read data set, punch data set,
and interpret punch data set.
Using a Paper Tape Reader
The system no longer supports paper tape readers (IBM 2671).
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
325
326
z/OS DFSMS Using Data Sets
Chapter 21. Specifying and Initializing Data Control Blocks
This topic covers the following subtopics.
Topic
“Processing Sequential and Partitioned Data Sets” on page 328
“Using OPEN to Prepare a Data Set for Processing” on page 332
“Selecting Data Set Options” on page 336
“Changing and Testing the DCB and DCBE” on page 344
“Using CLOSE to End the Processing of a Data Set” on page 346
“Opening and Closing Data Sets: Considerations” on page 349
“Positioning Volumes” on page 351
“Managing SAM Buffer Space” on page 354
“Constructing a Buffer Pool” on page 355
“Controlling Buffers” on page 359
“Choosing Buffering Techniques and GET/PUT Processing Modes” on page 363
“Using Buffering Macros with Queued Access Method” on page 363
“Using Buffering Macros with Basic Access Method” on page 364
For each data set that you want to process, there must be a corresponding data
control block (DCB) and data definition (DD) statement or its dynamic allocation
equivalent. The characteristics of the data set and device-dependent information
can be supplied by either source. As specified in z/OS MVS JCL User's Guide and
z/OS MVS JCL Reference, the DD statement must also supply data set identification.
Your program, SMS, and exit routines can supply device characteristics, space
allocation requests, and related information. You establish the logical connection
between a DCB and a DD statement by specifying the name of the DD statement
in the DDNAME field of the DCB macro, or by completing the field yourself
before opening the data set.
You can process a non-VSAM data set to read, update, or add data by following
this procedure:
1. Create a data control block (DCB) to identify the data set to be opened. A DCB
is required for each data set and is created in a processing program by a DCB
macro.
When the program is run, the data set name and other important information
(such as data set disposition) are specified in a JCL statement called the data
definition (DD) statement, or in a call to dynamic allocation.
2. Optionally supply a data control block extension (DCBE). You can supply
options and test data set characteristics that the system stores in the DCBE.
3. Connect your program to the data set you want to process, using the OPEN
macro. The OPEN macro also positions volumes, writes data set labels and
allocates virtual storage. You can consider various buffering macros and
options.
4. Request access to the data set. For example, if you are using BSAM to process a
sequential data set, you can use the READ, WRITE, NOTE, or POINT macro.
© Copyright IBM Corp. 1987, 2017
327
Data Control Block (DCB)
5. Disconnect your program from the data set, using the CLOSE macro. The
CLOSE macro also positions volumes, creates data set labels, completes writing
queued output buffers, and frees virtual and auxiliary storage.
Primary sources of information to be placed in the data control block are a DCB
macro, data definition (DD) statement, a dynamic allocation SVC 99 parameter list,
a data class, and a data set label. A data class can be used to specify all of your
data set's attributes except data set name and disposition. Also, you can provide or
change some of the information during execution by storing the applicable data in
the appropriate field of the DCB or DCBE.
Processing Sequential and Partitioned Data Sets
Data management is designed to provide a balance between ease of use, migration
to new releases, coexistence with various levels of software and hardware, device
independence, exploitation of hardware features, and performance. Sometimes
these considerations can conflict. If your program exploits a particular model's
features to maximize performance, it might not take full advantage of newer
technology.
It is the intent of IBM that your programs that use documented programming
interfaces and work on the current level of the system will run at least equally well
on future levels of the system. However, IBM cannot guarantee that. Characteristics
such as certain reason codes that are documented only in z/OS DFSMSdfp Diagnosis
are not part of the intended programming interface. Examples of potential
problems are:
v Your program has a timing dependency such as a READ or WRITE macro
completes before another event. In some cases READ or WRITE is synchronous
with your program.
v Your program tests a field or control block that is not part of the intended
programming interface. An example is status indicators not documented in
Figure 116 on page 556.
v Your program relies on the system to enforce a restriction such as the maximum
value of something. For example, the maximum block size on DASD used to be
less than 32 760 bytes, the maximum NCP value for BSAM used to be 99 and
the maximum block size on tape used to be 32 760.
v New releases might introduce new return and reason codes for system functions.
For these reasons, the operating system has many options. It is not the intent of
IBM to require extensive education to use assembly language programming. The
purpose of this topic is to show how to read and write sequential data sets simply
in High Level Assembler while maximizing ease of use, migration potential, the
likelihood of coexistence, and device independence, while getting reasonable
performance.
You can use the examples in this topic to read or write sequential data sets and
partitioned members. These include ordinary disk data sets, extended format data
sets, compressed format data sets, PDS members, PDSE members, UNIX files,
UNIX FIFOs, spooled data sets (SYSIN and SYSOUT), real or VM simulated unit
record devices, TSO/E terminals, magnetic tapes, dummy data sets, and most
combinations of them in a concatenation.
Recommendations:
v Use QSAM because it is simpler. Use BSAM if you need to read or write
nonsequentially or you need more control of I/O completion. With BSAM you
328
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
can issue the NOTE, POINT, CNTRL, and BSP macros. These macros work
differently on various device classes. See “Record Format—Device Type
Considerations” on page 320 and “Achieving Device Independence” on page
412. Use BPAM if you need to access more than one member of a PDS or PDSE.
v Specify LRECL and RECFM in the DCB macro if your program's logic depends
on the record length and record format. If you omit either of them, your
program is able to handle more types of data but you have to write more code.
See Chapter 20, “Selecting Record Formats for Non-VSAM Data Sets,” on page
303.
v Use format-F or format-V records, and specify blocking (RECFM=FB or VB). This
allows longer blocks. Format-U generally is less efficient. Format-D works only
on certain types of tape.
v Omit the block size in the DCB macro. Code BLKSIZE=0 in the DCBE macro to
use the large block interface. When your program is reading, this allows it to
adapt to the appropriate block size for the data set. If the data set has no label
(such as for an unlabeled tape), the user can specify the block size in the DD
statement or dynamic allocation. For some data set types (such as PDSEs and
UNIX files) there is no real block size; the system simulates any valid block size
and there is a default.
When your program is writing and you omit DCB BLKSIZE and code DCBE
BLKSIZE=0, this enables the user to select the block size in the DD statement or
dynamic allocation. The user should only do this if there is a reason to do so,
such as a reading program cannot accept large blocks. If the user does not
specify a block size, OPEN selects one that is valid for the LRECL and RECFM
and is optimal for the device. Coding BLKSIZE=0 in the DCBE macro lets OPEN
select a block size that exceeds 32 760 bytes if large block interface (LBI)
processing is being used, thereby possibly shortening run time significantly. If
OPEN might select a block size that is larger than the reading programs can
handle, the user can code the BLKSZLIM keyword in the DD statement or the
dynamic allocation equivalent or rely on the block size limit in the data class or
in the DEVSUPxx PARMLIB member.
If you want to provide your own default for BLKSIZE and not let OPEN do it,
you can provide a DCB OPEN exit routine. See “DCB OPEN Exit” on page 573.
The installation OPEN exit might override your program's selection of DCB
parameters.
v Omit BUFL (buffer length) because it relies on the value of the sum of BLKSIZE
and KEYLEN and because it cannot exceed 32 760.
v Omit BUFNO (number of buffers) for QSAM, BSAM, and BPAM and NCP if you
use BSAM or BPAM. Let OPEN select QSAM BUFNO. This is particularly
important with striped data sets. The user can experiment with different values
for QSAM BUFNO to see if it can improve run time.
With BSAM and BPAM, code MULTSDN and MULTACC in the DCBE macro.
See “Improving Performance for Sequential Data Sets” on page 414.
With QSAM, BSAM, and BPAM this generally has no effect on the EXCP count
that is reported in SMF type 14, 15, 21, and 30 records. On DASD, this counts
blocks that are transferred and not the number of channel programs. This causes
the counts to be repeatable and not to depend on random factors in the system.
v Omit BUFOFF because it works only with tapes with ISO/ANSI standard labels
or no labels.
v If you choose BSAM or BPAM in 31-bit addressing mode, do not use the BUILD
or GETPOOL macro and do not request OPEN to build a buffer pool. If you
Chapter 21. Specifying and Initializing Data Control Blocks
329
Data Control Block (DCB)
code a nonzero BUFNO value, you are requesting OPEN to build a buffer pool.
Such a buffer pool resides below the line. Use your own code to allocate data
areas above the line.
v Code A or M for RECFM or code OPTCD=J only if your program logic requires
reading or writing control characters. These are not the EBCDIC or ASCII control
characters such as carriage return, line feed, or new page.
v Omit KEYLEN, DEVD, DEN, TRTCH, MODE, STACK, and FUNC because they
are device dependent. KEYLEN also makes the program run slower unless you
code KEYLEN=0. The user can code most of them in the DD statement if
needed.
v Omit BFALN, BFTEK, BUFCB, EROPT, and OPTCD because they probably are
not useful, except OPTCD=J. OPTCD=J specifies that the records contain table
reference characters. See “Table Reference Character” on page 323.
v LOCATE mode (MACRF=(GL,PL)) might be more efficient than move mode.
This depends on your program's logic. The move mode requires QSAM to move
the data an extra time.
v If your program runs with 31-bit addressing mode (AMODE), code
RMODE31=BUFF in the DCBE so that the QSAM buffers are above the 16 MB
line. A nonreentrant, RMODE 24 program (residing below the 16 MB line) is
simpler than a reentrant or RMODE 31 program because the DCB must reside
below the line in storage that is separate for each open data set.
v Code a SYNAD (I/O error) routine to prevent the 001 ABEND that the system
issues when a data set has an I/O error. In the SYNAD routine, issue the
SYNADAF macro, write the message, and terminate the program. This writes a
message and avoids a dump because the dump is not likely to be useful.
v Use extended-format data sets even if you are not using striping. They tend to
be more efficient, and OPEN provides a more efficient default for BUFNO.
Avoid writing many blocks that are shorter than the maximum for the data set
because short blocks waste disk space.
v If using dynamic allocation on non-VSAM data sets allocated by your
application program, and if the NON_VSAM_XTIOT=YES option of the
DEVSUPxx member of PARMLIB is in effect, code LOC=ANY on the DCBE
macro in your program. You should always set this option before issuing an
OPEN macro as the application program signifies that the allocation can have an
XTIOT that can reside above the line (instead of a TIOT entry), the UCB can
reside above the line and the DSAB can reside above the line. If any of these
three is true, then OPEN will set the two-byte DCBTIOT field to zero instead of
setting it to an offset in the TIOT, and the application program will be able to
OPEN and process the data set allocated dynamically with an associated XTIOT.
The XTIOT, NOCAPTURE, and DSAB above the line option of dynamic
allocation will give VSCR benefits because each XTIOT is above the line.
Additionally, with XTIOTs come an increase on the limit of non-VSAM data sets
that can be allocated and opened in an address space at one time. This limit for
non-VSAM, non-XTIOT, data sets is about 3200 single volume data sets.
Whereas, the non-VSAM, XTIOT limit is 100,000 data sets. A major problem
addressed by supporting more than 3200 single volume data sets is VSCR.
Note: If the application program sets the DCBE option before OPEN, but the
NON_VSAM_XTIOT option of the DEVSUPxx member of PARMLIB is not in
effect, then OPEN will issue an ABEND 113–4C and a message IEC142I.
Figure 51 on page 331 shows the simplest way to read a sequential data set.
330
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
OPEN
(INDCB,INPUT)
Open to read
LTR
R15,R15
Branch if DD name seems not
BNZ
...
to be defined
* Loop to read all the records
LOOP
GET
INDCB
Get address of a record in R1
...
Process a record
B
LOOP
Branch to read next record
* I/O error routine for INDCB
IOERROR SYNADAF ACSMETH=QSAM
Get message area
MVI
6(R1),X’80’
Set WTO MCS flags
MVC
8(16,R1),=CL16’I/O Error’ Put phrase on binary fields
MVC
128(4,R1),=X’00000020’ Set ROUTCDE=11 (WTP)
WTO
MF=(E,4(R1))
Write message to user
SYNADRLS
Release SYNADAF area, fall through
* The GET macro branches here after all records have been read
EOD
CLOSE (INDCB)
Close the data set
FREEPOOL INDCB
Free the QSAM buffer pool
...
Rest of program
INDCB
DCB
DDNAME=INPUT,MACRF=GL,RECFM=VB,
Must be format-V
DCBE=INDCBE
INDCBE DCBE
EODAD=EOD,SYNAD=IOERROR,BLKSIZE=0 Request LBI
*
Figure 51. Reading a Sequential Data Set
Figure 52 on page 332 is the same as Figure 51 but converted to be reentrant and
reside above the 16 MB line:
Chapter 21. Specifying and Initializing Data Control Blocks
331
Data Control Block (DCB)
COPYPROG CSECT
COPYPROG RMODE ANY
COPYPROG AMODE 31
GETMAIN R,LV=Arealen,LOC=(BELOW,64)
LR
R11,R1
USING MYAREA,R11
USING IHADCB,InDCB
USING DCBE,INDCBE
MVC
IHADCB(AreaLen),MYDCB
Copy DCB and DCBE
LA
R0,DCBE
Point DCB copy to
ST
R0,DCBDCBE
DCBE copy
OPEN
(IHADCB,),MF=(E,INOPEN) Open to read
LTR
R15,R15
Branch if DDname seems not
BNZ
...
to be defined
* Loop to read all the records
LOOP
GET
INDCB
Get address of a record in R1
...
Process a record
B
LOOP
Branch to read next record
* I/O error routine for INDCB
IOERROR SYNADAF ACSMETH=QSAM
Get message area
MVI
6(R1),X’80’
Set WTO MCS flags
MVC
8(16,R1),=CL16’I/O Error’ Put phrase on binary fields
MVC
128(4,R1),=X’00000020’
Set ROUTCDE=11 (WTP)
WTO
MF=(E,4(R1))
Write message to user
SYNADRLS
Release SYNADAF area, fall through
* The GET macro branches here after all records have been read
EOD
CLOSE MF=(E,INOPEN)
Close the data set
* FREEPOOL not needed due to RMODE31=BUFF
...
Rest of program
MYDCB
DCB
DDNAME=INPUT,MACRF=GL,RECFM=VB,
DCBE=MYDCBE
MYDCBE DCBE
EODAD=EOD,SYNAD=IOERROR,BLKSIZE=0,RMODE31=BUFF
OPEN
(,INPUT),MF=L,MODE=24
AreaLen EQU
*-MYDCB
DCBD
DSORG=QS,DEVD=DA
IHADCBE
Could be above 16 MB line
MYAREA DSECT
INDCB
DS
XL(DCBLNGQS)
INDCBE DS
XL(DCBEEND-DCBE)
INOPEN OPEN
(,),MF=L
*
Figure 52. Reentrant—Above the 16 MB Line
Using OPEN to Prepare a Data Set for Processing
Use the OPEN macro to complete a DCB for a data set, and to supply the
specifications needed for I/O operations. Therefore, the appropriate data can be
provided when your job is run rather than when you write your program (see
Figure 53 on page 333).
When the OPEN macro is run, the OPEN routine:
v Completes the DCB
v Stores appropriate access method routine addresses in the DCB
v Initializes data sets by reading or writing labels and control information
v Builds the necessary system control blocks
The operating system stores information from a DD statement or dynamic
allocation in the job file control block (JFCB). The open function uses the JFCB.
332
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
The DCB is filled in with information from the DCB macro, the JFCB, or an
existing data set label. If more than one source specifies information for a
particular field, only one source is used. A DD statement takes priority over a data
set label, and a DCB macro over both.
You can change most DCB fields either before the data set is opened or when the
operating system returns control to your program (at the DCB OPEN user exit).
Some fields can be changed during processing. Do not try to change a DCB field,
such as data set organization, from one that permitted the data set to be allocated
to a system-managed volume, to one that makes the data set ineligible to be
system-managed. For example, do not specify a data set organization in the DD
statement as physical sequential and, after the data set has been allocated to a
system-managed volume, try to open the data set with a DCB that specifies the
data set as physical sequential unmovable. The types of data sets that cannot be
system-managed are listed in Chapter 2, “Using the Storage Management
Subsystem,” on page 31.
Filling in the DCB
Figure 53 shows the process and the sequence of filling in the DCB from various
sources.
DCB and
DCBE
Macro
Data
Control
Block
1
5
6
4
7
DD
Statement
or SVC 99
ACS
Routines
2
Job File
Control
Block
8
DCB
Exit
Routine
Installation
DCB OPEN
exit routine
New
Data Set
Label
3
Old
Data Set
Label
DA6D4074
Figure 53. Sources and Sequence of Operations for Completing the DCB
The following items correspond to the boxed numbers in Figure 53.
1. The primary source is your program; that is, the DCB and DCBE macro or
compiler. Usually, you should use only those DCB and DCBE parameters that
are needed to ensure correct processing. The other parameters can be filled in
when your program is to be run.
2. A JCL DD statement or a call to dynamic allocation (SVC 99) creates a job file
control block (JFCB). The DD or SVC 99 can supply a data class (DATACLAS)
name. The installation data class ACS routine can supply or override the data
class name. The resulting data class provides defaults for certain parameters
that were omitted from the DD or SVC 99. Parameters from a data class do not
Chapter 21. Specifying and Initializing Data Control Blocks
333
Data Control Block (DCB)
override a DD or SVC 99. If the DD statement or call to dynamic allocation has
a BLKSIZE value that exceeds 32 760, that value is in a system control block
that is a logical extension to the JFCB, and the JFCB BLKSIZE field has a zero
value.
3. When a DASD data set is opened (or a magnetic tape with standard labels is
opened for INPUT, RDBACK, or INOUT or is being extended), any field in the
JFCB not completed by a DD statement or data class is filled in from the data
set label (if one exists). When you open a new DASD data set, the system
might previously have calculated an optimal block size and stored it in the data
set label. It does that if RECFM, LRECL, and DSORG are available.
When opening a magnetic tape for output, the OPEN function usually assumes
the tape labels do not exist or to apply to the current data set. The exceptions
are if you specify DISP=MOD on the DD statement or the dynamic allocation
equivalent, or the OPEN macro has the EXTEND or OUTINX option and a
volume serial number is present. A volume serial number is present if any of
the following is true:
v The data set is cataloged
v The VOLUME parameter of the DD statement or dynamic allocation has a
volume serial number
v The DD statement has VOL=REF that refers to a DD statement with a
volume serial number that is resolved before the open for the DD statement
with VOL=REF
OPEN does not perform a merge from a data set label to JFCB for a “like”
sequential concatenation when making the transition between data sets. If you
want a merge, turn on the unlike attribute bit (DCBOFPPC) in the DCB. The
unlike attribute forces the system through OPEN for each data set in the
concatenation, where a label to JFCB merge takes place. See “Concatenating
Unlike Data Sets” on page 408.
4. From the JFCB, OPEN fills in any field not completed in the DCB or DCBE.
This completes what is called the forward merge.
5. Certain fields in the DCB or DCBE can then be completed or changed by your
own DCB user exit routine or JFCBE exit routine. The DCB and DCBE macro
fields are described in z/OS DFSMS Macro Instructions for Data Sets. These exits
are described in “DCB OPEN Exit” on page 573 and “JFCBE Exit” on page 578.
6. After OPEN calls the user's optional DCB OPEN exit or JFCBE exit, it calls the
installation's optional OPEN exit routine. Either type of exit or both can make
certain changes to the DCB and DCBE.
The block size field (BLKSIZE) is in two bytes in the DCB if you are not using
large block interface (LBI). Its maximum value is 32 760. The block size field is
in four bytes in the DCBE if you are using LBI. After possibly calling these
exits, OPEN tests if the block size field is zero or an exit changed LRECL or
RECFM after the system calculated a block size when the DASD data set space
was allocated. In either case, OPEN calculates an optimal block size according
to the device type if the RECFM is not U.
7. All DCB fields are then unconditionally merged into corresponding JFCB fields
if your data set is opened for output. This is the beginning of what is called the
reverse merge. Merging the DCB fields is caused by specifying OUTPUT,
OUTIN, EXTEND, or OUTINX in the OPEN macro.
The DSORG field is merged only when it contains zeros in the JFCB. If your
data set is opened for input (INPUT, INOUT, RDBACK, or UPDAT is specified
in the OPEN macro), the DCB fields are not merged unless the corresponding
JFCB fields contain zeros.
334
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
8. The open routines use the updated JFCB and associated control blocks to write
the DASD data set labels if the data set was open for OUTPUT, OUTIN,
OUTINX, or EXTEND. For standard labeled tapes, the open routines write
labels only for the OUTPUT or OUTIN options when you are not extending the
data set. You are extending if the OPEN option is OUTPUT or OUTIN with
DISP=MOD or the OPEN option is OUTINX, EXTEND or INOUT. When
extending a standard labeled tape data set, the EOV and CLOSE functions use
the updated JFCB and associated control blocks to write trailer labels. If the
data set is not closed when your program ends, the operating system closes it
automatically.
When the data set is closed, the DCB is restored to the condition it had before the
data set was opened (except that the buffer pool is not freed) unless you coded
RMODE31=BUFF and OPEN accepted it.
Specifying the Forms of Macros, Buffering Requirements, and
Addresses
The operating system requires several types of processing information to ensure
proper control of your I/O operations. You must specify the forms of macros in the
program, buffering requirements, and the addresses of your special processing
routines during either the assembly or the execution of your program. The DCB
parameters specifying buffer requirements are discussed in “Managing SAM Buffer
Space” on page 354.
Because macros are expanded during the assembly of your program, you must
supply the macro forms to be used in processing each data set in the associated
DCB macro. You can supply buffering requirements and related information in the
DCB and DCBE macro, the DD statement, or by storing the applicable data in the
appropriate field of the DCB or DCBE before the end of your DCB exit routine. If
the addresses of special processing routines (EODAD, SYNAD, or user exits) are
omitted from the DCB and DCBE macro, you must complete them in the DCB or
DCBE before they are required.
Coding Processing Methods
You can process a data set as input, output, or update by coding the processing
method in the OPEN macro. If the processing method parameter is omitted from
the OPEN macro, INPUT is assumed.
INPUT—BDAM, BPAM, BSAM, QSAM
OUTPUT—BDAM, BPAM, BSAM, QSAM
EXTEND—BDAM, BPAM (PDSE only), BSAM, QSAM
UPDAT—BDAM, BPAM, BSAM, QSAM
RDBACK—BSAM, QSAM
INOUT—BSAM
OUTIN—BSAM
OUTINX—BSAM
If the data set resides on a direct access volume, you can code UPDAT in the
processing method parameter to show that records can be updated.
RDBACK is supported only for magnetic tape. By coding RDBACK, you can
specify that a magnetic tape volume containing format-F or format-U records is to
be read backward. (Variable-length records cannot be read backward.)
Chapter 21. Specifying and Initializing Data Control Blocks
335
Data Control Block (DCB)
Restriction: When a tape that is recorded in Improved Data Recording Capability
(IDRC) mode, is read backward, it will have a severe performance degradation.
You can override the INOUT, OUTIN, UPDAT, or OUTINX at execution time by
using the IN or OUT options of the LABEL parameter of the DD statement, as
discussed in z/OS MVS JCL Reference. The IN option indicates that a BSAM data set
opened for INOUT or a direct data set opened for UPDAT is to be read only. The
OUT option indicates that a BSAM data set opened for OUTIN or OUTINX is to be
written in only.
Restriction: Unless allowed by the label validation installation exit, OPEN for
OUTPUT or OUTIN with DISP=MOD, INOUT, EXTEND, or OUTINX requests
cannot be processed for ISO/ANSI Version 3 tapes or for non-IBM-formatted
Version 4 tapes, because this kind of processing updates only the closing label of
the file, causing a label symmetry conflict. An unmatching label should not frame
the other end of the file. This restriction does not apply to IBM-formatted
ISO/ANSI Version 4 tapes.
Related reading: For information about the label validation installation exit, see
z/OS DFSMS Installation Exits.
Processing SYSIN, SYSOUT, and subsystem data sets. INOUT is treated as
INPUT. OUTIN, EXTEND, or OUTINX is treated as OUTPUT. UPDAT and
RDBACK cannot be used. SYSIN and SYSOUT data sets must be opened for
INPUT and OUTPUT, respectively.
Processing PDSEs. For PDSEs, INOUT is treated as INPUT. OUTIN, EXTEND, and
OUTINX are treated as OUTPUT.
Processing compressed-format data sets. Compressed-format data sets must not be
opened for UPDAT.
In Figure 54 the data sets associated with three DCBs are to be opened
simultaneously.
OPEN
(TEXTDCB,,CONVDCB,(OUTPUT),PRINTDCB,
(OUTPUT))
X
Figure 54. Opening Three Data Sets at the Same Time
Because no processing method parameter is specified for TEXTDCB, the system
assumes INPUT. Both CONVDCB and PRINTDCB are opened for output. No
volume positioning options are specified; thus, the disposition indicated by the DD
statement DISP parameter is used.
Selecting Data Set Options
After you have specified the data set characteristics in the DCB and DCBE macro,
you can change them only by changing the DCB or DCBE during execution. See
“Changing and Testing the DCB and DCBE” on page 344. The fields of the DCB
discussed in the following sections are common to most data organizations and
access methods. The DCBE is for BSAM, BPAM, QSAM, and BDAM. For more
information about the DCB and DCBE fields see z/OS DFSMS Macro Instructions for
Data Sets.
336
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
Block Size (BLKSIZE)
Format-F and format-V records: BLKSIZE specifies the maximum length, in bytes,
of a data block. If the records are format-F, the block size must be an integral
multiple of the record length, except for SYSOUT data sets. (See Chapter 24,
“Spooling and Scheduling Data Sets,” on page 397.) If the records are format-V,
you must specify the maximum block size. If format-V records are unblocked, the
block size must be 4 bytes greater than the record length (LRECL). If you do not
use the large block interface (LBI), the maximum block size is 32 760 except for
ISO/ANSI Version 3 records, where the maximum block size is 2048. You can
override the 2048 byte limit by a label validation installation exit (see z/OS DFSMS
Installation Exits). If you use LBI, the maximum block size is 32 760 except on
magnetic tape, where the maximum is larger. Additionally, the maximum block
size when using BSAM with UNIX is 65 535.
Extended-format data sets: In an extended-format data set, the system adds a
32-byte suffix to each block, which your program does not see. This suffix does not
appear in your buffers. Do not include the length of this suffix in the BLKSIZE or
BUFL values.
Compressed-format data sets: When you read blocked format-F or format-V
records with BSAM or BPAM from a compressed data set with DBB compression,
PDSE, or UNIX files, the records might be distributed between blocks differently
from when they were written. In a compressed format data set, the BLKSIZE value
has no relationship with the actual size of blocks on disk. The BLKSIZE value
specifies the maximum length of uncompressed blocks.
System-determined block size: The system can derive the best block size for
DASD, tape, and spooled data sets. The system does not derive a block size for
BDAM, old, or unmovable data sets, or when the RECFM is U. See
“System-Determined Block Size” on page 338 for more information on
system-determined block sizes for DASD and tape data sets.
|
Minimum block size: If you specify a block size other than zero, there is no
minimum requirement for block size except that format-V blocks have a minimum
block size of 8, and encrypted data sets require a minimum block size of 16 bytes. .
However, if a data check occurs on a magnetic tape device, any block shorter than
12 bytes in a read operation, or 18 bytes in a write operation, is treated as a noise
record and lost. No check for noise is made unless a data check occurs.
Large Block Interface (LBI)
The large block interface (LBI) lets your program handle much larger blocks with
BSAM or QSAM. On the current level of the system you can use LBI with BSAM,
BPAM, and QSAM for any kind of data set except unit record or a TSO/E
terminal. Currently blocks of more than 32 760 bytes are supported only on tape,
dummy data sets, and BSAM UNIX files.
You request LBI by coding a BLKSIZE value, even 0, in the DCBE macro or by
turning on the DCBEULBI bit before completion of the DCB OPEN exit. Coding
BLKSIZE causes the bit to be on. It is best if this bit is on before you issue the
OPEN macro. That lets OPEN merge a large block size into the DCBE.
Your DCB OPEN exit can test bit DCBESLBI to learn if the access method supports
LBI. If your program did not request unlike attributes processing (by turning on bit
DCBOFPPC) before issuing OPEN, then DCBESLBI being on means that all the
data sets in the concatenation support LBI. If your program requested unlike
attributes processing before OPEN, then DCBESLBI being on each time that the
Chapter 21. Specifying and Initializing Data Control Blocks
337
Data Control Block (DCB)
system calls your DCB OPEN exit or JFCBE exit means only that the next data set
supports LBI. After the exit, OPEN leaves DCBESLBI on only if DCBEULBI also is
on. Your exit routine can change DCBEULBI. Never change DCBESLBI.
Another way to learn if the data set type supports LBI is to issue a DEVTYPE
macro with INFO=AMCAP. See z/OS DFSMSdfp Advanced Services. After the DCB
OPEN exit, the following items apply when DCBESLBI is on:
v OPEN is honoring your request for LBI.
v Do not use the BLKSIZE field in the DCB. The system uses it. Use the BLKSIZE
field in the DCBE. For more information about DCBE field descriptions see z/OS
DFSMS Macro Instructions for Data Sets.
v You can use extended BDWs with format-V records. Format-V blocks longer
than 32 760 bytes require an extended BDW. See “Block Descriptor Word
(BDW)” on page 307.
v When reading with BSAM or BPAM, your program determines the length of the
block differently. See “Determining the Length of a Block when Reading with
BSAM, BPAM, or BDAM” on page 417.
v When writing with BSAM or BPAM, your program sets the length of each block
differently. See “Writing a Short Format-FB Block with BSAM or BPAM” on page
418.
v When reading undefined-length records with QSAM, your program learns the
length of the block differently. See the GET macro description in z/OS DFSMS
Macro Instructions for Data Sets.
To write format-U or format-D blocks without BUFOFF=L, you must code the 'S'
parameter for the length field on the WRITE macro. For more information, see
z/OS DFSMS Macro Instructions for Data Sets.
v When writing undefined-length records with QSAM, you store the record length
in the DCBE before issuing each PUT. See z/OS DFSMS Macro Instructions for
Data Sets.
v After an I/O error, register 0 and the status area in the SYNAD routine are
slightly different, and the beginning of the area returned by the SYNADAF
macro is different. See Figure 116 on page 556 and z/OS DFSMS Macro
Instructions for Data Sets.
v If the block size exceeds 32 760, you cannot use the BUILD, GETPOOL, or
BUILDRCD macro or the BUFL parameter.
v Your program cannot request exchange buffering (BFTEK=E), OPTCD=H (VSE
embedded checkpoints) or open with the UPDAT option.
v With LBI, fixed-length unblocked records greater than 32 760 bytes are not
supported by QSAM.
BSAM and QSAM do not support reading format-V (variable-length) blocks that
are created by the z/VSE operating system if the block length exceeds 32767. You
can read them as format-U blocks. z/VSE programs cannot read format-V blocks
that are longer than 32767 if the block is created by a z/OS program.
System-Determined Block Size
If you do not specify a block size for the creation of a data set, the system attempts
to determine the block size. Using a system-determined block size has the
following benefits:
v The program can write to DASD, tape, or SYSOUT without you or the program
calculating the optimal block size. DASD track capacity calculations are
complicated. Optimal block sizes differ for various models of DASD and tape.
338
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
v If the data set later is moved to a different DASD type, such as by DFSMShsm,
the system recalculates an appropriate block size and reblocks the data.
The system determines the block size for a data set as follows:
1. OPEN calculates a block size.
Note: A block size may be determined during initial allocation of a DASD data
set. OPEN will either use that block size or calculate a new block size if any of
the data set characteristics (LRECL,RECFM) were changed from the values
specified during initial allocation.
2. OPEN compares the calculated block size to a block size limit, which affects
only data sets on tape because the minimum value of the limit is 32 760.
3. OPEN attempts to decrease the calculated block size to be less than or equal to
the limit.
The block size limit is the first nonzero value from the following items:
1. BLKSZLIM value in the DD statement or dynamic allocation.
2. Block size limit in the data class. The SMS data class ACS routine can assign a
data class to the data set. You can request a data class name with the
DATACLAS keyword in the DD statement or the dynamic-allocation
equivalent. The data set does not have to be SMS managed.
3. TAPEBLKSZLIM value in the DEVSUPxx member of SYS1.PARMLIB. A system
programmer sets this value, which is in the data facilities area (DFA) (see z/OS
DFSMSdfp Advanced Services).
4. The minimum block-size limit, 32 760.
Your program can obtain the BLKSZLIM value that is in effect by issuing the
RDJFCB macro with the X'13' code (see z/OS DFSMSdfp Advanced Services).
Because larger blocks generally cause data transfer to be faster, why would you
want to limit it? Some possible reasons follow:
v A user will take the tape to an operating system or older z/OS system or
application program that does not support the large size that you want. The
other operating system might be a backup system that is used only for disaster
recovery. An OS/390® system before Version 2 Release 10 does not support the
large block interface that is needed for blocks longer than 32 760.
v You want to copy the tape to a different type of tape or to DASD without
reblocking it, and the maximum block size for the destination is less than you
want. An example is the IBM 3480 Magnetic Tape Subsystem, whose maximum
block size is 65 535. The optimal block size for an IBM 3590 is 224 KB or 256 KB,
depending on the level of the hardware. To copy from an optimized 3590 to a
3480 or 3490, you must reblock the data.
v A program that reads or writes the data set and runs in 24-bit addressing mode
might not have enough buffer space for very large blocks.
Table 39 describes block size support.
Table 39. Optimum and maximum block size supported
Device Type
Optimum
Maximum
DASD
Half track (usually)
32 760
Reel tape
32 760
32 760
3480, 3490
65 535
65 535
Chapter 21. Specifying and Initializing Data Control Blocks
339
Data Control Block (DCB)
Table 39. Optimum and maximum block size supported (continued)
Device Type
Optimum
Maximum
3490 Emulation (VTS)
262 144 (256 KB)
262 144 (256 KB)
3590
262 144 (256 KB) except on
some older models on which
it is 229 376 (224 KB)
262 144 (256 KB)
DUMMY
16
5 000 000
DASD Data Sets: When you create (allocate space for) a new DASD data set, the
system derives the optimum block size and saves it in the data set label if all of
the following are true:
v Block size is not available or specified from any source. BLKSIZE=0 can be
specified.
v You specify LRECL or it is in the data class. The data set does not have to be
SMS managed.
v You specify RECFM or it is in the data class. It must be fixed or variable.
v You specify DSORG as PS or PO or you omit DSORG and it is PS or PO in the
data class.
Your DCB OPEN exit can examine the calculated block size in the DCB or DCBE if
no source other than the system supplied the block size.
When a program opens a DASD data set for writing the first time since it was
created, OPEN derives the optimum block size again after calling the optional DCB
OPEN exit if all the following are true:
v Either of the following conditions is true:
–
The block size in the DCB (or DCBE with LBI) is zero.
– The system determined the block size when the data set was created, and
RECFM or LRECL in the DCB is different from the data set label.
v LRECL is in the DCB.
v RECFM is in the DCB and it is fixed or variable.
v The access method is BSAM, BPAM, or QSAM.
For sequential or PDSs, the system-determined block size returned is optimal in
terms of DASD space utilization. For PDSE's, the system-determined block size is
optimal in terms of I/O buffer size because PDSE physical block size on the DASD
is a fixed size determined by PDSE.
For a compressed format data set, the system does not consider track length. The
access method simulates blocks whose length is independent of the real physical
block size. The system-determined block size is optimal in terms of I/O buffer size.
The system chooses a value for the BLKSIZE parameter as it would for an IBM
standard labeled tape as in Table 40 on page 341 and always limits it to 32 760.
This value is stored in the DCB or DCBE and DS1BLKL in the DSCB. However,
regardless of the block size found in the DCB and DSCB, the actual size of the
physical blocks written to DASD is calculated by the system to be optimal for the
device.
The system does not determine the block size for the following types of data sets:
v Unmovable data sets
v Data sets with a record format of U
340
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
v Existing data sets with DISP=OLD (data sets being opened with the INPUT,
OUTPUT, or UPDAT options on the OPEN macro)
v Direct data sets
v When extending data sets
Unmovable data sets cannot be system managed. There are exceptions, however, in
cases where the checkpoint/restart function has set the unmovable attribute for
data sets that are already system managed. This setting prevents data sets opened
previously by a checkpointed application from being moved until you no longer
want to perform a restart on that application.
Tape Data Sets: The system can determine the optimum block size for tape data
sets. The system sets the block size at OPEN on return from the DCB OPEN exit
and installation DCB OPEN exit if:
v The block size in DCBBLKSI is zero (or DCBEBLKSI if using LBI).
v The record length is not zero.
v The record format is fixed or variable.
v The tape data set is open for OUTPUT or OUTIN.
v The access method is BSAM or QSAM.
Rule: For programming languages, the program must specify the file is blocked to
get tape system-determined block size. For example, with COBOL, the program
should specify BLOCK CONTAINS 0 RECORDS.
The system-determined block size depends on the record format of the tape data
set. Table 40 shows the block sizes that are set for tape data sets.
Table 40. Rules for setting block sizes for tape data sets or compressed format data sets
RECFM
Block Size Set
F or FS
LRECL
FB or FBS (Label type=AL
Version 3)
Highest possible multiple of LRECL that is ≤ 2048 if LRECL
≤ 2048
Highest possible multiple of LRECL that is ≤ 32 760 if
LRECL > 2048
FB or FBS (Label type=AL
Version 4 or not AL)
Not tape or not LBI: highest possible multiple of LRECL that
is ≤ 32 760
LBI on tape: Highest possible multiple of LRECL that is ≤
the device's optimal block size
V (not AL)
LRECL + 4 (LRECL must be less than or equal to 32 756)
VS (not AL)
LRECL + 4 if LRECL ≤ 32 756
32 760 if LRECL > 32 756
VB or VBS (not AL)
Not tape or not LBI: 32 760
LBI on tape: Device's optimal block size
D (Label type=AL)
LRECL + 4 (LRECL must be ≤ 32 756)
DBS or DS (Label type=AL
Version 3)
2048 (the maximum block size allowed unless an installation
exit allows it)
D or DS (Label type NL or
LRECL + 4 (LRECL must be ≤ 32 756)
NSL or label type=AL Version
4)
Chapter 21. Specifying and Initializing Data Control Blocks
341
Data Control Block (DCB)
Table 40. Rules for setting block sizes for tape data sets or compressed format data
sets (continued)
RECFM
Block Size Set
DB or DBS (Label type NL, or 32 760
NSL, or AL Version 4)
DB not spanned (Label
type=AL Version 3)
2048 if LRECL ≤ 2044
DCBBLKSI = 32 760 if LRECL > 2044 (you have the option,
for AL Version 3, to accept this block size in the label
validation installation exit)
Label Types:
AL = ISO/ANSI labels
NL = no labels
NSL = nonstandard labels
SL = IBM standard labels
Not AL = NL, NSL, or SL labels
RECFM Allowances:
v RECFM=D is not allowed for SL tapes
v RECFM=V is not allowed for AL tapes
Data Set Organization (DSORG)
DSORG specifies the organization of the data set as physical sequential (PS),
partitioned (PO), or direct (DA). If the data set is processed using absolute rather
than relative addresses, you must mark it as unmovable by adding a U to the
DSORG parameter (for example, by coding DSORG=PSU). You must specify the
data set organization in the DCB macro. In addition:
v When creating a direct data set, the DSORG in the DCB macro must specify PS
or PSU and the DD statement must specify DA or DAU.
v PS is for sequential and extended format DSNTYPE.
v PO is the data set organization for both PDSEs and PDSs. DSNTYPE is used to
distinguish between PDSEs and PDSs.
Unmovable and IS data sets cannot be system managed.
Key Length (KEYLEN)
KEYLEN specifies the length (0 to 255) in bytes of an optional key that precedes
each block on direct access storage devices. The value of KEYLEN is not included
in BLKSIZE or LRECL, but must be included in BUFL if buffer length is specified.
Thus, BUFL=KEYLEN+BLKSIZE. See “Using KEYLEN with PDSEs” on page 462
for information about using the KEYLEN parameter with PDSEs.
Rule: Do not specify nonzero key length when opening a PDSE or extended format
data set for output.
IBM recommends not coding KEYLEN or coding KEYLEN=0. A nonzero value
generally will make your program run slower.
Record Length (LRECL)
LRECL specifies the length, in bytes, of each record in the data set. If the records
are of variable length or undefined length, the maximum record length must be
342
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
specified. For input, the field has no effect for undefined-length (format-U) records.
The value of LRECL and when you specify it depends on the format of the
records:
v For fixed-length unblocked records, LRECL must equal BLKSIZE.
v For PDSEs or compressed-format data sets with fixed-length blocked records,
LRECL must be specified when the data set is opened for output.
v For the extended logical record interface (XLRI) for ISO/ANSI variable spanned
records, LRECL must be specified as LRECL=0K or LRECL=nK.
Record Format (RECFM)
RECFM specifies the characteristics of the records in the data set as fixed-length
(F), variable-length (V), ASCII variable-length (D), or undefined-length (U). Blocked
records are specified as FB, VB, or DB. Spanned records are specified as VS, VBS,
DS, or DBS. You can also specify the records as fixed-length standard by using FS
or FBS. You can request track overflow for records other than standard format by
adding a T to the RECFM parameter (for example, by coding FBT). Track overflow
is ignored for PDSEs.
The type of print control can be specified to be in ANSI format-A, or in machine
code format-M. See “Using Optional Control Characters” on page 321 and z/OS
DFSMS Macro Instructions for Data Sets for information about control characters.
Write Validity Check Option (OPTCD=W)
You can specify the write validity check option in the DCB parameter of the DD
statement, the dynamic allocation text units, or the DCB macro. After a block is
transferred from main to auxiliary storage, the system reads the stored block
(without data transfer) and, by testing for a data check from the I/O device,
verifies that the block was written correctly. Be aware that the write validity check
process requires an additional revolution of the device for each block. If the system
detects any errors, it starts its standard error recovery procedure.
For buffered tape devices, the write validity check option delays the device end
interrupt until the data is physically on tape. When you use the write validity
check option, you get none of the performance benefits of buffering and the
average data transfer rate is much less.
Rule: OPTCD=W is ignored for PDSEs and for extended format data sets.
DD Statement Parameters
Each of the data set description fields of the DCB, except for direct data sets, can
be specified when your job is to be run. Also, data set identification and
disposition, and device characteristics, can be specified at that time. To allocate a
data set, you must specify the data set name and disposition in the DD statement.
In the DD statement, you can specify a data class, storage class, and management
class, and other JCL keywords. You can specify the classes using the JCL keywords
DATACLAS, STORCLAS, and MGMTCLAS. If you do not specify a data class,
storage class, or management class, the ACS routines assign classes based on the
defaults defined by your storage administrator. Storage class and management
class can be assigned only to data sets that are to be system managed.
ACS Routines. Your storage administrator uses the ACS routines to determine
which data sets are to be system managed. The valid classes that can either be
specified in your DD statement or assigned by the ACS routines are defined in the
SMS configuration by your storage administrator. The ACS routines analyze your
Chapter 21. Specifying and Initializing Data Control Blocks
343
Data Control Block (DCB)
JCL, and if you specify a class that you are not authorized to use or a class that
does not exist, your allocation fails. For more information about specifying data
class, storage class, and management class in your DD statement see z/OS MVS
JCL User's Guide.
Data Class. Data class can be specified for both system-managed and
non-system-managed data sets. It can be specified for both DASD and tape data
sets. You can use data class together with the JCL keyword LIKE for tape data sets.
This simplifies migration to and from system-managed storage. When you allocate
a data set, the ACS routines assign a data class to the data set, either the data class
you specify in your DD statement, or the data class defined as the default by your
storage administrator. The data set is allocated using the information contained in
the assigned data class. See your storage administrator for information on the data
classes available to your installation and z/OS DFSMSdfp Storage Administration for
more information about allocating system-managed data sets and using SMS
classes.
You can override any of the information contained in a data class by specifying the
values you want in your DD statement or dynamic allocation. A data class can
contain any of the following information.
Data Set Characteristics
Data set organization
Data set type
Key length
Key offset
Record format
Record length
Block size
Block size limit
Record organization
Retention period
Space allocation
DASD data set key label
|
JCL Keywords Used To Override
DSORG
DSNTYPE
KEYLEN
KEYOFF
RECFM
LRECL
BLKSIZE
BLKSZLIM
RECORG
RETPD
SPACE, AVGREC
DSKEYLBL
Related reading: For more information on the JCL keywords that override data
class information, see z/OS MVS JCL User's Guide and z/OS MVS JCL Reference.
In a DD statement or dynamic-allocation call, you cannot specify directly through
the DSNTYPE value that the data set is to be an extended-format data set.
The easiest data set allocation is one that uses the data class, storage class, and
management class defaults defined by your storage administrator. The following
example shows how to allocate a system-managed data set:
//ddname DD DSNAME=NEW.PLI,DISP=(NEW,KEEP)
You cannot specify the keyword DSNTYPE with the keyword RECORG in the JCL
DD statement. They are mutually exclusive.
Changing and Testing the DCB and DCBE
With certain restrictions you can complete or change the DCB or DCBE during
execution of your program. You can also determine data set characteristics from
information supplied by the data set labels. You can make changes or additions
before you open a data set, after you close it, during the DCB OPEN exit routine,
344
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
or while the data set is open. See “DCB OPEN Exit” on page 573 and “Filling in
the DCB” on page 333 for information about using the DCB OPEN exit routines.
Also see z/OS DFSMS Macro Instructions for Data Sets for information about
changing DCB fields. (Naturally, you must supply the information before it is
needed.)
You should not attempt to change the data set characteristics of a system-managed
data set to characteristics that make it ineligible to be system managed. For
example, do not specify a data set organization in the DD statement as PS and,
after the data set has been allocated to a system-managed volume, change the DCB
to specify DSORG=PSU. That causes abnormal end of your program.
Using the DCBD Macro
Use the data control block DSECT (DCBD) macro to identify the DCB field names
symbolically. If you load a base register with a DCB address, you can refer to any
field symbolically. You can code the DCBD macro once to describe all DCBs.
The DCBD macro generates a dummy control section (DSECT) named IHADCB.
Each field name symbol consists of DCB followed by the first 5 letters of the
keyword subparameter for the DCB macro. For example, the symbolic name of the
block size parameter field is DCBBLKSI. (For other DCB field names see z/OS
DFSMS Macro Instructions for Data Sets.)
The attributes of each DCB field are defined in the dummy control section. Use the
DCB macro's assembler listing to determine the length attribute and the alignment
of each DCB field.
Changing an Address in the DCB
Figure 55 shows how to change a field in the DCB.
EOFEXIT
INERROR
OUTERROR
TEXTDCB
...
OPEN
...
CLOSE
LA
USING
MVC
B
STM
...
STM
...
DCB
DCBD
...
(TEXTDCB,INOUT),MODE=31
(TEXTDCB,REREAD),MODE=31,TYPE=T
10,TEXTDCB
IHADCB,10
DCBSYNAD+1(3),=AL3(OUTERROR)
OUTPUT
14,12,SYNADSA+12
14,12,SYNADSA+12
DSORG=PS,MACRF=(R,W),DDNAME=TEXTTAPE,
EODAD=EOFEXIT,SYNAD=INERROR
DSORG=PS
C
Figure 55. Changing a Field in the DCB
The data set defined by the data control block TEXTDCB is opened for both input
and output. When the application program no longer needs it for input, the
EODAD routine closes the data set temporarily to reposition the volume for
output. The EODAD routine then uses the dummy control section IHADCB to
change the error exit address (SYNAD) from INERROR to OUTERROR.
The EODAD routine loads the address TEXTDCB into register 10, the base register
for IHADCB. Then it moves the address OUTERROR into the DCBSYNAD field of
Chapter 21. Specifying and Initializing Data Control Blocks
345
Data Control Block (DCB)
the DCB. Even though DCBSYNAD is a fullword field and contains important
information in the high-order byte, change only the 3 low-order bytes in the field.
All unused address fields in the DCB, except DCBEXLST, are set to 1 when the
DCB macro is expanded. Many system routines interpret a value of 1 in an address
field as meaning no address was specified, so use it to dynamically reset any field
you do not need.
Using the IHADCBE Macro
Use the IHADCBE mapping macro to identify DCB extension field names
symbolically. If you load a base register with a DCBE address, you can refer to any
field symbolically. You can code the IHADCBE macro once to describe all DCBEs.
The IHADCBE macro generates a dummy control section (DSECT) named DCBE.
For the symbols generated see z/OS DFSMS Macro Instructions for Data Sets.
All address fields in the DCBE are 4 bytes. All undefined addresses are set to 0.
Using CLOSE to End the Processing of a Data Set
The CLOSE macro is used to end processing of a data set and release it from a
DCB. The volume positioning (tapes only) that is to result from closing the data set
can also be specified. See “Positioning Volumes” on page 351 for the definition of
volume positioning. Volume positioning options are the same as those that can be
specified for end-of-volume conditions in the OPEN macro or the DD statement.
An additional volume positioning option, REWIND, is available and can be
specified by the CLOSE macro for magnetic tape volumes. REWIND positions the
tape at the load point regardless of the direction of processing.
Unused space, in a non-VSAM data set, is released only if the data set is OPEN
with the OUTPUT, OUTIN, INOUT, EXTEND or OUTINX option, and the last
operation was OPEN, WRITE (and CHECK), PUT, or CLOSE with TYPE=T.
|
|
|
Issuing the CHECK Macro
Before issuing the CLOSE macro, a CHECK macro must be issued for all DECBs
that have outstanding I/O from WRITE macros. When CLOSE TYPE=T is
specified, a CHECK macro must be issued for all DECBs that have outstanding
I/O from either WRITE or READ macros except when issued from EODAD.
In Figure 56 the data sets associated with three DCBs are to be closed
simultaneously. Because no volume positioning parameters (LEAVE, REWIND) are
specified, the positioning indicated by the DD statement DISP parameter is used.
CLOSE
(TEXTDCB,,CONVDCB,,PRINTDCB)
Figure 56. Closing Three Data Sets at the Same Time
Closing a Data Set Temporarily
You can code CLOSE TYPE=T to temporarily close sequential data sets on
magnetic tape and direct access volumes processed with BSAM. When you use
TYPE=T, the DCB used to process the data set maintains its open status. You do
not have to issue another OPEN macro to continue processing the same data set.
CLOSE TYPE=T cannot be used in a SYNAD routine.
346
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
The TYPE=T parameter causes the system control program to process labels,
modify some of the fields in the system control blocks for that data set, and
reposition the volume (or current volume for multivolume data sets) in much the
same way that the normal CLOSE macro does. When you code TYPE=T, you can
specify that the volume is either to be positioned at the end of data (the LEAVE
option) or to be repositioned at the beginning of data (the REREAD option).
Magnetic tape volumes are repositioned either immediately before the first data
record or immediately after the last data record. The presence of tape labels has no
effect on repositioning.
When a DCB is shared among multiple tasks, only the task that opened the data
set can close it unless TYPE=T is specified.
Figure 57, which assumes a sample data set containing 1000 blocks, shows the
relationship between each positioning option and the point where you resume
processing the data set after issuing the temporary close.
Begin processing
tape data set
(open for read
backward)
Begin
processing
data set
Block
1
Block
2
Block
3
If you CLOSE CODE TYPE = T and specify
Block
999
Block
1000
After temporary close, you will
resume processing
LEAVE
Immediately after block 1000
LEAVE (with tape data set open
for read backward)
Immediately before block 1
REREAD
Immediately before block 1
REREAD (with tape data set open
for read backward)
Immediately after block 1000
Figure 57. Record Processed when LEAVE or REREAD is Specified for CLOSE TYPE=T
Using CLOSE TYPE=T with Sequential Data Sets
For data sets processed with BSAM, you can use CLOSE TYPE=T with the
following restrictions:
v The DCB for the data set you are processing on a direct access device must
specify either DSORG=PS or DSORG=PSU for input processing, and either
DSORG=PS, DSORG=PSU, DSORG=PO, or DSORG=POU for output processing.
(You cannot specify the REREAD option if DSORG=PO or DSORG=POU is
specified. The REREAD restriction prohibits the use of temporary close following
or during the building of a BDAM data set that is allocated by specifying BSAM
MACRF=WL.)
v The DCB must not be open for input to a member of a PDS. The CLOSE
TYPE=T operation is permitted against a PDS when the DCB has been opened
for INPUT mode and the PDS directory is being read.
v If you open the data set for input and issue CLOSE TYPE=T with the LEAVE
option, the volume will be repositioned only if the data set specifies DSORG=PS
or DSORG=PO.
Chapter 21. Specifying and Initializing Data Control Blocks
347
Data Control Block (DCB)
v
CLOSE TYPE=T is ignored for DUMMY data sets.
Releasing Space
The close function attempts to release unused tracks or cylinders for a data set if
all of the following are true:
v The SMS management class specifies YI or CI for the partial release attribute, or
you specified RLSE for the SPACE parameter in the DD statement or RELEASE
in the TSO ALLOCATE command.
v You did not specify TYPE=T on the CLOSE macro.
v The DCB was opened with the OUTPUT, OUTIN, OUTINX, INOUT or EXTEND
option and the last operation before CLOSE was WRITE (and CHECK), STOW
or PUT.
v No other DCB for this data set in the address space was open.
v No other address space in any system is allocated to the data set.
v The data set is sequential or partitioned.
v Certain functions of dynamic allocation are not currently executing in the
address space.
For a multivolume data set that is not in extended format, or is in extended format
with a stripe count of 1, CLOSE releases space only on the current volume.
Space also can be released when DFSMShsm is performing space management or
when an authorized program issues the PARTREL macro.
Space is released on a track boundary if the extent containing the last record was
allocated in units of tracks or in units of average record or block lengths with
ROUND not specified. Space is released on a cylinder boundary if the extent
containing the last record was allocated in units of cylinders or in units of average
block lengths with ROUND specified. However, a cylinder boundary extent could
be released on a track boundary if:
v The DD statement used to access the data set contains a space parameter
specifying units of tracks or units of average block lengths with ROUND not
specified, or
v No space parameter is supplied in the DD statement and no secondary space
value has been saved in the data set label for the data set.
Changing a cylinder boundary extent to a track boundary extent generally causes
loss of the possible performance benefit of a cylinder boundary. On the latest disk
drives there is no performance benefit of cylinder boundaries.
Managing Buffer Pools When Closing Data Sets
After closing the data set, you should issue a FREEPOOL macro to release the
virtual storage used for the buffer pool unless you specified RMODE31=BUFF on
the DCBE macro with QSAM or it is BSAM and BUFNO was not supplied from
any source. If you plan to process other data sets, use FREEPOOL to regain the
buffer pool storage space. If you expect to reopen a data set using the same DCB,
use FREEPOOL unless the buffer pool created the first time the data set was
opened will meet your needs when you reopen the data set. FREEPOOL is
discussed in more detail in “Constructing a Buffer Pool” on page 355.
After the data set has been closed, the DCB can be used for another data set. If you
do not close the data set before a task completes, the operating system tries to
close it automatically. If the DCB is not available to the system at that time, the
348
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
operating system abnormally ends the task, and data results can be unpredictable.
The operating system, however, cannot automatically close any DCBs in dynamic
storage (outside your program) or after the normal end of a program that was
brought into virtual storage by the loader. Therefore, reentrant or loaded programs
must include CLOSE macros for all open data sets.
Opening and Closing Data Sets: Considerations
This sections discusses the OPEN and CLOSE considerations.
Parameter Lists with 31-Bit Addresses
You can code OPEN and CLOSE with MODE=31 to specify a long form parameter
list that can contain 31-bit addresses. The default, MODE=24, specifies a short form
parameter list with 24-bit addresses. If TYPE=J is specified, you must use the short
form parameter list.
The short form parameter list must reside below 16 MB, but the calling program
can be above 16 MB. The long form parameter list can reside above or below 16
MB. VSAM and VTAM® access control blocks (ACBs) can reside above 16 MB.
Although you can code MODE=31 on the OPEN or CLOSE call for a DCB, the
DCB must reside below 16 MB. Therefore, the leading byte of the 4-byte DCB
address must contain zeros. If the byte contains something other than zeros, an
error message is issued. If an OPEN was attempted, the data set is not opened. If a
CLOSE was attempted, the data set is not closed. For both types of parameter lists,
the real address can be above the 2 GB bar. Therefore, you can code LOC=(xx,64)
on the GETMAIN or STORAGE macro.
You need to keep the mode that is specified in the MF=L and MF=E versions of
the OPEN macro consistent. The same is true for the CLOSE macro. If MODE=31 is
specified in the MF=L version of the OPEN or CLOSE macro, MODE=31 must also
be coded in the corresponding MF=E version of the macro. Unpredictable results
occur if the mode that is specified is not consistent.
Open and Close of Multiple Data Sets at the Same Time
An OPEN or CLOSE macro can be used to begin or end processing of more than
one data set. Simultaneous opening or closing is faster than issuing separate
macros. However, additional storage space is required for each data set specified.
The examples in Figure 54 on page 336 and Figure 56 on page 346 show how to
code simultaneous open and close operations.
Factors to Consider When Allocating Direct Access Data Sets
When the system allocates a new data set with DSORG=PS or no DSORG, the
access methods treat the data set as being null, that is, having no data. A program
can safely read the data set before data has been written in it. The system writes a
file mark at the beginning of the data set if it has at least one track. If the data set
begins with a file mark or has no space allocated on the volume, the first GET or
first CHECK for a READ causes the EODAD routine to be called.
If your program finds a way to read beyond the file mark, the program will
receive unpredictable results such as reading residual data from a prior user,
getting an I/O error or getting an ABEND. Reading residual data can cause your
program to appear to run correctly, but you can get unexpected output from the
residual data.
Chapter 21. Specifying and Initializing Data Control Blocks
349
Data Control Block (DCB)
After a data set is created, you can reset it so that it again begins with a file mark.
To do that, you can run a program that opens the data set for output and closes it
without writing anything.
After you delete your data set containing confidential data, you can be certain
another user cannot read your residual data if you use the erase feature described
in “Erasing DASD Data” on page 76.
Guidelines for Opening and Closing Data Sets
When you open and close data sets, consider the following guidelines:
v Two or more tasks or two or more DCBs can share data sets on DASD. See
Chapter 23, “Sharing Non-VSAM Data Sets,” on page 385 and “Sharing PDSEs”
on page 490 for more information.
v The system can override volume disposition specified in the OPEN or CLOSE
macro if necessary. However, you need not be concerned; the system
automatically requests the mounting and demounting of volumes, depending on
the availability of devices at a particular time. For more information about
volume disposition see z/OS MVS JCL User's Guide.
Open/Close/EOV Errors
There are two classes of errors that can occur during open, close, and
end-of-volume processing: determinate and indeterminate errors. Determinate
errors are errors associated with an ABEND issued by OPEN, CLOSE, or EOV. For
example, a condition associated with the 213 completion code with a return code
of 04 might be detected during open processing, indicating that the data set label
could not be found for a data set being opened. In general, the OPEN, CLOSE and
other system functions attempt to react to errors with return codes and
determinate abends; however, in some cases, the result is indeterminate errors,
such as program checks. In such cases, you should examine the last action taken
by your program. Pay particular attention to bad addresses supplied by your
program or overlaid storage.
If a determinate error occurs during the processing resulting from a concurrent
OPEN or CLOSE macro, the system attempts to forcibly close the DCBs associated
with a given OPEN or CLOSE macro. You can also immediately end the task
abnormally by coding a DCB ABEND user exit routine that shows the immediate
termination option. For more information on the DCB ABEND exit see “DCB
ABEND Exit” on page 568. You can also request the DELAY option. In that case,
when all open or close processing is completed, abnormal end processing is
started. Abnormal end involves forcing all DCBs associated with a given OPEN or
CLOSE macro to close status, thereby freeing all storage devices and other system
resources related to the DCBs.
If an indeterminate error (such as a program check) occurs during open, close, or
EOV processing, no attempt is made by the system control program to complete
concurrent open or close processing. The DCBs associated with the OPEN or
CLOSE macro are forced to close status if possible, and the resources related to
each DCB are freed.
To determine the status of any DCB after an error, check the OPEN (or CLOSE)
return code in register 15 or test DCBOFOPN. See z/OS DFSMS Macro Instructions
for Data Sets.
350
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
During task termination, the system issues a CLOSE macro for each data set that is
still open. If the task terminates abnormally due to a determinate system ABEND
for an output QSAM data set on tape, the close routines that would normally
finish processing buffers are bypassed. Any outstanding I/O requests are purged.
Thus, your last data records might be lost for a QSAM output data set on tape.
However, if the data set resides on DASD, the close routines perform the buffer
flushing, which writes the last records to the data set. If you cancel the task, the
buffer is lost.
Installation Exits
Four installation exit routines are provided for abnormal end with ISO/ANSI
Version 3 or Version 4 tapes.
v The label validation exit is entered during OPEN/EOV if a nonvalid label
condition is detected and label validation has not been suppressed. Nonvalid
conditions include incorrect alphanumeric fields, nonstandard values (for
example, RECFM=U, block size greater than 2048, or a zero generation number),
nonvalid label sequence, nonsymmetrical labels, nonvalid expiration date
sequence, and duplicate data set names. However, Version 4 tapes allow block
size greater than 2048, nonvalid expiration date sequence, and duplicate data set
names.
v The validation suppression exit is entered during OPEN/EOV if volume security
checking has been suppressed, if the volume label accessibility field contains an
ASCII space character, or if RACF accepts a volume and the accessibility field
does not contain an uppercase A through Z.
v The volume access exit is entered during OPEN/EOV if a volume is not RACF
protected and the accessibility field in the volume label contains an ASCII
uppercase A through Z.
v The file access exit is entered after locating a requested data set if the
accessibility field in the HDR1 label contains an ASCII uppercase A through Z.
ISO/ANSI Version 4 tapes also permits special characters !*"%&'()+,-./:;<=>?_ and
numeric 0-9.
Related reading: For additional information about ISO/ANSI Version 3 or Version
4 installation exits see z/OS DFSMS Installation Exits.
Positioning Volumes
Volume positioning is releasing the DASD or tape volume or rotating the tape
volume so that the read-write head is at a particular point on the tape. The
following sections discuss the steps in volume positioning: releasing the volume,
processing end-of-volume, positioning the volume.
Releasing Data Sets and Volumes
You are offered the option of being able to release data sets, and the volumes the
data sets reside on when your task is no longer using them. If you are not sharing
data sets, these data sets would otherwise remain unavailable for use by other
tasks until the job step that opened them ends.
There are two ways to code the CLOSE macro that can result in releasing a data
set and the volume on which it resides at the time the data set is closed:
1. For non-VSAM data sets, you can code the following with the FREE=CLOSE
parameter:
Chapter 21. Specifying and Initializing Data Control Blocks
351
Data Control Block (DCB)
CLOSE
CLOSE
(DCB1,DISP) or
(DCB1,REWIND)
See z/OS MVS JCL Reference for information about using and coding the
FREE=CLOSE parameter of the DD statement.
2. If you do not code FREE=CLOSE on the DD statement, you can code:
CLOSE
(DCB1,FREE)
In either case, tape data sets and volumes are freed for use by another job step.
Data sets on direct access storage devices are freed and the volumes on which they
reside are freed if no other data sets on the volume are open. For additional
information on volume disposition and coding restrictions on the CLOSE macro,
see z/OS MVS JCL User's Guide.
If you issue a CLOSE macro with the TYPE=T parameter, the system does not
release the data set or volume. They can be released using a subsequent CLOSE
without TYPE=T or by the unallocation of the data set.
Processing End-of-Volume
The access methods pass control to the data management end-of-volume (EOV)
routine when another volume or concatenated data set is present and any of the
following conditions is detected:
v Tape mark (input tape volume).
v File mark or end of last extent (input direct access volume).
v End-of-data indicator (input device other than magnetic tape or direct access
volume). An example of this would be the last card read on a card reader.
v End of reel or cartridge (output tape volume).
v End of last allocated extent (output direct access volume).
v Application program issued an FEOV macro.
If the LABEL parameter of the associated DD statement shows standard labels, the
EOV routine checks or creates standard trailer labels. If you specify SUL or AUL,
the system passes control to the appropriate user label routine if you specify it in
your exit list.
If your DD statement specifies multiple volume data sets, the EOV routine
automatically switches the volumes. When an EOV e condition exists on an output
data set, the system allocates additional space, as indicated in your DD statement.
If no more volumes are specified or if more than specified are required, the storage
is obtained from any available volume on a device of the same type. If no such
volume is available, the system issues an ABEND.
If you perform multiple opens and closes without writing any user data in the area
of the end-of-tape reflective marker, then header and trailer labels can be written
past the marker. Access methods detect the marker. Because the creation of empty
data sets does not involve access methods, the end-of-tape marker is not detected,
which can cause the tape to run off the end of the reel.
Exception: The system calls your optional DCB OPEN exit routine instead of your
optional EOV exit routine if all of the following are true:
v You are reading a concatenation.
v You read the end of a data set other than the last or issued an FEOV macro on
its last volume.
352
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
v You turned on the DCB “unlike” attributes bit. See “Concatenating Unlike Data
Sets” on page 408.
Recommendation: If EOV processing extends a data set on the same volume or a
new volume for DASD output, EXTEND issues an enqueue on SYSVTOC.
(SYSVTOC is the enqueue major name for the GRS resource.) If the system issues
the EOV request for a data set on a volume where the application already holds
the SYSVTOC enqueue, this request abnormally terminates. To prevent this
problem from occurring, perform either step:
v Allocate an output data set that is large enough not to require a secondary
extent on the volume.
v Place the output data set on a different volume than the one that holds the
SYSVTOC enqueue.
Positioning During End-of-Volume
When a tape end-of-volume condition is detected and the system does not need
the drive for another tape, the system positions the volume according to the
disposition specified in the DD statement unless the volume disposition is
specified in the OPEN macro. Volume positioning instructions for a sequential data
set on magnetic tape can be specified as LEAVE or REREAD.
Using the OPEN Macro to Position Tape Volumes
If the tape was last read forward, LEAVE and REREAD have the following effects.
LEAVE— Positions a labeled tape to the point following the tape mark that follows
the data set trailer label group. Positions an unlabeled volume to the point
following the tape mark that follows the last block of the data set.
REREAD—Positions a labeled tape to the point preceding the data set header label
group. Positions an unlabeled tape to the point preceding the first block of the data
set.
If the tape was last read backward, LEAVE and REREAD have the following
effects.
LEAVE—Positions a labeled tape to the point preceding the data set header label
group, and positions an unlabeled tape to the point preceding the first block of the
data set.
REREAD—Positions a labeled tape to the point following the tape mark that
follows the data set trailer label group. Positions an unlabeled tape to the point
following the tape mark that follows the last block of the data set.
Using the DISP Parameter to Position Volumes
If however you want to position the current volume according to the option
specified in the DISP parameter of the DD statement, you code DISP in the OPEN
macro.
DISP specifies that a tape volume is to be disposed of in the manner implied by
the DD statement associated with the data set. Direct access volume positioning
and disposition are not affected by this parameter of the OPEN macro. There are
several dispositions that can be specified in the DISP parameter of the DD
statement; DISP can be PASS, DELETE, KEEP, CATLG, or UNCATLG.
Chapter 21. Specifying and Initializing Data Control Blocks
353
Data Control Block (DCB)
The resultant action when an end-of-volume condition arises depends on (1) how
many tape units are allocated to the data set, and (2) how many volumes are
specified for the data set in the DD statement. The UNIT and VOLUME
parameters of the DD statement associated with the data set determine the number
of tape units allocated and the number of volumes specified. If the number of
volumes is greater than the number of units allocated, the current volume will be
rewound and unloaded. If the number of volumes is less than or equal to the
number of units, the current volume is merely rewound.
For magnetic tape volumes that are not being unloaded, positioning varies
according to the direction of the last input operation and the existence of tape
labels. When a JCL disposition of PASS or RETAIN is specified, the result is the
same as the OPEN or CLOSE LEAVE option. The CLOSE disposition option takes
precedence over the OPEN option and the OPEN and CLOSE disposition options
take precedence over the JCL.
Forcing End-of-Volume
The FEOV macro directs the operating system to start the end-of-volume
processing before the physical end of the current volume is reached. If another
volume has been specified for the data set or a data set is concatenated after the
current data set, volume switching takes place automatically. The REWIND and
LEAVE volume positioning options are available.
If an FEOV macro is issued for a spanned multivolume data set that is being read
using QSAM, errors can occur when the next GET macro is issued. Make sure that
each volume begins with the first (or only) segment of a logical record. Input
routines cannot begin reading in the middle of a logical record.
The FEOV macro can only be used when you are using BSAM or QSAM. FEOV is
ignored if issued for a SYSOUT data set or if the data set is closed. If you issue
FEOV for a spooled input data set, control passes to your end-of-data (EODAD)
routine or your program is positioned to read the next data set in the
concatenation.
Managing SAM Buffer Space
The operating system provides several methods of buffer acquisition and control.
Each buffer (virtual storage area used for intermediate storage of I/O data) usually
corresponds in length to the size of a block in the data set being processed.
You can assign more than one buffer to a data set by associating the buffer with a
buffer pool. A buffer pool must be constructed in a virtual storage area allocated
for a given number of buffers of a given length.
The number of buffers you assign to a data set should be a trade-off against the
frequency with which you refer to each buffer. A buffer that is not referred to for a
fairly long period could be paged out. If much of this were allowed, throughput
could decrease.
Using QSAM, buffer segments and buffers within the buffer pool are controlled
automatically by the system. However, you can notify the system that you are
finished processing the data in a buffer by issuing a release (RELSE) macro for
input, or a truncate (TRUNC) macro for output. This simple buffering technique
354
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
can be used to process a sequential data set. IBM recommends not using the
RELSE or QSAM TRUNC macros because they can cause your program to become
dependent on the size of each block.
When using QSAM to process tape blocks larger than 32 760 bytes, you must let
the system build the buffer pool automatically during OPEN. The macros
GETPOOL, BUILD, and BUILDRCD do not support the large block size or buffer
size. If, during QSAM OPEN, or a BSAM OPEN with a nonzero BUFNO the
system finds that the DCB has a buffer pool, and that the buffer length is smaller
than the data set block size, an ABEND 013 is issued.
For QSAM, IBM recommends that you let the system build the buffer pool
automatically during OPEN and omit the BUFL parameter. This simplifies your
program. It permits concatenation of data sets in any order of block size. If you
code RMODE31=BUFF on the DCBE macro, the system attempts to get buffers
above the line.
When you use BSAM or BPAM, OPEN builds a buffer pool only if you code a
nonzero value for BUFNO. OPEN issues ABEND 013-4C if BUFL is nonzero and is
less than BLKSIZE in the DCB or DCBE, depending on whether you are using LBI.
If the system builds the buffer pool for a BSAM user, the buffer pool resides below
the 16 MB line.
If you use the basic access methods, you can use buffers as work areas rather than
as intermediate storage areas. You can control the buffers in a buffer pool directly
by using the GETBUF and FREEBUF macros.
For BSAM, IBM recommends that you allocate data areas or buffers through
GETMAIN, STORAGE, or CPOOL macros and not through BUILD, GETPOOL, or
by the system during OPEN. Allocated areas can be above the line. Areas that you
allocate can be better integrated with your other areas.
Constructing a Buffer Pool
Buffer pool construction can be accomplished using any of the following
techniques:
v Statically in an area that you provide, using the BUILD macro
v Explicitly in subpool 0, using the GETPOOL macro
v Automatically, by the system, when the data set is opened
Recommendation: For QSAM, use the automatic technique so that the system can
rebuild the pool automatically when using concatenated data sets.
For the basic access methods, these techniques cannot build buffers above the 16
MB line or build buffers longer than 32 760 bytes.
If QSAM is used, the buffers are automatically returned to the pool when the data
set is closed. If you did not use the BUILD macro and the buffer pool is not above
the 16 MB line due to RMODE31=BUFF on the DCBE macro, you should use the
FREEPOOL macro to return the virtual storage area to the system. If you code
RMODE31=BUFF on a DCBE macro, then FREEPOOL has no effect and is optional.
The system automatically frees the buffer pool.
The following applies to DASD, most tape devices, spooled, subsystem, and
dummy data sets, TSO/E terminals, and UNIX files. For both data areas and
buffers that have virtual addresses greater than 16 MB or less than 16 MB, the real
Chapter 21. Specifying and Initializing Data Control Blocks
355
Data Control Block (DCB)
address can exceed 2 GB. In other words, the real addresses of buffers can have 64
bits. IBM recommends that when you obtain storage for buffers or data areas with
GETMAIN or STORAGE that you specify that the real addresses can be above the
2 GB bar. Therefore, you can code LOC=(xx,64). To get storage with real addresses
below the 2 GB bar, you can code LOC=(xx,ANY) or LOC=(xx,31). This coding has
no effect on your application program unless it deals with real storage addresses,
which is uncommon.
For tape devices that do not support 64 bit IDAWs, your program cannot use
storage that has 64-bit real addresses. For these drives, bit UCBEIDAW is zero.
These drives are the reel tape drives (IBM 3420) and some non-IBM cartridge
drives. In addition for reel tape devices, the real addresses must be 24-bit. For all
tape drives, the value in UCBTBYT3 is X'80'. For all tape drives with reels the
value in UCBTBYT4 is less than X'80'.
In some rare applications, fullword or doubleword alignment of a block within a
buffer is significant. You can specify in the DCB that buffers are to start on either a
doubleword boundary or on a fullword boundary that is not also a doubleword
boundary (by coding BFALN=D or F). If doubleword alignment is specified for
format-V records, the fifth byte of the first record in the block is so aligned. For
that reason, fullword alignment must be requested to align the first byte of the
variable-length record on a doubleword boundary. The alignment of the records
following the first in the block depends on the length of the previous records.
Buffer alignment provides alignment for only the buffer. If records from ASCII
magnetic tape are read and the records use the block prefix, the boundary
alignment of logical records within the buffer depends on the length of the block
prefix. If the length is 4, logical records are on fullword boundaries. If the length is
8, logical records are on doubleword boundaries.
If you use the BUILD macro to construct the buffer pool, alignment depends on
the alignment of the first byte of the reserved storage area.
When you code RMODE31=BUFF for QSAM, the theoretical upper limit for the
size of the buffer pool is 2 GB. This imposes a limit on the buffer size, and thus on
block size, of 2 GB divided by the number of buffers. If the system is to build the
buffer pool, and the computed buffer pool size exceeds 2 GB, an ABEND 013 is
issued. In practice, you can expect maximum buffer pool size to be less than 2 GB
because of maximum device block sizes.
Building a Buffer Pool
When you know both the number and the size of the buffers required for a given
data set before program assembly, you can reserve an area of the appropriate size
to be used as a buffer pool. Any type of area can be used–for example, a
predefined storage area or an area of coding no longer needed.
A BUILD macro, issued during execution of your program, uses the reserved
storage area to build a buffer pool. The address of the buffer pool must be the
same as that specified for the buffer pool control block (BUFCB) in your DCB. The
BUFCB parameter cannot refer to an area that resides above the 16 MB line. The
buffer pool control block is an 8 byte field preceding the buffers in the buffer pool.
The number (BUFNO) and length (BUFL) of the buffers must also be specified. The
length of BUFL must be at least the block size.
356
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
When the data set using the buffer pool is closed, you can reuse the area as
required. You can also reissue the BUILD macro to reconstruct the area into a new
buffer pool to be used by another data set.
You can assign the buffer pool to two or more data sets that require buffers of the
same length. To do this, you must construct an area large enough to accommodate
the total number of buffers required at any one time during execution. That is, if
each of two data sets requires 5 buffers (BUFNO=5), the BUILD macro should
specify 10 buffers. The area must also be large enough to contain the 8 byte buffer
pool control block.
You can issue the BUILD macro in 31-bit mode, but the buffer area cannot reside
above the line and be associated with a DCB. In any case, real addresses can point
above the 2 GB bar.
Building a Buffer Pool and a Record Area
The BUILDRCD macro, like the BUILD macro, causes a buffer pool to be
constructed in an area of virtual storage you provide. Also, BUILDRCD makes it
possible for you to access variable-length, spanned records as complete logical
records, rather than as segments.
You must be processing with QSAM in the locate mode and you must be
processing either VS/VBS or DS/DBS records, if you want to access the
variable-length, spanned records as logical records. If you issue the BUILDRCD
macro before the data set is opened, or during your DCB exit routine, you
automatically get logical records rather than segments of spanned records.
Only one logical record storage area is built, no matter how many buffers are
specified; therefore, you cannot share the buffer pool with other data sets that
might be open at the same time.
You can issue the BUILDRCD macro in 31-bit mode, but the buffer area cannot
reside above the line and be associated with a DCB.
Getting a Buffer Pool
If a specified area is not reserved for use as a buffer pool, or if you want to delay
specifying the number and length of the buffers until execution of your program,
you can use the GETPOOL macro. This macro allows you to vary the size and
number of buffers according to the needs of the data set being processed. The
storage resides below the line in subpool zero.
The GETPOOL macro causes the system to allocate a virtual storage area to a
buffer pool. The system builds a buffer pool control block and stores its address in
the data set's DCB. If you choose to issue the GETPOOL macro, issue it either
before opening the data set or during your DCB's OPEN exit routine.
When using GETPOOL with QSAM, specify a buffer length (BUFL) at least as large
as the block size or omit the BUFL parameter.
Constructing a Buffer Pool Automatically
If you have requested a buffer pool and have not used a BUILD or GETPOOL
macro for the DCB by the end of your DCB exit routine, the system automatically
allocates virtual storage space for a buffer pool. The buffer pool control block is
also assigned and the pool is associated with a specific DCB. For BSAM and
Chapter 21. Specifying and Initializing Data Control Blocks
357
Data Control Block (DCB)
BPAM, a buffer pool is optional. You can request it by specifying BUFNO. For
QSAM, BUFNO can be specified or permitted to default in the following ways:
If you do not code a non-zero value for MULTSDN on the DCBE macro:
n—Extended format but not compressed format and not LBI (n = 2 × blocks per
track × number of stripes)
1—Compressed format data set, PDSE, SYSIN, SYSOUT, SUBSYS, UNIX files
2—Block size > =32 760
3—2540 Card Reader or Punch
5—All others
If you code a non-zero value for MULTSDN on the DCBE macro, then see “DASD
and Tape Performance” on page 415.
If you are using the basic access method to process a direct data set, you must
specify dynamic buffer control. Otherwise, the system does not construct the buffer
pool automatically.
If all of your GET, PUT, PUTX, RELSE, and TRUNC macros for a particular DCB
are issued in 31-bit mode, then you should consider supplying a DCBE macro with
RMODE31=BUFF.
Because a buffer pool obtained automatically is not freed automatically when you
issue a CLOSE macro unless the system recognized your specification of
RMODE31=BUFF on the DCBE macro, you should also issue a FREEPOOL or
FREEMAIN macro (see “Freeing a Buffer Pool”).
Freeing a Buffer Pool
Any buffer pool assigned to a DCB either automatically by the OPEN macro
(except when dynamic buffer control is used or the system is honoring
RMODE31=BUFF on the DCBE macro), or explicitly by the GETPOOL macro
should be released before your program is completed. The FREEPOOL macro
should be issued to release the virtual storage area when the buffers are no longer
needed. When you are using the queued access technique, you must close the data
set first. If you are not using the queued access method, it is still advisable to close
the data set first.
If the OPEN macro was issued while running in problem state, protect key of zero,
a buffer pool that was obtained by OPEN should be released by issuing the
FREEMAIN macro instead of the FREEPOOL macro. This is necessary because the
buffer pool acquired under these conditions will be in storage assigned to subpool
252 (in user key storage).
Constructing a Buffer Pool: Examples
Figure 58 on page 359 and Figure 59 on page 359 show several possible methods of
constructing a buffer pool. They do not consider the method of processing or
controlling the buffers in the pool.
358
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
In Figure 58, a static storage area named INPOOL is allocated during program
assembly.
ENDJOB
INDCB
OUTDCB
INPOOL
...
BUILD
OPEN
...
CLOSE
...
RETURN
DCB
DCB
CNOP
DS
...
Processing
INPOOL,10,52
Structure a buffer pool
(INDCB,,OUTDCB,(OUTPUT))
Processing
(INDCB,,OUTDCB)
Processing
Return to system control
BUFNO=5,BUFCB=INPOOL,EODAD=ENDJOB,--BUFNO=5,BUFCB=INPOOL,--0,8
Force boundary alignment
CL528
Buffer pool
Figure 58. Constructing a Buffer Pool from a Static Storage Area
The BUILD macro, issued during execution, arranges the buffer pool into 10
buffers, each 52 bytes long. Five buffers are assigned to INDCB and five to
OUTDCB, as specified in the DCB macro for each. The two data sets share the
buffer pool because both specify INPOOL as the buffer pool control block. Notice
that an additional 8 bytes have been allocated for the buffer pool to contain the
buffer pool control block.
In Figure 59, two buffer pools are constructed explicitly by the GETPOOL macros.
ENDJOB
...
GETPOOL
GETPOOL
OPEN
...
CLOSE
FREEPOOL
INDCB,10,52
Construct a 10-buffer pool
OUTDCB,5,112
Construct a 5-buffer pool
(INDCB,,OUTDCB,(OUTPUT))
(INDCB,,OUTDCB)
INDCB
*
INDCB
OUTDCB
Release buffer pools after all
I/O is complete
FREEPOOL
OUTDCB
...
RETURN
Return to system control
DCB
DSORG=PS,BFALN=F,LRECL=52,RECFM=F,EODAD=ENDJOB,--DCB
DSORG=IS,BFALN=D,LRECL=52,KEYLEN=10,BLKSIZE=104,
...
RKP=0,RECFM=FB,---
C
Figure 59. Constructing a Buffer Pool Using GETPOOL and FREEPOOL
Ten input buffers are provided, each 52 bytes long, to contain one fixed-length
record. Five output buffers are provided, each 112 bytes long, to contain 2 blocked
records plus an 8 byte count field. Notice that both data sets are closed before the
buffer pools are released by the FREEPOOL macros. The same procedure should be
used if the buffer pools were constructed automatically by the OPEN macro.
Controlling Buffers
You can use several techniques to control which buffers are used by your program.
The advantages of each depend to a great extent on the type of job you are doing.
The queued access methods permits simple buffering. The basic access methods
permits either direct or dynamic buffer control.
Queued Access Method
The queued access methods provide three processing modes (move, data, and
locate mode) that determine the extent of data movement in virtual storage. Move,
data, and locate mode processing can be specified for either the GET or PUT
Chapter 21. Specifying and Initializing Data Control Blocks
359
Data Control Block (DCB)
macro. (Substitute mode is no longer supported; the system defaults to move
mode.) The movement of a record is determined by the following modes.
Move Mode. The system moves the record from a system input buffer to your
work area, or from your work area to an output buffer.
Data Mode (QSAM Format-V Spanned Records Only). Data mode works the
same as the move mode, except only the data portion of the record is moved.
Locate Mode. The system does not move the record. Instead, the access method
macro places the address of the next input or output buffer in register 1. For
QSAM format-V spanned records, if you have specified logical records by
specifying BFTEK=A or by issuing the BUILDRCD macro, the address returned in
register 1 points to a record area where the spanned record is assembled or
segmented.
PUT-Locate Mode. The PUT-locate routine uses the value in the DCBLRECL field
to determine if another record will fit into your buffer. Therefore, when you write a
short record, you can get the largest number of records per block by modifying the
DCBLRECL field before you issue a PUT-locate to get a buffer segment for the
short record. Perform the following steps:
1. Record the length of the next (short) record into DCBLRECL.
2. Issue PUT-locate.
3. Move the short record into the buffer segment.
GET-Locate Mode. Two processing modes of the PUTX macro can be used with a
GET-locate macro. The update mode returns an updated record to the data set
from which it was read. The output mode transfers an updated record to an output
data set. There is no actual movement of data in virtual storage. See z/OS DFSMS
Macro Instructions for Data Sets for information about the processing mode specified
by the parameter of the PUTX macro.
Basic Access Method
If you use a basic access method and want the system to assist in buffer control,
you can control buffers directly by using the GETBUF macro to retrieve a buffer
constructed. A buffer can then be returned to the pool by the FREEBUF macro.
Because GETBUF does not support a buffer pool that is above the 16 MB line, IBM
suggests that you write your own routine to allocate buffers above the line.
QSAM in an Application
The term simple buffering refers to the relationship of segments within the buffer.
All segments in a simple buffer are together in storage and are always associated
with the same data set. Each record must be physically moved from an input
buffer segment to an output buffer segment. The record can be processed within
either segment or in a work area.
If you use simple buffering, records of any format can be processed. New records
can be inserted and old records deleted as required to create a new data set. The
following examples of using QSAM use buffers that could have been constructed
in any way previously described.
GET-locate, PUT-move, PUTX-output. Processed in an input buffer and moved to
an output buffer.
360
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
GET-move, PUT-locate. Moved from an input buffer to an output buffer where it
can be processed.
GET-move, PUT-move. Moved from an input buffer to a work area where it can be
processed and moved to an output buffer.
GET-locate, PUT-locate. Processed in an input buffer, copied to an output buffer,
and possibly processed some more.
GET-locate, PUTX-update. Processed in an input buffer and returned to the same
data set.
GET-locate, PUT-move/PUTX-output. The GET macro (step A, Figure 60) locates
the next input record to be processed.
GET
A
INPUT
INPUT
OUTPUT
OUTPUT
INPUT
INPUT
OUTPUT
OUTPUT
PUT
B
System
Figure 60. Simple Buffering with MACRF=GL and MACRF=PM
GET returns a record address in register 1. This address remains valid until the
next GET or CLOSE for the DCB. Your program passes the address to the PUT
macro in register 0. PUT copies the record synchronously.
The PUTX-output macro can be used in place of the PUT-move macro.
GET-move, PUT-locate. The PUT macro locates the address of the next available
output buffer. PUT returns its address in register 1 and your program passes it to
the GET macro in register 0.
On the GET macro you specify the address of the output buffer into which the
system moves the next input record.
A filled output buffer is not written until the next PUT macro is issued. PUT
returns a buffer address before GET moves a record. This means that when GET
branches to the end-of-data routine because all data has been read, the output
buffer still needs a record. Your program should replace the unpredictable output
buffer content with another record, which you might set to blanks or zeros. The
next PUT or CLOSE macro writes the record.
GET-move, PUT-move. The GET macro (step A, Figure 61 on page 362) specifies
the address of the work area into which the system moves the next record from the
input buffer.
Chapter 21. Specifying and Initializing Data Control Blocks
361
Data Control Block (DCB)
GET
A
INPUT
INPUT
WORK
OUTPUT
OUTPUT
WORK
OUTPUT
OUTPUT
System
PUT
B
INPUT
INPUT
System
Figure 61. Simple Buffering with MACRF=GM and MACRF=PM
The PUT macro (step B, Figure 61) specifies the address of the work area from
which the system moves the record into the next output buffer.
GET-locate, PUT-locate. The GET macro (step A, Figure 62) locates the address of
the next available input buffer. GET returns the address in register 1.
GET
A
INPUT
INPUT
OUTPUT
OUTPUT
PUT
B
INPUT
INPUT
OUTPUT
OUTPUT
C
INPUT
INPUT
OUTPUT
OUTPUT
Program
Figure 62. Simple Buffering with MACRF=GL and MACRF=PL
The PUT macro (step B, Figure 62) locates the address of the next available output
buffer. PUT returns its address in register 1. You must then move the record from
the input buffer to the output buffer (step C, Figure 62). Your program can process
each record either before or after the move operation.
A filled output buffer is not written until the next PUT, TRUNC or CLOSE macro
is issued.
Be careful not to issue an extra PUT before issuing CLOSE or FEOV. Otherwise,
when the CLOSE or FEOV macro tries to write your last record, the extra PUT will
write a meaningless record or produce a sequence error.
UPDAT mode. When a data set is opened with UPDAT specified (Figure 63 on
page 363), only GET-locate and PUTX-update are supported.
362
z/OS DFSMS Using Data Sets
Data Control Block (DCB)
GET
INPUT/OUTPUT
INPUT/OUTPUT
PUTX
(No movement of data takes place)
Figure 63. Simple Buffering with MACRF=GL and MACRF=PM-UPDAT Mode
The GET macro locates the next input record to be processed and returns its
address in register 1. You can update the record and issue a PUTX macro that will
cause the block to be written back in its original location in the data set after all
the logical records in that block have been processed.
If you modify the contents of a buffer but do not issue a PUTX macro for that
record, the system can still write the modified record block to the data set. This
happens with blocked records when you issue a PUTX macro for one or more
other records in the buffer.
Exchange Buffering
Exchange buffering is no longer supported. Its request is ignored by the system
and move mode is used instead.
Choosing Buffering Techniques and GET/PUT Processing Modes
As you can see from the previous examples, the most efficient code is achieved by
using automatic buffer pool construction, and GET-locate and PUTX-output with
simple buffering. Table 41 summarizes the combinations of buffering techniques
and processing modes you might use:
Table 41. Buffering Technique and GET/PUT processing modes
Simple Input
Buffering
GET-move
PUT-locate
Actions
GET-move
PUT-move
Program must move
record
System moves record
GET-locate
PUT-locate
GET-locate
PUT-move
X
X
X
X
X
System moves record
segment
Work area required
GET-locate
(logical record),
PUT-locate
X
X
PUTX-output can be
used
X
Using Buffering Macros with Queued Access Method
This topic describes how to use the RELSE and TRUNC macros.
RELSE—Release an Input Buffer
When using QSAM to read blocked records, you can direct the system to ignore
the remaining records in the input buffer being processed. The next GET macro
Chapter 21. Specifying and Initializing Data Control Blocks
363
Data Control Block (DCB)
retrieves a record from another buffer. If format-V spanned records are being used,
the next logical record obtained can begin on any segment in any subsequent
block.
When you are using locate mode, the record address returned from the most recent
GET macro remains valid until you issue the next GET. Issuing a RELSE macro
does change the effect of a previous PUTX macro.
TRUNC—Truncate an Output Buffer
When using QSAM to write blocked records, you can issue the TRUNC macro to
direct the system to write a short block. The first record in the next buffer is the
next record processed by a PUT-output or a PUTX-output mode.
If the locate mode is being used, the system assumes a record has been placed in
the buffer segment pointed to by the last PUT macro.
The last block of a data set is truncated by the CLOSE routine. A data set that
contains format-F records with truncated blocks generally cannot be read as
efficiently as a standard format-F data set.
A TRUNC macro issued against a PDSE does not create a short block because the
block boundaries are not saved on output. On input, the system uses the block size
specified in the DCB or DCBE for reading the PDSE. Logical records are packed
into the user buffer without respect to the block size specified when the PDSE
member was created.
To help the storage administrator find programs that issue a QSAM TRUNC macro
for PDSEs, the SMF type 15 record (see z/OS MVS System Management Facilities
(SMF)) contains an indicator that the program did it.
Recommendation: Avoid using the QSAM TRUNC macro. Many data set copying
and backup programs reblock the records. This means they do not preserve the
block boundaries that your program can have set.
Using Buffering Macros with Basic Access Method
This topic describes how to use the GETBUF and FREEBUF macros.
GETBUF—Get a Buffer from a Pool
The GETBUF macro can be used with the basic access method to request a buffer
from a buffer pool constructed by the BUILD, GETPOOL, or OPEN macro. That
buffer pool resides below the 16 MB line even if you issue BUILD, GETPOOL, or
OPEN in 31-bit mode. The address of the buffer is returned by the system in a
register you specify when you issue the macro. If no buffer is available, the register
contains a 0 instead of an address.
FREEBUF—Return a Buffer to a Pool
The FREEBUF macro is used with the basic access method to return a buffer to the
buffer pool from which it was obtained by a GETBUF macro. Although the buffers
need not be returned in the order in which they were obtained, they must be
returned if you want to make them available for later GETBUF macros.
364
z/OS DFSMS Using Data Sets
Chapter 22. Accessing Records
This topic covers the following subtopics.
Topic
“Accessing Data with READ and WRITE”
“Accessing Data with GET and PUT” on page 370
“Analyzing I/O Errors” on page 374“Limitations with Using SRB or Cross-Memory Mode”
on page 375“Using BSAM, BPAM, and QSAM support for XTIOT, uncaptured UCBs, and
DSAB above the 16 MB line” on page 375
Accessing Data with READ and WRITE
The basic sequential access method (BSAM) and basic partitioned access method
(BPAM) provide the READ, WRITE and TRUNC macros for transmitting data
between virtual and auxiliary storage. These macros can be issued in 24- or 31-bit
addressing mode. Macros are provided to help you manage buffers, or to do
overlapped I/O.
The READ and WRITE macros process blocks, not records. Thus, you must block
and unblock records. Buffers, allocated by either you or the operating system, are
filled or emptied individually each time a READ or WRITE macro is issued. The
READ and WRITE macros only start I/O operations. To ensure the operation is
completed successfully, you must issue a CHECK, WAIT, or EVENTS macro to test
the data event control block (DECB). The only exception is that, when the SYNAD
or EODAD routine is entered, do not issue a CHECK, WAIT, or EVENTS macro for
outstanding READ or WRITE requests.
Using the Data Event Control Block (DECB)
A data event control block is a 20- to 32-byte area reserved by each READ or
WRITE macro. It contains the ECB, control information, and pointers to control
blocks. It must reside below the 16 MB line. The DECB is described in z/OS
DFSMS Macro Instructions for Data Sets and “Data Event Control Block” on page
551. The ECB is described in “Event Control Block” on page 553.
The DECB is examined by the CHECK routine when the I/O operation is
completed to determine if an uncorrectable error or exceptional condition exists. If
it does, CHECK passes control to your SYNAD routine. If you have no SYNAD
routine, the task is abnormally ended.
Grouping Related Control Blocks in a Paging Environment
Code related control blocks (the DCB and DECB) and data areas (buffers and key
areas) so they reside in the same area of your program. This reduces the number of
paging operations required to read from and write to your data set.
Rule: DCB and DECBs must reside below 16 MB, but their central storage
addresses can be above the 2 GB bar.
© Copyright IBM Corp. 1987, 2017
365
Accessing Records
Using Overlapped I/O with BSAM
When using BSAM with overlapped I/O (multiple I/O requests outstanding at one
time), you must use more than one DECB. Specify a different DECB for each I/O
request. For example, if you specify NCP=3 in your DCB for the data set and you
are reading records from the data set, you can code the following macros in your
program:
...
READ DECB1,...
READ DECB2,...
READ DECB3,...
CHECK DECB1
CHECK DECB2
CHECK DECB3
...
This is a more efficient technique:
READ DECB1,...
READ DECB2,...
READ DECB3,...
CHECK DECB1
Beginning of loop
READ DECB1,...
CHECK DECB2
READ DECB2,...
CHECK DECB3
READ DECB3,...
(Repeat the previous six macros until a
CHECK macro causes entry to EODAD routine.)
This is a generalized technique that supports any value for NCP:
1. Supply a DCBE with a nonzero MULTSDN and a nonzero MULTACC. For
optimization you can select the MULTACC value to be half of the MULTSDN
value.
2. Issue an OPEN macro. OPEN calculates an NCP value. If using LBI to process
a tape data set and the block size is greater than 32 768, the minimum
calculated NCP value is 2 and the maximum value is 16.
3. Allocate storage for a number of data areas equal to the NCP value and for an
equal number of DECBs. They do not have to be contiguous. The DECBs must
be below the 16 MB line, but the data areas can be above the 16 MB line.
Central storage addresses can be above 2 GB. After each DECB you can add a
word pointing to the next DECB and point the last one to the first DECB. This
simplifies finding DECBs.
4. For each DECB area, copy a single DECB to it, and issue a READ or WRITE
macro to it, supplying an appropriate data area address.
The source of the DECB copy can be above or below the 16 MB line but the
destination must be below the 16 MB line.
5. Repeat the following steps for each DECB until a CHECK macro for a READ
causes entry to the end-of-data exit (EODAD) routine or until you have nothing
more to write:
a. Issue the CHECK macro (for oldest outstanding READ or WRITE)
b. Process data in block if you are reading, or create a block in data area if you
are writing.
c. Issue the READ or WRITE macro to the DECB.
d. Load a pointer to the next DECB (to get oldest outstanding READ or
WRITE).
366
z/OS DFSMS Using Data Sets
Accessing Records
6. If you are writing, then issue a CHECK macro for each remaining outstanding
DECB in the order of the WRITEs. If you are reading, do not issue another
CHECK.
7. Issue a CLOSE macro and free storage.
Figure 85 on page 449 shows this technique, except for the FIND macro and
DSORG=PO in the DCB macro. To process a sequential data set, code DSORG=PS.
You can easily adapt this technique to use WRITE or READ.
Reading a Block
The READ macro retrieves a data block from an input data set and places it in a
designated area of virtual storage. To permit overlap of the input operation with
processing, the system returns control to your program before the read operation is
completed. You must test the DECB created for the read operation for successful
completion before the block is processed or the DECB is reused.
When you use the READ macro for BSAM to read a direct data set with spanned
records and keys, and you specify BFTEK=R in your DCB, the data management
routines displace record segments after the first in a record by key length. This is
called offset reading. With offset reading you can expect the block descriptor word
and the segment descriptor word at the same locations in your buffer or buffers,
even if you read the first segment of a record (preceded in the buffer by its key), or
a subsequent segment (which does not have a key).
You can specify variations of the READ macro according to the organization of the
data set being processed and the type of processing to be done by the system as
follows.
Sequential and Partitioned :
SF
Read the data set sequentially.
SB
Read the data set backward (magnetic tape, format-F, and format-U only).
When RECFM=FBS, data sets with the last block truncated cannot be read
backward.
Direct :
D
Use the direct access method.
I
Locate the block using a block identification.
K
Locate the block using a key.
F
Provide device position feedback.
X
Maintain exclusive control of the block.
R
Provide next address feedback.
U
Next address can be a capacity record or logical record, whichever
occurred first.
Writing a Block
The WRITE macro places a data block in an output data set from a designated area
of virtual storage. The WRITE macro can also be used to return an updated data
block to a data set. To permit overlap of output operations with processing, the
system returns control to your program before the write operation is completed.
You must test the DECB that is created for the write operation for successful
Chapter 22. Accessing Records
367
Accessing Records
completion before you reuse the DECB. For ASCII tape data sets, do not issue
more than one WRITE on the same block, because the WRITE macro causes the
data in the record area to be converted from EBCDIC to ASCII. Or, if CCSIDs are
specified for ISO/ANSI V4 tapes, from the CCSID specified for the application
program to the CCSID of the data records on tape.
As with the READ macro, you can specify variations of the WRITE macro
according to the organization of the data set and type of processing to be done by
the system as follows.
Sequential :
SF
Write the data set sequentially.
Direct :
SD
Write a dummy fixed-length record. (BDAM load mode)
SZ
Write a capacity record (R0). The system supplies the data, writes the
capacity record, and advances to the next track. (BDAM load mode)
SFR
Write the data set sequentially with next-address feedback. (BDAM load
mode, variable spanned)
D
Use the direct access method.
I
Search argument identifies a block.
K
Search argument is a key.
A
Add a new block.
F
Provide record location data (feedback).
X
Release exclusive control.
Ensuring I/O Initiation with the TRUNC Macro
The TRUNC macro is not required for BSAM or BPAM. It is necessary only if you
have supplied a DCBE with a nonzero MULTACC value and you are about to
issue WAIT or EVENTS for a DECB instead of issuing a CHECK macro. See
“Waiting for Completion of a Read or Write Operation” on page 369 and “DASD
and Tape Performance” on page 415.
Testing Completion of a Read or Write Operation
When processing a data set, you can test for completion of a READ or WRITE
request by issuing a CHECK macro. The system tests for errors and exceptional
conditions in the data event control block (DECB). Successive CHECK macros
issued for the same data set must be issued in the same order as the associated
READ and WRITE macros.
The check routine passes control to the appropriate exit routines specified in the
DCB or DCBE for error analysis (SYNAD) or, for sequential or PDSs, end-of-data
(EODAD). It also automatically starts the end-of-volume procedures (volume
switching or extending output data sets).
If you specify OPTCD=Q in the DCB, CHECK causes input data to be converted
from ASCII to EBCDIC or, if CCSIDs are specified for ISO/ANSI V4 tapes, from
the CCSID of the data records on tape to the CCSID specified for the application
program.
368
z/OS DFSMS Using Data Sets
Accessing Records
If the system calls your SYNAD or EODAD routine, then all other I/O requests for
that DCB have been terminated, although they have not necessarily been posted.
There is no need to test them for completion or issue CHECK for them.
Waiting for Completion of a Read or Write Operation
When processing a data set, you can test for completion of any READ or WRITE
request by issuing a WAIT or EVENTS macro. You can choose to do this so you
can wait for multiple unrelated events. You can process whichever events have
completed. The I/O operation is overlapped with processing, but the DECB is not
checked for errors or exceptional conditions, nor are end-of-volume procedures
initiated. Your program must perform these operations.
If you use overlapped BSAM or BPAM READ or WRITE macros, your program
can run faster if you use the MULTACC parameter on the DCBE macro. If you do
that and use WAIT or EVENTS for the DCB, then you must also use the TRUNC
macro. See TRUNC information in “Ensuring I/O Initiation with the TRUNC
Macro” on page 368 and “DASD and Tape Performance” on page 415.
For BDAM, a WAIT macro must be issued for each READ or WRITE macro if
MACRF=C is not coded in the associated DCB. When MACRF=C is coded, a
CHECK macro must be issued for each READ or WRITE macro. Because the
CHECK macro incorporates the function of the WAIT macro, a WAIT is normally
unnecessary. The EVENTS macro or the ECBLIST form of the WAIT macro can be
useful, though, in selecting which of several outstanding events should be checked
first. Each operation must then be checked or tested separately.
Handling Exceptional Conditions on Tape
In this topic an exceptional condition is any READ or WRITE macro that did not
have normal completion.
Most programs do not care about how much data in the data set is on each
volume and if there is a failure, they do not care what the failure was. A person is
more likely to want to know the cause of the failure.
In some cases you might want to take special actions before some of the system's
normal processing of an exceptional condition. One such exceptional condition is
reading a tape mark and another such exceptional condition is writing at the end
of the tape.
With BSAM, your program can detect when it has reached the end of a magnetic
tape and do some processing before BSAM's normal processing to go to another
volume. To do that, do the following:
1. Instead of issuing the CHECK macro, issue the WAIT or EVENTS macro. Use
the ECB, which is the first word in the DECB. The first byte is called the post
code. As a minor performance enhancement, you can skip all three macros if
the second bit of the post code already is 1.
2. Inspect the post code. Do one of the following:
a. Post code is X'7F': The READ or WRITE is successful. If you are reading
and either the tape label type is AL or OPTCD=Q is in effect, then you must
issue the CHECK macro to convert between ASCII and EBCDIC. Otherwise,
the CHECK is optional and you can continue normal processing as if your
program had issued the CHECK macro.
b. Post code is not X'7F': You cannot issue another READ or WRITE
successfully unless you take one of the following actions. All later READs
Chapter 22. Accessing Records
369
Accessing Records
or WRITEs that you issued for the DCB have post codes that you cannot
predict, but they are guaranteed not to have started. If your only reason to
issue WAIT or EVENTS is to wait for multiple events, then issue CHECK to
handle the exceptional condition. If part or all of your purpose was to
handle a certain exceptional condition, such as a full volume, take one of
the following actions:
v If the post code is X'41' and the status indicators show unit exception and
an error status, you read a tape mark or wrote at the end of the volume.
Coincidentally, however, you got an input or output error that prevented
reading or writing to the block. You can still take one of the preceding
actions. Issuance of CHECK causes entry to your SYNAD routine or
issuance of an ABEND. You can issue CLOSE to bypass the SYNAD
routine, but CLOSE might detect another input or output error and issue
an ABEND.
v If the post code and the status indicators are different from the preceding
ones, the system probably did not read or write to the data block. Issue
CHECK or CLOSE. CHECK causes entry to your SYNAD routine or the
issuance of an ABEND. The system discards all other WRITEs with an
unpredictable post code or no post code.
Accessing Data with GET and PUT
The queued access method provides GET and PUT macros for transmitting data
within virtual storage. The GET and PUT macros can be issued in 24- or 31-bit
addressing mode. The QSAM GET and PUT macros automatically block and
unblock the records that are stored and retrieved. The queued access method
anticipates required buffering and overlaps I/O operations with instruction stream
processing.
Because the operating system controls buffer processing, you can use as many I/O
buffers as needed without reissuing GET or PUT macros to fill or empty buffers.
Usually, more than one input block is in storage at a time, so I/O operations do
not delay record processing.
Because the operating system overlaps I/O with processing, you need not test for
completion, errors, or exceptional conditions. After a GET or PUT macro is issued,
control is not returned to your program until an input area is filled or an output
area is available. Exits to error analysis (SYNAD) and end-of-volume or
end-of-data (EODAD) routines are automatically taken when necessary.
GET—Retrieve a Record
The GET macro obtains a record from an input data set. It operates in a
logical-sequential and device-independent manner. The GET macro schedules the
filling of input buffers, unblocks records, and directs input error recovery
procedures. For spanned-record data sets, it also merges record segments into
logical records.
After all records have been processed and the GET macro detects an end-of-data
indication, the system automatically checks labels on sequential data sets and
passes control to your end-of-data exit (EODAD) routine. If an end-of-volume
condition is detected for a sequential data set, the system automatically switches
volumes if the data set extends across several volumes, or if concatenated data sets
are being processed.
370
z/OS DFSMS Using Data Sets
Accessing Records
If you specify OPTCD=Q in the DCB or DD statement, or if the LABEL parameter
on the DD statement specifies ISO/ANSI labels, the GET macro converts input
data from ASCII to EBCDIC. If CCSIDs are specified for ISO/ANSI V4 tapes, it
converts input data from the CCSID of the data records on tape to the CCSID
specified for the application program. This parameter is supported only for a
magnetic tape that does not have IBM standard labels.
PUT—Write a Record
The PUT macro writes a record into an output data set. Like the GET macro, it
operates in a logical-sequential and device-independent manner. As required, the
PUT macro blocks records, schedules the emptying of output buffers, and handles
output error correction procedures. For sequential data sets, it also starts automatic
volume switching and label creation, and also segments records for spanning.
If you specify OPTCD=Q in the DCB or DD statement, or if the LABEL parameter
on the DD statement specifies ISO/ANSI labels, the PUT macro causes output to
be converted from EBCDIC to ASCII. If CCSIDs are specified for ISO/ANSI V4
tapes, it causes output to be converted from the CCSID specified for the
application program to the CCSID of the data records on tape. This parameter is
supported only for a magnetic tape that does not have IBM standard labels. If the
tape has ISO/ANSI labels (LABEL=(,AL)), the system assumes OPTCD=Q.
If the PUT macro is directed to a card punch or printer, the system automatically
adjusts the number of records or record segments per block of format-F or
format-V blocks to 1. Thus, you can specify a record length (LRECL) and block size
(BLKSIZE) to provide an optimum block size if the records are temporarily placed
on magnetic tape or a direct access volume.
For spanned variable-length records, the block size must be equivalent to the
length of one card or one print line. Record size might be greater than block size in
this case.
PUTX—Write an Updated Record
Use the PUTX macro to update a data set or to write a new output data set using
records from an input data set as a base. PUTX updates, replaces, or inserts records
from existing data sets, but does not create records.
When you use the PUTX macro to update, each record is returned to the data set
referred to by a previous locate mode GET macro. The buffer containing the
updated record is flagged and written back to the same location on the direct
access storage device where it was read. The block is not written until a GET
macro is issued for the next buffer, except when a spanned record is to be updated.
In that case, the block is written with the next GET macro.
When you use the PUTX macro to write a new output data set, you can add new
records by using the PUT macro. As required, the PUTX macro blocks records,
schedules the writing of output buffers, and handles output error correction
procedures.
PDAB—Parallel Input Processing (QSAM Only)
QSAM parallel input processing can be used to process two or more input data
sets concurrently, such as sorting or merging several data sets at the same time.
QSAM parallel input processing eliminates the need for issuing a separate GET
macro to each DCB processed. The GET routine for parallel input processing
Chapter 22. Accessing Records
371
Accessing Records
selects a DCB with a ready record, then transfers control to the normal GET
routine. If there is no DCB with a ready record, the GET routine issues a multiple
WAIT macro.
Parallel input processing provides a logical input record from a queue of data sets
with equal priority. The function supports QSAM with input processing, simple
buffering, locate or move mode, and fixed-, variable-, or undefined-length records.
Spanned records, track-overflow records, dummy data sets, and SYSIN data sets
are not supported.
Parallel input processing can be interrupted at any time to retrieve records from a
specific data set, or to issue control instructions to a specific data set. When the
retrieval process has been completed, parallel input processing can be resumed.
Data sets can be added to or deleted from the data set queue at any time. You
should note, however, that, as each data set reaches an end-of-data condition, the
data set must be removed from the queue with the CLOSE macro before a
subsequent GET macro is issued for the queue. Otherwise, the task could be ended
abnormally.
Using Parallel Data Access Blocks (PDAB)
You specify a request for parallel input processing by including the address of a
parallel data access block (PDAB) in the DCB exit list. For more information on the
DCB exit list, see “DCB Exit List” on page 564.
Use the PDAB macro to create and format a work area that identifies the
maximum number of DCBs that can be processed at any one time. If you exceed
the maximum number of entries specified in the PDAB macro when adding a DCB
to the queue with the OPEN macro, the data set will not be available for parallel
input processing. However, it will be available for sequential processing.
When issuing a parallel GET macro, register 1 must always point to a PDAB. You
can load the register or let the GET macro do it for you. When control is returned
to you, register 1 contains the address of a logical record from one of the data sets
in the queue. Registers 2 - 13 contain their original contents at the time the GET
macro was issued. Registers 14, 15, and 0 are changed.
Through the PDAB, you can find the data set from which the record was retrieved.
A fullword address in the PDAB (PDADCBEP) points to the address of the DCB. It
should be noted that this pointer could be nonvalid from the time a CLOSE macro
is issued to the issuing of the next parallel GET macro.
In Figure 64 on page 373, not more than three data sets (MAXDCB=3 in the PDAB
macro) are open for parallel processing at a time.
372
z/OS DFSMS Using Data Sets
Accessing Records
*
*
GETRTN
EODRTN
DATASET1
DATASET2
DATASET3
DATASET4
DCBQUEUE
SET3XLST
ZEROS
...
OPEN (DATASET1,(INPUT),DATASET2,(INPUT),DATASET3,
(INPUT),DATASET4,(OUTPUT))
TM
DATASET1+DCBQSWS-IHADCB,DCBPOPEN Opened for
parallel processing
BZ
SEQRTN
Branch on no to
sequential routine
TM
DATASET2+DCBQSWS-IHADCB,DCBPOPEN
BZ
SEQRTN
TM
DATASET3+DCBQSWS-IHADCB,DCBPOPEN
BZ
SEQRTN
GET DCBQUEUE,TYPE=P
LR
10,1
Save record pointer
...
...
Record updated in place
...
PUT DATASET4,(10)
B
GETRTN
L
2,DCBQUEUE+PDADCBEP-IHAPDAB
L
2,0(0,2)
CLOSE ((2))
CLC ZEROS(2),DCBQUEUE+PDANODCB-IHAPDAB Any DCBs left?
BL
GETRTN
Branch if yes
...
DCB DDNAME=DDNAME1,DSORG=PS,MACRF=GL,RECFM=FB,
LRECL=80,EODAD=EODRTN,EXLST=SET3XLST
DCB DDNAME=DDNAME2,DSORG=PS,MACRF=GL,RECFM=FB,
LRECL=80,EODAD=EODRTN,EXLST=SET3XLST
DCB DDNAME=DDNAME3,DSORG=PS,MACRF=GL,RECFM=FB,
LRECL=80,EODAD=EODRTN,EXLST=SET3XLST
DCB DDNAME=DDNAME4,DSORG=PS,MACRF=PM,RECFM=FB,
LRECL=80
PDAB MAXDCB=3
DC
0F’0’,AL1(EXLLASTE+EXLPDAB),AL3(DCBQUEUE)
DC
X’0000’
DCBD DSORG=QS
PDABD
IHAEXLST ,
DCB exit list mapping
...
X
X
X
X
X
Figure 64. Parallel Processing of Three Data Sets
The number of bytes required for PDAB is equal to 24 + 8n, where n is the value
of the keyword, MAXDCB.
If data definition statements and data sets are supplied, DATASET1, DATASET2,
and DATASET3 are opened for parallel input processing as specified in the input
processing OPEN macro. Other attributes of each data set are QSAM (MACRF=G),
simple buffering by default, locate or move mode (MACRF=L or M), fixed-length
records (RECFM=F), and exit list entry for a PDAB (X'92'). Note that both locate
and move modes can be used in the same data set queue. The mapping macros,
DCBD and PDABD, are used to refer to the DCBs and the PDAB respectively.
Testing for Parallel Processing
Following the OPEN macro, tests are made to determine whether the DCBs were
opened for parallel processing. If not, the sequential processing routine is given
control.
In Figure 64 when one or more data sets are opened for parallel processing, the
GET routine retrieves a record, saves the pointer in register 10, processes the
record, and writes it to DATASET4. This process continues until an end-of-data
condition is detected on one of the input data sets. The end-of-data routine locates
the completed input data set and removes it from the queue with the CLOSE
Chapter 22. Accessing Records
373
Accessing Records
macro. A test is then made to determine whether any data sets remain on the
queue. Processing continues in this manner until the queue is empty.
Analyzing I/O Errors
The basic and queued access methods both provide special macros for analyzing
I/O errors. These macros can be used in SYNAD routines or in error analysis
routines. If your program does not have a SYNAD routine, the access method
issues ABEND 001.
SYNADAF—Perform SYNAD Analysis Function
The SYNADAF macro analyzes the status, sense, and exceptional condition code
data that is available to your error analysis routine. It produces an error message
that your routine can write into any appropriate data set. The message is in the
form of unblocked variable-length records, but you can write them as fixed-length
records by omitting the block length and record length fields that precede the
message texts.
The SYNADAF message can come in two parts, with each message being an
unblocked variable-length record. If the data set being analyzed is not a PDSE,
extended format data set, or UNIX file; only the first message is filled in. If the
data set is a PDSE, extended format data set or UNIX file, both messages are filled
in. An 'S' in the last byte of the first message means a second message exists. This
second message is located 8 bytes past the end of the first message.
The text of the first message is 120 characters long, and begins with a field of 36,
42, or 20 blanks. You can use the blank field to add your own remarks to the
message. The text of the second message is 128 characters long and ends with a
field of 76 blanks that are reserved for later use. This second message begins in the
fifth byte in the message buffer.
Example: A typical message for a tape data set with the blank field omitted
follows:
,TESTJOBb,STEP2bbb,0283,T,MASTERbb,READb,DATA CHECKbbbbb,0000015,BSAMb
In the preceding example, 'b' means a blank.
That message shows that a data check occurred during reading of the 15th block of
a data set being processed with BSAM. The data set was identified by a DD
statement named MASTER, and was on a magnetic tape volume on unit 283. The
name of the job was TESTJOB; the name of the job step was STEP2.
Example: Two typical messages for a PDSE with the blank fields omitted follow:
,PDSEJOBb,STEP2bbb,0283,D,PDSEDDbb,READb,DATA CHECKbbbbb,
00000000100002,BSAMS
,003,000005,0000000002,00000000,00000000,00 ... (76 blanks)
That message shows that a data check occurred during reading of a block referred
to by a BBCCHHR of X'00000000100002' of a PDSE being processed by BSAM. For
the BBCCHHR explanation, see Actual Addresses in “Glossary” on page 683. The
data set was identified by a DD statement named PDSEDD, and was on a DASD
on unit 283. The name of the job was PDSEJOB. The name of the job step was
STEP2. The 'S' following the access method 'BSAM' means that a second message
has been filled in. The second message identifies the record in which the error
occurred. The concatenation number of the data set is 3 (the third data set in a
374
z/OS DFSMS Using Data Sets
Accessing Records
concatenation), the TTR of the member is X'000005', and the relative record number
is 2. The SMS return and reason codes are zero, meaning that no error occurred in
SMS.
If the error analysis routine is entered because of an input error, the first 6 or 16
bytes of the first message (at offset 8) contain binary information. If no data was
transmitted, these first bytes are blanks. If the error did not prevent data
transmission, these first bytes contain the address of the input buffer and the
number of bytes read. You can use this information to process records from the
block. For example, you can print each record after printing the error message.
Before printing the message, however, you should replace the binary information
with EBCDIC characters.
The SYNADAF macro provides its own save area and makes this area available to
your error analysis routine. When used at the entry point of a SYNAD routine, it
fulfills the routine's responsibility for providing a save area. See z/OS DFSMS
Macro Instructions for Data Sets for more information on the SYNADAF macro.
SYNADRLS—Release SYNADAF Message and Save Areas
The SYNADRLS macro releases the message and save areas provided by the
SYNADAF macro. You must issue this macro before returning from the error
analysis routine.
Device Support Facilities (ICKDSF): Diagnosing I/O Problems
Use Device Support Facilities (ICKDSF) Release 17 or later to determine if there are
problems with the disk drive or a problem reading or writing data stored on the
volume. The ANALYZE command for the Device Support Facilities program can
be used to examine the drive and the user's data to determine if errors exist. See
Device Support Facilities (ICKDSF) User's Guide and Reference.
Limitations with Using SRB or Cross-Memory Mode
You cannot use the service request block (SRB) or cross-memory mode with
non-VSAM access methods.
Using BSAM, BPAM, and QSAM support for XTIOT, uncaptured UCBs,
and DSAB above the 16 MB line
In z/OS V1R12, BSAM, BPAM, QSAM and OCE were enhanced to support the
existing XTIOT (extended task input/output table), UCB nocapture, and
DSAB-above-the-line options of dynamic allocation. Previously, VSAM and EXCP
were the only access methods to support these dynamic allocation options. In
V1R12 the EXCP support was enhanced and BSAM, BPAM and QSAM support
was provided. This support applies to dynamic allocation of DASD, tape, and
dummy data sets, and cases where PATH= is coded. EXCP support including the
EXCPVR and XDAP macros is also affected. These enhancements provide virtual
storage constraint relief especially in the areas of DASD and tape support, and
enable you to have more than about 3200 dynamically-allocated data sets.
To exploit these enhancements, the following types of programs must be changed
and installations using them must set to YES the DEVSUPxx PARMLIB option
NON_VSAM_XTIOT:
1. Those programs that call dynamic allocation and want to exploit XTIOT
(extended task input/output table), UCB nocapture, and DSAB-above-the-line
Chapter 22. Accessing Records
375
Accessing Records
options of dynamic allocation. They must check that DFAXTBAM is set on
before they exploit any of these dynamic allocation options. This bit signifies
that the installation enables this function by setting the option in the
DEVSUPxx member of PARMLIB.
2. Those programs that issue OPEN or RDJFCB for data sets which might have
been dynamically allocated with XTIOT (extended task input/output table),
UCB nocapture, or DSAB-above-the-line options of dynamic allocation. These
programs need to either:
v Have no dependency on the dynamic allocation options at all, and so need to
specify a new DCBE macro LOC=ANY option, or
v Have dependencies on dynamic allocation in order to support XTIOT,
uncaptured UCBs, and DSAB above the line. These changes MUST be made
prior to using the new DCBE macro LOC=ANY option.
If the system programmer does not set NON_VSAM_XTIOT=YES, then application
programs cannot use the three options of dynamic allocation for data sets with
BSAM, QSAM, or BPAM DCBs. In this case, those programs will continue to fail
with existing error message IEC133I when opening the files dynamically allocated
with the XTIOT (extended task input/output table), UCB nocapture, or
DSAB-above-the-line options of dynamic allocation. Application programs that use
the three options of dynamic allocation for data sets with EXCP DCBs will
experience no difference.
The following sections list the tasks and associated procedures for using these
enhancements.
Planning to use BSAM, BPAM, QSAM and OCE support for
XTIOT, uncaptured UCBs, and DSAB above the line
Before you begin: Understand the concepts of the three dynamic allocation options
and their effect on BSAM, BPAM and QSAM, described previously in this
information.
Coexistence requirements: On a z/OS system lower than V1R12, dynamic
allocation (DYNALLOC or SVC99) is supported, however VSAM is the only access
method to support the following options:
v The XTIOT option (S99TIOEX). This option causes an XTIOT above the 16 MB
line instead of an entry in the TIOT below the 16 MB line. If you set this bit, it
requires APF authorization, supervisor state or system key.
v The UCB nocapture option (S99ACUCB). This option avoids the UCB capture
process and causes creation of an XTIOT without requiring the caller to set
S99TIOEX on or to be authorized. Therefore most programs that exploit the
XTIOT will request the UCB nocapture option instead. Capturing a UCB refers to
creating a 24-bit view of a unit control block, a system control block, that
typically has a 31-bit address. Capturing and uncapturing are extra overhead to
maintain compatibility with old programs. JCL allocation always causes UCB
capture when the actual UCB resides above the 16 MB line.
v The DSAB-above-the-line option (S99DSABA). This option will request the DSAB
for the allocation to be above the 16 MB line. Although this bit is in the byte that
does not require authorization, it requires the caller to set S99TIOEX on and
therefore requires authorization.
Perform the following steps to plan for using BSAM, BPAM, QSAM and OCE
support for XTIOT, uncaptured UCBs, and DSAB above the 16 MB line:
376
z/OS DFSMS Using Data Sets
Accessing Records
1. As needed, the system programmer should code the NON_VSAM_XTIOT
option in the DEVSUPxx member of PARMLIB. For details, see .
2. Examine programs that call dynamic allocation, issue RDJFCB, or open data
sets which might have been dynamically allocated with the XTIOT (extended
task input/output table), UCB nocapture, and DSAB-above-the-line options of
dynamic allocation, to see if they require updates.For details, see .
3. As appropriate, modify the programs and specify the DCBE option LOC=ANY
to signify that the programs support the XTIOT, UCB nocapture and
DSAB-above-the-line options of dynamic allocation, or that they are not
impacted by the support. For more information, see “Adapting applications for
BSAM, BPAM, QSAM and OCE support for XTIOT, uncaptured UCBs, and
DSAB above the line.”
Adapting applications for BSAM, BPAM, QSAM and OCE
support for XTIOT, uncaptured UCBs, and DSAB above the
line
Before you begin: For related information, see DEVSUPxx member of PARMLIB in
the z/OS MVS Initialization and Tuning Reference.
Perform the following steps to prepare your applications to use BSAM, BPAM,
QSAM and OCE support for XTIOT, uncaptured UCBs, and DSAB above the line.
Note: Most users might not need to perform the first four steps, and can start with
the fifth step if appropriate.
1. Examine whether your program controls allocations in its own address space or
opens or issues RDJFCB for only data sets that it allocated dynamically. If your
program does either, then you do not have to make a change in the address
space or change any documentation. Step (JCL) allocation does not support the
XTIOT, UCB nocapture or DSAB-above-the-line options. Only dynamic
allocation (SVC 99) supports these options.
2. If your program uses BSAM, BPAM or QSAM and has no reference to (1) a
UCB address, file mask or modeset byte from the DEB (data extent block), (2)
the TIOT entry or DCBTIOT field or (3) the DSAB address, then it is not
necessary to change any code but you should do either of these:
v Update your documentation to state that the program does not support these
three options of dynamic allocation or
v Add the LOC=ANY option to the DCBE macro supplied by your program
and update your documentation to state that it supports these three options
of dynamic allocation.
3. If your program searches the TIOT starting with where TCBTIO points or with
the TIOT entry identified by DCBTIOT or ACBTIOT, that search will fail if the
DD name is allocated with any of the three dynamic allocation options.
TCBTIO is the word at offset 12 in the TCB. Your program might be searching
for a particular DD name, data set name, UCB address, device type, volume
serial or other characteristic. If your program starts searching the TIOT from an
existing entry that is identified by the value in DCBTIOT or ACBTIOT, then it
will not find an XTIOT because OPEN sets DCBTIO or ACBTIOT to zero if the
DD name is defined by an XTIOT instead of a TIOT entry.
Alternately your program might be performing this search by issuing the
GETDSAB or IEFDDSRV macro. If the macro does not have LOC=ANY, then it
will fail.
Chapter 22. Accessing Records
377
Accessing Records
Alternately your program might search the TIOT by issuances of SVC 99
dynamic information retrieval.
In all three cases (direct TIOT search, search by macro or search by SVC 99)
you might choose to rely on that failure if your program gives understandable
diagnostics such as a message like “DD xxxxxx NOT AVAILABLE”. Searching
the TIOT is something that often is done by TSO commands.
Instead you might choose to rely on the system default of the
NON_VSAM_XTIOT=NO option in DEVSUPxx in PARMLIB to cause OPEN or
RDJFCB to fail. This choice is inadvisable because it prevents other programs in
the system such as Db2 and DFSORT from exploiting these options for
non-VSAM access methods. It does not prevent JES2 from exploiting it for
spool data sets.
There is a one-to-one relationship between each DSAB (data set association
block) and either a TIOT entry or an XTIOT.
Your existing program might use the value in the TIOELNGH byte to learn the
length of the current entry to go to the next entry or to learn how many
devices are allocated. This logic will not find an XTIOT but it will still tell you
how many devices are allocated. A poorly-written program might not use the
TIOELNGH symbol. It is the first byte in each TIOT entry or XTIOT.
If you want your program to tolerate its caller or the program itself using any
of these dynamic allocation options, then these are some alternate ways to
upgrade it by exploiting techniques that have been unchanged in recent years
but previously supported only by VSAM:
v To find a TIOT entry or XTIOT when you do not know which type it is, do
either of the following:
– Issue the GETDSAB macro as it is documented. Code LOC=ANY to
include XTIOTs in the search. This is the preferred method because when
there are many TIOT entries or XTIOTs, it is significantly faster than the
other method. The DSAB is mapped by the IHADSAB macro and
DSABTIOT points to the TIOT entry or XTIOT.
– To find the first DSAB use TCBJSCBB in the current TCB, which points to
a JSCB. Use the IEZJSCB mapping macro and pick up JSCBACT to point
to the active JSCB. Use JSCDSABQ to point to the QDB, DSAB queue
description block. Use the IHAQDB mapping macro and pick up
QDBFELMA, which points to the first DSAB if it is non-zero.
To get to the next TIOT entry or XTIOT, you must use DSABFCHA
(address of next DSAB). Do not use DSABFCHN, which can point only to
24-bit DSABs. DSABTIOT points to the TIOT entry or XTIOT. To point to
the previous DSAB (or TIOT entry or XTIOT), use DSABBCHA, which
points to the previous DSAB. Do not use DSABBCHN, which points only
to a 24-bit previous DSAB.
v To examine all TIOT entries and XTIOTs your program can do one of these:
– Find the first DSAB by issuing the GETDSAB macro with the FIRST
option and LOC=ANY. To find the next DSAB, issue GETDSAB with the
NEXT option, LOC=ANY and the current DSAB address.
– Use the preceding technique to search the DSAB chain that begins with
QDBFELMA.
v If your program issues OPEN or RDJFCB for a DD name that it found in the
TIOT, then it will work fine unless the caller of your program expected your
program to find the XTIOT. An example of this is that some programs
support a naming convention for DD names such as it opens all DD names
that begin with “WORK”. If your program is not upgraded to search for
378
z/OS DFSMS Using Data Sets
Accessing Records
XTIOTs as described previously, then your program will not discover these
XTIOTs. The result depends on the logic of your program.
4. If your program issues OPEN to a specified DD name that the caller of your
program allocated with an XTIOT, you might choose to rely on OPEN failing
due to your program not specifying the DCBE option LOC=ANY. As described
previously, a service might have succeeded before the OPEN, leading the
program incorrectly to assume that OPEN will succeed. As before, the result
depends on the logic of your program. What does it do when OPEN fails with
a non-zero return code and the DCBOFOPN bit is off? OPEN will issue
message IEC133I ddname, OPEN FAILED FOR EXTENDED TIOT. Before z/OS
V1R12, OPEN always issued it for a non-EXCP DCB that had an XTIOT. With
an XTIOT in V1R12, OPEN issues it only when the program does not supply
the LOC=ANY option of the DCBE macro or the NON_VSAM_XTIOT=YES
option in PARMLIB is not in effect.
Alternately you can choose to upgrade your program to handle the XTIOT.
Take care of any of the previously-described problems and point the DCB to a
DCBE that has LOC=ANY before issuing the OPEN macro. When you upgrade
your program, you can choose between the following designs:
v Require the system programmer to specify NON_VSAM_XTIOT=YES in the
DEVSUPxx member of PARMLIB.
v Code the program to adapt to the presence or absence of
NON_VSAM_XTIOT=YES.
If your DCB is for EXCP and you upgrade it to supply a DCBE with
LOC=ANY, then the result depends on the NON_VSAM_XTIOT option in the
DEVSUPxx member of PARMLIB. Its default is NO. If that keyword has not
been set to YES, then OPEN will capture the UCB as in previous releases but
will issue the warning message IEC136I ddname, DCBE LOC=ANY NOT
HONORED DUE TO PARMLIB OPTION. If that keyword has been set to YES,
then OPEN will capture the UCB as in previous releases but and will not issue
the warning message.
It is important that if your program does not support these options you
determine whether to (1) change it to support them if DFAXTBAM is set to on,
(2) change it to support them and require the system programmer to specify
NON_VSAM_XTIOT=YES in the DEVSUPxx member of PARMLIB, (3) change
it to, if it wouldn’t already do so, fail gracefully, or (4) leave it to fail
ungracefully. If (4) might affect system integrity, then (1), (2), or (3) must be
done. Item (4) can expose system integrity if your program resides in an
APF-authorized library such as SYS1.LPALIB or SYS1.LINKLIB even if your
program is not APF-authorized. This is because an APF-authorized program
can call your program.
5. If your program uses a UCB address that it obtained from a TIOT entry, this
will no longer work if the TIOT entry actually is an XTIOT. This is because the
three-byte TIOEFSRT field (UCB address at offset 17) in an XTIOT contains
zeroes instead of an actual or captured UCB address. The mapping macro is
IEFTIOT1. Your program might test a UCB field or might pass the UCB address
to a system service such as UCBINFO. If you wish to learn the UCB address
(captured or actual), issue the IEFDDSRV macro as currently documented.
Whether the UCB was captured or not, you should code LOC=ANY with
IEFDDSRV to allow the full 31-bit UCB address. If the UCB was not captured,
then the DSABAUCB bit will be on. The result might still be a zero UCB
address, which has the same meaning as a zero UCB address in a TIOT entry.
A zero UCB address in the TIOT entry or XTIOT means it is a dummy data set
unless the TIOTTERM bit (TERM=TS, TSO terminal) is on or the TIOESSDS bit
(subsystem data set or PATH= coded) is on.
Chapter 22. Accessing Records
379
Accessing Records
6. If your program passes a 31-bit UCB address to a DADSM or CVAF macro or
to the MSGDISP macro, your program must issue the macro in 31-bit mode.
The relevant DADSM macros are RENAME, LSPACE, REALLOC and
PARTREL. RENAME accepts a zero UCB address. The CVAF macros are
CVAFDIR, CVAFSEQ, CVAFDSM and CVAFFILT. Other system services do not
require 31-bit mode but they require the LOC=ANY parameter to handle a
31-bit UCB address. These include TRKCALC, UCBLOOK, GETDSAB,
RESERVE and EDTINFO. If your code might have gotten a UCB address from
a 24-bit field and now might get a 31-bit address, then code LOC=ANY on the
macro. If you pass a 31-bit UCB address to the DEVTYPE macro, the third
option on the UCBLIST keyword must be “ANY”.
7. If your program calls dynamic allocation and you wish to exploit the new
functions or you wish to exploit the new functions because another program
caused an XTIOT, do the following:
v If you have code that has any of the problems described earlier, upgrade it to
handle the three dynamic allocation options as described previously.
v Check that the DFAXTBAM bit is on (set by DEVSUPxx PARMLIB option
NON_VSAM_XTIOT=YES or the respective SET command) before using the
three dynamic allocation options. Point the DCB to a DCBE that has
LOC=ANY before issuing the OPEN or RDJFCB macros. For details on the
DFAXTBAM bit, see z/OS DFSMSdfp Advanced Services.
v Examine all code that uses a UCB address or device-modifier byte in the
DEB (after OPEN). It must be changed to test the DEB31UCB bit to correctly
get the address or device-modifier byte and to ensure that all routines that it
calls correctly handle a four-byte UCB address. If DEB31UCB is off, use
DEBUCBA and DEBSUCBB (three-byte UCB addresses) and DEBSDVM and
DEBDVMOD (device modifier byte). If DEB31UCB is on, use DEBUCBAD
and DEBSUCBA (four-byte UCB addresses) and DEBSDVMX and
DEBDVMOD31. These four DEB UCB address symbols existed before z/OS
V1R12.
v Code that accesses the DEB sections after the device-dependent section will
have to be changed only if the code does not follow the documented
algorithm to get the length of the device-dependent section (see description
of DEBEXSCL in z/OS DFSMSdfp Advanced Services). The sections after the
device-dependent section are the access method section and the subroutine
name section. Programs are unlikely to have a need to examine the
subroutine name section but some programs obtain the volume sequence
number from the access method section.
v Finding the TIOT entry from an open DCB when it is open to an XTIOT. The
two-byte field DCBTIOT that contains the offset in the TIOT will be zero if
the XTIOT option is in effect. To get from the DCB to the TIOT entry or
XTIOT, one way is to pass the open DCB to the GETDSAB macro and pick
up DSABTIOT. Another way is to (1) pick up the DEB address from the
DCB, (2) back up to the DEB prefix and pick up the pointer to the DEB
extension (DEBXTNP) at offset -8, (3) pick up the DSAB address from the
DEB extension (DEBXDSAB, which might point above the line), (4) pick up
the TIOT entry or XTIOT address in DSABTIOT. Both algorithms have
worked for years and will continue to work as long as you allow for the
possibility of the DSAB and/or XTIOT being above the line. You can use this
algorithm for any DEB that was built by OPEN. DEBs that were not built by
OPEN typically do not have a DEB extension and therefore the DEBXTNIN
bit is off. Some DEBs that are not built by OPEN have a DEB extension but
no DSAB.
380
z/OS DFSMS Using Data Sets
Accessing Records
8. SMF records. To help you find programs that open a DCB and do not code
LOC=ANY on the DCBE macro, you can examine the following bits in SMF
type 14 and 15 records:
v SMF14EX31. DCBE specified LOC=ANY
v SMF14XTIO. DD has XTIOT, not TIOT entry
The first bit helps identify programs that should be or have been upgraded to
handle the three dynamic allocation options. These bits are in the additional
data set characteristics section of the extended information segment of the SMF
type 14 and 15 record -- the type 5 section as mapped by the IFGSMF14 macro.
Both bits are useful for EXCP, BSAM, BPAM and QSAM.
9. Installation Exit Routines. Examine the source code for installation exit routines
to look for needed changes even if the DEVSUPxx PARMLIB option is not
enabled. Be sensitive to the fact that authorized code might use a 31-bit TIOT
or UCB address to modify storage accidently as if it were a 24-bit address. The
DADSM pre- and post-processing exits will always see 31-bit UCB addresses
but for the other exits the UCB address will be 24-bit unless the user requests
the XTIOT UCB nocapture option and the NON_VSAM_XTIOT option is set to
YES. These exits are:
v DADSM pre- and post-processing exits (IGGPRE00 and IGGPOST0).
v Tape management exits (IFG019LA (label anomaly), IFG019VM (volume
mount), IFG019FV (file validation), IFG019FS (file start on volume) and
IFG055FE (file end on volume). They receive UCB addresses from TEPMUCB
in IFGTEP, from DEBUCBA and from TIOEFSRT. All three sources will allow
a 31-bit UCB address. TEPMUCB sometimes will be an uncaptured 31-bit
address. If the DEB31UCB bit is on, the UCB address and modeset byte will
be different as described in IEZDEB.
v NSL tape exits (NSLOHDRI, NSLEHDRI, NSLOHDRO, NSLEHDRO,
NSLETRLI, NSLETRLO, NSLCTRLO, IEFXVNSL and NSLREPOS). OPEN,
EOV and CLOSE will always turn DEB31UCB on in the work area to signify
that DXDEBUCB is a 31-bit UCB address and the modeset byte is moved as
described previously. Even though the UCB address field will be four bytes,
it typically will still contain a three-byte address.
v Volume label editor routines (IFG0193C and IFG0553C). Same work area
changes as described for the NSL routines.
v DCB OPEN installation exit (IFG0EX0B).
v The IGXMSGEX installation exit for the MSGDISP macro already supports its
caller passing a 31-bit UCB address but there might be more cases in which
this occurs.
v The data management ABEND installation exit (IFG0199I) passes a UCB
address in field OAIXUCBA. It might now be 31-bit.
v IECIEUCB as mapped by the IECIEPRM macro for the ISO/ANSI Version 3
and Version 4 installation exits (IFG0193G) contains the tape UCB address. In
the past this has always been a 24-bit addresss. Now it might be a 31-bit
address.
The preceding exits are documented in z/OS DFSMS Using Magnetic Tapes. An
exit that is not documented there is IEFDB401, dynamic allocation input
validation exit. The interface to this exit is not being changed but it might see
new combinations of options for non-VSAM data sets.
Chapter 22. Accessing Records
381
Accessing Records
Coding the LOC=ANY DCBE option
OPEN and RDJFCB support the DCBE option LOC=ANY, to signify that the
application program supports the XTIOT, UCB nocapture, and
DSAB-above-the-line options of dynamic allocation or that it is not sensitive to the
use of those options. The default value is LOC=BELOW, which results in OPEN
giving a return code of 8 and RDJFCB giving a return code of 4 if the DD name
has any of these three dynamic allocation options. Open also issues message
IEC133I.
The LOC=ANY option is the 10 bit in the DCBEFLG3 byte. It is named
DCBELOCANY.
If you set this option before issuing an OPEN or RDJFCB macro, it means that the
allocation can have an XTIOT that can reside above the line (instead of a TIOT
entry), the UCB can reside above the line and the DSAB can reside above the line.
If any of these is true, then OPEN will set the two-byte DCBTIOT field to zero
instead of setting it to an offset in the TIOT.
If the application program sets this DCBE option before OPEN or RDJFCB but the
new NON_VSAM_XTIOT=YES option in PARMLIB is not in effect, and any of the
three dynamic allocation options is in effect, then OPEN will issue an ABEND
113–4C and existing message IEC142I, and RDJFCB will give a non-zero return
code (normally 8). If OPEN succeeds, it will set the DCBTIOT field to zeroes
instead of to the offset to an entry in the TIOT, task I/O table. An EXCP DCB for a
device other than DASD or tape will continue to get the existing failures.
If the DEB has a DASD or tape UCB address, then for EXCP, BSAM, BPAM or
QSAM, the resulting DEB will have an optional bit on the DEB basic section that
means: UCB address is 31–bit and the address may not point above the line. The
bit is DEB31UCB. The DEB31UCB bit and other new DEB symbols were shipped in
R11, but with no code to set or test them. This allows you to assemble z/OS V1R12
code on V1R11, but the DEB31UCB bit will not be set to on in V1R11.
For tape, this means that the device-dependent section will be 8 bytes instead of 4
bytes. It will cause a problem for programs that assume the tape section is four
bytes.
Note: Having a 31–bit UCB address field in the DEB does not mean that the UCB
has not been captured or that it is above the line. The actual UCB might be below
the line so the 24–bit UCB address might be in a four-byte field.
If the DD does not have an XTIOT, then the DEB is the old format and it will not
matter whether you code the LOC=ANY DCBE option. It also means that if the
DD has an XTIOT, then DCBTIOT will be zero, but the DEB might be in the old or
the new format.
Coding the DEVSUPxx option
The primary system programming task for this support is coding the
NON_VSAM_XTIOT option in PARMLIB member DEVSUPxx.
The NON_VSAM_XTIOT option in the DEVSUPxx member of SYS1.PARMLIB
controls whether the access method OPEN macro and RDJFCB support three
options of the data set dynamic allocation function for BSAM, BPAM, QSAM, and
382
z/OS DFSMS Using Data Sets
Accessing Records
EXCP. The options are XTIOT, UCB nocapture, and DSAB above the line. The
default value is NO and prevents BSAM, BPAM, and QSAM from supporting these
three options. Use NO if you are concerned that some programs, including
installed products, might not correctly handle these options. You can set YES if all
programs that might process data sets that were dynamically allocated by other
programs can handle these options. Setting YES but not using these options has no
effect on virtual storage or performance.
In a future release IBM might change the default for this option to YES. If you
wish to continue using NO, you should set NO.
To enable BSAM, BPAM, QSAM and OCE support for XTIOT, uncaptured UCBs,
and DSAB above the 16 megabyte line, set the NON_VSAM_XTIOT keyword in
PARMLIB member DEVSUPxx to YES.
The default value for this keyword is NO, to disable that support. The default
value of NO means that OPEN and RDJFCB do the following:
v If the DCB is BSAM, BPAM, or QSAM and the DCBE option LOC=BELOW was
defaulted or specified, OPEN will continue to fail if the DD name is defined
with an XTIOT and will write existing message IEC133I ddname,OPEN FAILED
FOR EXTENDED TIOT. When OPEN issues this message, it will give a non-zero
return code without an ABEND and will not open the DCB.
v If the DCB is BSAM, BPAM, or QSAM and the DCBE option LOC=ANY was
specified, OPEN will fail if the DD name is defined with an XTIOT and will
write existing message IEC133I ddname,OPEN FAILED FOR EXTENDED TIOT,
along with issuing ABEND 113-4C.
v If the DCB is for EXCP, OPEN will continue to capture the UCB address and
CLOSE will uncapture it. However if the program specified the DCBE
LOC=ANY option, OPEN also will issue this message: IEC136I ddname, DCBE
LOC=ANY NOT HONORED DUE TO PARMLIB OPTION.
v If the DCB is BSAM, BPAM, or QSAM, RDJFCB will fail with a return code of 4
if the DD name is defined with an XTIOT. If you used the X’13’ exit list code
with RDJFCB, then this return code 4 will also cause ARLRCODE to be a new
code of 12. It means that either the application program did not specify
LOC=ANY with one or more of the dynamic allocation options or the
NON_VSAM_XTIOT option was not set to YES.
v If the DCB is for EXCP, RDJFCB will continue to function as in previous releases.
You can enable or disable the new capability by changing the PARMLIB option
and taking either of the following actions:
v Re-IPL.
v Issue the SET DEVSUP=xx command to reprocess DEVSUPxx.
When the option is set to YES, the following message is displayed at IPL or when
the SET is issued: IEA253I DEVSUPxx XTIOT FOR NON-VSAM IS SUPPORTED. If
NON_VSAM_XTIOT=YES is not coded, the system will clear the DFAXTBAM bit
at IPL time but no message will be issued.
For reference information about the NON_VSAM_XTIOT option in DEVSUPxx, see
z/OS MVS Initialization and Tuning Reference
Chapter 22. Accessing Records
383
Accessing Records
Diagnosing problems with BSAM, BPAM, QSAM and OCE
support for XTIOT, uncaptured UCBs, and DSAB above the
line
The following ABEND code indicates that an application program set the
LOC=ANY DCBE option before OPEN, but the NON_VSAM_XTIOT=YES option
in the DEVSUPxx member in PARMLIB was not in effect:
v 113–4C
Note: only the system programmer can change a PARMLIB setting.
Related reading: For information about the 113 ABEND, see the description of
message IEC142I in z/OS MVS System Messages.
384
z/OS DFSMS Using Data Sets
Chapter 23. Sharing Non-VSAM Data Sets
This topic covers the following subtopics.
Topic
“PDSEs” on page 393
“Direct Data Sets (BDAM)” on page 394
“Factors to Consider When Opening and Closing Data Sets” on page 394
“Control of Checkpoint Data Sets on Shared DASD Volumes” on page 394
“System Use of Search Direct for Input Operations” on page 396
“Enhanced Data Integrity for Shared Sequential Data Sets” on page 388
You can share non-VSAM data sets among:
v Different jobs in a single operating system
v Multiple DCBs in a task or different subtasks
v One DCB in a task or different subtasks
v Different instances of the operating system. To share between different systems
safely, you need global resource serialization (GRS) or an equivalent product.
Failure to use GRS or an equivalent can result in both data set and VTOC
corruption. See z/OS MVS Planning: Global Resource Serialization for more
information.
There are two conditions under which a data set on a direct access device can be
shared by two or more tasks:
v Two or more DCBs are opened and used concurrently by the tasks to refer to the
same, shared data set (multiple DCBs).
v Only one DCB is opened and used concurrently by multiple tasks in a single job
step (a single, shared DCB).
Except for PDSEs, the system does not protect data integrity when multiple DCBs
are open for output and the DCBs access a data set within the same job step. The
system ensures that only one program in the sysplex can open a PDS with the
OUTPUT option, even if you specify DISP=SHR. If a second program issues OPEN
with the OUTPUT option, for the PDS with DISP=SHR, while a DCB is still open
with the OUTPUT option, the second program gets a 213-30 ABEND. This does not
apply to two programs in one address space with DISP=OLD or MOD, which
would cause overlaid data. This 213-30 enforcement mechanism does not apply
when you issue OPEN with the UPDAT option. Therefore programs that issue
OPEN with UPDAT and DISP=SHR can corrupt the PDS directory. Use DISP=OLD
to avoid the possibility of an abend during the processing of a PDS for output or
of corrupting the directory when it is open for update. If a program writes in a
PDS while protected with DISP=NEW, DISP=OLD, or DISP=MOD, a program
reading from outside of the GRS complex might see unpredictable results such as
members that are temporarily missing or overlaid.
The DCBE must not be shared by multiple DCBs that are open. After the DCB is
successfully closed, you may open a different DCB pointing to the same DCBE.
© Copyright IBM Corp. 1987, 2017
385
Sharing Non-VSAM Data Sets
The operating system provides job control language (JCL) statements and macros
that help you ensure the integrity of the data sets you want to share among the
tasks that process them. Figure 65 and Figure 66 on page 387 show which JCL and
macros you should use, depending on the access method your task is using and
the mode of access (input, output, or update). Figure 65 describes the processing
procedures you should use if more than one DCB has been opened to the shared
data set. The DCBs can be used by tasks in the same or different job steps.
The purpose of the RLSE value for the space keyword in the DD statement is to
cause CLOSE to free unused space when the data set becomes closed. The system
does not perform this function if the DD has DISP=SHR or more than one DCB is
open to the data set.
Figure 65. JCL, Macros, and Procedures Required to Share a Data Set Using Multiple DCBs
DISP=SHR. Each job step sharing an existing data set must code SHR as the
subparameter of the DISP parameter on the DD statement for the shared data set
to let the steps run concurrently. For more information about ensuring data set
integrity see z/OS MVS JCL User's Guide.
Related reading: For more information about sharing PDSEs see “Sharing PDSEs”
on page 490. If the tasks are in the same job step, DISP=SHR is not required. For
more information about detecting sharing violations with sequential data sets, see
“Enhanced Data Integrity for Shared Sequential Data Sets” on page 388.
No facility. There are no facilities in the operating system for sharing a data set
under these conditions.
ENQ on data set. Besides coding DISP=SHR on the DD statement for the data set
that is to be shared, each task must issue ENQ and DEQ macros naming the data
set or block as the resource for which exclusive control is required. The ENQ must
be issued before the GET (READ); the DEQ macro should be issued after the PUTX
or CHECK macro that ends the operation.
Related reading: For more information about using the ENQ and DEQ macros see
z/OS MVS Programming: Assembler Services Reference ABE-HSP.
386
z/OS DFSMS Using Data Sets
Sharing Non-VSAM Data Sets
Guarantee discrete blocks. When you are using the access method that provides
blocking and unblocking of records (QSAM), it is necessary that every task
updating the data set ensure that it is not updating a block that contains a record
being updated by any other task. There are no facilities in the operating system for
ensuring that discrete blocks are being processed by different tasks.
ENQ on block. If you are updating a shared data set (specified by coding
DISP=SHR on the DD statement) using BSAM or BPAM, your task and all other
tasks must serialize processing of each block of records by issuing an ENQ macro
before the READ macro and a DEQ macro after the CHECK macro that follows the
WRITE macro you issued to update the record. If you are using BDAM, it provides
for enqueuing on a block using the READ exclusive option that is requested by
coding MACRF=X in the DCB and an X in the type operand of the READ and
WRITE macros. For an example of the use of the BDAM macros see “Exclusive
Control for Updating” on page 603.
Figure 66 describes the macros you can use to serialize processing of a shared data
set when a single DCB is being shared by several tasks in a job step.
Figure 66. Macros and Procedures Required to Share a Data Set Using a Single DCB
ENQ. When a data set is being shared by two or more tasks in the same job step
(all that use the same DCB), each task processing the data set must issue an ENQ
macro on a predefined resource name before issuing the macro or macros that
begin the I/O operation. Each task must also release exclusive control by issuing
the DEQ macro at the next sequential instruction following the I/O operation.
Note also that if two tasks are writing different members of a PDS, each task
should issue the ENQ macro before the FIND macro and issue the DEQ macro
after the STOW macro that completes processing of the member. See z/OS MVS
Programming: Assembler Services Reference ABE-HSP for more information about the
ENQ and DEQ macros.
No action required. See “Sharing DCBs” on page 606.
ENQ on block. When updating a shared direct data set, every task must use the
BDAM exclusive control option that is requested by coding MACRF=X in the DCB
macro and an X in the type operand of the READ and WRITE macros. See
“Exclusive Control for Updating” on page 603 for an example of the use of BDAM
macros. Note that all tasks sharing a data set must share subpool 0. See the
ATTACH macro description in z/OS MVS Programming: Assembler Services Reference
ABE-HSP.
Chapter 23. Sharing Non-VSAM Data Sets
387
Sharing Non-VSAM Data Sets
Key sequence. The DISP=SHR specification on the DD statement is not required.
Data sets can also be shared both ways at the same time. More than one DCB can
be opened for a shared data set, while more than one task can be sharing one of
the DCBs. Under this condition, the serialization techniques specified for direct
data sets in Figure 65 on page 386 satisfy the requirement. For sequential and
PDSs, the techniques specified in Figure 65 on page 386 and Figure 66 on page 387
must be used.
Open and Close of Data Sets Shared by More than One Task. When more than
one task is sharing a data set, the following restrictions must be recognized. Failure
to comply with these restrictions endangers the integrity of the shared data set.
v All tasks sharing a DCB must be in the job step that opened the DCB. See
Chapter 23, “Sharing Non-VSAM ">