IBM Data Sets, z/OS, DFSMS User manual

z/OS
DFSMS: Using Data Sets
SC26-7410-04
z/OS
DFSMS: Using Data Sets
SC26-7410-04
Note
Before using this information and the product it supports, be sure to read the general information under “Notices” on page
637.
Fifth Edition, September 2004
This edition applies to Version 1 Release 6 of z/OS® (5694-A01), Version 1 Release 6 of z/OS.e (5655-G52), and to all
subsequent releases and modifications until otherwise indicated in new editions.
This edition replaces SC26-7410-03.
IBM® welcomes your comments. A form for readers’ comments may be provided at the back of this publication, or
you may address your comments to the following address:
International Business Machines Corporation
Department 55JA, Mail Station P384
2455 South Road
Poughkeepsie, NY 12601-5400
United States of America
FAX (United States & Canada): 1+845+432-9405
FAX (Other Countries):
Your International Access Code +1+845+432-9405
IBMLink™ (United States customers only): IBMUSM10(MHVRCFS)
Internet e-mail: [email protected]
World Wide Web: http://www.ibm.com/servers/eserver/zseries/zos/webqs.html
If you would like a reply, be sure to include your name, address, telephone number, or FAX number.
Make sure to include the following in your comment or note:
v Title and order number of this document
v Page number or topic related to your comment
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 1987, 2004. All rights reserved.
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 . . . . . . xvii
Required product knowledge . . . . . . . . xvii
Referenced documents . . . . . . . . . . xviii
Accessing z/OS DFSMS documents on the
Internet . . . . . . . . . . . . . . . xviii
Using LookAt to look up message explanations
xviii
Accessing z/OS licensed documents on the Internet xix
Summary of Changes . . . . . . . . xxi
Summary of Changes for SC26-7410-04 z/OS
Version 1 Release 6 . . . . . . . . .
New Information . . . . . . . . .
Changed Information . . . . . . . .
Summary of Changes for SC26-7410-03 z/OS
Version 1 Release 5 . . . . . . . . .
New Information . . . . . . . . .
Changed Information . . . . . . .
Moved Information . . . . . . . .
Summary of Changes for SC26-7410-02 z/OS
Version 1 Release 3 . . . . . . . . .
New Information . . . . . . . . .
Changed Information . . . . . . .
.
.
.
.
.
.
.
.
. xxi
. xxi
. xxi
.
.
. xxi
. xxi
. xxii
. xxii
. xxii
. xxii
. xxiii
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) . . . . . . . . . . 5
Indexed Sequential Access Method . . . . . . 5
Object Access Method . . . . . . . . . . 6
Queued Sequential Access Method . . . . . . 6
Virtual Storage Access Method . . . . . . . 6
Access to z/OS UNIX Files . . . . . . . . 7
Selection of an Access Method . . . . . . . 7
Direct Access Storage Device (DASD) Volumes . . . 8
DASD Labels . . . . . . . . . . . . . 8
Track Format . . . . . . . . . . . . . 8
Track Overflow . . . . . . . . . . . . 9
VSAM Record Addressing . . . . . . . . . 9
Actual and Relative Addressing with Non-VSAM
Access Methods . . . . . . . . . . . . 10
Magnetic Tape Volumes . . . . . . . . . . 11
Using Magnetic Tape Labels . . . . . . . . 11
© Copyright IBM Corp. 1987, 2004
Specifying the File Sequence Number . . . .
Identifying Unlabeled Tapes . . . . . . .
Using Tape Marks . . . . . . . . . .
Data Management Macros . . . . . . . .
Data Set Processing . . . . . . . . . . .
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
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 . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
12
14
14
15
16
16
17
17
18
18
18
19
. 19
. 20
21
. 21
. 22
. 22
. 23
. 24
. 24
. 24
. 25
Chapter 2. Using the Storage
Management Subsystem . . . . . . . 27
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 .
. 29
. 30
. 30
. 32
. 33
. 34
Chapter 3. Allocating Space on Direct
Access Volumes . . . . . . . . . . 35
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 . . . . . .
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 . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
35
35
36
36
37
37
37
37
37
37
.
.
.
.
38
38
38
38
. 39
iii
Guaranteed Space with DISP=NEW or MOD . .
Guaranteed Space for VSAM . . . . . . .
Guaranteed Space with DISP=OLD or SHR . . .
Guaranteed Space with Extended-Format Data
Sets . . . . . . . . . . . . . . . .
Guaranteed Space Example . . . . . . . .
Allocation of Data Sets with the Space Constraint
Relief Attributes . . . . . . . . . . . . .
Extension to Another DASD Volume . . . . . .
Examples of Dynamic Volume Count When
Defining a Data Set . . . . . . . . . . .
Examples of Dynamic Volume Count When
Allocating an Existing Data Set . . . . . . .
Multiple Volume Considerations for Sequential Data
Sets . . . . . . . . . . . . . . . . .
Additional Information on Space Allocation . . .
39
39
40
40
40
41
41
42
43
43
44
Chapter 4. Backing Up and Recovering
Data Sets . . . . . . . . . . . . . 45
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 . . . . . . . . . .
. 46
.
.
.
.
47
48
48
48
49
. 49
. 49
. 50
. 50
. 52
Chapter 5. Protecting Data Sets . . . . 53
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 Password Protection . . . . . . . .
Passwords for VSAM Data Sets . . . . . . .
Passwords for Non-VSAM Data Sets . . . . .
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 . .
53
53
54
54
55
55
56
59
60
60
60
61
62
63
63
66
Part 2. VSAM Data Sets . . . . . . 69
Chapter 6. Organizing VSAM Data Sets
VSAM Data Formats .
Data Set Size . . .
Control Intervals .
iv
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
z/OS V1R6.0 DFSMS: Using Data Sets
.
.
.
.
.
.
.
.
.
.
.
.
73
. 73
. 73
. 74
Control Information Fields . . . . . . . .
Compressed Control Information Field . . . .
Control Areas. . . . . . . . . . . . .
Spanned Records . . . . . . . . . . .
Selection of VSAM Data Set Types . . . . . . .
Entry-Sequenced Data Sets . . . . . . . .
Simulated VSAM Access to UNIX files . . . .
Key-Sequenced Data Sets . . . . . . . . .
Linear Data Sets . . . . . . . . . . . .
Fixed-Length Relative-Record Data Sets . . . .
Variable-Length Relative-Record Data Sets . . .
Summary of VSAM Data Set Types . . . . .
Extended-Format VSAM Data Sets. . . . . . .
Restrictions on Defining Extended-Format Data
Sets . . . . . . . . . . . . . . . .
VSAM Data Striping . . . . . . . . . .
Compressed Data . . . . . . . . . . .
Access to Records in a VSAM Data Set . . . . .
Access to Entry-Sequenced Data Sets . . . . .
Access to Key-Sequenced Data Sets . . . . .
Access to Linear Data Sets . . . . . . . .
Access to Fixed-Length Relative-Record Data Sets
Access to Variable-Length Relative-Record Data
Sets . . . . . . . . . . . . . . . .
Access to Records through Alternate Indexes . . .
Alternate Index Structure for a Key-Sequenced
Data Set . . . . . . . . . . . . . .
Alternate Index Structure for an Entry-Sequenced
Data Set . . . . . . . . . . . . . .
Building of an Alternate Index . . . . . . .
Automatic Upgrade of Alternate Indexes . . .
Data Compression . . . . . . . . . . . .
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 . . . . . .
Defining a Path. . . . . . . . . . .
Defining a Page Space . . . . . . . . .
Checking for Problems in Catalogs and Data Sets
74
75
76
76
77
78
80
81
84
85
86
86
87
88
88
92
93
94
94
95
95
95
96
96
98
98
99
99
101
. 102
102
. 102
. 104
. 104
. 106
. 109
. 110
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
110
110
111
111
112
113
114
115
117
117
117
119
119
120
121
122
Listing Catalog Entries . . . .
Printing the Contents of Data Sets
Deleting Data Sets . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
. 122
. 123
. 123
Chapter 8. Defining and Manipulating
VSAM Data Sets: Examples . . . . . 125
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 . . . . . . . . . . . . .
126
128
128
129
129
129
130
Chapter 9. Processing VSAM Data
Sets . . . . . . . . . . . . . . . 133
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 . . . . .
.
.
.
.
.
.
134
134
135
136
138
138
. 138
. 139
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
139
139
140
142
144
145
145
145
146
147
147
148
149
149
150
151
Chapter 10. Optimizing VSAM
Performance . . . . . . . . . . . . 155
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 . . . . .
Selecting the Optimal Percentage of Free Space
Altering the Free Space Specification When
Loading a Data Set . . . . . . . . .
.
.
.
.
.
.
.
.
.
155
155
157
158
158
159
160
160
160
162
. 163
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 . . . . . . . . . . . .
164
164
165
170
170
173
174
174
175
175
175
175
176
176
176
Chapter 11. Processing Control
Intervals . . . . . . . . . . . . . 177
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 . .
.
.
.
.
.
.
178
179
180
180
184
185
. 185
. 185
. 186
. 186
Chapter 12. Sharing VSAM Data Sets
189
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 . .
. 190
. 190
. 191
.
.
.
.
.
.
.
.
.
.
.
.
193
195
195
196
197
198
199
200
201
201
201
203
204
Chapter 13. Sharing Resources
Among VSAM Data Sets . . . . . . . 205
Provision of a Resource Pool . . . . . .
Building a Resource Pool: BLDVRP . . .
Connecting a Data Set to a Resource Pool:
OPEN . . . . . . . . . . . . .
.
.
. 205
. 205
.
. 209
Contents
v
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
. 209
210
. 210
211
. 211
. 213
214
Chapter 14. Using VSAM Record-Level
Sharing . . . . . . . . . . . . . . 217
|
Controlling Access to VSAM Data Sets . . . . .
Accessing Data Sets Using DFSMStvs and VSAM
Record-Level Sharing . . . . . . . . . . .
Record-Level Sharing CF Caching . . . . .
Using VSAM RLS with CICS . . . . . . .
Using VSAM RLS Outside of CICS . . . . .
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 . .
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 . .
217
217
218
219
222
222
222
222
223
223
226
226
227
228
228
Chapter 15. Checking VSAM
Key-Sequenced Data Set Clusters for
Structural Errors . . . . . . . . . . 229
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 Tests of a Data Set
with a Structural Error . . . . . . . . .
INDEXTEST and DATATEST Tests of a Data Set
with a Duplicate Key Error . . . . . . . .
229
229
229
230
230
230
230
231
231
232
232
232
233
Chapter 16. Coding VSAM
User-Written Exit Routines. . . . . . 235
Guidelines for Coding Exit Routines . . . . . . 235
Programming Guidelines . . . . . . . . . 236
Multiple Request Parameter Lists or Data Sets
237
vi
z/OS V1R6.0 DFSMS: Using 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 . . . . . .
237
238
238
238
239
239
240
240
240
240
241
241
241
247
248
248
248
249
249
250
250
250
251
252
253
254
255
Chapter 17. Using 31-Bit Addressing
Mode with VSAM . . . . . . . . . . 257
VSAM Options .
.
.
.
.
.
.
.
.
.
.
.
. 257
Chapter 18. Using Job Control
Language for VSAM . . . . . . . . 259
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
.
.
.
.
.
.
.
.
.
.
259
259
259
260
262
.
.
.
.
.
.
.
.
263
266
266
266
Chapter 19. Processing Indexes of
Key-Sequenced Data Sets . . . . . . 269
Access to a Key-Sequenced Data Set Index . . .
Access to an Index with GETIX and PUTIX . .
Access to the Index Component Alone . . . .
Prime Index . . . . . . . . . . . . .
Index Levels . . . . . . . . . . . . .
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 . . . . .
269
269
269
270
271
273
273
275
275
276
279
280
Part 3. Non-VSAM Data Sets and
UNIX Files . . . . . . . . . . . . 281
Chapter 20. Selecting Record Formats
for Non-VSAM Data Sets . . . . . . 287
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 . . . . . . . .
287
288
289
289
290
290
292
294
296
297
297
298
300
302
305
305
306
307
307
308
309
310
Chapter 21. Specifying and Initializing
Data Control Blocks . . . . . . . . 311
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 . . .
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 . . . .
312
317
318
320
320
321
321
327
328
328
328
329
329
330
331
331
332
332
332
332
333
334
335
335
335
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 . . .
. 335
. 336
336
. 336
. 337
. 338
. 338
. 338
. 339
. 340
. 341
. 342
. 343
. 343
. 344
. 344
. 344
. 345
. 346
. 346
. 347
. 347
. 349
. 350
. 350
. 350
. 350
351
. 351
. 351
Chapter 22. Accessing Records . . . 353
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 . . .
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 . . . . . . . . . . . .
Contents
353
353
353
353
355
356
356
356
357
358
359
359
359
360
360
363
363
364
364
vii
Limitations with Using SRB or Cross-Memory
Mode . . . . . . . . . . . . . . .
. 364
Chapter 23. Sharing Non-VSAM Data
Sets . . . . . . . . . . . . . . . 365
|
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
368
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
370
370
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 . . . . . . . . . . .
Sequential Concatenation . . . . . . . .
Partitioned Concatenation . . . . . . . .
Reading a PDS Directory Sequentially . . . . .
371
371
374
374
375
375
377
. 379
. 380
. 380
viii
z/OS V1R6.0 DFSMS: Using Data Sets
.
.
.
.
.
.
.
.
.
.
.
.
. 404
. 404
. 404
Chapter 26. Processing a Partitioned
Data Set (PDS) . . . . . . . . . . . 407
Chapter 25. Processing Sequential
Data Sets . . . . . . . . . . . . . 383
Creating a Sequential Data Set . . . . . . .
Retrieving a Sequential 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 . . . . . . . . . . . . . .
. 403
369
Chapter 24. Spooling and Scheduling
Data Sets . . . . . . . . . . . . . 379
Job Entry Subsystem .
SYSIN Data Set . . .
SYSOUT Data Set . .
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 . .
383
384
385
386
390
392
392
392
393
393
394
395
395
. 396
. 397
. 398
. 399
. 400
400
400
. 401
. 402
. 403
407
408
411
411
412
412
413
413
413
414
416
416
417
420
421
422
426
426
429
429
429
429
430
Chapter 27. Processing a Partitioned
Data Set Extended (PDSE) . . . . . . 431
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 . . . . . . . . .
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 . . . . . . . . . . . .
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 . . . . . . . . . . . .
431
433
433
433
434
434
435
435
436
437
437
437
438
439
439
439
442
442
443
443
444
445
|
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 . . . . . . . .
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 . . . . . . . . . .
446
446
446
447
448
448
455
456
457
457
458
459
460
462
462
462
463
465
466
466
466
467
467
467
468
468
468
469
470
470
470
470
470
Chapter 28. Processing z/OS UNIX
Files . . . . . . . . . . . . . . . 473
Accessing the z/OS UNIX File System . . . .
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 . . . . . . . .
Creating 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 . . . . .
. 473
474
. 474
. 475
. 475
. 476
. 477
. 477
. 479
. 480
481
. 482
. 482
. 483
. 484
. 485
. 486
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 . . . . . . .
.
.
.
.
.
.
.
.
.
487
487
487
488
488
488
488
489
489
.
.
.
.
.
.
489
490
490
490
490
491
Chapter 29. Processing Generation
Data Groups . . . . . . . . . . . . 493
| Data Set Organization of Generation Data Sets . . 494
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 . . . . . . . . .
Creating an ISAM Data Set as Part of a
Generation Data Group . . . . . . . .
Retrieving a Generation Data Set . . . . . .
Reclaiming Generation Data Sets . . . . . .
Turning on GDS Reclaim Processing . . . .
Turning off GDS Reclaim Processing. . . .
Building a Generation Data Group Index . . .
. 494
. 495
. 495
. 496
. 496
.
.
.
.
.
497
498
498
501
501
. 502
.
.
.
.
.
.
502
502
503
503
503
504
Chapter 30. Using I/O Device Control
Macros . . . . . . . . . . . . . . 505
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
505
506
506
507
507
508
509
Chapter 31. Using Non-VSAM
User-Written Exit Routines . . . . . . 511
General Guidance .
.
.
.
.
.
.
.
.
.
.
Contents
. 511
ix
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 . . . . .
. 512
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
512
519
519
519
520
523
525
527
529
529
530
530
530
531
533
535
535
. 535
. 536
.
.
.
.
.
.
.
536
536
537
538
539
540
541
545
548
. 550
. 550
Appendix A. Using Direct Access
Labels . . . . . . . . . . . . . . 553
Direct Access Storage Device Architecture .
Volume Label Group . . . . . . . .
Data Set Control Block (DSCB) . . . .
User Label Groups . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
553
554
556
556
Appendix B. Using the Double-Byte
Character Set (DBCS) . . . . . . . . 559
DBCS Character Support . . .
Record Length When Using DBCS
Fixed-Length Records . . .
Variable-Length Records . . .
. . . .
Characters
. . . .
. . . .
.
.
.
.
.
.
.
.
559
559
559
560
Appendix C. Processing Direct Data
Sets . . . . . . . . . . . . . . . 561
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 . . . . . . . . . . . . . . .
x
z/OS V1R6.0 DFSMS: Using Data Sets
561
562
562
562
562
563
563
563
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 . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
563
564
565
565
565
566
566
566
566
567
567
567
568
569
569
570
Appendix D. Processing Indexed
Sequential Data Sets . . . . . . . . 571
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 . . . . . . . . . . . .
571
571
572
572
574
574
576
576
576
577
578
579
579
581
582
582
582
582
582
583
583
584
584
585
585
585
586
587
587
588
592
593
594
595
597
598
599
600
SETL—Specifying Start of Sequential Retrieval
600
ESETL—Ending Sequential Retrieval . . . . 601
Appendix E. Using ISAM Programs
with VSAM Data Sets . . . . . . . . 603
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 . . . .
604
605
609
610
612
614
615
Appendix F. Converting Character
Sets . . . . . . . . . . . . . . . 617
Coded Character Sets Sorted by CCSID.
Coded Character Sets Sorted by Default
LOCALNAME . . . . . . . . .
.
.
.
. 617
.
.
.
. 620
CCSID Conversion Groups . . . .
CCSID Decision Tables . . . . .
Tables for Default Conversion Codes
Converting from EBCDIC to ASCII
Converting from ASCII to EBCDIC
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
626
629
634
634
634
Appendix G. Accessibility . . . . . . 635
Using assistive technologies . . . . .
Keyboard navigation of the user interface .
z/OS information . . . . . . . . .
.
.
.
.
.
.
. 635
. 635
. 635
Notices . . . . . . . . . . . . . . 637
Programming interface information .
Trademarks . . . . . . . . .
.
.
.
.
.
.
.
.
. 638
. 638
Glossary . . . . . . . . . . . . . 639
Index . . . . . . . . . . . . . . . 653
Contents
xi
xii
z/OS V1R6.0 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.
DASD Volume Track Formats . . . . . . . 9
REPRO Encipher and Decipher Operations
65
VSAM Logical Record Retrieval . . . . . . 73
Control Interval Format . . . . . . . . 74
Record Definition Fields of Control Intervals
75
Data Set with Nonspanned Records . . . . 76
Data Set with Spanned Records . . . . . . 77
Entry-Sequenced Data Set . . . . . . . . 79
Example of RBAs of an Entry-Sequenced Data
Set . . . . . . . . . . . . . . . 79
Record of a Key-Sequenced Data Set . . . . 81
Inserting Records into a Key-Sequenced Data
Set . . . . . . . . . . . . . . . 82
Inserting a Logical Record into a CI . . . . 83
Fixed-length Relative-Record Data Set . . . . 85
Control Interval Size . . . . . . . . . 88
Primary and Secondary Space Allocations for
Striped Data Sets . . . . . . . . . . . 89
Control Interval in a Control Area . . . . . 90
Layering (Four-Stripe Data Set) . . . . . . 91
Alternate Index Structure for a Key-Sequenced
Data Set . . . . . . . . . . . . . . 97
Alternate Index Structure for an
Entry-Sequenced Data Set . . . . . . . . 98
VSAM Macro Relationships . . . . . . . 152
Skeleton VSAM Program. . . . . . . . 153
Control Interval Size, Physical Track Size, and
Track Capacity . . . . . . . . . . . 157
Determining Free Space . . . . . . . . 162
Scheduling Buffers for Direct Access . . . . 172
General Format of a Control Interval
179
Format of Control Information for
Nonspanned Records . . . . . . . . . 182
Format of Control Information for Spanned
Records . . . . . . . . . . . . . 183
Exclusive Control Conflict Resolution
192
Relationship Between the Base Cluster and
the Alternate Index . . . . . . . . . 194
VSAM RLS address and data spaces and
requestor address spaces . . . . . . . . 218
CICS VSAM non-RLS access . . . . . . 220
CICS VSAM RLS . . . . . . . . . . 220
Example of a JRNAD exit . . . . . . . 243
Example of a SYNAD exit routine . . . . 252
Relation of Index Entry to Data Control
Interval . . . . . . . . . . . . . 270
Relation of Index Entry to Data Control
Interval . . . . . . . . . . . . . 271
Levels of a Prime Index . . . . . . . . 272
General Format of an Index Record . . . . 273
Format of the Index Entry Portion of an
Index Record . . . . . . . . . . . 276
Format of an Index Record . . . . . . . 276
Example of Key Compression . . . . . . 279
Control Interval Split and Index Update
280
Fixed-Length Records . . . . . . . . . 288
© Copyright IBM Corp. 1987, 2004
44. Nonspanned, Format-V Records . . . . .
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 Members of a PDS Using STOW
77. BLDL List Format . . . . . . . . . .
78. DESERV GET by NAME_LIST Control Block
Structure . . . . . . . . . . . . .
290
292
295
296
299
302
303
315
316
318
321
331
332
333
345
346
348
348
349
349
362
366
367
384
385
390
391
399
408
408
409
413
415
417
418
xiii
79. DESERV GET by PDSDE Control Block
Structure . . . . . . . . . . . . .
80. DESERV GET_ALL Control Block Structure
81. Retrieving One Member of a PDS . . . . .
82. Retrieving Several Members and Subgroups
of a PDS without Overlapping I/O Time and
CPU Time. . . . . . . . . . . . .
83. Reading a Member of a PDS or PDSE using
Asynchronous BPAM . . . . . . . . .
84. Updating a Member of a PDS . . . . . .
85. A Partitioned Data Set Extended (PDSE)
86. TTRs for a PDSE Member (Unblocked
Records) . . . . . . . . . . . . .
87. TTRs for Two PDSE Members (LRECL=80,
BLKSIZE=800) . . . . . . . . . . .
88. Example of How PDSE Records Are
Reblocked. . . . . . . . . . . . .
89. Example of Reblocking When the Block Size
Has Been Changed . . . . . . . . . .
90. Creating One Member of a PDSE . . . . .
91. Adding PDSE Members Serially . . . . .
92. Replacing Multiple PDSE Members
Concurrently . . . . . . . . . . . .
93. DESERV GET by NAME_LIST Control Block
Structure . . . . . . . . . . . . .
94. DESERV GET by PDSDE Control Block
Structure . . . . . . . . . . . . .
95. DESERV GET_ALL Control Block Structure
96. DESERV GET_NAMES Control Block
Structure . . . . . . . . . . . . .
97. DESERV RELEASE Input Control Block
Structure . . . . . . . . . . . . .
98. DESERV UPDATE . . . . . . . . . .
99. ISITMGD Example . . . . . . . . . .
100. Using NOTE and FIND to Switch Between
Members of a Concatenated PDSE . . . .
101. STOW INITIALIZE Example . . . . . .
102. Retrieving One Member of a PDSE . . . .
103. Retrieving Several Members of a PDSE or
PDS . . . . . . . . . . . . . . .
104. OPEN Success/Failure . . . . . . . .
105. OPEN for UPDAT and Positioning to a
Member Decision Table . . . . . . . .
106. UNIX Directories and Files in a File System
xiv
z/OS V1R6.0 DFSMS: Using Data Sets
419
420
422
107.
108.
109.
110.
111.
424
112.
425
428
432
113.
435
114.
115.
116.
436
438
438
443
445
117.
118.
119.
120.
121.
451
452
122.
123.
124.
125.
126.
127.
128.
453
129.
454
455
456
130.
459
460
460
132.
445
450
461
463
464
474
131.
133.
134.
135.
136.
137.
138.
Creating a UNIX File with QSAM. . . . .
Edit-Entry Panel . . . . . . . . . .
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 . . . . . . .
478
484
484
485
491
518
531
534
539
541
546
549
554
555
556
564
568
569
574
575
578
588
591
593
595
596
604
627
627
627
627
628
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.
Data Management Access Methods. . . . . 15
Access Method Services Commands . . . . 16
Data Set Activity for Non-System-Managed
and System-Managed Data Sets . . . . . . 28
Differences Between Stripes in Sequential and
VSAM Data Sets . . . . . . . . . . . 39
Entry-Sequenced Data Set Processing . . . . 79
Key-Sequenced Data Set Processing . . . . 82
RRDS Processing . . . . . . . . . . . 85
Variable-Length RRDS Processing . . . . . 86
Comparison of ESDS, KSDS, Fixed-Length
RRDS, Variable-Length RRDS, and Linear Data
Sets . . . . . . . . . . . . . . . 87
Adding Data to Various Types of Output Data
Sets . . . . . . . . . . . . . . . 116
Effect of RPL Options on Data Buffers and
Positioning . . . . . . . . . . . . 145
Relationship between SHAREOPTIONS and
VSAM Functions . . . . . . . . . . 200
VSAM user-written exit routines . . . . . 236
Contents of registers at entry to IGW8PNRU
exit routine . . . . . . . . . . . . 238
Contents of registers at entry to EODAD exit
routine . . . . . . . . . . . . . . 239
Contents of registers at entry to
EXCEPTIONEXIT routine . . . . . . . 240
Contents of registers at entry to JRNAD exit
routine . . . . . . . . . . . . . . 241
Contents of parameter list built by VSAM for
the JRNAD exit . . . . . . . . . . . 245
Contents of registers at entry to LERAD exit
routine . . . . . . . . . . . . . . 248
Contents of registers for RLSWAIT exit
routine . . . . . . . . . . . . . . 249
Contents of registers at entry to SYNAD exit
routine . . . . . . . . . . . . . . 250
Conditions when exits to UPAD routines are
taken . . . . . . . . . . . . . . 253
Contents of registers at entry to UPAD exit
routine . . . . . . . . . . . . . . 253
Parameter list passed to UPAD routine
254
Communication with user-securityverification routine . . . . . . . . . . 256
31-Bit Address Keyword Parameters . . . . 258
Format of the Header of an Index Record
273
Segment Control Codes . . . . . . . . 293
Tape Density (DEN) Values . . . . . . . 307
Optimum and Maximum Block Size
Supported . . . . . . . . . . . . 324
© Copyright IBM Corp. 1987, 2004
31.
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.
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 . . . . . . . . . . . . .
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
DEB Fields Supported by ISAM Interface
DCB Fields Supported by ISAM Interface
Output DISP=NEW,OLD . . . . . . . .
Output DISP=MOD (IBM V4 tapes only)
Input . . . . . . . . . . . . . .
327
350
372
373
433
448
474
483
512
513
514
515
517
519
521
523
524
524
528
532
533
537
543
547
580
605
606
607
607
608
608
610
630
630
632
xv
xvi
z/OS V1R6.0 DFSMS: Using Data Sets
About This Document
|
|
|
|
|
|
This document is intended for system and application programmers. This
document is intended to help you use access methods to process virtual storage
access method (VSAM) data sets, sequential data sets, partitioned data sets (PDSs),
partitioned data sets extended (PDSEs), z/OS UNIX files, and generation data sets
in the DFSMS environment. This document also explains how to use access
method services commands, macro instructions, and JCL to process data sets.
For information about the accessibility features of z/OS, for users who have a
physical disability, see Appendix G, “Accessibility,” on page 635.
Major Divisions of This Document
This document is divided into four 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 Part 4 covers 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 for Catalogs 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 Reference and z/OS DFSMS:
Implementing System-Managed Storage describe storage
administration.
Macros
© Copyright IBM Corp. 1987, 2004
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 z/OS UNIX System Services User’s Guide describes how to process
Services
z/OS UNIX files.
Referenced documents
For a complete list of DFSMS documents and related z/OS documents referenced
by this document, see the z/OS Information Roadmap. You can obtain a softcopy
version of this document and other DFSMS documents from sources listed here.
This document refers to the following documents:
||
Document Title
Description
|
|
z/OS Collection, SK2T-6700
CD-ROM that includes the DFSMS library
and other z/OS element libraries.
|
|
|
http://www.ibm.com/servers/eservers
/zseries/zos
z/OS web site that includes the unlicensed
documents from DFSMS library and other
z/OS element libraries.
|
|
|
|
|
Character Data Representation Architecture
Reference and Registry
Document that includes information about
coded character set identifiers in the
character data representation architecture
repository.
Accessing z/OS DFSMS documents on the Internet
In addition to making softcopy documents available on CD-ROM, IBM provides
access to unlicensed z/OS softcopy documents on the Internet. To view, search,
and print z/OS documents, go to the z/OS Internet Library:
http://www.ibm.com/eserver/zseries/zos/bkserv/
Using LookAt to look up message explanations
LookAt is an online facility that lets you look up explanations for most of the IBM
messages you encounter, as well as for some system abends and codes. Using
LookAt to find information is faster than a conventional search because in most
cases LookAt goes directly to the message explanation.
You can use LookAt from the following locations to find IBM message
explanations for z/OS elements and features, z/VM®, and VSE:
v The Internet. You can access IBM message explanations directly from the LookAt
Web site at http://www.ibm.com/eserver/zseries/zos/bkserv/lookat/.
v Your z/OS TSO/E host system. You can install code on your z/OS or z/OS.e
systems to access IBM message explanations, using LookAt from a TSO/E
command line (for example, TSO/E prompt, ISPF, or z/OS UNIX System
Services running OMVS).
v Your Windows® workstation. You can install code to access IBM message
explanations on the z/OS Collection (SK3T-4269), using LookAt from a Windows
DOS command line.
v Your wireless handheld device. You can use the LookAt Mobile Edition with a
handheld device that has wireless access and an Internet browser (for example,
xviii
z/OS V1R6.0 DFSMS: Using Data Sets
Internet Explorer for Pocket PCs, Blazer, or Eudora for Palm OS, or Opera for
Linux handheld devices). Link to the LookAt Mobile Edition from the LookAt
Web site.
You can obtain code to install LookAt on your host system or Windows
workstation from a disk on your z/OS Collection (SK3T-4269), or from the LookAt
Web site (click Download, and select the platform, release, collection, and location
that suit your needs). More information is available in the LOOKAT.ME files
available during the download process.
Accessing z/OS licensed documents on the Internet
z/OS licensed documentation is available on the Internet in PDF format at the IBM
Resource Link™ Web site at:
http://www.ibm.com/servers/resourcelink
Licensed documents are available only to customers with a z/OS license. Access to
these documents requires an IBM Resource Link user ID and password, and a key
code. With your z/OS order you received a Memo to Licensees, (GI10-0671), that
includes this key code. 1
To obtain your IBM Resource Link user ID and password, log on to:
http://www.ibm.com/servers/resourcelink
To register for access to the z/OS licensed documents:
1. Sign in to Resource Link using your Resource Link user ID and password.
2. Select User Profiles located on the left-hand navigation bar.
Note: You cannot access the z/OS licensed documents unless you have registered
for access to them and received an e-mail confirmation informing you that
your request has been processed.
Printed licensed documents are not available from IBM.
You can use the PDF format on either z/OS Licensed Product Library CD-ROM or
IBM Resource Link to print licensed documents.
1. z/OS.e customers received a Memo to Licensees, (GI10-0684) that includes this key code.
About This Document
xix
xx
z/OS V1R6.0 DFSMS: Using Data Sets
Summary of Changes
This document contains terminology, maintenance, and editorial changes. Technical
changes or additions to the text and illustrations are indicated by a vertical line to
the left of each change.
You might notice changes in the style and structure of some content in this
document—for example, more specific headings for notes, such as Tip and
Requirement. The changes are ongoing improvements to the consistency and
retrievability of information in DFSMS documents.
Summary of Changes for SC26-7410-04 z/OS Version 1 Release 6
This document contains information that was previously presented in z/OS
DFSMS: Using Data Sets, SC26-7410-03.
The following sections summarize the changes to that information.
New Information
This edition includes the following new enhancements:
v Restartable PDSE address space. For more information, see “PDSE Address
Spaces” on page 470.
Changed Information
The following information changed in this edition:
v Corrected information about allocating space for a linear data set in “Linear
Data Sets” on page 108.
v Added information about using entry-sequenced data sets (ESDSs) with VSAM
record-level sharing to “Using VSAM RLS with ESDS” on page 227.
v Added information about using 64-bit real storage to “Constructing a Buffer
Pool” on page 342.
v Added information about using partitioned data sets (PDSs) as generation data
sets (GDS) to “Data Set Organization of Generation Data Sets” on page 494.
v Updated information about coded character set identifiers (CCSID) in
Appendix F, “Converting Character Sets,” on page 617.
v This book has been enabled for z/OS LibraryCenter advanced searches by
command name.
Summary of Changes for SC26-7410-03 z/OS Version 1 Release 5
This document contains information that was previously presented in z/OS
DFSMS: Using Data Sets, SC26-7410-02.
The following sections summarize the changes to that information.
New Information
This edition includes the following new enhancements:
v You can specify a maximum file sequence number up to 65 535 for a data set on
a tape volume.
v The JOBCAT and STEPCAT DD statements are now disabled by default.
© Copyright IBM Corp. 1987, 2004
xxi
v When the name-hiding function is in effect, you can retrieve the names of data
sets only if you have read access to the data sets or VTOC.
v VSAM automatically determines the resources required to upgrade VSAM
alternate indexes.
v Unrelated messages do not appear between the lines of a multiple-line VSAM
message, so that the operator can interpret the information more easily.
v The system consolidates adjacent extents for VSAM data sets when extending
data on the same volume.
v You can activate the enhanced data integrity function to prevent users from
concurrently opening a shared sequential data set for output or update
processing.
v You can use extended-format sequential data sets with a maximum of 59 stripes.
v You can use the basic partitioned access method (BPAM) to read z/OS UNIX
files.
v Users can specify whether to reclaim generation data sets (GDSs) automatically.
Changed Information
The following information changed in this edition:
v You must specify the directory block size when allocating of PDSE and PDS data
sets.
v The page space size limit is now 4 GB.
v You can use Integrated Cryptographic Service Facility (ICSF) with the access
method services REPRO ENCIPHER command.
v End-of-volume processing extends to the same volume or to a new volume.
v The large block interface (LBI) section has new information on writing format-U
or format-D blocks without BUFOFF=L.
v You can define a VSAM striped data set as reusable.
v The system affixes a 32-byte suffix to each block for compressed extended-format
data sets.
v Additional information on specifying normal or extended sharing for PDSEs is
provided.
v Recommendations for updating generation data groups with concurrent jobs
have been improved.
Moved Information
The following information has moved to a new location in this document:
v The information on using magnetic tape volumes is in “Magnetic Tape Volumes”
on page 11.
v The information on hierarchical file system (HFS) data sets is now in Chapter 28,
“Processing z/OS UNIX Files,” on page 473.
Summary of Changes for SC26-7410-02 z/OS Version 1 Release 3
This document contains information that was previously presented in z/OS
Version 1 Release 1 DFSMS: Using Data Sets (SC26-7410-01).
The following sections summarize the changes to that information.
New Information
This edition includes the following new information:
v Data set naming conventions
v Virtual input/output (VIO) limit
v Real addresses greater than 2 GB available for all VSAM data sets
xxii
z/OS V1R6.0 DFSMS: Using Data Sets
v Caching all or some of the VSAM record level sharing (RLS) data in a coupling
facility (CF) cache structure
v VSAM RLS system-managed duplexing rebuild process, and validity checking
for a user-managed rebuild or alter process
v Dynamic volume count for space constraint relief when you store data sets on
DASD volumes
v A summary of the effects of specifying all extents (ALX) or maximum
contiguous extents (MXIG) for virtual input/output (VIO) data sets
Changed Information
The following information changed in this edition:
v Allocation of HFS data sets requiring directory block size
v Requirements for the ENCIPHER and DECIPHER functions of the REPRO
command
v Relative byte address (RBA) in an entry-sequenced data set
v Processing techniques for VSAM system-managed buffering
v Calculating the index control interval size for a key-sequenced data set
v Extensions of VSAM data sets when you specify zero as a secondary allocation
quantity
v Sharing of non-VSAM data sets
v Use of the BYPASSLLA option with the BLDL list
v Partitioned concatenation of PDSs and PDSEs
v Processing restrictions for PDSEs
v Rules for updating a data set in place
v Conversion of the exclamation point character between EBCDIC and ASCII
v Direct insertion of records into a key-sequenced data set
v Addition of QSAM LRECL value
v Sharing of PDSEs by multiple systems in a sysplex
Summary of Changes
xxiii
xxiv
z/OS V1R6.0 DFSMS: Using Data Sets
Part 1. All Data Sets
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) . . . . . . . . . . 5
Indexed Sequential Access Method . . . . . . 5
Object Access Method . . . . . . . . . . 6
Queued Sequential Access Method . . . . . . 6
Virtual Storage Access Method . . . . . . . 6
Access to z/OS UNIX Files . . . . . . . . 7
Selection of an Access Method . . . . . . . 7
Direct Access Storage Device (DASD) Volumes . . . 8
DASD Labels . . . . . . . . . . . . . 8
Track Format . . . . . . . . . . . . . 8
Track Overflow . . . . . . . . . . . . 9
VSAM Record Addressing . . . . . . . . . 9
Actual and Relative Addressing with Non-VSAM
Access Methods . . . . . . . . . . . . 10
Actual Addresses . . . . . . . . . . 10
Relative Addresses . . . . . . . . . . 10
Magnetic Tape Volumes . . . . . . . . . . 11
Using Magnetic Tape Labels . . . . . . . . 11
Specifying the File Sequence Number . . . . . 12
Example of Creating a Tape Data Set with a
File Sequence Number Greater than 9999 . . 12
Example of Creating a Tape Data Set Using
Any File Sequence Number . . . . . . . 13
Identifying Unlabeled Tapes . . . . . . . . 14
Using Tape Marks . . . . . . . . . . . 14
Data Management Macros . . . . . . . . . 15
Data Set Processing . . . . . . . . . . . . 16
Allocating Data Sets . . . . . . . . . . 16
Access Method Services . . . . . . . . 16
ALLOCATE Command . . . . . . . . 16
JCL . . . . . . . . . . . . . . . 17
Processing Data Sets through Programs . . . . 17
Using Access Methods . . . . . . . . . . 17
Using Addressing Modes . . . . . . . . . 18
VSAM Addressing Modes . . . . . . . 18
Non-VSAM Addressing Modes . . . . . . 18
Using Hiperspace and Hiperbatch . . . . . . 18
Processing VSAM Data Sets . . . . . . . . 18
Processing PDSs, PDSEs, and UNIX Directories
19
Processing Sequential Data Sets and Members of
PDSEs and PDSs . . . . . . . . . . . 19
BSAM Processing . . . . . . . . . . 19
QSAM Processing . . . . . . . . . . 20
Processing UNIX Files with an Access Method . 20
Processing EXCP, EXCPVR, and XDAP Macros
21
Distributed Data Management (DDM) Attributes . . 21
Virtual I/O for Temporary Data Sets . . . . . . 22
Data Set Names . . . . . . . . . . . . . 22
© Copyright IBM Corp. 1987, 2004
Catalogs and Volume Table of Contents
VTOC . . . . . . . . . .
Catalogs . . . . . . . . .
Data Set Names and Metadata . .
Security of Data Set Names . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 2. Using the Storage Management
Subsystem . . . . . . . . . . . . . .
Using Automatic Class Selection Routines . . . .
Allocating Data Sets . . . . . . . . . . .
Allocating Data Sets with JCL . . . . . . .
Allocating an HFS Data Set . . . . . . .
Allocating System-Managed Data Sets . . .
Allocating Non-System-Managed Data Sets . .
Allocating System-Managed Data Sets with the
Access Method Services ALLOCATE Command .
Allocating a Data Set Using Class
Specifications . . . . . . . . . . . .
Allocating a VSAM Data Set Using Class
Specifications . . . . . . . . . . . .
Allocating a System-Managed Non-VSAM
Data Set . . . . . . . . . . . . .
Allocating a PDSE . . . . . . . . . .
Allocating a New Non-System-Managed Data
Set . . . . . . . . . . . . . . .
Allocating Data Sets with the TSO ALLOCATE
Command . . . . . . . . . . . . . .
Allocating Data Sets with Dynamic Allocation . .
Chapter 3. Allocating Space on Direct Access
Volumes . . . . . . . . . . . . . .
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 . . . . . .
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 . .
Guaranteed Space with Extended-Format Data
Sets . . . . . . . . . . . . . . .
Guaranteed Space Example . . . . . . .
Allocation of Data Sets with the Space Constraint
Relief Attributes . . . . . . . . . . . .
23
24
24
24
25
27
29
30
30
31
31
32
32
32
32
32
33
33
33
34
.
.
.
.
.
.
.
.
.
.
.
35
35
35
36
36
37
37
37
37
37
37
.
.
.
.
38
38
38
38
.
.
.
.
39
39
39
40
. 40
. 40
. 41
1
Extension to Another DASD Volume . . . . . . 41
Examples of Dynamic Volume Count When
Defining a Data Set . . . . . . . . . . . 42
Examples of Dynamic Volume Count When
Allocating an Existing Data Set . . . . . . . 43
Multiple Volume Considerations for Sequential Data
Sets . . . . . . . . . . . . . . . . . 43
Additional Information on Space Allocation . . . 44
Chapter 4. Backing Up and Recovering Data Sets
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 . . . . . . . . . . . . . .
Recovering from Errors Due to an Improperly
Closed VSAM Data Set . . . . . . . .
Using VERIFY with Catalogs . . . . . .
CICS VSAM Recovery . . . . . . . . . . .
45
46
Chapter 5. Protecting Data Sets . . . . . . .
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 Password Protection . . . . . . . .
Passwords for VSAM Data Sets . . . . . . .
Passwords to Authorize Access . . . . . .
Password-Protection Precautions . . . . .
Data Set and Catalog Protection . . . . .
Password Prompting . . . . . . . . .
Passwords for Non-VSAM Data Sets . . . . .
Assigning a Password . . . . . . . . .
Protecting a Data Set When You Define It . .
Supplying a Password for a Catalog . . . .
Handling Incorrect Passwords . . . . . .
Entering a Record in the PASSWORD Data Set
User-Security-Verification Routine . . . . . . .
Erasure of Residual Data . . . . . . . . . .
Erasing DASD Data . . . . . . . . . .
System Erasure of Data . . . . . . . .
RAMAC Virtual Array . . . . . . . . .
Erasing Tape Data . . . . . . . . . . .
Authorized Program Facility and Access Method
Services . . . . . . . . . . . . . . .
Access Method Services Cryptographic Option . .
Data Enciphering and Deciphering . . . . .
Encryption of VSAM Data Sets . . . . . .
Data Encryption Keys . . . . . . . . .
Secondary Key-Encrypting Keys . . . . .
REPRO ENCIPHER and DECIPHER on ICSF . .
53
53
53
54
54
55
55
56
56
57
58
58
59
59
59
59
60
60
60
60
60
61
61
61
2
z/OS V1R6.0 DFSMS: Using Data Sets
47
48
48
48
49
49
49
50
50
51
51
52
62
63
63
65
66
66
66
Chapter 1. Working with Data Sets
This chapter covers the following topics.
Topic
Location
Data Storage and Management
3
Access Methods
4
Direct Access Storage Device (DASD) Volumes
8
Magnetic Tape Volumes
11
Data Management Macros
15
Data Set Processing
16
Distributed Data Management (DDM) Attributes
21
Virtual I/O for Temporary Data Sets
22
Data Set Names
22
Catalogs and Volume Table of Contents
23
A data set is a collection of logically related data and can be a source program, a
library of macros, or a file of data records used by a processing program. Data
records are the basic unit of information used by a processing program. By placing
your data into volumes of organized data sets, you can save and process the data.
You can also print the contents of a data set or display the contents on a terminal.
Exception: z/OS UNIX files are different from the typical data set because they are
byte oriented rather than record oriented.
Data Storage and Management
You can store data on secondary storage devices, such as a direct access storage
device (DASD) or magnetic tape volume. The term DASD applies to disks or to a
mass storage medium on which a computer stores data. A volume is a standard
unit of secondary storage. You can store all types of data sets on DASD but only
sequential data sets on magnetic tape. Mountable tape volumes can reside in an
automated tape library. For information about magnetic tape volumes, see z/OS
DFSMS: Using Magnetic Tapes. You can also direct a sequential data set to or from
spool, a UNIX file, a TSO/E terminal, a unit record device, virtual I/O (VIO), or a
dummy data set.
Each block of data on a DASD volume has a distinct location and a unique
address, making it possible to find any record without extensive searching. You can
store and retrieve records either directly or sequentially. Use DASD volumes for
storing data and executable programs, including the operating system itself, and
for temporary working storage. You can use one DASD volume for many different
data sets, and reallocate or reuse space on the volume.
Data management is the part of the operating system that organizes, identifies,
stores, catalogs, and retrieves all the information (including programs) that your
installation uses. Data management does these main tasks:
v Sets aside (allocates) space on DASD volumes.
v Automatically retrieves cataloged data sets by name.
© Copyright IBM Corp. 1987, 2004
3
Working with Data Sets
v Mounts magnetic tape volumes in the drive.
v Establishes a logical connection between the application program and the
medium.
v Controls access to data.
v Transfers data between the application program and the medium.
System-Managed Data Sets
The Storage Management Subsystem (SMS) is an operating environment that
automates the management of storage. Storage management uses the values
provided at allocation time to determine, for example, on which volume to place
your data set, and how many tracks to allocate for it. Storage management also
manages tape data sets on mountable volumes that reside in an automated tape
library. With SMS, users can allocate data sets more easily.
The data sets allocated through SMS are called system-managed data sets or
SMS-managed data sets. For information about allocating system-managed data
sets, see Chapter 2, “Using the Storage Management Subsystem,” on page 27. If
you are a storage administrator, also see z/OS DFSMSdfp Storage Administration
Reference for information about using SMS.
Distributed File Manager
With distributed file manager (DFM) target server, applications running on a
processor with the DFM source server can create or access certain types of
SMS-managed data sets. They can also access certain types of non-SMS-managed
data sets on an System/390 processor running DFSMS, with the DFM target server.
See z/OS DFSMS DFM Guide and Reference for details about the supported data set
types and a discussion of considerations in making them available for remote
access. Also see “Distributed Data Management (DDM) Attributes” on page 21.
Access Methods
An access method defines the technique that is used to store and retrieve data.
Access methods have their own data set structures to organize data, macros to
define and process data sets, and utility programs to process data sets.
Access methods are identified primarily by the data set organization. For example,
use the basic sequential access method (BSAM) or queued sequential access
method (QSAM) with sequential data sets. However, there are times when an
access method identified with one organization can be used to process a data set
organized in a different manner. For example, a sequential data set (not
extended-format data set) created using BSAM can be processed by the basic direct
access method (BDAM), and vice versa. Another example is UNIX files, which you
can process using BSAM, QSAM, basic partitioned access method (BPAM), or
virtual storage access method (VSAM).
Basic Direct Access Method
BDAM arranges records in any sequence your program indicates, and retrieves
records by actual or relative address. If you do not know the exact location of a
record, you can specify a point in the data set where a search for the record is to
begin. Data sets organized this way are called direct data sets.
Optionally, BDAM uses hardware keys. Hardware keys are less efficient than the
optional software keys in virtual sequential access method (VSAM).
4
z/OS V1R6.0 DFSMS: Using Data Sets
Working with Data Sets
Related reading: See the following material:
v “Track Format” on page 8
v Appendix C, “Processing Direct Data Sets,” on page 561
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 sequential data sets
v extended-format data sets
v z/OS UNIX files
Data-in-Virtual (DIV)
The data-in-virtual (DIV) macro provides access to VSAM linear data sets. For
more information, see z/OS MVS Programming: Assembler Services Guide.
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 that
ISAM processes are called indexed sequential data sets. ISAM arranges records in
sequence by key fields, and retrieves records by key. The structure of multilevel
indexes in ISAM is similar to the structure of indexes in VSAM.
Chapter 1. Working with Data Sets
5
Working with Data Sets
Recommendation: Do not use ISAM. The system supports ISAM only for
compatibility with other IBM operating systems. You should plan to convert all
indexed sequential data sets to VSAM data sets. Indexed sequential data sets
cannot be system managed. See Appendix D, “Processing Indexed Sequential Data
Sets,” on page 571.
Object Access Method
Object access method (OAM) processes very large, named byte streams (objects)
that have no record boundary or other internal orientation. These objects can be
recorded in a DB2 database or on an optical storage volume. For information about
OAM, see z/OS DFSMS OAM Application Programmer’s Reference and z/OS DFSMS
OAM Planning, Installation, and Storage Administration Guide for Object Support.
Queued Sequential Access Method
QSAM arranges records sequentially in the order that they are entered to form
sequential data sets, which are the same as those data sets that BSAM creates. The
system organizes records with other records. QSAM anticipates the need for
records based on their order. To improve performance, QSAM reads these records
into storage before they are requested. This is called queued access. You can use
QSAM with the following data types:
v sequential data sets
v extended-format data sets
v z/OS UNIX files
Virtual Storage Access Method
VSAM arranges records by an index key, relative record number, or relative byte
addressing. VSAM is used for direct or sequential processing of fixed-length and
variable-length records on DASD. Data that is organized by VSAM is cataloged for
easy retrieval and is stored in one of five types of data sets.
v Entry-sequenced data set (ESDS). Contains records in the order in which they
were entered. Records are added to the end of the data set and can be accessed.
v Key-sequenced data set (KSDS). Contains records in ascending collating
sequence. Records can be accessed by a field, called a key, or by a relative byte
address.
v Linear data set (LDS). Contains data that has no record boundaries. Linear data
sets contain none of the control information that other VSAM data sets do.
Linear data sets must be cataloged in a catalog.
v Relative record data set (RRDS). Contains records in relative record number
order, and the records can be accessed only by this number. There are two types
of relative record data sets.
– Fixed-length RRDS: The records must be of fixed length.
– Variable-length RRDS: The records can vary in length.
Throughout this document, the term RRDS refers to both types of relative record
data sets, unless they need to be differentiated.
v z/OS UNIX files. A UNIX file can be accessed as if it were a VSAM
entry-sequenced data set (ESDS). Although UNIX files are not actually stored as
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.
6
z/OS V1R6.0 DFSMS: Using Data Sets
Working with Data Sets
Any type of VSAM data set can be in extended format. Extended-format data sets
have a different internal storage format than data sets that are not extended. This
storage format gives extended-format data sets additional usability characteristics
and possibly better performance due to striping. You can choose for an
extended-format key-sequenced data set to be in the compressed format.
Extended-format data sets must be SMS managed. You cannot use an
extended-format data set for certain system data sets.
Recommendation: Do not use BISAM or QISAM. Use VSAM instead.
Access to z/OS UNIX Files
Programs can access the information in UNIX files through z/OS UNIX System
Services (z/OS UNIX) calls, such as open(pathname), read(file descriptor), and
write(file descriptor). Programs can also access the information in UNIX files
through the BSAM, BPAM, QSAM, and VSAM access methods. When you use
BSAM or QSAM, a UNIX file is simulated as a single-volume sequential data set.
When you use VSAM, a UNIX file is simulated as an ESDS. When you use BPAM,
a UNIX directory and its files are simulated as a partitioned data set directory and
its members.
You can use the following types of UNIX files with the access methods:
v Regular files, including files accessed through Network File System (NFS),
temporary file system (TFS), HFS, or zSeries file system (zFS)
v Character special files
v First-in-first-out (FIFO) special files
v Symbolic links
Restriction: You cannot use the following types of UNIX files with the access
methods:
v UNIX directories, except indirectly through BPAM
v External links
Files can reside on other systems. The access method user can use NFS to access
them.
Selection of an Access Method
In selecting an access method for a data set, consider the organization of the data
set, what you need to specify through macros, and the device type:
v VSAM data sets, PDSEs, PDSs, extended-format data sets, direct data sets,
indexed sequential 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.
Chapter 1. Working with Data Sets
7
Working with Data Sets
See z/OS TSO/E Command Reference for information about using BSAM and QSAM
to read from and write to a TSO/E terminal in line mode.
Direct Access Storage Device (DASD) Volumes
Although DASD volumes differ in physical appearance, capacity, and speed, they
are similar in data recording, data checking, data format, and programming. The
recording surface of each volume is divided into many concentric tracks. The
number of tracks and their capacity vary with the device. Each device has an
access mechanism that contains read/write heads to transfer data as the recording
surface rotates past them.
DASD Labels
The operating system uses groups of labels to identify DASD volumes and the
data sets they contain. Application programs generally do not use these labels
directly. DASD volumes must use standard labels. Standard labels include a
volume label, a data set label for each data set, and optional user labels. A volume
label, stored at track 0 of cylinder 0, identifies each DASD volume.
A utility program initializes each DASD volume before it is used on the system.
The initialization program generates the volume label and builds the volume table
of contents (VTOC). The VTOC is a structure that contains the data set labels.
See Appendix A, “Using Direct Access Labels,” on page 553 for information about
direct access labels.
Track Format
Information is recorded on all DASD volumes in a standard format. This format is
called count-key data (CKD) or extended count-key data (ECKD).
Each track contains a record 0 (also called track descriptor record or capacity
record) and data records. Historically, S/390 hardware manuals and software
manuals have used inconsistent terminology to refer to units of data written on
DASD volumes. Hardware manuals call them records. Software manuals call them
blocks and use “record” for something else. The DASD sections of this document
use both terms as appropriate. Software records are described in Chapter 6,
“Organizing VSAM Data Sets,” on page 73 and Chapter 20, “Selecting Record
Formats for Non-VSAM Data Sets,” on page 287.
For these data formats, one or more of the following is true:
v Each VSAM control interval consists of one or more contiguous blocks. Control
intervals are grouped into control areas.
v Each non-VSAM block contains part of a record or one or more records.
Examples of these programming interfaces are BSAM, BDAM, and EXCP.
v Each VSAM record occupies multiple control intervals or all or part of a control
interval. Each non-VSAM record occupies multiple blocks or all or part of a
block. An example is QSAM.
v The application program might regard byte streams as being grouped in records.
The program does not see blocks. Examples of such programs include UNIX
files and OAM objects.
8
z/OS V1R6.0 DFSMS: Using Data Sets
Working with Data Sets
The process of grouping records into blocks is called blocking. The extraction of
records from blocks is called unblocking. Blocking or unblocking might be done by
the application program or the operating system. In z/OS UNIX, blocking means
suspension of program execution.
Although IBM does not recommend the use of ISAM, BDAM and ISAM use the
data area of record zero to contain information about the remaining space on the
track. BDAM uses the track descriptor record to contain the number of empty
bytes following the last user data record on the track. ISAM uses the track
descriptor record for that purpose for variable-length format data sets.
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
Key
Track Descriptor
Record (RO)
Block (R1)
Data
...
Count
Key
Data
Block (Rn)
Figure 1. DASD Volume Track Formats
Count-Data Format: Records are formatted without keys. The key length is 0. The
count area contains 8-bytes that identify the location of the block by cylinder, head,
and record numbers, and its data length.
Count-Key-Data Format: The blocks are written with hardware keys. The key area
(1 - 255 bytes) contains a record key that specifies the data record, such as the part
number, account number, sequence number, or some other identifier.
In data sets, only ISAM, 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 77.
Chapter 1. Working with Data Sets
9
Working with Data Sets
Actual and Relative Addressing with Non-VSAM Access
Methods
With certain access methods, you can access data non-sequentially. You can use
addresses to identify block locations. Use two types of addresses to store and
retrieve data on DASD volumes: actual addresses and relative addresses. When
sequentially processing a multiple volume data set with a BSAM DCB, except for
extended-format data sets, you can refer to only records of the current volume.
Actual Addresses
When the system returns the actual address of a block on a direct access volume to
your program, it is in the form MBBCCHHR, in which the characters represent the
following values:
M
BBCCHH
R
1-byte binary number specifying the relative extent number. Each extent is a set
of consecutive tracks allocated for the data set.
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.
1-byte binary number specifying the relative block number on the track. The
block number is also recorded in the count area.
If your program stores actual addresses in your data set, and you refer to those
addresses, the data set must be treated as unmovable. Data sets that are
unmovable cannot reside on system-managed volumes.
If you store actual addresses in another data set, those addresses become nonvalid
if the first data set is moved or migrated. Although you can mark the data set with
the unmovable attribute in DSORG, that prevents the data set from being SMS
managed.
Relative Addresses
BDAM, BSAM, BPAM, and ISAM use relative block addresses and relative track
addresses. BDAM uses relative block addresses. BSAM (except with
extended-format data sets), BPAM, and BDAM use relative track addresses. ISAM
records are accessed by key or sequentially.
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.
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.
The relative track address has the form TTR:
TT
R
10
An unsigned 2-byte binary number specifying the position of the track starting
from the first track allocated for the data set. The TT for the first track is 0.
Allocation of noncontiguous sets of tracks does not affect the TT number.
1-byte binary number specifying the number of the block starting from the first
block on the track TT. The R value for the first block of data on a track is 1.
z/OS V1R6.0 DFSMS: Using Data Sets
Working with Data Sets
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 in which the three high-order bytes are the BLT value and
the fourth byte is a zero. 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 435 for a description of TTRs for PDSE members and
blocks.
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.
Magnetic Tape Volumes
This section discusses using tape labels and specifying the file sequence number
for data sets that are stored on magnetic tape volumes.
Because data sets on magnetic tape devices must be organized sequentially, the
procedure for allocating space is different from allocating space on DASD. All data
sets that are stored on a given magnetic tape volume must be recorded in the same
density. See z/OS DFSMS: Using Magnetic Tapes for information about magnetic
tape volume labels and tape processing.
Related reading: For information about nonstandard label processing routines, see
z/OS DFSMS Installation Exits.
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,
Chapter 1. Working with Data Sets
11
Working with Data Sets
even though the two computers can be products of different manufacturers. IBM
standard labels are coded in the extended binary-coded-decimal interchange code
(EBCDIC). ISO/ANSI labels are coded in the American National Standard Code for
Information Interchange (ASCII).
Specifying the File Sequence Number
When a new data set is to be placed on a magnetic tape volume, you must specify
the file sequence number if the data set is not the first one on the reel or cartridge.
The maximum value of the file sequence number of a data set on a tape volume is
65 535 for the following tapes:
v Standard label (SL) tapes
v Standard user label (SUL) tapes
v Leading tape mark (LTM) tapes
v Unlabeled (NL) tapes
v Bypass label processing (BLP) tapes
Restriction: The ISO/ANSI (AL) labeled tapes do not allow a file sequence
number greater than 9999.
Related reading: For additional information about using file sequence numbers,
see z/OS DFSMSdfp Using DFSMSdfp in the z/OS V1R6 Environment and z/OS
DFSMS: Using Magnetic Tapes.
You can specify the file sequence number in one of the following ways:
v Code the file sequence number as the first value of the LABEL keyword on the
DD statement or using the DYNALLOC, macro for dynamic allocation. The
maximum file sequence number is 9999 when it is specified this way.
v Catalog each data set using the appropriate file sequence number and volume
serial number. If you use IDCAMS, IEHPROGM, or the CATALOG macro, the
maximum file sequence number is 65 535. Issue the OPEN macro because the
catalog provides the file sequence number.
If you use DISP=(,CATLG), the maximum file sequence number is 9999. OPEN
uses the file sequence number from the catalog if you do not specify it on the
DD statement or dynamic allocation.
v 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
12
z/OS V1R6.0 DFSMS: Using Data Sets
Working with Data Sets
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
CLOSE DCBAD
CLOSE FILE
. . .
DCBAD DCB
DDNAME=DD1,DSORG=PS,EXLST=LSTA,MACRF=PM,LRECL=80,RECFM=FB
LSTA
DS
0F
RJFCB EXIT LIST
DC
X'87’
CODE FOR JFCB
DC
AL3(JFCBAREA)
POINTER TO JFCB AREA
JFCBAREA DS
XL176
JFCB AREA
IEFJFCBN
DEFINE THE JFCB FIELDS
RECORD
DC
CL80’RECORD10011’
RECORD AREA
END
//* JCL FOR ALLOCATING TAPE DATA SET
//DD1
DD DSN=DATASET1,UNIT=TAPE,VOL=SER=TAPE01,DISP=(NEW,CATLG),
//
LABEL=(1,SL)
Result: The output displays information about the new tape data set with a file
sequence number of 10 011:
IEC205I DD1,OCEFS005,G.STEP05,FILESEQ=10011, COMPLETE VOLUME LIST,
DSN=DS10011,VOLS=TAPE01,TOTALBLOCKS=1
Example of Creating a Tape Data Set Using Any File Sequence
Number
You can use the previous example with OPEN, TYPE=J to create a tape data set
with a file sequence number of 9999, if you change the L 6,10011 line to L 6,9999.
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 *
Chapter 1. Working with Data Sets
13
Working with Data Sets
STCM
CVD
UNPK
OI
MVC
5,B'0011’,JFCBAREA+68
STORE NEW FSN IN JFCB
5,WORKAREA
UPDATE DSNAME
JFCBAREA+2(5),WORKAREA(8)
LOAD JFCB
JFCBAREA+6,X'F0’
SET DSfsn
RECORD+6(5),JFCBAREA+2
MOVE FSN INTO RECORD
*
RECORD FORMAT IS ’RECORDfsn’
OPEN (DCBAD, (OUTPUT)),TYPE=J CREATE FILE NUMBER
PUT DCBAD,RECORD
WRITE RECORD
CLOSE (DCBAD,LEAVE)
CLOSE FILE NUMBER
CONTIN
EQU *
RDJFCB (DCBAD)
READ JFCB
SR
5,5
ICM
5,B’0011’,JFCBAREA+68
GET CURRENT FSN
LA
5,1(5)
INCREMENT FSN
BCT
6,LOOP
CONTINUE PROCESSING UNTIL DONE
. . .
* DEFINITIONS
DS
0D
SAVE
DC
18F’0’
DCBAD DCB DDNAME=DD1,DSORG=PS,EXLST=LSTA,MACRF=PM,BLKSIZE=80,RECFM=F
LSTA
DS
0F
RJFCB EXIT LIST
DC
X’87’
DC
AL3(JFCBAREA)
JFCBAREA DC
50F’0’
JFCB AREA
RECORD
DC
CL80’RECORD’
RECORD AREA
DS
0D
WORKAREA DC
2F’0’
WORK AREA
END
/*
* JCL FOR ALLOCATING TAPE DATA SET
Result: This excerpt from the output shows information about the tape data set
with a file sequence number of 9999:
IEC205I DD1,OCEFS001,G.STEP06,FILESEQ=09999, COMPLETE VOLUME LIST,
DSN=DS09999,VOLS=TAPE01,TOTALBLOCKS=1
Identifying Unlabeled Tapes
When you want to store a data set on unlabeled tape volumes, the system needs a
volume serial number to identify each volume. If the data set is in an automatic
tape library, the system uses the volume serial number that is encoded in the bar
code on the outside of each cartridge. If the data set is not in an automatic tape
library, it is advisable to specify enough volume serial numbers to contain the data
set. If you do not specify any volume serial numbers or do not specify enough of
them, the system or a tape management system assigns a serial number to each
unidentified volume. If the system assigns a serial number, the serial number is in
the form Lxxxyy, in which xxx is the data set sequence number and yy is the
volume sequence number for the data set.
If you want to catalog or pass data sets that reside on unlabeled volumes, specify
the volume serial numbers for the required volumes. Specifying the volume serial
numbers ensures that data sets residing on multiple volumes are not cataloged or
passed with duplicate volume serial numbers. Retrieving such data sets can give
unpredictable errors.
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
14
z/OS V1R6.0 DFSMS: Using Data Sets
Working with Data Sets
marks. Two tape marks follow the last trailer label group on a standard-label
volume. On an unlabeled volume, the two tape marks appear after the last data
set.
When a program writes data on a nonstandard labeled tape, the installation must
supply routines to process labels and tape marks and to position the tape. If you
want the system to retrieve a data set, the installation routine that creates
nonstandard labels must write tape marks. Otherwise, tape marks are not required
after nonstandard labels because installation routines manage positioning of the
tape volumes.
Data Management Macros
You can use macros to process all the data set types supported by the access
methods just described. Macros control data set allocation, input and output, the
buffering techniques used, and data security. See z/OS DFSMS Macro Instructions
for Data Sets for information about data management macros. See z/OS DFSMSdfp
Advanced Services for information about system programming macros.
Table 1 contains a summary of data management access methods:
Table 1. Data Management Access Methods
Data Set Organization
Access Methods
Direct
BDAM
ESDS
VSAM
Indexed Sequential
BISAM
KSDS
VSAM
LDS
VSAM
DIV1
Partitioned2
BPAM
BSAM3
4
VSAM
RRDS
Sequential
UNIX file
5
6
BSAM
BSAM
QISAM
QSAM
QSAM
7
QSAM7
BPAM
VSAM8
Notes:
1. The data-in-virtual (DIV) macro, which is used to access a linear data set, is
described in z/OS MVS Programming: Assembler Services Guide.
2. PDSs and PDSEs are both partitioned organization data sets.
3. BSAM and QSAM cannot be used to create or modify user data in directory
entries.
4. Refers to fixed-length and variable-length RRDSs.
5. Sequential data sets and extended-format data sets are both sequential
organization data sets.
6. A UNIX file can be in any type of z/OS UNIX file system such as HFS, NFS,
TFS, or zFS.
7. When you access a UNIX file with BSAM or QSAM, the file is simulated as a
single-volume sequential data set.
8. When you access a UNIX file with VSAM, the file is simulated as an ESDS.
Chapter 1. Working with Data Sets
15
Working with Data Sets
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.
Recommendation: Do not use these non-VSAM macros:
DCB (BDAM, BISAM, QISAM)
ESETL
FREEDBUF
GET (QISAM)
PUT (QISAM)
READ (BDAM, BISAM)
RELEX
SETL
WRITE (BDAM, BISAM)
Data Set Processing
To process a data set, first allocate it (establish a link to it), then access the data
using macros for the access method that you have chosen. For information about
accessing UNIX files, see “Processing UNIX Files with an Access Method” on page
20.
Allocating Data Sets
Allocate means either or both of two things:
v To set aside (create) space for a new data set on a disk.
v To establish a logical link between a job step and any data set.
Related reading: For information about dynamic allocation, see z/OS MVS
Programming: Authorized Assembler Services Guide.
You can use any of the following methods to allocate a data set.
Access Method Services
You can define data sets and establish catalogs by using a multifunction services
program called access method services. Use the following commands with all data
sets.
Table 2. Access Method Services Commands
Command
Description
ALLOCATE
Allocate a new data set
ALTER
Change the attributes of a data set
DEFINE NONVSAM
Catalog a data set
DELETE
Delete a data set
LISTCAT
List catalog entries
PRINT
Print a data set
ALLOCATE Command
You can issue the ALLOCATE command either through access method services or
TSO/E to define VSAM and non-VSAM data sets.
16
z/OS V1R6.0 DFSMS: Using Data Sets
Working with Data Sets
JCL
All data sets can be defined directly through JCL.
Related reading: For information about access method services commands see
z/OS DFSMS Access Method Services for Catalogs. For information about TSO
commands, see z/OS TSO/E Command Reference. For information about using JCL,
see z/OS MVS JCL Reference and z/OS MVS JCL User’s Guide.
Processing Data Sets through Programs
Programs process data sets in the following sequence:
1. Allocate the data set to establish the logical link between a program and a data
set. You can do this either outside the program with JCL or the TSO
ALLOCATE command or inside the program with dynamic allocation.
2. Open the data set, identifying it with a DDNAME.
3. Do reads and writes using an access method.
4. Close the data set.
5. Deallocate the data set. There are three ways to do this:
v For non-VSAM data sets only, specifying FREE=CLOSE when closing the
data set. (The FREE=CLOSE parameter is ignored for VSAM data sets.)
v Your program can call dynamic deallocation.
v During the step termination process, the operating system automatically
deallocates any remaining allocated data sets.
Using Access Methods
All the access methods described in this document allow you to do the following:
v Share a data set among different systems, different jobs in a single system,
multiple access method control blocks (ACBs) or data control blocks (DCBs) in a
task, or different subtasks in an address space. See Chapter 12, “Sharing VSAM
Data Sets,” on page 189 for information about sharing a VSAM data set. See
Chapter 23, “Sharing Non-VSAM Data Sets,” on page 365 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 205.
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 511 and Chapter 16, “Coding VSAM User-Written Exit
Routines,” on page 235.
v Back up and recover data sets. See Chapter 4, “Backing Up and Recovering Data
Sets,” on page 45.
v Maintain data security and integrity. See Chapter 5, “Protecting Data Sets,” on
page 53.
BSAM, QSAM, BPAM, and VSAM convert between record-oriented data and
byte-stream oriented data that is stored in UNIX files.
Non-VSAM access methods also let you:
v Convert non-VSAM data from ASCII to EBCDIC, and the reverse.
v Position and reposition tape volumes automatically.
v Process user labels for data sets on DASD and magnetic tape.
Chapter 1. Working with Data Sets
17
Working with Data Sets
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 257.
Non-VSAM Addressing Modes
You can run most BSAM, BPAM, QSAM, and BDAM macros in 24-bit or 31-bit
addressing mode. Data to which the macros refer must reside below the 16 MB line
if you run the macro in 24-bit mode.
The BSAM, BPAM, QSAM, and BDAM access methods let you create certain data
areas, buffers, certain user exits, and some control blocks in virtual storage above
the 16 MB line if you run the macro in 31-bit mode. See z/OS DFSMS Macro
Instructions for Data Sets.
Using Hiperspace and Hiperbatch
Hiperbatch can significantly reduce the execution time of batch job streams that
access QSAM or VSAM data sets. Hiperspace improves the performance for VSAM
applications that use local shared resources (LSR). Batch LSR lets you use the
advantages of Hiperspace for VSAM applications that use nonshared resources
without changing the application. See “Using Hiperbatch” on page 400 and “Using
Hiperspace Buffers with LSR” on page 206.
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.
18
z/OS V1R6.0 DFSMS: Using Data Sets
Working with Data Sets
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),...
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 439.
v You can use the STOW macro to add, delete, change, or replace a member name
or alias in the PDS or PDSE directory, or clear a PDSE directory. You can also
use the STOW macro to delete all the members of a PDSE. However, you cannot
use the STOW macro to delete all the members of a PDS. For program libraries,
you cannot use STOW to add or replace a member name or alias in the
directory.
v You can read multiple members of PDSs, PDSEs, or UNIX directories by passing
a list of members to BLDL; then use the FIND macro to position to a member
before processing it.
v You can code a DCBE and use 31-bit addressing for BPAM.
v PDSs, PDSEs, members, and UNIX files cannot use sequential data striping. See
Chapter 26, “Processing a Partitioned Data Set (PDS),” on page 407 and
Chapter 27, “Processing a Partitioned Data Set Extended (PDSE),” on page 431.
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.
Chapter 1. Working with Data Sets
19
Working with Data Sets
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.
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
The most common type of UNIX file system is the hierarchical file system. A HFS
data set contains a hierarchical file system. Examples of other types of UNIX file
systems are Network File System (NFS), temporary file system (TFS), and zSeries
File System (zFS). 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
20
z/OS V1R6.0 DFSMS: Using Data Sets
Working with Data Sets
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 MVS or non-MVS. 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.
Related Reading: For more information about the following topics, see:
v Chapter 28, “Processing z/OS UNIX Files,” on page 473
v “Simulated VSAM Access to UNIX files” on page 80
v For information on coding the DCB and DCBE macros for BSAM, QSAM,
BPAM, and EXCP, see z/OS DFSMS Macro Instructions for Data Sets.
Processing EXCP, EXCPVR, and XDAP Macros
It is possible to control an I/O device directly while processing a data set with
almost any data organization without using a specific access method. The EXCP
(execute channel program), EXCPVR, and XDAP macros use the system function
that provides for scheduling and queuing I/O requests, efficient use of channels
and devices, data protection, interruption procedures, error recognition, and retry.
See z/OS DFSMSdfp Advanced Services for information about the EXCP, EXCPVR,
and XDAP macros.
Guideline: Do not use the EXCP and XDAP macros to access data. These macros
cannot be used to process PDSEs, extended-format data sets, VSAM data sets,
UNIX files, dummy data sets, TSO/E terminals, spooled data sets, or OAM objects.
The use of EXCP, EXCPVR, and XDAP require detailed knowledge of channel
programs, error recovery, and physical data format. Use BSAM, QSAM, BPAM, or
VSAM instead of the EXCP and XDAP macros to access data.
Distributed Data Management (DDM) Attributes
Distributed file manager is the z/OS implementation of Systems Application
Architecture (SAA) distributed data management (DDM). Distributed file manager
facilitates access by programs running on non-MVS systems to data sets stored on
an MVS 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.
Chapter 1. Working with Data Sets
21
Working with Data Sets
Distributed file manager also provides the ability to process data sets along with
their associated attributes. Any DDM attributes associated with a data set cannot
be propagated with the data set unless DFSMShsm uses DFSMSdss as its data
mover. See z/OS DFSMS DFM Guide and Reference for information about the DDM
file attributes.
Virtual I/O for Temporary Data Sets
Temporary data sets can be handled by a function called virtual I/O (VIO). Data
sets for which VIO is specified are located in external page storage. However, to
the access methods, the data sets appear to reside on real direct access storage
devices. A VIO data set must be a non-VSAM data set; it can be sequential,
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:
22
z/OS V1R6.0 DFSMS: Using Data Sets
Working with Data Sets
v If quotation marks delimit a data set name in a JCL DD statement, JCL
processing cannot perform syntax checking on the statement, and SMS rejects
the input based on its parsing of the data set name. SMS does not allow the
name to be catalogued because quoted data sets cannot be SMS managed.
v IDCAMS does not allow the specification of non-valid data set names.
v When you invoke Dynamic Allocation services or directly invoke SVC 26, it is
possible to create data set names that are not valid. When the CATALOG routine
is called to add the data set to a catalog, there is no way to determine whether
the original name was in JCL or whether quotation marks delimit the name. The
catalog component validates the syntax of a data set name and fails the request
if the syntax is not valid, unless the syntax-checking option for data set names is
off. See the description of the MODIFY CATALOG command’s DSNCHECK
parameter in z/OS DFSMS: Managing Catalogs.
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 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 102 and “Naming an Alternate Index” on page
117 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.
Chapter 1. Working with Data Sets
23
Working with 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 553.
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 a data set control block (DSCB) from a
VTOC.
CVAF macros
Reads a VTOC and VTOC index. These macros are
CVAFDIR, CVAFDSM, CVAFFILT, CVAFSEQ, and
CVAFTST.
|
|
|
|
RDJFCB macro
You can use the RDJFCB macro to learn the name
of a data set and the volume serial number of a
VSAM data set. You also can use RDJFCB with the
OPEN TYPE=J macro to read a VTOC. When you
use the RDJFCB macro, use a DCB and the exit list
for the DCB because using an ACB and VSAM exit
list would not work.
|
OPEN TYPE=J macro
Can be used to open and read a VTOC. This macro
supplies a job file control block (JFCB), which
represents the information in the DD statement.
VSAM does not support OPEN TYPE=J.
LOCATE macro
Locates and extracts information from catalogs.
24
z/OS V1R6.0 DFSMS: Using Data Sets
Working with Data Sets
Catalog search interface
Locates and extracts information from catalogs. For
more information, see z/OS DFSMS: Managing
Catalogs.
Related reading: For more information on these macros, see z/OS DFSMSdfp
Advanced Services.
The utility and service aid programs include:
ISPF
A full-screen editor and dialog manager, it
generates standard screen panels and interactive
dialogues between the application programmer and
terminal user. For more information, see z/OS ISPF
User’s Guide.
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 24. For more
information, see “Hiding Data Set Names” on page 55.
Chapter 1. Working with Data Sets
25
26
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 2. Using the Storage Management Subsystem
This chapter covers the following topics.
Topic
Location
Using Automatic Class Selection Routines
29
Allocating Data Sets
30
When you allocate or define a data set to use SMS, you specify your data set
requirements by using a data class, a storage class, and a management class.
Typically, you do not need to specify these classes because a storage administrator
has set up automatic class selection (ACS) routines to determine which classes to
use for a data set.
Descriptions of the classes follow:
v A data class is a named list of data set allocation and space attributes that SMS
assigns to a data set when it is allocated. You can also use a data class with a
non-system-managed data set.
v A storage class is a named list of data set service or performance objectives that
SMS uses to identify performance and availability requirements for data sets.
The object access method (OAM) uses storage classes to control the placement of
objects in an object storage hierarchy. Each data set has a storage class if and
only if the data set is SMS-managed.
v A management class is a named list of management attributes that DFSMShsm
uses to control action for retention, migration, backup, and release of allocated
but unused space in data sets. OAM uses management classes to control action
for the retention, backup, and class transition of objects in an object storage
hierarchy. DFSMSrmm can use the management class name assigned to a tape
data set to identify a policy which should be used to manage the data set. For
non-system-managed tape data sets, DFSMSrmm calls the management class
ACS routine. See z/OS DFSMSrmm Implementation and Customization Guide.
Your storage administrator defines the attributes of each class in an SMS
configuration. An SMS configuration is a complete set of definitions, ACS routines,
and other system information SMS uses to manage your data sets. The definitions
group data sets according to common characteristics. As you allocate new data
sets, the ACS routines assign those characteristics. With the information contained
in the SMS configuration, SMS manages your data sets most effectively with a
knowledgeable use of the available hardware. See z/OS DFSMSdfp Storage
Administration Reference for information about using SMS classes and managing
data sets and volumes.
The Storage Management Subsystem (SMS) can manage tape data sets on native
volumes in a tape library and on the logical volumes in a Virtual Tape Server
(VTS). DFSMSrmm provides some services for the stacked volumes contained in a
Virtual Tape Server. See z/OS DFSMSrmm Implementation and Customization Guide.
Some requirements for using SMS follow:
v Extended-format data sets and compressed-format data sets must be system
managed.
© Copyright IBM Corp. 1987, 2004
27
Using the Storage Management Subsystem
v SMS must be active when you allocate a new data set to be SMS managed.
v Job steps in which a JOBCAT or STEPCAT DD statement is used cannot use
system-managed data sets.
v Your storage administrator must be aware that ACS routines are used for data
sets created with distributed file manager (DFM). These data sets must be
system managed. If the storage class ACS routine does not assign a storage class,
distributed file manager deletes the just-created data set, because distributed file
manager does not create non-system-managed data sets. Distributed file
manager does, however, access non-system-managed data sets.
Table 3 lists the storage management functions and products you can use with
system-managed and non-system-managed data sets. For details, see z/OS
DFSMSdfp Storage Administration Reference.
Table 3. Data Set Activity for Non-System-Managed and System-Managed Data Sets
Activity Allocation
Non-System-Managed Data
System-Managed Data
Data placement
JCL, storage pools
ACS, storage groups
Allocation control
Software user installation
exits
ACS
Allocation authorization,
definition
RACF3, 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
Not available
JCL (PATH=)
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
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 Guide for information about using DFSMSdss.
2. DFSMShsm: Manages space, migrates data, and backs up data through SMS classes and
groups. See z/OS DFSMShsm Managing Your Own Data for information about using
DFSMShsm.
3. RACF: Controls access to data sets and use of system facilities.
The following types of data sets cannot be system managed:
v Data sets having the same name as an already cataloged data set
v DASD data sets not cataloged
28
z/OS V1R6.0 DFSMS: Using Data Sets
Using the Storage Management Subsystem
v Unmovable data sets (DSORG is xxU) except when set by a checkpoint function
v Data sets with absolute track allocations (ABSTR value for SPACE parameter on
DD statement)
v ISAM data sets
v Tape data sets
v Spooled data sets
Direct data sets (BDAM) can be system-managed but if a program uses OPTCD=A,
the program might become dependent on where the data set is on the disk. For
example, the program might record the cylinder and head numbers in a data set.
Such a data set should not be migrated or moved. You can specify a management
class that prevents automatic migration.
Tape volumes in a system-managed tape library can be managed as
system-managed storage classes.
Using Automatic Class Selection Routines
ACS routines determine if a data set is system managed and which classes are to
be used.
You can use a storage class and a management class only with system-managed
data sets. You can use a data class for data sets that are either system managed or
not system managed, and for data sets on either DASD or tape volumes. SMS can
manage tape data sets on physical volumes in a tape library and on the logical
volumes in a Virtual Tape Server (VTS). DFSMSrmm provides some services for
the stacked volumes contained in a Virtual Tape Server (see z/OS DFSMSrmm
Implementation and Customization Guide). Your storage administrator defines the data
classes, storage classes, and management classes your installation will use. Your
storage administrator provides a description of each named class, including when
to use the class.
Recommendation: Your storage administrator must code storage class ACS
routines to ensure data sets allocated by remote applications using distributed file
management are system managed.
Using a data class, you can easily allocate data sets without specifying all of the
data set attributes normally required. Your storage administrator can define
standard data set attributes and use them to create data classes, for use when you
allocate your data set. For example, your storage administrator might define a data
class for data sets whose names end in LIST and OUTLIST because they have
similar allocation attributes. The ACS routines can then be used to assign this data
class, if the data set names end in LIST or OUTLIST.
You can request a data class explicitly, by specifying it in the DD statement,
DYNALLOC macro, the TSO or IDCAMS ALLOCATE command, or the DEFINE
CLUSTER command. Request a data class implicitly, by not specifying a data class
and letting the ACS routines assign the data class defined by your storage
administrator. Whichever method is used, you need to know:
v The data set characteristics
v The data class that describes what this data set looks like
v Whether the ACS routines will pick this data class automatically
v Which characteristics to code in the JCL to override the data class attributes
Chapter 2. Using the Storage Management Subsystem
29
Using the Storage Management Subsystem
You can override any of the attributes specified in the assigned data class by
specifying the values in the DD statement, or the ALLOCATE or the DEFINE
CLUSTER commands. See z/OS DFSMS Access Method Services for Catalogs
(ALLOCATE and DEFINE CLUSTER command sections) for information about the
attributes that can be assigned through the SMS class parameters, and examples of
defining data sets.
Another way to allocate a data set without specifying all of the data set attributes
normally required is to model the data set after an existing data set. You can do
this by referring to the existing data set in the DD statement for the new data set,
using the JCL keywords LIKE or REFDD. See z/OS MVS JCL Reference and z/OS
MVS JCL User’s Guide.
Allocating Data Sets
Allocation has two related meanings:
1. Setting aside DASD space for a new data set.
2. Connecting a program to a new or existing data set or to a device.
The program can then use the DD name to issue an OPEN macro and use an
access method to read or write data.
To allocate a new data set on DASD, you can use any of the following methods:
v JCL DD statements. See z/OS MVS JCL Reference.
v Access method services ALLOCATE command or DEFINE command. See z/OS
DFSMS Access Method Services for Catalogs for the syntax and more examples.
v TSO ALLOCATE command. See z/OS TSO/E Command Reference for the syntax
and more examples.
v DYNALLOC macro using the SVC 99 parameter list. See z/OS MVS
Programming: Authorized Assembler Services Guide.
There are two ways to cause a new data set to be system-managed:
v Specify the SMS parameter STORCLAS explicitly. You can also specify
MGMTCLAS and DATACLAS.
v Let the ACS routines assign the SMS classes to the data set.
To allocate non-system-managed data sets, you can specify the DATACLAS
parameter. Do not specify the MGMTCLAS and STORCLAS parameters.
Allocating Data Sets with JCL
To allocate a new data set using JCL, specify DISP=(NEW,CATLG,DELETE). If the
application program completes normally, the data set is cataloged, but if the
application program fails, the data set is deleted. All system-managed data sets are
automatically cataloged, even if you use a disposition of KEEP.
To update an existing data set, specify a DISP value of OLD, MOD, or SHR. Do
not use DISP=SHR while updating a sequential data set unless you have some
other means of serialization because you might lose data.
To share a data set during access, specify a DISP value of SHR. If a DISP value of
NEW, OLD, or MOD is specified, the data set cannot be shared.
30
z/OS V1R6.0 DFSMS: Using Data Sets
Using the Storage Management Subsystem
Tip: If SMS is active and a new data set is a type that SMS can manage, it is
impossible to determine if the data set will be system-managed based solely on the
JCL because an ACS routine can assign a storage class to any data set.
Allocating an HFS Data Set
An HFS data set is allocated if the DSNTYPE value is HFS and the SPACE
parameter specifies the number of directory blocks, in either JCL or the data class.
You must specify the number of directory blocks for an HFS data set, but the value
has no effect on allocation.
Related reading: For more information, see “Using HFS Data Sets” on page 475.
Allocating System-Managed Data Sets
Allocating a new data set under SMS, using the ACS routines defined by your
storage administrator, is easier than without SMS. With SMS it is unnecessary to
specify the UNIT, VOL=SER, SPACE, or the DCB parameters in the DD statement.
For this allocation to succeed, the ACS routines must select a data class that
defines the space and data set attributes required by the application.
You can request the name of the data class, storage class, and management class in
the JCL DD statement. However, in most cases, the ACS routines pick the classes
needed for the data set.
Allocating a PDSE. The DSNTYPE parameter determines if the data set is
allocated as a PDSE or as a PDS. A DSNTYPE of LIBRARY causes the data set to
be a PDSE. The DSNTYPE parameter can be specified in the JCL DD statement, the
data class, or the system default, or by using the JCL LIKE keyword to refer to an
existing PDSE.
If the SPACE parameter is omitted in the DD statement, it must be supplied by the
data class. You can omit STORCLAS and DATACLAS in the DD statement if the
default storage class and data class contain the data set attributes you want. A
PDSE also can be allocated using access method services.
When first allocated, the PDSE is neither a program library or a data library. If the
first member written, by either the binder or by IEBCOPY, is a program object, the
library becomes a program library and remains such until the last member has
been deleted. If the first member written is not a program object, then the PDSE
becomes a data library. Program objects and other types of data cannot be mixed in
the same PDSE library.
Allocating an Extended-Format Data Set. Extended format data sets must be
system-managed. The mechanism for requesting extended format is through the
SMS data class DSNTYPE=EXT parameter and subparameters R (required) or P
(preferred). The storage administrator can specify R to ensure the data set is
extended. Then, for VSAM data sets the storage administrator can set the extended
addressability attribute to Y to request extended addressability.
In addition to a DSNTYPE of EXTENDED, COMPACTION=YES in a data class
definition must be specified if you want to request allocation of an extended
format data set in the compressed format. A compressed data set can be created
using the LIKE keyword on the DD statement and not just through a data class.
Allocating a VSAM Data Set. See Chapter 18, “Using Job Control Language for
VSAM,” on page 259 for information about allocating VSAM data sets using JCL.
Chapter 2. Using the Storage Management Subsystem
31
Using the Storage Management Subsystem
Allocating Non-System-Managed Data Sets
If your installation is running SMS, you can use a data class with a
non-system-managed data set, such as a tape data set. The DCB information
defined in the data class is used as the default. If you do not use a data class, you
need to supply in the JCL, or in the program, the DCB information such as LRECL
and RECFM, and the DSORG. You cannot use data class if your installation is not
running SMS.
Allocating System-Managed Data Sets with the Access Method
Services ALLOCATE Command
The examples in the following sections show you how to allocate a new data set to
the job step using the access method services ALLOCATE command. See z/OS
DFSMS Access Method Services for Catalogs (ALLOCATE section).
Allocating a Data Set Using Class Specifications
In the following example, the ALLOCATE command is used to allocate a new data
set using the SMS classes. SMS must be active. The data set can be VSAM or
non-VSAM.
//ALLOC
//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.
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:
32
z/OS V1R6.0 DFSMS: Using Data Sets
Using the Storage Management Subsystem
//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) 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.
Chapter 2. Using the Storage Management Subsystem
33
Using the Storage Management Subsystem
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
See z/OS MVS Programming: Authorized Assembler Services Guide for examples of
allocating a data set using the DYNALLOC macro. To allocate a VSAM data set
using the DYNALLOC macro with the SVC 99 parameter list, specify text unit
800B - RECORG.
34
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 3. Allocating Space on Direct Access Volumes
This chapter covers the following topics.
Topic
Location
Specification of Space Requirements
35
Maximum Data Set Size
37
Primary and Secondary Space Allocation without the Guaranteed Space
Attribute
38
Allocation of Data Sets with the Guaranteed Space Attribute
39
Allocation of Data Sets with the Space Constraint Relief Attributes
41
Extension to Another DASD Volume
41
Multiple Volume Considerations for Sequential Data Sets
43
Additional Information on Space Allocation
44
Specification of Space Requirements
You can specify the amount of space required in blocks, records, tracks, or
cylinders. When creating a DASD data set, specify the amount of space needed
explicitly by using the SPACE parameter, or specify the amount of space implicitly
by using the information available in a data class. The data class is not used if SMS
is inactive at the time of your allocation.
The system can use a data class if SMS is active even if the data set is not SMS
managed. For system-managed data sets, the system selects the volumes.
Therefore, you do not need to specify a volume when you define your data set.
If you specify your space request by average record length, space allocation is
independent of device type. Device independence is especially important to
system-managed storage.
Blocks
When the amount of space required is expressed in blocks, you must specify the
number and average length of the blocks within the data set, as in this example:
//
DD SPACE=(300,(5000,100)), ...
300 = average block length in bytes
5000 = primary quantity (number of blocks)
100 = secondary quantity, to be allocated if the primary
quantity is not enough (in blocks)
From this information, the operating system estimates and allocates the number of
tracks required.
The system uses this block length value only to calculate space. This value does
not have to be the same as the BLKSIZE value. If the data set is extended format,
the system adds 32 to this value when calculating space.
© Copyright IBM Corp. 1987, 2004
35
Allocating Space on Direct Access Volume
Recommendation: For sequential and partitioned data sets, let the system calculate
the block size instead of requesting space by average block length. See
“System-Determined Block Size” on page 323.
If the average block length of the real data does not match the value coded here,
the system might allocate much too little or much too much space.
Average Record Length
When the amount of space required is expressed in average record length, you
must specify the number of records within the data set and their average length.
Use the AVGREC keyword to modify the scale of your request. When AVGREC is
specified, the first subparameter of SPACE becomes the average record length. The
system applies the scale value to the primary and secondary quantities specified
for the SPACE keyword. Possible values for the AVGREC keyword follow:
U—Use a scale of 1
K—Use a scale of 1024
M—Use a scale of 1048576
When the AVGREC keyword is specified, the values specified for primary and
secondary quantities in the SPACE keyword are multiplied by the scale and those
new values will be used in the space allocation. For example, the following request
results in the primary and secondary quantities being multiplied by 1024:
//
DD SPACE=(80,(20,2)),AVGREC=K, ...
80 = average record length in bytes
80 * 20 * 1024 = 1.6 MB = primary space
80 * 2 * 1024 = 160 KB = secondary space, to be allocated if the
primary space is not enough
From this information, the operating system estimates and allocates the number of
tracks required using one of the following block lengths, in the order indicated:
1. 4096, if the data set is a PDSE.
2. The BLKSIZE parameter on the DD statement or the BLKSIZE subparameter of
the DCB parameter on the DD.
3. The system determined block size, if available.
4. A default value of 4096.
For an extended-format data set, the operating system uses a value 32 larger than
the above block size. The primary and secondary space are divided by the block
length to determine the number of blocks requested. The operating system
determines how many blocks of the block length can be written on one track of the
device. The primary and secondary space in blocks is then divided by the number
of blocks per track to obtain a track value, as shown in the examples below. These
examples assume a block length of 23200. Two blocks of block length 23200 can be
written on a 3380 device:
(1.6MB / 23200) / 2 = 36 = primary space in tracks
(160KB / 23200) / 2 = 4 = secondary space in tracks
In the preceding calculations, the system does not consider if it is a compressed
format data set. This means the calculation is done with the user-perceived
uncompressed block size and not the actual block size that the system calculates.
Tracks or Cylinders
The following example shows the amount of space required in tracks or cylinders:
36
z/OS V1R6.0 DFSMS: Using Data Sets
Allocating Space on Direct Access Volume
//
//
DD SPACE=(TRK,(100,5)), ...
DD SPACE=(CYL,(3,1)), ...
Absolute Track
If the data set contains location-dependent information in the form of an actual
track address (such as MBBCCHHR or CCHHR), you can request space in the number of
tracks and the beginning address. In this example, 500 tracks is required, beginning
at relative track 15, which is cylinder 1, track 0:
//
DD SPACE=(ABSTR,(500,15)),UNIT=3380, ...
Restriction: Data sets that request space by absolute track are not eligible to be
system managed and they interfere with DASD space management done by the
space management products and the storage administrator. Avoid using absolute
track allocation.
Additional Space-Allocation Options
The DD statement provides flexibility in specifying space requirements. See z/OS
MVS JCL Reference about option information.
Maximum Data Set Size
This section contains information about the following maximum amounts for data
sets:
v Maximum size on one volume
v Maximum number of volumes
v Maximum size for a VSAM data set
Maximum Size on One Volume
Most 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 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.
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.
Chapter 3. Allocating Space on Direct Access Volumes
37
Allocating Space on Direct Access Volume
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 VSAM data set can have up to 255 extents per component.
v A striped VSAM data set can have up to 255 extents per stripe.
v A PDSE can have 123 extents.
v An HFS data set can have 123 extents on each volume.
You can allocate space for a multivolume data set the same as for a single volume
data set. DASD space is initially allocated on the first volume only (exceptions are
striped extended-format data sets and guaranteed space data sets). When the
primary allocation of space is filled, space is allocated in secondary storage
amounts (if specified). The extents can be allocated on other volumes. VIO space
allocation is handled differently from other data sets. See “Virtual I/O for
Temporary Data Sets” on page 22.
Multivolume VSAM Data Sets
When a multivolume VSAM data set extends to the next volume, the data class
specifies if the initial space allocated on that volume is the primary or secondary
amount. The default is the primary amount. After the primary amount of space is
used up, space is allocated in secondary amounts. By using a data class, it is
possible to indicate whether to take a primary or secondary amount when VSAM
extends to a new volume. The previous comments do not pertain to VSAM data
that is striped. See Chapter 6, “Organizing VSAM Data Sets,” on page 73 about
VSAM data in the striped format.
Multivolume Non-VSAM Data Sets
When a multivolume non-VSAM, non-extended-format data set extends to the next
volume, the initial space allocated on that volume is the secondary amount.
Extended-Format Data Sets
When space for a striped extended-format data set is allocated, the system divides
the primary amount among the volumes. If it does not divide evenly, the system
rounds the amount up. For extended-format data sets, when the primary space on
any volume is filled, the system allocates space on that volume. The amount is the
secondary amount divided by the number of stripes. If the secondary amount
cannot be divided evenly, the system rounds up the amount.
Data sets allocated in the extended-format achieve the added benefits of improved
error detection when writing to DASD as well as the use of a more efficient and
functionally complete interface to the I/O subsystem.
38
z/OS V1R6.0 DFSMS: Using Data Sets
Allocating Space on Direct Access Volume
Table 4 shows how stripes for an extended-format sequential data set are different
from stripes for an extended-format VSAM data set.
Table 4. Differences Between Stripes in Sequential and VSAM Data Sets
Sequential Extended-Format Striped
VSAM Extended-Format Striped
The data set can have a maximum of 59 stripes. The data set can have a maximum of 16
stripes.
Each stripe must reside on one volume and
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:
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.
Chapter 3. Allocating Space on Direct Access Volumes
39
Allocating Space on Direct Access Volume
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.
3. The same process is repeated on each volume.
40
z/OS V1R6.0 DFSMS: Using Data Sets
Allocating Space on Direct Access Volume
Allocation of Data Sets with the Space Constraint Relief Attributes
To reduce allocation failures, three data class attributes can influence the allocation
and extension of data sets to new volumes. Allocations that might have failed for
lack of space can succeed.
These three attributes follow:
v Space Constraint Relief (values are YES or NO)
v Reduce Space Up To % (0 - 99%)
v Dynamic Volume Count (1 - 59 or blank)
Allocations and extends to new volumes proceed normally until space cannot be
obtained by normal means.
The system performs space constraint relief in two situations: when a new data set
is allocated and when a data set is extended to a new volume. During EOV
processing, space constraint relief affects the primary or secondary allocation
amount for VSAM data sets, or the secondary allocation amount for non-VSAM
data sets. During CREATE processing, the primary quantity might be reduced for
both non-VSAM and VSAM data sets.
Exception: The system does not use space constraint relief when data sets are
extended on the same volume.
Space constraint relief, if requested, occurs in one or two methods, depending on
the volume count that you specified for the failing allocation.
1. If the volume count is greater than 1, SMS attempts to satisfy the allocation by
spreading the requested primary allocation over more than one volume, but no
more than the volume count specified.
2. If method 1 also fails or if the volume count is 1, SMS modifies the requested
primary space or the secondary space for extension, by the percentage that you
specified in the REDUCE SPACE UP TO parameter.
The allocation fails as before if either or both methods 1 and 2 are not successful.
Recommendation: You can specify 0% in the data class for this parameter so space
is not reduced.
SMS removes the 5-extent-at-a-time limit. (For example, sequential data sets can
have a maximum of 16 extents.) Without this change, the system tries to satisfy
your primary or secondary space request with no more than five extents. If you
request a large amount of space or the space is fragmented, the system might need
more than five extents.
Restriction: VSAM and non-VSAM multistriped data sets do not support space
constraint relief. However, single-striped VSAM and non-VSAM data sets use
space constraint relief.
Extension to Another DASD Volume
The system attempts to extend to another DASD volume if all of the following
conditions exist:
v The current volume does not have the secondary space amount available, or the
data set reached the extent limit for that type of data set, or the application
program issued the FEOV macro.
Chapter 3. Allocating Space on Direct Access Volumes
41
Allocating Space on Direct Access Volume
v The volume count has not yet been reached. For a system-managed data set, the
volume count was determined when the data set was created (DISP=NEW) and
is the largest of the volume count (VOL=(,,,nn)), the number of volumes coded
with the VOL parameter, and the unit count (UNIT=(xxxx,nn)).
For either system-managed or non-system-managed data sets, the volume count
can come from the data class. The volume count can be increased after data set
creation with the IDCAMS ADDVOL command.
v The dynamic volume count has not been reached for a system-managed data set.
You can define the Space Constraint Relief and Dynamic Volume Count
attributes in the data class. If Space Constraint Relief=YES, you can specify a
dynamic volume count from 1 to 59 for SMS to extend a data set automatically
to another volume or volumes. For more information, see z/OS DFSMSdfp
Storage Administration Reference.
v A secondary allocation amount is available. This can come from the data class
when the data set was created even if the data set is not system managed. When
the data set is created with DISP=NEW or IDCAMS DEFINE, the secondary
amount permanently overrides data class for the data set. For a non-VSAM data
set the above two sources of the secondary amount can be overridden
temporarily with DISP other than NEW.
Examples of Dynamic Volume Count When Defining a Data Set
These examples are of using the Volume Count attribute from the data class or
volume count information from a JCL, TSO, or IDCAMS command. Using the
dynamic volume count causes the number of primary volumes to increase, if
necessary. The use of dynamic volume count does not add any candidate volumes
to the catalog:
1. Example 1:
Volume count:
6
Dynamic volume count: 0
Required volumes:
1
Volumes in catalog:
1 primary, 5 candidates
2. Example 2:
Volume count:
6
Dynamic volume count: 12
Required volumes:
1
Volumes in catalog:
1 primary, 5 candidates
3. Example 3:
Volume Count:
6
Dynamic volume count: 12
Required volumes:
7
Volumes in catalog:
7 primary, 0 candidates
4. Example 4:
Volume count:
Dynamic volume count:
Required volumes:
Volumes in catalog:
6
12
13
None; request fails
In example 2, although the catalog contains only five candidate volumes, the data
set can be extended to 11 candidate volumes, including the primary volume.
42
z/OS V1R6.0 DFSMS: Using Data Sets
Allocating Space on Direct Access Volume
Examples of Dynamic Volume Count When Allocating an
Existing Data Set
In the following examples, a list of specific volumes is returned to allocation, and a
count of nonspecific volumes. Also, the allocation in Example 7 fails because the
total volume count exceeds the limit of 59 volumes.
1. Example 5: VSAM KSDS
Specific volume count:
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):
Nonspecific volume count (base cluster):
Specific and total volume count (alternate index):
Base cluster dynamic volume count:
Specific volumes returned to allocation:
Nonspecific volumes returned to allocation:
Total count of volumes returned to allocation:
5
1
1
20
6
15
21
3. Example 7: Alternate Indexes in Upgrade Set
Specific and total volume count (base cluster):
Specific and total volume count (first alternate index):
Specific and total volume count (second alternate index):
Base cluster dynamic volume count:
Specific volumes returned to allocation:
Nonspecific volumes returned to allocation:
Total count of volumes returned to allocation:
5
1
1
59
7
54
61
Multiple Volume Considerations for Sequential Data Sets
Consider the following when working with multiple volumes: Your program is
extending a sequential data set if it uses the EXTEND or OUTINX option of OPEN
or it uses the OUTPUT or OUTIN option of OPEN with DISP=MOD on the DD
statement. If you plan to rewrite a multivolume sequential data set that is not SMS
managed, and you might later extend the data set, you should delete and
reallocate the data set. This avoids the problems described in item 2 below and the
system will extend on the volume that you want.
1. When writing to a sequential data set, EOV turns off the last volume bit as it
finishes each volume and CLOSE turns on the last volume bit in the DSCB on
the current volume. It identifies the last volume containing data, not necessarily
the last volume allocated to the data set. The DSCB on a later volume can also
have this bit on, either due to earlier writings or due to guaranteed space.
2. Writing with the DISP=MOD, OPEN EXTEND, or OUTINX option works
differently with system-managed and non-system-managed data sets. On
system-managed volumes, OPEN determines where to start writing using the
following algorithm. No matter which volume you finish writing on, OPEN
will find that volume to resume. Starting with the first volume, OPEN searches
for the last volume bit. The first new block will be written immediately after
the previous last block. If the old last block was short, it does not get larger.
This specifically applies to SMS volumes.
Writing with the DISP=MOD, OPEN EXTEND, or OUTINX option on non-SMS
volumes, OPEN determines where to start writing using the following
algorithm: It looks first on the last volume in the JFCB or its extensions to see if
its DSCB has the last volume bit ON. If it is not ON, OPEN searches the other
volumes in order starting with the first volume. This means that if the last
Chapter 3. Allocating Space on Direct Access Volumes
43
Allocating Space on Direct Access Volume
volume and an earlier volume each have the last volume bit ON, your added
data will not be reachable when reading sequentially.
For striped data sets, which are SMS only, the last volume bit works a little
different but it has the same effect as for other SMS data sets. The bit is ON on
the last volume, even if that volume does not contain the last record of the data
set. OPEN uses the DS1LSTAR fields to calculate the volume containing the last
record.
3. With partial release, CLOSE releases the unused space only on the current
volume except with a striped data set. It does not release space on later
volumes that can contain data either from a prior writing or due to guaranteed
space. With a system-managed data sets this has no effect on a later use of
DISP=MOD but it does mean that the space on the later volumes can be there
due to guaranteed space allocation.
Additional Information on Space Allocation
If you want to know how many DASD tracks your data set requires, see the
appropriate device document. See z/OS DFSMSdfp Storage Administration Reference
for information about allocating space for system-managed data sets. See
“Allocating Space for a PDS” on page 411 and “Allocating Space for a PDSE” on
page 439 for information about PDS/PDSE space allocation.
44
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 4. Backing Up and Recovering Data Sets
This chapter covers the following topics.
Topic
Location
Using REPRO for Backup and Recovery
46
Using EXPORT and IMPORT for Backup and Recovery of VSAM Data Sets
47
Writing a Program for Backup and Recovery
48
Using Concurrent Copy for Backup and Recovery
49
Updating a Data Set After Recovery
49
Synchronizing Catalog and VSAM Data Set Information During Recovery
49
It is important to establish backup and recovery procedures for data sets so you
can replace a destroyed or damaged data set with its backup copy. Generally data
administrators set up automated procedures for backup so you do not have to be
concerned with doing it yourself. SMS facilitates this automation by means of
management class.
There are several methods of backing up and recovering VSAM and non-VSAM
data sets:
v Using Data Facility Storage Management Subsystem Hierarchical Storage
Manager (DFSMShsm™). You can use DFSMShsm only if DSS and DFSMShsm
are installed on your system and your data sets are cataloged in a catalog. For
information about using DFSMShsm backup and recovery, see z/OS DFSMShsm
Managing Your Own Data.
v Using the access method services REPRO command.
v Using the Data Facility Storage Management Subsystem Data Set Services
(DFSMSdss™) DUMP and RESTORE commands. You can use DSS if it is
installed on your system and your data sets are cataloged in a catalog. For
uncataloged data sets, DSS provides full volume, and physical or logical data set
dump functions. For compressed extended format data sets, DFSMShsm
processes the compressed data sets using DFSMSdss as the data mover. When
using DFSMSdss for logical dump/restore with VSAM compressed data sets, the
target data set allocation must be consistent with the source data set allocation.
For DFSMShsm, a VSAM extended format data set migrated and/or backed up
will only be recalled and/or recovered as an extended format data set. For
information about using DFSMSdss, see z/OS DFSMSdss Storage Administration
Reference.
v Writing your own program for backup and recovery.
v For VSAM data sets, using the access method services EXPORT and IMPORT
commands.
v For PDSs using IEBCOPY utility.
v Using concurrent copy to take an instantaneous copy. You can use concurrent
copy if your data set resides on DASD attached to IBM storage controls that
support the concurrent copy function.
Each of these methods of backup and recovery has its advantages. You need to
decide the best method for the particular data you want to back up. For the
© Copyright IBM Corp. 1987, 2004
45
Backing Up and Recovering Data Sets
requirements and processes of archiving, backing up, and recovering data sets
using DFSMShsm, DSS, or ISMF, see z/OS DFSMShsm Managing Your Own Data,
which also contains information on disaster recovery.
Using REPRO for Backup and Recovery
Use the REPRO command to create a duplicate data set for back up. For
information about using REPRO, see “Copying and Merging Data Sets” on page
115.
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 217.
REPRO provides you with several options for creating backup copies and using
them for data set recovery. The following are suggested ways to use REPRO:
1. Use REPRO to copy the data set to a data set with a different name.
Either change your references to the original copy or delete the original and
rename the copy.
2. Create a backup copy on another catalog, then use the backup copy to replace
the original.
v Define a data set on another catalog, and use REPRO to copy the original
data set into the new data set you have defined.
v You can leave the backup copy in the catalog it was copied to when you
want to replace the original with the backup copy. Then, change the JCL
statements to reflect the name of the catalog that contains the backup copy.
3. Create a copy of a nonreusable VSAM data set on the same catalog, then delete
the original data set, define a new data set, and load the backup copy into the
newly defined data set.
v To create a backup copy, define a data set, and use REPRO to copy the
original data set into the newly defined data set. If you define the backup
data set on the same catalog as the original data set or if the data set is SMS
managed, the backup data set must have a different name.
v To recover the data set, use the DELETE command to delete the original data
set if it still exists. Next, redefine the data set using the DEFINE command,
then restore it with the backup copy using the REPRO command.
46
z/OS V1R6.0 DFSMS: Using Data Sets
Backing Up and Recovering Data Sets
4. Create a copy of a reusable VSAM data set, then load the backup copy into the
original data set. When using REPRO, the REUSE attribute permits repeated
backups to the same VSAM reusable target data set.
v To create a backup copy, define a data set, and use REPRO to copy the
original reusable data set into the newly defined data set.
v To recover the data set, load the backup copy into the original reusable data
set.
5. Create a backup copy of a data set, then merge the backup copy with the
damaged data set. When using REPRO, the REPLACE parameter lets you
merge a backup copy into the damaged data set. You cannot use the REPLACE
parameter with entry-sequenced data sets, because records are always added to
the end of an entry-sequenced data set.
v To create a backup copy, define a data set, and use REPRO to copy the
original data set into the newly defined data set.
v To recover the data set, use the REPRO command with the REPLACE
parameter to merge the backup copy with the destroyed data set. With a
key-sequenced data set, each source record whose key matches a target
record’s key replaces the target record. Otherwise, the source record is
inserted into its appropriate place in the target cluster. With a fixed-length or
variable-length RRDS, each source record, whose relative record number
identifies a data record in the target data set, replaces the target record.
Otherwise, the source record is inserted into the empty slot its relative record
number identifies. When only part of a data set is damaged, you can replace
only the records in the damaged part of the data set. The REPRO command
lets you specify a location to begin copying and a location to end copying.
6. If the index of a key-sequenced data set or variable-length RRDS becomes
damaged, follow this procedure to rebuild the index and recover the data set.
This does not apply to a compressed key-sequenced data set. It is not possible
to REPRO just the data component of a compressed key-sequenced data set.
v Use REPRO to copy the data component only. Sort the data.
v Use REPRO with the REPLACE parameter to copy the cluster and rebuild
the index.
Restrictions:
1. Do not use JOBCAT or STEPCAT DD statements for system-managed data sets.
The JOBCAT or STEPCAT DD statement fails if it references a system-managed
catalog, or if the data set that is being searched is system managed. Also, you
must connect all referenced catalogs to the system master catalog.
2. JOBCAT and STEPCAT DD statements are disabled by default. For information
on enabling JOBCAT and STEPCAT DD statements, see z/OS DFSMS: Managing
Catalogs.
Using EXPORT and IMPORT for Backup and Recovery of VSAM Data
Sets
Using EXPORT/IMPORT for backup and recovery has the following advantages:
v Key-sequenced data set or variable-length RRDS is reorganized. Using
EXPORT for backup results in data reorganization and the recreation of an index
for a key-sequenced data set or variable-length RRDS. The data records are
rearranged physically in ascending key sequence and free-space quantities are
balanced. (Control interval and control area splits can have placed the records
physically out of order.) When a key-sequenced data set is reorganized, absolute
references using the RBA are no longer valid.
Chapter 4. Backing Up and Recovering Data Sets
47
Backing Up and Recovering Data Sets
v Redefinition is easy. Because most catalog information is exported along with
the data set, you are not required to define a data set before importing the copy.
The IMPORT command deletes the original copy, defines the new object, and
copies the data from the exported copy into the newly defined data set.
v Attributes can be changed or added. When you IMPORT a data set for recovery,
you can specify the OBJECTS parameter to show new or changed attributes for
the data set. Importing a data set lets you change the name of the data set, the
key ranges, the volumes on which the data set is to reside, and the SMS classes.
For information about accessing a data set using RLS, see Chapter 14, “Using
VSAM Record-Level Sharing,” on page 217.
Structure of an Exported Data Set
An exported data set is an unloaded copy of the data set. The backup copy can be
only a sequential data set.
Most catalog information is exported along with the data set, easing the problem
of redefinition. The backup copy contains all of the information necessary to
redefine the VSAM cluster or alternate index when you IMPORT the copy.
EXPORT and IMPORT Commands
When you export a copy of a data set for backup, specify the TEMPORARY
attribute. Exporting a data set means that the data set is not to be deleted from the
original system.
You can export entry-sequenced or linear data set base clusters in control interval
mode by specifying the CIMODE parameter. When CIMODE is forced for a linear
data set, a RECORDMODE specification is overridden.
Use the IMPORT command to totally replace a VSAM cluster whose backup copy
was built using the EXPORT command. The IMPORT command uses the backup
copy to replace the cluster’s contents and catalog information.
You can protect an exported data set by specifying the INHIBITSOURCE or
INHIBITTARGET parameters. Using these parameters means the source or target
data set cannot be accessed for any operation other than retrieval.
IMPORT will not propagate distributed data management (DDM) attributes if you
specify the INTOEMPTY parameter. Distributed file manager (DFM) will
reestablish the DDM attributes when the imported data set is first accessed.
Compressed data must not be considered portable. IMPORT will not propagate
extended format or compression information if the user specifies the INTOEMPTY
parameter.
Writing a Program for Backup and Recovery
There are two methods of creating your own program for backup and recovery:
v If you periodically process a data set sequentially, you can easily create a backup
copy as a by-product of normal processing. The backup copy can be used like
one made by REPRO.
v You can write your own program to back up your data sets. Whenever possible,
this program should be integrated into the regular processing procedures.
In VSAM, the JRNAD user exit routine is one way to write your own backup
program. When you request a record for update, VSAM calls the JRNAD exit
48
z/OS V1R6.0 DFSMS: Using Data Sets
Backing Up and Recovering Data Sets
routine to copy the record you are going to update, and write it to a different
data set. When you return to VSAM, VSAM completes the requested update. If
something goes wrong, you have a backup copy. See “JRNAD Exit Routine to
Journalize Transactions” on page 241.
Using Concurrent Copy for Backup and Recovery
Concurrent copy takes what appears to be an instantaneous copy of data. The copy
can be a backup copy (such as to tape) or for replicating a database from one set of
DASD volumes to another. Concurrent copy also benefits the nondatabase
environment by permitting a backup or copy occur with only a very short
serialization.
Using concurrent copy for backup has the following advantages:
v It has little or no disruption.
v It is logically consistent.
v It is not necessary to take down the application using the data.
v It runs without regard to how the data is being used by the application.
v It works for any kind of DSS dump or copy operation.
v It eliminates the unavailability of DFSMShsm while control data sets are being
backed up.
DFSMShsm can use concurrent copy to copy its own control data sets and journal.
Running concurrent copy (like any copy or backup) during off-peak hours results
in better system throughput.
Related reading: For information about using concurrent copy, see z/OS DFSMSdss
Storage Administration Guidey.
Updating a Data Set After Recovery
After replacing a damaged data set with its backup copy, you can update the
restored data set. To update the restored data set, rerun the jobs that updated the
original between the time it was backed up and the time it became inaccessible.
Synchronizing Catalog and VSAM Data Set Information During
Recovery
Because the physical and logical description of a VSAM data set is contained in its
catalog entries, VSAM requires up-to-date catalog entries to access data sets. If
either your data set or your catalog is damaged, your recovery procedure must
match both data set and catalog entry status. Recovery by reloading the data set
automatically takes care of this problem. A new catalog entry is built when the
data set is reloaded.
Backing up the data sets in a user catalog lets you recover from damage to the
catalog. You can import the backup copy of a data set whose entry is lost or you
can redefine the entry and reload the backup copy.
For information about backing up and recovering a catalog, see z/OS DFSMS:
Managing Catalogs and z/OS DFSMShsm Managing Your Own Data.
Chapter 4. Backing Up and Recovering Data Sets
49
Backing Up and Recovering Data Sets
Handling an Abnormal Termination
When a user program closes a VSAM data set, the system uses the data set’s
end-of-data information to update its cataloged information. If a system failure
occurs before the user program closes the data set, its cataloged information is not
updated and any records in unwritten buffers are not written to the data set.
If an error occurs while a component is opened for update processing, it can
improperly close (leaving the open-for-output indicator on). At OPEN, VSAM
implicitly issues a VERIFY command when it detects an open-for-output indicator
on and issues an informational message stating whether the VERIFY command is
successful.
When the last CLOSE for a VSAM data set completes successfully, VSAM turns off
the open-for-output indicator. If the data set is opened for input, however, VSAM
leaves the open-for-output indicator on. It is the successful CLOSE after an OPEN
for output that causes the open-for-output indicator to turn off. Before you use any
data set that was not successfully closed, determine the status of the data in the
data set. Turning off the open-for-output indicator in the catalog does not make the
data set error free.
Using VERIFY to Process Improperly Closed Data Sets
You can use a VSAM VERIFY macro call with certain types of opened VSAM data
sets to ensure that fields in the VSAM control blocks are accurate. The VERIFY
macro does not change the data in the data set. VERIFY does not correct missing
or duplicate records or repair any damage in the index structure. The verification
of control-block fields enables you to perform recovery actions on the improperly
closed data set, if necessary.
You can also use the IDCAMS VERIFY command to verify a VSAM data set. When
you issue this command, IDCAMS opens the VSAM data set for output, issues a
VSAM VERIFY macro call, and closes the data set. The IDCAMS VERIFY
command and the verification by VSAM OPEN are the same. Neither changes the
data in the verified data set.
The catalog will be updated from the verified information in the VSAM control
blocks when the VSAM data set which was opened for output is successfully
closed.
The actual VSAM control-block fields that get updated depend on the type of data
set being verified. VSAM control block fields that can be updated include “High
used RBA/CI” for the data set, “High key RBA/CI”, “number of index levels”,
and “RBA/CI of the first sequence set record”.
The VERIFY command should be used following a system failure that caused a
component opened for update processing to be improperly closed. Clusters,
alternate indexes, entry-sequenced data sets, and catalogs can be verified. Paths
over an alternate index and linear data sets cannot be verified. Paths defined
directly over a base cluster can be verified. The VERIFY macro will perform no
function when VSAM RLS is being used. VSAM RLS is responsible for maintaining
data set information in a shared environment.
Although the data and index components of a key-sequenced cluster or alternate
index can be verified, the timestamps of the two components are different
following the separate verifies, possibly causing further OPEN errors. Therefore,
use the cluster or alternate index name as the target of your VERIFY command.
50
z/OS V1R6.0 DFSMS: Using Data Sets
Backing Up and Recovering Data Sets
You should issue the VERIFY command every time you open a VSAM cluster that
is shared across systems. For information about using VERIFY with clusters that
are shared, see “Cross-System Sharing” on page 198.
Recovering from Errors Due to an Improperly Closed VSAM Data
Set
Sometimes a data set is closed properly, but an error occurred. The most likely
error is an incorrect high RBA in the catalog. Other possible errors are an
incomplete write to a DASD or duplicate data exists. One way to avoid these
errors is by doing synchronous direct inserts. Another way is by using abnormal
termination user exits in which you issue a CLOSE (perhaps with the TYPE=T
parameter) to close the data set properly.
If you suspect that a write operation is incomplete, issue either an IMPORT or
REPRO command to get an old copy of the data. Intermediate updates or inserts
are lost. You must have an exported version of the data set available to use
IMPORT. Use a backup copy for REPRO.
Duplicate data in a key-sequenced data set, the least likely error to occur, can
result from a failure during a control interval or control area split. To reduce the
number of splits, specify free space for both control intervals and control areas. If
the failure occurred before the index was updated, the insert is lost, no duplicate
exits, and the data set is usable.
If the failure occurred between updating the index and writing the updated control
interval into secondary storage, some data is duplicated. However, you can access
both versions of the data by using addressed processing. If you want the current
version, use REPRO to copy it to a temporary data set and again to copy it back to
a new key-sequenced data set. If you have an exported copy of the data, use the
IMPORT command to obtain a reorganized data set without duplicate data.
If the index is replicated and the error occurred between the write operations for
the index control intervals, but the output was not affected, both versions of the
data can be retrieved. The sequence of operations for a control area split is similar
to that for a control interval split. To recover the data, use the REPRO or IMPORT
command in the same way as for the failure described in the previous paragraph.
Use the journal exit (JRNAD) to determine control interval and control area splits
and the RBA range affected.
Using VERIFY with Catalogs
VSAM OPEN calls VERIFY when it opens a catalog.
You cannot use VERIFY to correct catalog records for a key-sequenced data set, or
a fixed-length or variable-length RRDS after load-mode failure. An entry-sequenced
data set defined with the RECOVERY attribute can be verified after a create (load)
mode failure; however, you cannot run VERIFY against an empty data set or a
linear data set. Any attempt to do either will result in a VSAM logical error. For
information about VSAM issuing the implicit VERIFY command, see “Opening a
Data Set” on page 135.
Chapter 4. Backing Up and Recovering Data Sets
51
Backing Up and Recovering Data Sets
CICS VSAM Recovery
IBM CICS® VSAM Recovery (CICSVR) recovers lost or damaged VSAM data sets.
CICSVR is for organizations where the availability and integrity of VSAM data is
vital. CICSVR provides automated complete recovery, forward recovery, and
backout functions, as well as logging for batch applications.
The following are some of the tasks that you can perform with CICSVR:
v Perform complete recovery to restore and recover lost or damaged VSAM data
sets that were updated by CICS and batch applications.
v Perform logging for batch applications.
v Recover groups of VSAM data sets.
v Process backup-while-open (BWO) VSAM data sets.
v Automate the creation and submission of recovery jobs using an ISPF dialog
interface.
v Use Change Accumulation to consolidate log records and reduce the amount of
time required to recover a VSAM data set.
v Use Selective Forward Recovery to control which log records get applied to the
VSAM data set when you recover it.
Related reading: For more information, see IBM CICS VSAM Recovery
Implementation Guide.
52
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 5. Protecting Data Sets
You can prevent unauthorized access to payroll data, sales forecast data, and all
other data sets that require special security attention. You can protect confidential
data in a data set using Resource Access Control Facility (RACF) or passwords.
This chapter covers the following topics.
Topic
Location
Data Set Password Protection
55
User-Security-Verification Routine
60
Erasure of Residual Data
60
Authorized Program Facility and Access Method Services
62
Access Method Services Cryptographic Option
63
z/OS Security Server (RACF)
The z/OS Security Server is the primary tool that IBM recommends for managing
security. Often the Security Server is called the Resource Access Control Facility
(RACF). In the MVS™ environment, you can use RACF identify and verify users’
authority to access data and to use system facilities. RACF protection can apply to
a catalog and to individual VSAM data sets.
The system ignores password protection for SMS-managed data sets. See “Data Set
Password Protection” on page 55.
If a discrete profile or a generic profile does not protect a data set, password
protection is in effect.
Related reading: For more information about RACF, see z/OS Security Server RACF
Security Administrator’s Guide.
RACF Protection for VSAM Data Sets
A catalog that contains a VSAM data set does not have to be RACF protected for
its data sets to be RACF protected.
RACF and password protection can coexist for the same VSAM data set. The
RACF authorization levels of alter, control, update, and read correspond to the
VSAM password levels of master, control, update, and read.
To have password protection take effect for a non-system-managed data set, the
catalog that contains the data set must be either RACF protected or password
protected, and the data set itself must not be defined to RACF. Although
passwords are not supported for an RACF-protected data set, they can still provide
protection if the data set is moved to a system that does not have RACF protection.
If a user-security-verification routine (USVR) exists, it is not invoked for
RACF-defined data sets.
© Copyright IBM Corp. 1987, 2004
53
Protecting Data Sets
Deleting any type of RACF-protected entry from an RACF-protected catalog
requires alter-level authorization for the catalog or the entry being deleted. Altering
the passwords in an RACF-protected catalog entry requires RACF alter authority
for the entry being altered or the operations attribute. Alter authority for the
catalog itself is not sufficient for this operation.
Note: VSAM OPEN routines bypass RACF security checking if the program
issuing OPEN is in supervisor state or protection key 0.
Generic and Discrete Profiles for VSAM Data Sets
For cataloged clusters, a generic profile is used to verify access to the entire cluster,
or any of its components. Discrete profiles for the individual components might
exist, but only the cluster’s profile (generic or discrete) is used to protect the
components in the cluster.
Profiles that automatic data set protection (ADSP) processing defines during a data
set define operation are cluster profiles only.
If a data set protected by a discrete profile is moved to a system where RACF is
not installed, no user is given authority to access the data set. However, if the data
set is protected with a generic profile, access authority is determined by normal
VSAM password protection.
RACF Protection for Non-VSAM Data Sets
You can define a data set to RACF automatically or explicitly. The automatic
definition occurs when space is allocated for the DASD data set, if you have the
automatic data set protection attribute, or if you code PROTECT=YES or
SECMODEL=(,) in the DD statement. SECMODEL=(,) lets you specify the name of
the model profile RACF should use in creating a discrete profile for your data set.
The explicit definition of a data set to RACF is by use of the RACF command
language.
Multivolume data sets. To protect multivolume non-VSAM DASD and tape data
sets, you must define each volume of the data set to RACF as part of the same
volume set.
v When an RACF-protected data set is opened for output and extended to a new
volume, the new volume is automatically defined to RACF as part of the same
volume set.
v When a multivolume physical-sequential data set is opened for output, and any
of the data set’s volumes are defined to RACF, either each subsequent volume
must be RACF-protected as part of the same volume set, or the data set must
not yet exist on the volume.
v The system automatically defines all volumes of an extended sequential data set
to RACF when the space is allocated.
v When an RACF-protected multivolume tape data set is opened for output, either
each subsequent volume must be RACF-protected as part of the same volume
set, or the tape volume must not yet be defined to RACF.
v If the first volume opened is not RACF protected, no subsequent volume can be
RACF protected. If a multivolume data set is opened for input (or a
nonphysical-sequential data set is opened for output), no such consistency check
is performed when subsequent volumes are accessed.
54
z/OS V1R6.0 DFSMS: Using Data Sets
Protecting Data Sets
Tape data sets. You can use RACF to provide access control to tape volumes that
have no labels (NL), IBM standard labels (SL), ISO/ANSI standard labels (AL), or
tape volumes referred to with bypass label processing (BLP).
RACF protection of tape data sets is provided on a volume basis or on a data set
basis. A tape volume is defined to RACF explicitly by use of the RACF command
language, or automatically. A tape data set is defined to RACF whenever a data set
is opened for OUTPUT, OUTIN, or OUTINX and RACF tape data set protection is
active, or when the data set is the first file in a sequence. All data sets on a tape
volume are RACF protected if the volume is RACF protected.
If a data set is defined to RACF and is password protected, access to the data set is
authorized only through RACF. If a tape volume is defined to RACF and the data
sets on the tape volume are password protected, access to any of the data sets is
authorized only through RACF. Tape volume protection is activated by issuing the
RACF command SETROPTS CLASSACT(TAPEVOL). Tape data set name
protection is activated by issuing the RACF command SETROPTS
CLASSACT(TAPEDSN). Data set password protection is bypassed. The system
ignores data set password protection for system-managed DASD data sets.
ISO/ANSI Version 3 and Version 4 installation exits that run under RACF will
receive control during ISO/ANSI volume label processing. Control goes to the
RACHECK preprocessing and postprocessing installation exits. The same
IECIEPRM exit parameter list passed to ISO/ANSI installation exits is passed to
the RACF installation exits if the accessibility code is any alphabetic character from
A through Z.
Related reading: For more information about these exits, see z/OS DFSMS
Installation Exits.
Note: ISO/ANSI Version 4 tapes also permits special characters
!*″%&’()+,-./:;<=>?_ and numeric 0-9.
Hiding Data Set Names
To ensure that your enterprise’s information is protected, the security administrator
can enable RACF name-hiding for those data sets that contain critical information.
When name-hiding is in effect, you cannot obtain data set names unless you have
at least READ authority to access that data set. If you have access to the RACF
FACILITY class 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.
Related reading: For more information on name-hiding and RACF protection of
data set names, see z/OS DFSMSdfp Using DFSMSdfp in the z/OS V1R6 Environment
and z/OS Security Server RACF Security Administrator’s Guide.
Data Set Password Protection
Passwords are ignored for all system-managed data sets, new and existing.
However, passwords can still be defined for system-managed data sets, and used
to protect those data sets when you are sharing them with non-SMS systems that
do not have RACF or an equivalent product.
Chapter 5. Protecting Data Sets
55
Protecting Data Sets
Passwords for VSAM Data Sets
To use password protection effectively, you need to understand the difference
between operations on a catalog and operations on a data set represented by a
catalog entry:
v Referring to a catalog entry when new entries are defined (ALLOCATE or
DEFINE), or existing entries are altered (ALTER), deleted (DELETE), or listed
(LISTCAT).
v Using the data set represented by a catalog entry when it is connected to a
user’s program (OPEN), or disconnected (CLOSE).
Different passwords might be needed for each type of operation. Operations on a
catalog can be authorized by the catalog’s password or, sometimes, by the
password of the data set defined in the catalog. For information about password
levels, see z/OS DFSMS Access Method Services for Catalogs.
The following are examples of passwords required for defining, listing, and
deleting non-system-managed catalog entries:
v Defining a non-system-managed data set in a password-protected catalog
requires the catalog’s update (or higher) password.
v Listing, altering, or deleting a data set’s catalog entry requires the appropriate
password of either the catalog or the data set. However, if the catalog, but not
the data set, is protected, no password is needed to list, alter, or delete the data
set’s catalog entry.
OPEN and CLOSE operations on a data set can be authorized by the password
pointed to by the PASSWD parameter of the ACB macro. For information about
the password level required for each type of operation, see z/OS DFSMS Macro
Instructions for Data Sets.
Passwords to Authorize Access
You can define passwords for access to clusters, cluster components (data and
index), page spaces, alternate indexes, alternate index components (data and
index), paths, master and user catalogs. Different passwords have various degrees
of security, with higher levels providing greater protection than lower levels:
v Full access. The full access password is the master password, which lets you
perform all operations (retrieving, updating, inserting, and deleting) on an entire
VSAM data set and any index and catalog record associated with it. The master
password permits all operations and bypasses any additional verification
checking by the user-security-verification routine.
v Control access. The control-access password authorizes you to use control
interval access. For more information, see Chapter 11, “Processing Control
Intervals,” on page 177.
v Update access. The update-access password authorizes you to retrieve, update,
insert, or delete records in a data set. The update password does not let you
alter passwords or other security information.
v Read access. The read-only password allows you to examine data records and
catalog records, but not add, alter, or delete them, nor see password information
in a catalog record.
Each higher-level password allows all operations permitted by lower levels. Any
level can be null (not specified), but if a low-level password is specified, the
DEFINE and ALTER commands give the higher passwords the value of the highest
password specified. For example, if only a read-level password is specified, the
read-level becomes the update-, control-, and master-level password as well. If you
56
z/OS V1R6.0 DFSMS: Using Data Sets
Protecting Data Sets
specify a read password and a control password, the control password value
becomes the master-level password as well. However, in this case, the update-level
password is null because the value of the read-level password is not given to
higher passwords.
Catalogs are themselves VSAM data sets, and can have passwords. For some
operations (for example, listing all the catalog’s entries with their passwords or
deleting catalog entries), the catalog’s passwords can be used instead of the entry’s
passwords. If the master catalog is protected, the update- or higher-level password
is required when defining a user catalog, because all user catalogs have an entry in
the master catalog. When deleting a protected user catalog, the user catalog’s
master password must be specified.
Some access method services operations might involve more than one password
authorization. For example, importing a data set involves defining the data set and
loading records into it. If the catalog into which the data set is being imported is
password protected, its update-level (or higher-level) password is required for the
definition; if the data set is password protected, its update-level (or higher-level)
password is required for the load. The IMPORT command lets you specify the
password of the catalog; the password, if any, of the data set being imported is
obtained by the commands from the exported data.
Every VSAM data set is represented in a catalog by two or more components: a
cluster component and a data component, or, if the data set is a key-sequenced
data set, a cluster component, a data component, and an index component. Of the
two or three components, the cluster component is the controlling component.
Each of the two or three components can have its own set of four passwords; the
passwords you assign have no relationship to each other. For example, password
protecting a cluster but not the cluster’s data component, lets you issue LISTCAT
to determine the name of your cluster’s data component, open the data
component, and access records in it, even though the cluster itself is password
protected.
One reason for password-protecting the components of a cluster is to prevent
access to the index of a key-sequenced data set. (One way to gain access to an
index is to open it independently of the cluster.)
Password-Protection Precautions
When you use protection commands for a non-system-managed catalog or for a
data set, you need to observe certain password-protection precautions, which the
following lists describe.
For a Catalog. Observe the following precautions when you use protection
commands for a non-system-managed catalog:
v To create a non-system-managed catalog entry using the DEFINE command, the
update-level or higher-level password of the catalog is required.
v To modify a catalog entry using the ALTER command, the master password of
the entry, or the master password of the catalog that contains the entry, is
required. However, if the entry to be modified is a non-VSAM or generation
data group entry, the update-level password of the catalog is sufficient.
v To gain access to passwords in a catalog (for example, to list or change
passwords), specify the master-level password of either the entry or the catalog.
A master-level password must be specified with the DEFINE command to model
an entry’s passwords.
Chapter 5. Protecting Data Sets
57
Protecting Data Sets
v To delete a protected data set entry from a catalog, requires the master-level
password of the entry or the master-level password of the catalog containing the
entry. However, if the entry in a catalog describes a VSAM data space, the
update-level password of the catalog is sufficient.
v To delete a non-VSAM, generation data group, or alias entry, the update-level
password of the catalog is sufficient.
v To list catalog entries with the read-level passwords, specify the read password
of the entry or the catalog’s read-level password. However, entries without
passwords can be listed without specifying the catalog’s read-level password.
v To list the passwords associated with a catalog entry, specify the master
password of the entry or the catalog’s master password.
To avoid unnecessary prompts, specify the catalog’s password, which permits
access to all entries the operation affects. A catalog’s master-level password lets
you refer to all catalog entries. However, a protected cluster cannot be processed
with the catalog’s master password.
Specification of a password where none is required is always ignored.
For a Data Set. Observe the following precautions when you use protection
commands for a data set:
v To access a VSAM data set using its cluster name instead of data or index
names, specify the proper level password for the cluster even if the data or
index passwords are null.
v To access a VSAM data set using its data or index name instead of its cluster
name, specify the proper data or index password. However, if cluster passwords
are defined, the master password of the cluster can be specified instead of the
data or index password.
v Null means no password was specified, if a cluster has only null passwords,
access the data set using the cluster name without specifying passwords, even if
the data and index entries of the cluster have defined passwords. Using null
passwords permits unrestricted access to the VSAM cluster but protects against
unauthorized modification of the data or index as separate components.
Data Set and Catalog Protection
If you define passwords for any data sets in a catalog, you must also protect the
catalog by defining passwords for the catalog or by defining the catalog to RACF.
If you do not protect the catalog, no password checking takes place during
operations on the data set’s catalog entries or during open processing of data sets
cataloged in that catalog.
Password Prompting
Computer operators and TSO/E terminal users should supply a correct password
if a processing program does not give the correct one when it tries to open a
password-protected data set. When the data set is defined, use the CODE
parameter to specify a code instead of the data set name to prompt the operator or
terminal user for a password. The prompting code keeps your data secure by not
permitting the operator or terminal user to know both the name of the data set
and its password.
A data set’s code is used for prompting for any operation against a
password-protected data set. The catalog code is used for prompting when the
catalog is opened as a data set, when an attempt is made to locate catalog entries
that describe the catalog, and when an entry is to be defined in the catalog.
58
z/OS V1R6.0 DFSMS: Using Data Sets
Protecting Data Sets
If you do not specify a prompting code, VSAM identifies the job for which a
password is needed with the JOBNAME and DSNAME for background jobs or
with the DSNAME alone for foreground (TSO/E) jobs.
When you define a data set, use the ATTEMPTS parameter to specify the number
of times the computer operator or terminal user is permitted to give the password
when a processing program is trying to open a data set.
If the ATTEMPTS parameter is coded with 0, no password prompting is done. If
you exceed the allowed number of attempts When you use System Management
Facilities, a record is written to the SMF data set to indicate a security violation.
If you are logged in to TSO/E, VSAM tries the login password before prompting at
your terminal. Using the TSO/E login password counts as one attempt.
Passwords for Non-VSAM Data Sets
IBM recommends not using passwords for data sets. The security provided by data
set passwords is not as good as security provided by RACF. See z/OS DFSMSdfp
Advanced Services.
The system ignores data set password protection for system-managed data sets.
Assigning a Password
Use the PROTECT macro or the IEHPROGM PROTECT command to assign a
password to the non-VSAM data set. See z/OS DFSMSdfp Advanced Services and
z/OS DFSMSdfp Utilities.
Protecting a Data Set When You Define It
When you define a non-VSAM data set in a catalog, the data set is not protected
with passwords in its catalog entry. However, you can password-protect the
catalog.
Two levels of protection options for your data set are available. Specify these
options in the LABEL field of a DD statement with the parameter PASSWORD or
NOPWREAD. See z/OS MVS JCL Reference.
v Password protection (specified by the PASSWORD parameter) makes a data set
unavailable for all types of processing until a correct password is entered by the
system operator, or for a TSO/E job by the TSO/E user.
v No-password-read protection (specified by the NOPWREAD parameter) makes a
data set available for input without a password, but requires that the password
be entered for output or delete operations.
The system sets the data set security indicator either in the standard header label 1,
as shown in z/OS DFSMS: Using Magnetic Tapes, or in the data set control block
(DSCB). After you have requested security protection for magnetic tapes, you
cannot remove it with JCL unless you overwrite the protected data set.
Supplying a Password for a Catalog
If the catalog is update protected, you must supply the catalog’s update- or
higher-level password to define, delete, or alter a non-VSAM data set. The
password can be supplied as a subparameter of the command’s CATALOG
parameter, or as a response to the password-prompting message.
Chapter 5. Protecting Data Sets
59
Protecting Data Sets
Handling Incorrect Passwords
If an incorrect password is entered twice when a password is being requested by
the open or EOV routine, the system issues an ABEND 913. For a SCRATCH or
RENAME request, a return code is given.
Entering a Record in the PASSWORD Data Set
In addition to requesting password protection in your JCL, you must enter at least
one record for each protected data set in a data set named PASSWORD. The
PASSWORD data set must be created on the system-residence volume. The
system-residence volume contains the nucleus of the operating system. The system
programmer should also request password protection for the PASSWORD data set
itself to prevent both reading and writing without knowledge of the password.
For a data set on direct access storage devices, place the data set under protection
when you enter its password in the PASSWORD data set. Use the PROTECT macro
or the IEHPROGM utility program to add, change, or delete an entry in the
PASSWORD data set. Using either of these methods, the system updates the DSCB
of the data set to reflect its protected status. Therefore, you do not need to use JCL
whenever you add, change, or remove security protection for a data set on direct
access storage devices. For information about maintaining the PASSWORD data
set, including the PROTECT macro, see z/OS DFSMSdfp Advanced Services. For
information about the IEHPROGM utility, see z/OS DFSMSdfp Utilities.
User-Security-Verification Routine
Besides password protection, VSAM lets you protect data by specifying a program
that verifies a user’s authorization. “User-Security-Verification Routine” on page
255 describes specific requirements. To use this additional protection, specify the
name of your authorization routine in the AUTHORIZATION parameter of the
DEFINE or ALTER command.
If a password exists for the type of operation you are performing, you must
specify the password, either in the command or in response to prompting. VSAM
calls the user-security-verification routine only after it verifies the password. VSAM
bypasses this routine whenever you specify a correct master password, whether
the operation requires the master password.
You can use the USVR to detect VSAM password usage.
Erasure of Residual Data
When you release media space, you can erase your data.
Erasing DASD Data
When you delete any DASD data set or release part of the space, the system makes
the space available for allocation for new data sets. There are ways that the creator
of the new data set can read residual data that was in the previous data set. To
prevent others from reading your deleted data, run a program that overwrites the
data before you delete it. Alternatively, you can have the system erase (overwrite)
the data during data set deletion or space release, with its erase-on-scratch
function. The system erasure is faster than a program that writes new data. If the
system erasure fails, then the deletion or space release fails.
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
60
z/OS V1R6.0 DFSMS: Using Data Sets
Protecting Data Sets
the erasure of DASD space when it is releases. Space release occurs when you
delete a data set or release part of a data set. SETROPTS selects one of the
following methods for erasing the space:
v The system erases all released space.
v The system erases space only in data sets that have a security level greater than
or equal to a certain level.
v The system erases space in a data set only if its RACF data set profile specifies
the ERASE option.
v The system never erases space.
If the ERASE option is set in the RACF profile, you cannot override the option by
specifying NOERASE in access methods services commands.
System Erasure of Data
If DASD data erasure is in effect and you use any of the following items, the
system overwrites the entire data set area:
v The DELETE subparameter in the JCL DISP parameter of a data definition (DD)
statement
v The TSO DELETE command (for non-VSAM objects)
v The SCRATCH macro
v The SCRATCH control statement for the IEHPROGM utility program
v The access method services DELETE command
For a sequential, partitioned, PDSE, or VSAM extended-format data set, if DASD
data erasure is in effect, the system also overwrites the released area when you use
any of the following:
v RLSE subparameter in the JCL SPACE parameter in a DD statement to which a
program writes
v Partial release option in the management class
v PARTREL macro
RAMAC Virtual Array
With RAMAC® Virtual Array, the DDSR option of IXFP does almost the same thing
as the erase-on-scratch function. The storage administrator uses DDSR to manage
disk space more efficiently. DDSR has the side effect of usually erasing released
tracks, even if you do not request the ERASE option. DDSR is faster than the
erase-on-scratch function on other types of disks. Without erase-on-scratch,
however, DDSR is less secure. The erasure might not complete before data set
deletion or space release. After a successful erasure, your data remains physically
on disk, in a compressed form, but is not accessible by any software.
If you request erase-on-scratch on a RAMAC Virtual Array for which DDSR is
active, the system optimizes the erasure so that it happens much faster than on
other kinds of disks. The erasure is guaranteed to complete before data set deletion
or space release. After a successful erasure, your data is not accessible by any
software.
Erasing Tape Data
If you want to prevent the reading of residual data on tape volumes, you can
implement some method of overwriting the volume. A DFSMSrmm™ user can
define security classes in EDGRMMxx, a DFSMSrmm PARMLIB member, by using
name masks to identify data sets that must be erased before the volume can be
released for use as scratch. If DFSMSrmm determines that the security class of a
data set requires erasure, DFSMSrmm sets release actions of ERASE and INIT for
Chapter 5. Protecting Data Sets
61
Protecting Data Sets
any volume that contains the data set. When all data sets on the volume have
expired, DFSMSrmm holds the volume until these actions have been confirmed.
To automate the overwriting of residual data, schedule a regular EDGINERS job to
process volumes that have the erase action pending. DFSMSrmm selects the
volumes to process and prompts the operator to mount each one. After verifying
that the correct volume is mounted, DFSMSrmm erases the volume, using the
hardware-security erase feature, where supported, to free the channel for other
activity during the erasure.
If the hardware-security erase feature is not available, DFSMSrmm overwrites
volumes with a bit pattern of X'FF'. When erasing volumes, DFSMSrmm also
reinitializes them so that the correct volume labels are written, and the volumes are
ready for reuse in a single operation.
Authorized Program Facility and Access Method Services
The authorized program facility (APF) limits the use of sensitive system services
and resources to authorized system and user programs. For information about
program authorization, see z/OS MVS Programming: Authorized Assembler Services
Guide.
All access method services load modules are contained in 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.
62
z/OS V1R6.0 DFSMS: Using Data Sets
Protecting Data Sets
The following restricted access method services functions cannot be requested in
an unauthorized state:
DEFINE—When the RECATALOG parameter is specified
DELETE—When the RECOVERY parameter is specified
EXPORT—When the object to be exported is a catalog
IMPORT—When the object to be imported is a catalog
PRINT—When the object to be printed is a catalog
REPRO—When copying a catalog or when the catalog unload/reload is to be used
VERIFY—When a catalog is to be verified
If the above functions are required and access method services is invoked from an
application program or TSO/E terminal monitor program, the invoking program
must be authorized.
For information about authorizing for TSO/E and ISPF, see z/OS DFSMSdfp Storage
Administration Reference.
Access Method Services Cryptographic Option
Although you can provide security for online data by using such facilities as
VSAM password protection and RACF, these facilities do not protect data when it
is stored offline. Sensitive data stored offline is susceptible to misuse.
Cryptography is an effective means of protecting offline data, if the enciphering
techniques are adequate. The enciphering function is available by using the access
method services REPRO ENCIPHER command. The data remains protected until
you use the REPRO DECIPHER command to decipher it with the correct key.
When you use the REPRO ENCIPHER command, you can specify whether to use
the Programmed Cryptographic Facility or Integrated Cryptographic Service
Facility (ICSF) to manage the cryptographic keys, depending on which
cryptographic facility is running as a started task. You can use the REPRO
ENCIPHER and REPRO DECIPHER to perform simple encryption and decryption
of sensitive data. The data remains protected until you use the REPRO DECIPHER
option to decipher it with the correct key. If you also have cryptographic hardware
and RACF, you can use these REPRO commands with ICSF to perform more
sophisticated encryption and decryption.
Related reading: For information on using the REPRO command to encrypt and
decrypt data, see z/OS DFSMS Access Method Services for Catalogs. For information
on using ICSF, z/OS Cryptographic Services ICSF Overview.
Data Enciphering and Deciphering
In the following three types of offline environments, the enciphering of sensitive
data adds to data security:
v Data sets are transported to another installation, where data security is required
during transportation and while the data is stored at the other location.
v Data sets are stored for long periods of time at a permanent storage location
Chapter 5. Protecting Data Sets
63
Protecting Data Sets
v Data sets are stored offline at the site at which they are normally used.
You can use the REPRO command to copy a plaintext (not enciphered) data set to
another data set in enciphered form. Enciphering converts data to an unintelligible
form called a ciphertext. You can then store the enciphered data set offline or send
it to a remote location. When desired, you can bring back the enciphered data set
online and use the REPRO command to recover the plaintext from the ciphertext
by copying the enciphered data set to another data set in plaintext (deciphered)
form.
Enciphering and deciphering are based on an 8-byte binary value called the key.
Using the REPRO DECIPHER option, you can either decipher the data on the
system that it was enciphered on, or decipher the data on another system that has
the required key to decipher the data.
The input data set for the decipher operation must be an enciphered copy of a data
set produced by REPRO. The output data set for the encipher operation can only
be a VSAM entry-sequenced, linear, or sequential data set. The target (output) data
set of both an encipher and a decipher operation must be empty. If the target data
set is a VSAM data set that has been defined with the reusable attribute, use the
REUSE parameter of REPRO to reset it to empty.
For both REPRO ENCIPHER and REPRO DECIPHER, if the input data set
(INDATASET) is system managed, the output data set (OUTDATASET) can be
either system managed or not system managed, and must be cataloged.
The REPRO ENCIPHER parameter indicates that REPRO is to produce an
enciphered copy of the data set. The INFILE or INDATASET parameter identifies
and allocates the plaintext (not enciphered) source data set.
The REPRO DECIPHER parameter indicates that REPRO is to produce a
deciphered copy of the data set. The OUTFILE or OUTDATASET parameter
identifies and allocates a target data set to contain the plaintext data.
Figure 2 on page 65 is a graphic representation of the input and output data sets
involved in REPRO ENCIPHER and DECIPHER operations.
64
z/OS V1R6.0 DFSMS: Using Data Sets
Protecting Data Sets
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
VSAM
ESDS
KSDS
LDS
RRDS
ISAM
SAM
Output
REPRO
Decipher
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
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.
Chapter 5. Protecting Data Sets
65
Protecting Data Sets
Data Encryption Keys
Use the plaintext data encrypting key to encipher or decipher the data using the
Data Encryption Standard. REPRO lets you supply an 8-byte value as the plaintext
data encrypting key. If you do not supply the data encrypting key, REPRO
provides an 8-byte value to be used as the plaintext data encrypting key. Using the
REPRO DECIPHER option, you can either decipher the data on the system that it
was enciphered on or decipher the data on another system that has this functional
capability and the required key to decipher the data. Given the same key, encipher
and decipher are inverse operations.
If you supply your own plaintext data encrypting key on ENCIPHER or
DECIPHER through the REPRO command, you risk exposing that key when the
command is listed on SYSPRINT. To avoid this exposure, direct REPRO to a data
encrypting key data set to obtain the plaintext data encrypting key.
Secondary Key-Encrypting Keys
When you want to decipher the data, you must supply the data encrypting key
that enciphered the data. However, as a security precaution, you might want to
supply the data encrypting key in a disguised form. When enciphering the data
set, supply the name of a key-encrypting key. The REPRO command uses the
key-encrypting keys indicated by the supplied name to disguise the data
encrypting key. When deciphering the data set, supply the name of the file key
and the disguised data encrypting key rather than the plaintext data encrypting
key. In this way, the actual plaintext data encrypting key is not revealed.
You can use the Programmed Cryptographic Facility or ICSF to install the
secondary key-encrypting keys. If you are using the Programmed Cryptographic
Facility, use the Programmed Cryptographic Facility key generator utility to set up
the key pairs.
If you are using ICSF, use the Key Generation Utility Program (KGUP) to set up
the key pairs on both the encrypting and decrypting systems.
The key generator utility generates the key-encrypting keys you request and stores
the keys, in enciphered form, in the cryptographic key data set (CKDS). It lists the
external name of each secondary key and the plaintext form of the secondary key.
If the secondary encrypting key is to be used on a system other than the system on
which the keys were generated, the utility must also be run on the other system to
define the same plaintext key-encrypting keys. The plaintext key-encrypting keys
can be defined in the CKDS of the other system with different key names. If you
want to manage your own private keys, no key-encrypting keys are used to
encipher the data encrypting key; it is your responsibility to ensure the secure
nature of your private data encrypting key.
Related reading: For more information on setting up keys with KGUP, see z/OS
Cryptographic Services ICSF Administrator’s Guide.
REPRO ENCIPHER and DECIPHER on ICSF
In planning to use the ENCIPHER and DECIPHER functions of the REPRO
command, you should be aware of the following requirements:
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.
66
z/OS V1R6.0 DFSMS: Using Data Sets
Protecting Data Sets
v If you are using ICSF, you must start it before executing the REPRO command.
If you are using the Programmed Cryptographic Facility, you must start it before
executing the REPRO command.
Chapter 5. Protecting Data Sets
67
Protecting Data Sets
68
z/OS V1R6.0 DFSMS: Using Data Sets
Part 2. VSAM Data Sets
Chapter 6. Organizing VSAM Data Sets . . . .
VSAM Data Formats . . . . . . . . . . .
Data Set Size . . . . . . . . . . . . .
Control Intervals . . . . . . . . . . .
Control Information Fields . . . . . . . .
Compressed Control Information Field . . . .
Control Areas. . . . . . . . . . . . .
Spanned Records . . . . . . . . . . .
Selection of VSAM Data Set Types . . . . . . .
Entry-Sequenced Data Sets . . . . . . . .
Simulated VSAM Access to UNIX files . . . .
Record Processing for UNIX Files . . . . .
Restrictions on UNIX Files . . . . . . .
Services and Utilities for UNIX Files . . . .
Key-Sequenced Data Sets . . . . . . . . .
Free Space . . . . . . . . . . . . .
Considerations for Increasing Keys and Space
Insertion of a Logical Record in a CI . . . .
Prime Index . . . . . . . . . . . .
Key Compression . . . . . . . . . .
Control Interval Splits . . . . . . . . .
Linear Data Sets . . . . . . . . . . . .
Fixed-Length Relative-Record Data Sets . . . .
Variable-Length Relative-Record Data Sets . . .
Summary of VSAM Data Set Types . . . . .
Extended-Format VSAM Data Sets. . . . . . .
Restrictions on Defining Extended-Format Data
Sets . . . . . . . . . . . . . . . .
VSAM Data Striping . . . . . . . . . .
Layering Concept for Data Striping . . . .
Other Considerations for Data Striping . . .
Compressed Data . . . . . . . . . . .
Access to Records in a VSAM Data Set . . . . .
Access to Entry-Sequenced Data Sets . . . . .
Access to Key-Sequenced Data Sets . . . . .
Keyed-Sequential Access . . . . . . . .
Keyed-Direct Access . . . . . . . . .
Skip-Sequential Access. . . . . . . . .
Addressed Access . . . . . . . . . .
Access to Linear Data Sets . . . . . . . .
Access to Fixed-Length Relative-Record Data Sets
Keyed-Sequential Access . . . . . . . .
Skip-Sequential Access. . . . . . . . .
Keyed-Direct Access . . . . . . . . .
Access to Variable-Length Relative-Record Data
Sets . . . . . . . . . . . . . . . .
Keyed-Sequential Access . . . . . . . .
Skip-Sequential Access. . . . . . . . .
Keyed-Direct Access . . . . . . . . .
Access to Records through Alternate Indexes . . .
Alternate Index Structure for a Key-Sequenced
Data Set . . . . . . . . . . . . . .
Alternate Index Structure for an Entry-Sequenced
Data Set . . . . . . . . . . . . . .
Building of an Alternate Index . . . . . . .
Automatic Upgrade of Alternate Indexes . . .
© Copyright IBM Corp. 1987, 2004
73
73
73
74
74
75
76
76
77
78
80
80
80
81
81
82
82
83
84
84
84
84
85
86
86
87
88
88
90
91
92
93
94
94
94
94
95
95
95
95
95
95
95
95
95
96
96
96
Data Compression .
.
.
.
.
.
.
.
.
.
.
. 99
Chapter 7. Defining VSAM Data Sets . . . . . 101
Using Cluster Names for Data and Index
Components . . . . . . . . . . . . . . 102
Defining a Data Set with Access Method Services
102
Naming a Cluster . . . . . . . . . . . 102
Duplicate Data Set Names . . . . . . . 103
Temporary Data Set Names . . . . . . 103
Specifying Cluster Information . . . . . . 104
Using Access Method Services Parameters . . . 104
Descriptive Parameters . . . . . . . . 104
Performance Parameters . . . . . . . . 105
Security and Integrity Parameters . . . . 106
Allocating Space for VSAM Data Sets . . . . 106
Partial Release . . . . . . . . . . . 107
Small Data Sets . . . . . . . . . . . 107
Multiple Cylinder Data Sets . . . . . . 108
Linear Data Sets . . . . . . . . . . 108
Using VSAM Extents . . . . . . . . . 108
VSAM Extent Consolidation . . . . . . 109
Calculating Space for the Data Component of a
KSDS . . . . . . . . . . . . . . . 109
Calculating Space for the Index Component . . 110
Using ALTER to Modify Attributes of a
Component . . . . . . . . . . . . . 110
Using ALTER to Rename Data Sets . . . . . 110
Defining a Data Set with JCL . . . . . . . . 111
Loading a VSAM Data Set . . . . . . . . . 111
Using REPRO to Copy a VSAM Data Set . . . 112
Using a Program to Load a Data Set . . . . . 113
Reusing a VSAM Data Set as a Work File . . . 114
Copying and Merging Data Sets . . . . . . . 115
Defining Alternate Indexes . . . . . . . . . 117
Naming an Alternate Index . . . . . . . . 117
Specifying Alternate Index Information . . . . 117
Specifying Descriptive Information for an
Alternate Index . . . . . . . . . . . 118
Specifying RECORDSIZE for an Alternate
Index with Nonunique Keys . . . . . . 118
Building an Alternate Index . . . . . . . 119
Maintaining Alternate Indexes . . . . . . . 119
How Reorganization Affects Alternate
Indexes . . . . . . . . . . . . . 120
Alternate Index Backups. . . . . . . . 120
Defining a Path. . . . . . . . . . . . 120
Defining a Page Space . . . . . . . . . . 121
Checking for Problems in Catalogs and Data Sets
122
Listing Catalog Entries . . . . . . . . . 122
Printing the Contents of Data Sets . . . . . 123
Deleting Data Sets . . . . . . . . . . . . 123
96
98
98
99
Chapter 8. Defining and Manipulating VSAM
Data Sets: Examples . . . . . . . . . . 125
Example of Defining a VSAM Data Set . . . . . 126
Examples of Defining Temporary VSAM Data Sets 128
69
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 . . . . . . . . . . . . .
128
129
129
129
130
Chapter 9. Processing VSAM Data Sets . . . .
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 . . . . . . .
Insertions into an Entry-Sequenced Data Set
Insertions into a Key-Sequenced Data Set . .
Insertions into a Fixed-Length
Relative-Record Data Set . . . . . . .
Insertions into a Variable-Length
Relative-Record Data Set . . . . . . .
Insertions into a Linear Data Set . . . . .
Retrieving Records . . . . . . . . . .
Sequential Retrieval . . . . . . . . .
POINT Macro for Positioning . . . . . .
Direct Retrieval . . . . . . . . . . .
Updating Records . . . . . . . . . . .
Changing Record Length . . . . . . .
Processing the Data Component of a
Key-Sequenced Data Set . . . . . . . .
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 . . . . . .
Specifying Asynchronous Mode . . . . .
Checking for Completion of Asynchronous
Requests . . . . . . . . . . . . .
Ending a Request . . . . . . . . . . .
Closing Data Sets . . . . . . . . . . . .
Operating in SRB or Cross-Memory Mode . . . .
Using VSAM Macros in Programs . . . . . .
133
134
134
135
136
138
138
Chapter 10. Optimizing VSAM Performance . .
Optimizing Control Interval Size . . . . . . .
Control Interval Size Limitations . . . . . .
Physical Block Size and Track Capacity . . .
Track Allocations versus Cylinder Allocations
Data Control Interval Size . . . . . . . .
Index Control Interval Size . . . . . . . .
How VSAM Adjusts Control Interval Size . . .
155
155
155
156
157
157
158
158
70
z/OS V1R6.0 DFSMS: Using Data Sets
138
139
139
139
140
140
140
141
141
142
142
142
143
144
144
144
144
145
145
145
146
147
147
148
148
148
149
149
150
151
Optimizing Control Area Size . . . . . . . .
Advantages of a Large Control Area Size . . .
Disadvantages of a Large Control Area Size . .
Optimizing Free Space Distribution . . . . . .
Selecting the Optimal Percentage of Free Space
Altering the Free Space Specification When
Loading a Data Set . . . . . . . . . .
Determining I/O Buffer Space for Nonshared
Resource . . . . . . . . . . . . . . .
Obtaining Buffers Above 16 MB . . . . . .
Virtual Storage Constraint Relief . . . . .
Dynamic Allocation Options for Reducing
Storage Usage . . . . . . . . . . .
Tuning for System-Managed Buffering . . . .
Processing Techniques . . . . . . . .
Internal Processing Techniques . . . . .
Processing Guidelines and Restrictions . . .
General Considerations for the Use of SMB
Allocating Buffers for Concurrent Data Set
Positioning . . . . . . . . . . . . .
Allocating Buffers for Direct Access . . . . .
Data Buffers for Direct Access . . . . . .
Index Buffers for Direct Access . . . . .
Example of Buffer Allocation 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 . . . . . . . . . . . .
159
160
160
160
162
163
164
164
165
165
165
166
167
167
169
170
170
170
170
171
173
174
174
175
175
175
175
176
176
176
Chapter 11. Processing Control Intervals . . . 177
Access to a Control Interval . . . . . . . . 178
Structure of Control Information . . . . . . . 179
CIDF—Control Interval Definition Field . . . 180
RDF—Record Definition Field . . . . . . . 180
Control Field Values for Nonspanned
Key-Sequenced, Entry-Sequenced, and
Variable-Length Relative Record Data Sets . . 181
Control Field Values for Spanned
Key-Sequenced and Entry-Sequenced Data
Sets . . . . . . . . . . . . . . 183
Control Field Values for Fixed-Length
Relative-Record Data Sets . . . . . . . 184
User Buffering . . . . . . . . . . . . . 184
Improved Control Interval Access . . . . . . 185
Opening an Object for Improved Control
Interval Access . . . . . . . . . . . . 185
Processing a Data Set with Improved Control
Interval Access . . . . . . . . . . . . 185
Fixing Control Blocks and Buffers in Real
Storage . . . . . . . . . . . . . . 186
Control Blocks in Common (CBIC) Option . . . 186
Chapter 12. Sharing VSAM Data Sets
.
.
.
. 189
Subtask Sharing . . . . . . . . . . .
Building a Single Control Block Structure . .
Resolving Exclusive Control Conflicts . . .
Preventing Deadlock in Exclusive Control of
Shared Resources . . . . . . . . . .
Data Set Name Sharing . . . . . . .
Consistent Processing Options . . . . .
Shared Subtasks . . . . . . . . .
Cross-Region Sharing . . . . . . . . . .
Cross-Region Share Options . . . . . .
Read Integrity During Cross-Region Sharing .
Invalidating Index Buffers . . . . . .
Invalidating Data Buffers . . . . . .
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 . .
. 190
. 190
. 191
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
193
193
194
195
195
195
196
197
197
197
198
199
200
201
201
201
203
204
Chapter 13. Sharing Resources Among VSAM
Data Sets . . . . . . . . . . . . . . 205
Provision of a Resource Pool . . . . . . . . 205
Building a Resource Pool: BLDVRP . . . . . 205
Using Hiperspace Buffers with LSR . . . . 206
Deciding the Size of a Virtual Resource Pool 207
Displaying Information about an Unopened
Data Set . . . . . . . . . . . . . 208
Displaying Statistics about a Buffer Pool . . 208
Connecting a Data Set to a Resource Pool:
OPEN . . . . . . . . . . . . . . . 209
Deleting a Resource Pool Using the DLVRP
Macro . . . . . . . . . . . . . . . 209
Management of I/O Buffers for Shared Resources 210
Deferring Write Requests . . . . . . . . 210
Relating Deferred Requests by Transaction ID
211
Writing Buffers Whose Writing is Deferred:
WRTBFR . . . . . . . . . . . . . . 211
Handling Exits to Physical Error Analysis
Routines . . . . . . . . . . . . . 212
Using the JRNAD Exit with Shared
Resources . . . . . . . . . . . . 212
Accessing a Control Interval with Shared
Resources . . . . . . . . . . . . . 213
Locating an RBA in a Buffer Pool: SCHBFR
213
Marking a Buffer for Output: MRKBFR . . . 213
Restrictions and Guidelines for Shared Resources
214
Chapter 14. Using VSAM Record-Level Sharing
Controlling Access to VSAM Data Sets . . . .
Accessing Data Sets Using DFSMStvs and VSAM
Record-Level Sharing . . . . . . . . . .
Record-Level Sharing CF Caching . . . .
Using VSAM RLS with CICS . . . . . .
Recoverable and Nonrecoverable Data Sets
CICS Transactional Recovery for VSAM
Recoverable Data Sets . . . . . . .
Using VSAM RLS Outside of CICS . . . .
217
. 217
. 217
. 218
. 219
221
. 221
. 222
|
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 . .
Comparing RLS Access and Non-RLS Access
Share Options . . . . . . . . . . .
Locking . . . . . . . . . . . . .
VSAM Options Not Used by RLS . . . .
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 . .
Chapter 15. Checking VSAM Key-Sequenced
Data Set Clusters for Structural Errors . . . .
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 Tests of a Data Set
with a Structural Error . . . . . . . . .
INDEXTEST and DATATEST Tests of a Data Set
with a Duplicate Key Error . . . . . . . .
Chapter 16. Coding VSAM User-Written Exit
Routines . . . . . . . . . . . . .
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 . . . . . .
Journalizing Transactions . . . . . .
RBA Changes . . . . . . . . . .
Control Interval Splits . . . . . . .
Parameter List . . . . . . . . . .
LERAD Exit Routine to Analyze Logical Errors .
Register Contents . . . . . . . . . .
Part 2. VSAM Data Sets
222
222
222
223
223
223
223
225
226
226
227
228
228
229
229
229
229
230
230
230
230
231
231
232
232
232
233
. 235
. 235
. 236
237
. 237
. 238
. 238
. 238
. 239
. 239
. 240
. 240
. 240
. 240
. 241
. 241
. 241
. 242
. 242
. 242
. 244
. 247
. 248
71
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 . . . . . .
248
248
249
249
250
250
250
251
252
253
254
255
Chapter 17. Using 31-Bit Addressing Mode with
VSAM . . . . . . . . . . . . . . . 257
VSAM Options . . . . . . . . . . . . . 257
Chapter 18. Using Job Control Language for
VSAM . . . . . . . . . . . . . . .
Using JCL Statements and Keywords . . . . .
Data Set Name . . . . . . . . . . . .
Disposition . . . . . . . . . . . . .
Creating VSAM Data Sets with JCL . . . . . .
Temporary VSAM Data Sets . . . . . . .
Data Set Names . . . . . . . . . .
Allocation . . . . . . . . . . . .
Restrictions for Temporary VSAM Data Sets
Examples Using JCL to Allocate VSAM Data
Sets . . . . . . . . . . . . . . .
Example 1: Allocate a Key-Sequenced Data
Set . . . . . . . . . . . . . . .
Example 2: Allocate a System-Managed
Key-Sequenced Data Set Using Keywords . .
Example 3: Allocate a VSAM Data Set Using
Keyword Defaults . . . . . . . . . .
Example 4: Allocate a Temporary VSAM
Data Set . . . . . . . . . . . . .
Example 5: Allocate a Temporary VSAM
Data Set Taking All Defaults . . . . . .
Retrieving an Existing VSAM Data Set . . . . .
Migration Consideration . . . . . . . . .
Keywords Used to Process VSAM Data Sets . .
Chapter 19. Processing Indexes of
Key-Sequenced Data Sets . . . . . . . .
Access to a Key-Sequenced Data Set Index . . .
Access to an Index with GETIX and PUTIX . .
Access to the Index Component Alone . . . .
Prime Index . . . . . . . . . . . . .
Index Levels . . . . . . . . . . . . .
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 . . . . .
72
z/OS V1R6.0 DFSMS: Using Data Sets
259
259
259
259
260
262
262
262
262
263
263
264
264
265
265
266
266
266
269
269
269
269
270
271
273
273
275
275
276
279
280
Chapter 6. Organizing VSAM Data Sets
This chapter covers the following topics.
Topic
Location
VSAM Data Formats
73
VSAM Data Striping
88
Selection of VSAM Data Set Types
77
Extended-Format VSAM Data Sets
87
Access to Records in a VSAM Data Set
93
Access to Records through Alternate Indexes
96
Data Compression
99
VSAM Data Formats
The organization of data in all VSAM data sets, except linear data sets, is arranged
in records, also called logical records. A logical record is the user record requested
from, or given to, the VSAM record management function.
Logical records of VSAM data sets are stored differently from logical records in
non-VSAM data sets. VSAM stores records in control intervals. A control interval is
a continuous area of direct access storage that VSAM uses to store data records
and control information that describes the records. Whenever a record is retrieved
from direct access storage, the entire control interval containing the record is read
into a VSAM I/O buffer in virtual storage. The desired record is transferred from
the VSAM buffer to a user-defined buffer or work area. Figure 3 shows how a
logical record is retrieved from direct access storage.
DASD storage
Virtual storage
I/O buffer
CI
I/O path
R1
R2
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 (1 073 741 824 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, 2004
73
Organizing VSAM Data Sets
can be expanded to 123 extents per volume and up to 255 extents per component.
A striped VSAM component can have up to 255 extents.
VSAM attempts to extend a data set when the total number of extents is less than
250. 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 106.
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 155.
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
CIDFs are 4 bytes long, and contain the amount and location of free space. RDFs
are 3 bytes long, and describe the length of records and how many adjacent
records are of the same length.
If two or more adjacent records have the same length, only two RDFs are used for
this group. One RDF gives the length of each record, and the other gives the
number of consecutive records of the same length. Figure 5 shows RDFs for records
of the same and different lengths:
74
z/OS V1R6.0 DFSMS: Using Data Sets
Organizing VSAM Data Sets
Control interval 1
Control interval size = 512 bytes
Record length = 160-byte records
Record definition fields: Only 2 RDFs are needed because all
records are the same length.
R1
R2
R3
FS
RDF
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
RDF
3
RDF
2
RDF
1
CIDF
3
3
3
4
3
Control Interval 3
Control interval size = 512 bytes
Record length: Records 1 through 3 are 80-byte records
Records 4 and 5 have different length
Record definition fields: Two RDFs are used for records 1 through 3
Record 4 and 5 each have their own RDF
R1
R2
R3
R4
R5
FS
RDF
RDF
RDF
RDF
CIDF
80
80
80
100
93
63
3
3
3
3
4
FS = Free space
Figure 5. Record Definition Fields of Control Intervals
If a record exceeds the maximum record length, an error message is generated. If a
record in an entry-sequenced or key-sequenced data set, or variable-length RRDS is
smaller than the maximum record length, VSAM saves disk space by storing the
actual record length in the RDF. However, in a fixed-length RRDS, records do not
vary in length. The RDF reflects the length of the record slot, and cannot be
adjusted.
Compressed Control Information Field
Compressed data records in an extended-format key-sequenced data set have a
different format than noncompressed data records. This format includes a record
prefix that contains internal compression information. When the record is a
spanned record, each segment of the record contains a segment prefix with
Chapter 6. Organizing VSAM Data Sets
75
Organizing VSAM Data Sets
information similar to the record prefix for describing the segment. The length of
the record prefix for nonspanned records is 3 bytes, and the length for spanned
records is 5 bytes.
The stored record format has no affect on the data seen by the user as a result of a
VSAM GET request. In addition, no special processing is required to place the
record in the data set in a compressed format.
The presence of the record prefix does result in several incompatibilities that can
affect the definition of the key-sequenced data set or access to the records in the
key-sequenced data set. When a VSAM data set is in compressed format, VSAM
must be used to extract and expand each record to obtain data that is usable. If a
method other than VSAM is used to process a compressed data set and the
method does not recognize the record prefix, the end result is unpredictable and
could result in loss of data. See “Compressed Data” on page 92.
Control Areas
The control intervals in a VSAM data set are grouped together into fixed-length
contiguous areas of direct access storage called control areas. A VSAM data set is
actually composed of one or more control areas. The number of control intervals in
a control area is fixed by VSAM.
The maximum size of a control area is one cylinder, and the minimum size is one
track of DASD storage. When you specify the amount of space to be allocated to a
data set, you implicitly define the control area size. For information about defining
an alternate index, see “Defining Alternate Indexes” on page 117. For information
about defining an alternate index, see “Optimizing Control Area Size” on page 159.
Spanned Records
Sometimes a record is larger than the control interval size used for a particular
data set. In VSAM, you do not need to break apart or reformat such records,
because you can specify spanned records when defining a data set. The SPANNED
parameter permits a record to extend across or span control interval boundaries.
Spanned records might reduce the amount of DASD space required for a data set
when data records vary significantly in length, or when the average record length
is larger compared to the CI size. The following figures show the use of spanned
records for more efficient use of space.
In Figure 6, each control interval is 10 240 bytes long.
CI1
R
Free space
CI length
CI2
Control
info
R
CI3
FS
Control
info
R
Free space
Control
info
10240 bytes
Figure 6. Data Set with Nonspanned Records
In Figure 6 control interval 1 contains a 2000-byte record. Control interval 2
contains a 10 000-byte record. Control interval 3 contains a 2000-byte record. All
together, these three records use 30 720 bytes of storage.
76
z/OS V1R6.0 DFSMS: Using Data Sets
Organizing VSAM Data Sets
Figure 7 contains a data set with the same space requirements as in Figure 6, but
one that permits spanned records.
CI1
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 7. Data Set with Spanned Records
The control interval size is reduced to 4096 bytes. When the record to be stored is
larger than the control interval size, the record is spanned between control
intervals. In Figure 7, control interval 1 contains a 2000-byte record. Control
intervals 2, 3, and 4 together contain one 10 000-byte record. Control interval 3
contains a 2000-byte record. By changing control interval size and permitting
spanned records, you can store the three records in 20 480 bytes, reducing the
amount of storage needed by 10 240 bytes.
Remember the following rules:
v A spanned record always begins on a control interval boundary and fills more
than one control interval within a single control area.
v For compressed data sets with spanned records, the length of the record prefix is
5 bytes. Because of the additional 5 bytes, the key offset plus the key length (that
is, relative key position) must be less than or equal to the CI size less 15.
v For key-sequenced data sets, the entire key field of a spanned record must be in
the first control interval.
v The control interval containing the last segment of a spanned record might also
contain unused space. Use the unused space only to extend the spanned record;
it cannot contain all or part of any other record.
v Spanned records can only be used with key-sequenced data sets and
entry-sequenced data sets.
v To span control intervals, you must specify the SPANNED parameter when you
define your data set. VSAM decides whether a record is spanned or
nonspanned, depending on the control interval length and the record length.
Spanned/nonspanned can also be specified in the data class.
v Locate mode (OPTCD=LOC on the RPL) is not a valid processing mode for
spanned records. A nonzero return code will be issued if locate mode is used.
Selection of VSAM Data Set Types
VSAM supports several data set types: entry-sequenced (ESDS), key-sequenced
(KSDS), linear (LDS), fixed-length, and variable-length relative record (RRDS).
Before you select a data set type, consider the following questions:
v Will you need to access the records in sequence, randomly, or both ways?
v Are all the records the same length?
v Will the record length change?
v How often will you need to move records?
v How often will you need to delete records?
v Do you want spanned records?
v Do you want to keep the data in order by the contents of the record?
v Do you want to access the data by an alternate index?
Chapter 6. Organizing VSAM Data Sets
77
Organizing VSAM Data Sets
v Do you want to use access method services utilities with an IBM DB2® cluster?
Entry-sequenced data sets are best for the following kinds of applications:
v Applications that require sequential access only. It is better to use
entry-sequenced data sets or variable-length RRDSs for sequential access,
because they support variable-length records and can be expanded as records
are added.
v Online applications that need to use an existing entry-sequenced data set. If you
want to use an entry-sequenced data set in an online application, load the data
set sequentially by a batch program and access the data set directly by the
relative byte address (RBA).
Key-sequenced data sets are best for the following kinds of applications:
v Applications that require that each record have a key field.
v Applications that require both direct and sequential access.
v Applications that use high-level languages which do not support RBA use.
v Online applications usually use key-sequenced data sets.
v You want to access the data by an alternate index.
v The advantage of key-sequenced data sets over fixed-length RRDS using direct
access is ease of programming.
v You want to have compressed data.
Linear data sets, although rarely used, are best for the following kinds of
applications:
v Specialized applications that store data in linear data sets
v Data-in-virtual (DIV)
Relative-record data sets are best for the following kinds of applications:
v Applications that require direct access only.
v Applications in which there is a one-to-one correspondence between records and
relative record numbers. For example, you could assign numeric keys to records
sequentially, starting with the value 1. Then, you could access a RRDS both
sequentially and directly by key.
v Fixed-length RRDSs use less storage and are usually faster at retrieving records
than key-sequenced data sets or variable-length RRDSs.
v If the records vary in length, use a variable-length RRDS.
v Variable-length RRDSs can be used for COBOL applications.
Entry-Sequenced Data Sets
An entry-sequenced data set is comparable to a sequential (non-VSAM) data set. It
contains records that can be either spanned or nonspanned. As Figure 8 on page 79
shows, records are sequenced by the order of their entry in the data set, rather
than by a key field in the logical record.
78
z/OS V1R6.0 DFSMS: Using Data Sets
Organizing VSAM Data Sets
R5
R4
R1
R2
R3
Figure 8. Entry-Sequenced Data Set
Records are added only at the end of the data set. Existing records cannot be
deleted. If you want to delete a record, you must flag that record as inactive. As
far as VSAM is concerned, the record is not deleted. Records can be updated, but
they cannot be lengthened. To change the length of a record in an entry-sequenced
data set, you must store it either at the end of the data set (as a new record) or in
the place of a record of the same length that you have flagged as inactive or that is
no longer required.
When a record is loaded or added, VSAM indicates its relative byte address (RBA).
The RBA is the offset of this logical record from the beginning of the data set. The
first record in a data set has an RBA of 0. The value of the RBA for the second and
subsequent records depends on whether the file is spanned and on the control
interval size chosen for the file, either manually or automatically. In general, it is
not possible to predict the RBA of each record, except for the case of fixed-length
records and a known control interval size. For a more detailed description of the
internal format of VSAM files, see “VSAM Data Formats” on page 73.
You build an alternate index to keep track of these RBAs. Although an
entry-sequenced data set does not contain an index component, alternate indexes
are permitted. See “Defining Alternate Indexes” on page 117. Figure 9 shows the
record lengths and corresponding RBAs for the data set shown in Figure 8.
RBA
X'00'
X'62'
X'9A'
X'D6'
X'11C'
R1
R2
R3
R4
R5
98
56
60
70
70
Record Length
X'162'
Figure 9. Example of RBAs of an Entry-Sequenced Data Set
Table 5 lists the operations and types of access for processing entry-sequenced data
sets.
Table 5. Entry-Sequenced Data Set Processing
Operation
Sequential Access
Direct Access
Loading the data set
Yes
No
Adding records
Space after the last record is used for adding
records
No
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
Chapter 6. Organizing VSAM Data Sets
79
Organizing VSAM Data Sets
Simulated VSAM Access to UNIX files
You can have simulated VSAM access to a UNIX file (simulated as an ESDS) by
specifying PATH=pathname in the JCL DD statement, SVC 99, or TSO ALLOCATE
command. For information about access using MVS access methods, see
“Processing UNIX Files with an Access Method” on page 20.
When you use simulated VSAM, the application program sees the UNIX file as if it
were an ESDS.
Because the system does not actually store UNIX files as ESDSs, the system cannot
simulate all the characteristics of an ESDS. Certain macros and services have
incompatibilities or restrictions when dealing with UNIX files.
Related reading: For information about VSAM interfaces and UNIX files, see
Chapter 28, “Processing z/OS UNIX Files,” on page 473 and z/OS DFSMS Macro
Instructions for Data Sets.
Record Processing for UNIX Files
Record boundaries are not maintained within binary files. Text files are presumed
to be EBCDIC. Repositioning functions (such as POINT, CLOSE TYPE=T, GET
DIRECT) are not permitted for FIFO or character special files.
When a file is accessed as binary, the length of each record is returned in the RPL,
except, possibly, the last record. Use the SHOWCB macro with FIELDS=RECLEN
to retrieve the length.
When a file is accessed as text, if any record in the file consists of zero bytes (that
is, a text delimiter is followed by another text delimiter), the record returned
consists of one blank. If any record is longer than the length of the buffer, it results
in an error return code for GET (for an ACB).
Restrictions on UNIX Files
The following VSAM restrictions are associated with UNIX files:
v Only ESDS is simulated.
v No file sharing or buffer sharing is supported except for multiple readers and, of
course, for a reader and a writer for FIFO.
v STRNO > 1 is not supported.
v Chained RPLs are not supported.
v Shared resources is not supported.
v Updated and backward processing is not supported.
v Direct processing or POINT for FIFO and character special files are not
supported.
v There is no catalog support for HFS data sets.
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.
80
z/OS V1R6.0 DFSMS: Using Data Sets
Organizing VSAM Data Sets
v To specify the maximum record size, code the LRECL keyword on the JCL DD
statement, SVC 99, or TSO ALLOCATE. If not specified, the default is 32 767.
v On return from a synchronous PUT or a CHECK associated with an
asynchronous PUT, it is not guaranteed that data written has been synchronized
to the output device. To ensure data synchronization, use ENDREQ, CLOSE, or
CLOSE TYPE=T.
v There is no CI (control interval) access (MACRF=CNV).
Services and Utilities for UNIX Files
The following services and utilities support UNIX files:
v Access method services (IDCAMS) REPRO—REPRO by DD name is supported
and uses QSAM.
v IDCAMS PRINT—PRINT by DD name is supported and uses QSAM. Instead of
displaying ’RBA OF RECORD’, PRINT displays ’RECORD NUMBER’.
v DEVTYPE macro—DEVTYPE provides information related to the UNIX file. If
PATH is specified in the DD statement, DEVTYPE returns a return code of 0, a
UCBTYP simulated value of X’00000103’, and a maximum block size of 32 760.
The following services and utilities do not support UNIX files. Unless stated
otherwise, these services and utilities return an error or unpredictable value when
issued for a UNIX file:
v IDCAMS—ALTER, DEFINE, DELETE, DIAGNOSE, EXAMINE, EXPORT,
IMPORT, LISTCAT, and VERIFY
v OBTAIN, SCRATCH, RENAME, TRKCALC, and PARTREL macros
These macros require a DSCB or UCB. HFS data sets do not have DSCBs or
valid UCBs.
Guideline: ISPF Browse/Edit does not support UNIX files, but you can use the
OBROWSE command.
Key-Sequenced Data Sets
In a key-sequenced data set, logical records are placed in the data set in ascending
collating sequence by a field, called the key. Figure 10 shows that the key contains
a unique value, such as an employee number or invoice number, that determines
the record’s collating position in the data set.
Key Field
4265
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 10. Record of a Key-Sequenced Data Set
The key must be in the same position in each record, the key data must be
contiguous, and each record’s key must be unique. After it is specified, the value of
Chapter 6. Organizing VSAM Data Sets
81
Organizing VSAM Data Sets
the key cannot be altered, but the entire record can be erased or deleted. For
compressed data sets, the key itself and any data before the key will not be
compressed.
When a new record is added to the data set, it is inserted in its collating sequence
by key, as shown in Figure 11.
Key Field
654
198
389
771
Figure 11. Inserting Records into a Key-Sequenced Data Set
Table 6 lists the operations and types of access for processing key-sequenced data
sets.
Table 6. Key-Sequenced Data Set Processing
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
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 160.
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
82
z/OS V1R6.0 DFSMS: Using Data Sets
Organizing VSAM Data Sets
pointers to each CI within a single CA. Each entry contains a compressed value
representing the highest key that can be contained within that control interval. The
value stored for the control interval containing records with the highest key in that
control area represents the highest record-key value that can be contained in that
control area. Once all the records are deleted from any single control interval, the
current high-key value is no longer associated with that control interval’s entry in
the sequence set record. It becomes a “free” control interval in which records
containing any key within the range of keys for that control area can be inserted.
This is called a CI reclaim.
However, this does not apply when it is the last empty control interval within the
control area. In that case, the high-key value for that control interval is maintained
and it becomes the highest key for any record that can be inserted into that control
area. There is no reclaim capability for control areas that is comparable to that
provided for control intervals. What can occasionally be observed as a normal
result of not reclaiming control areas is data sets that just continue to grow in size.
This will result when applications continually add records with keys that are in
ascending sequence, followed by another or the same application that deletes old
records after they have undergone some type of processing. During the deletion
processing, the high-key value that was associated with that CA will be
maintained, requiring that only records falling within that high-key range are
eligible for insertion into that control area.
Since the record keys are always getting higher, no additional records will qualify
for insertion into these empty control areas. The result is a data set in which a
majority of the space is occupied by empty control intervals. When such a
condition is detected, the only option a user has to reclaim this space is to rebuild
the data set. This will require a logical copy of the data set, followed by a deletion
of the old data set and a reload operation from the logical copy.
For more information, see z/OS DFSMS: Managing Catalogs.
Insertion of a Logical Record in a CI
Figure 12 shows how CI free space is used to insert and delete a logical record in a
KSDS or variable-length RRDS.
Figure 12. Inserting a Logical Record into a CI
Two logical records are stored in the first control interval shown in Figure 12. Each
logical record has a key (11 and 14). The second control interval shows what
happens when you insert a logical record with a key of 12.
Chapter 6. Organizing VSAM Data Sets
83
Organizing VSAM Data Sets
1. Logical record 12 is inserted in its correct collating sequence in the CI.
2. The CI definition field (CIDF) is updated to show the reduction of available
free space.
3. A corresponding record definition field (RDF) is inserted in the appropriate
location to describe the length of the new record.
When a record is deleted, the procedure is reversed, and the space occupied by the
logical record and corresponding RDF is reclaimed as free space.
Prime Index
A key-sequenced data set always has a prime index that relates key values to the
relative locations of the logical records in a data set. The prime index, or simply
index, has two uses in locating:
v The collating position when inserting records
v Records for retrieval
When initially loading a data set, records must be presented to VSAM in key
sequence. The index for a key-sequenced data set is built automatically by VSAM
as the data set is loaded with records.
When a data control interval is completely loaded with logical records, free space,
and control information, VSAM makes an entry in the index. The entry consists of
the highest possible key in the data control interval and a pointer to the beginning
of that control interval.
Key Compression
The key in an index entry is stored by VSAM in a compressed form. Compressing
the key eliminates from the front and back of a key those bytes that are not
necessary to distinguish it from the adjacent keys. Compression helps achieve a
smaller index by reducing the size of keys in index entries. VSAM automatically
does key compression in any key-sequenced data set. It is independent of whether
the data set is in compressed format.
Control Interval Splits
When a data set is first loaded, the key sequence of data records and their physical
order are the same. However, when data records are inserted, control interval splits
can occur, causing the data control intervals to have a physical order that differs
from the key sequence.
Linear Data Sets
A linear data set is a VSAM data set with a control interval size of 4096 bytes to 32
768 bytes in increments of 4096 bytes. A linear data set does not have imbedded
control information. All linear data set bytes are data bytes.
A linear data set is processed as an entry-sequenced data set, with certain
restrictions. Because a linear data set does not contain control information (CIDFs
and RDFs), it cannot be accessed as if it contained individual records. Access a
linear data set with the DIV macro. If you use DIV to access a data set, the control
interval size must be 4096; otherwise, the data set will not be processed.
Related reading: For information about using data-in-virtual (DIV), see z/OS MVS
Programming: Assembler Services Guide.
84
z/OS V1R6.0 DFSMS: Using Data Sets
Organizing VSAM Data Sets
Fixed-Length Relative-Record Data Sets
A fixed-length RRDS consists of several fixed-length slots. A fixed-length RRDS is
defined using NUMBERED and a RECORDSIZE whose average and maximum
lengths are the same.
Each slot has a unique relative record number, and the slots are sequenced by
ascending relative record number. Each record occupies a slot and is stored and
retrieved by the relative record number of that slot. The position of a data record is
fixed; its relative record number cannot change. A fixed-length RRDS cannot have
a prime index or an alternate index.
Because the slot can either contain data or be empty, a data record can be inserted
or deleted without affecting the position of other data records in the fixed-length
RRDS. The record definition field (RDF) shows whether the slot is occupied or
empty. Free space is not provided in a fixed-length RRDS because the entire data
set is divided into fixed-length slots.
In a fixed-length RRDS, each control interval contains the same number of slots.
The number of slots is determined by the control interval size and the record
length. Figure 13 shows the structure of a fixed-length RRDS after adding a few
records. Each slot has a relative record number and an RDF. Table 7 shows the
access options available for RRDS processing.
Figure 13. Fixed-length Relative-Record Data Set
Table 7 lists the operations and types of access for processing fixed-length RRDSs.
Table 7. RRDS Processing
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)
Chapter 6. Organizing VSAM Data Sets
85
Organizing VSAM Data Sets
Table 7. RRDS Processing (continued)
Operation
Sequential Access
Direct or Skip- Sequential
Access
Updating records
Yes
Yes
Deleting records
Yes (a slot given up by a
Yes (a slot given up by a
deleted record can be reused) deleted record can be reused)
Variable-Length Relative-Record Data Sets
A variable-length RRDS (VRRDS) is similar to a fixed-length RRDS, except that it
contains variable-length records. Each record has a unique relative record number,
and is placed in ascending relative record number order. Each record is stored and
retrieved using its relative record number. Unlike a fixed-length RRDS, a
variable-length RRDS does not have slots. The relative record number of a record
cannot change. When that record is erased, the relative record number can be
reused for a new record.
You must load the variable-length RRDS sequentially in ascending relative record
number order. To define a variable-length RRDS, specify NUMBERED and
RECORDSIZE. The average record length and maximum record length in
RECORDSIZE must be different.
Free space is used for inserting and lengthening variable-length RRDS records.
When a record is deleted or shortened, the space given up is reclaimed as free
space for later use. When you define your data set, use the FREESPACE parameter
to specify what percentage of each control interval and control area is to be set
aside as free space when the data set is initially loaded. “Insertion of a Logical
Record in a CI” on page 83 shows how free space is used to insert and delete a
logical record.
A variable-length RRDS cannot have spanned records and alternate indexes.
VRRDS is a KSDS processed as an RRDS so a prime index is created.
Variable-length RRDS performance is similar to a key-sequenced data set, and is
slower than for a fixed-length RRDS. Table 8 shows the operations available for
key-sequenced data sets and direct or skip-sequential access.
Table 8. Variable-Length RRDS Processing
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 9 summarizes what each data set format offers.
86
Direct or Skip- Sequential
Access
Operation
z/OS V1R6.0 DFSMS: Using Data Sets
Organizing VSAM Data Sets
Table 9. 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
Note:
1. Not supported for HFS data sets.
Extended-Format VSAM Data Sets
There are four types of VSAM extended-format data sets:
v Data compression
v Data striping
v Extended addressability (EA)
v Any combination of the above
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 Catalogs
v Other system data sets
v Temporary data sets
Chapter 6. Organizing VSAM Data Sets
87
Organizing VSAM Data Sets
When a data set is allocated as an extended format data set, the data and index are
extended format. Any alternate indexes related to an extended format cluster are
also extended format.
If a data set is allocated as an extended format data set, 32 bytes (X’20’) are added
to each physical block. Consequently, when the control interval size is calculated or
explicitly specified, this physical block overhead may increase the amount of space
actually needed for the data set. Figure 14 shows the percentage increase in space
as indicated. Other control intervals do not result in an increase in needed space
- 3390 Direct Access Device
Control Interval Size
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 14. Control Interval Size
Restrictions on Defining Extended-Format Data Sets
The following restrictions apply to defining extended-format data sets:
v An extended-format data set does not permit the indexes to be imbedded with
the data (IMBED parameter) or the data to be split into key ranges
(KEYRANGES parameter).
v Extended-format data sets must be SMS managed. The mechanism for
requesting extended format for VSAM data sets is using the SMS data class
DSNTYPE=EXT parameter and the subparameter R or P to indicate required or
preferred.
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.
88
z/OS V1R6.0 DFSMS: Using Data Sets
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 15 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 15. Primary and Secondary Space Allocations for Striped Data Sets
Figure 16 shows examples of the CIs within a control area (CA) on multiple
volumes for a four-stripe VSAM data set.
Chapter 6. Organizing VSAM Data Sets
89
Organizing VSAM Data Sets
Figure 16. Control Interval in a Control Area
Layering Concept for Data Striping
Layering is a concept generally associated with data that is striped. A layer in a
striped environment is defined as the relationship of the volumes that make up the
total number of stripes. That is, those volumes that will participate as part of the
I/O packet. Once any volume or volumes, up to a maximum of stripe count,
composing this I/O packet changes, this constitutes another layer. As relates to
striped data, the volumes that constitute this I/O packet should be viewed in the
same context as a single volume data set, as opposed to multivolume if the data
were not striped. Once the data set extends to a second layer, this would be
analogous to a multivolume nonstriped data set. Again, the definition of striped is
a stripe count greater than 1. The sequential access method (SAM) does not
support the concept of multilayering. VSAM supports multilayering. Figure 17
shows an example of the concept of layering with a four-stripe data set.
90
z/OS V1R6.0 DFSMS: Using Data Sets
Organizing VSAM Data Sets
Figure 17. Layering (Four-Stripe Data Set)
Other Considerations for Data Striping
To use data striping, you also need to consider space allocation, control area size,
and processing.
Space Allocation for Striped VSAM Data Sets: The general rules discussed for
striped extended format data sets apply to striped VSAM data sets. When the
system allocates space for a striped extended-format data set, the system divides
the primary amount among the volumes. If it does not divide evenly, the system
rounds up the amount. For extended-format data sets, when the primary space on
any volume is full, the system allocates space on that volume. The amount is the
secondary amount divided by the number of stripes. If the secondary amount does
not divide evenly, the system rounds up the amount.
Some additional considerations apply to the control area (CA) for VSAM. All
allocations must be rounded to a CA boundary. The number of stripes influences
the size of the control area, resulting in some differences in allocation quantity
required to meet the stripe count and CA requirements. The following section on
CA size considerations discusses this in more detail.
All data set extends are as described for striped data set extends. Basically, the
system divides the secondary amount by the stripe count and allocates the result
to each stripe. This occurs in all cases, including a data set with the guaranteed
space attribute from the associated storage class (SC), as well as extending to a
new layer.
Restriction: Volume High Used RBA statistics do not apply for multistriped VSAM
data sets. The high-use RBA is kept on the volume for the first stripe because the
value is the same for all stripes.
Secondary Allocation Quantity of Zero: When you specify a secondary allocation
quantity of zero for nonstriped VSAM data sets, an extend causes the allocation to
occur on a new volume, using the primary-space amount. You can also use this
feature to spread data over multiple volumes. For striped VSAM data sets,
Chapter 6. Organizing VSAM Data Sets
91
Organizing VSAM Data Sets
extensions occur by stripe and can occur on the same volume or on a new volume,
using the primary-space amount when a secondary-space amount of zero is
specified.
Increased Number of Extents: A striped VSAM data set can have 255 extents per
stripe in the data component. Only the data component is striped. The index
component of a striped VSAM data set has a limit of 255 extents, regardless of
striping. Because a striped VSAM data set can have a maximum of 16 stripes, a
striped data component can have a maximum of 4080 extents.
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 stripes. A VSAM striped data set can be striped up to
a count of 16. The minimum size for an allocation is a single track. The maximum
CA size is a cylinder. Traditionally that would have meant that the maximum CA
size, based on 3390 geometry, would be 15 tracks. That changes with striped
VSAM data set in that the maximum CA size now has to accommodate the
maximum stripe count (16), and the maximum CA now becomes 16 tracks.
The required allocation quantity now becomes a factor of both user specified
amount and stripe count. As an example, take a specification for space of
TRACKS(1 1) with the following results:
v For nonstriped, traditional VSAM, a control areas size of one track with a
resulting primary and secondary allocation quantity of 1 track.
v For a striped data set with a striped count = maximum =16, the control area size
is then 16 tracks with a resulting primary and secondary quantity of 16 tracks.
A larger CA results in a larger number of control intervals (CIs) in the CA,
resulting in a larger number of entries to index in a data set organization
containing an index (KSDS and VRRDS), with the end result being a requirement
for a larger index CI size.
Processing Considerations for Striped Data Sets: The basic restrictions associated
with data sets in the extended format also apply to striped data sets.
In addition, VSAM striped data sets do not support:
v RLS access
v Improved CI access
For the alternate index, neither the data nor the index will be striped.
Compressed Data
To use compression, a data set must be in extended format. Only extended-format
key-sequenced data sets can be compressed. The compressed data records have a
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:
92
z/OS V1R6.0 DFSMS: Using Data Sets
Organizing VSAM Data Sets
v The maximum record length for nonspanned data sets is three bytes less than
the maximum record length of data sets that do not contain compressed data
(this length is CISIZE−10).
v The relative byte address (RBA) of another record, or the address of the next
record in a buffer, cannot be determined using the length of the current record
or the length of the record provided to VSAM.
v The length of the stored record can change when updating a record without any
length change.
v The key and any data in front of the key will not be compressed. Data sets with
large key lengths and RKP data lengths might not be good candidates for
compression.
v Only the data component of the base cluster is eligible for compression.
Alternate indexes are not eligible for compression.
v The global shared resources (GSR) option is not permitted for compressed data
sets.
In addition to these incompatibilities, the data set must meet certain requirements
to permit compression at the time it is allocated:
v The data set must have a primary allocation of at least 5 MBs, or 8 MBs if no
secondary allocation is specified.
v The maximum record length specified must be at least key offset plus key length
plus forty bytes.
v Compressed data sets must be SMS managed. The mechanism for requesting
compression for VSAM data sets is through the SMS data class
COMPACTION=Y parameter.
Spanned record data sets require the key offset plus the key length to be less than
or equal to the control interval size minus fifteen. These specifications regarding
the key apply to alternate keys as well as primary keys.
Compressed data sets cannot be accessed using control interval (CI) processing
except for VERIFY and VERIFY REFRESH processing and may not be opened for
improved control interval (ICI) processing. A compressed data set can be created
using the LIKE keyword and not just using a data class.
Access to Records in a VSAM Data Set
You can use addressed-sequential and addressed-direct access for the following
types of data sets:
v Entry-sequenced data sets
v Key-sequenced data sets
You can use keyed-sequential, keyed-direct, and skip-sequential access for the
following types of data sets:
v Key-sequenced data sets
v Fixed-length RRDSs
v Variable-length RRDS
All types of VSAM data sets, including linear, can be accessed by control interval
access, but this is used only for very specific applications. CI mode processing is
not permitted when accessing a compressed data set. The data set can be opened
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 177.
Chapter 6. Organizing VSAM Data Sets
93
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 78.
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.
94
z/OS V1R6.0 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 the DIV macro.
Related reading: For information about using data-in-virtual (DIV), see z/OS MVS
Programming: Assembler Services Guide.
Access to Fixed-Length Relative-Record Data Sets
The relative record number is always used as a search argument for a fixed-length
RRDS.
Keyed-Sequential Access
Sequential processing of a fixed-length RRDS is the same as sequential processing
of an entry-sequenced data set. Empty slots are automatically skipped by VSAM.
Skip-Sequential Access
Skip-sequential processing is treated like direct requests, except that VSAM
maintains a pointer to the record it just retrieved. When retrieving subsequent
records, the search begins from the pointer, rather than from the beginning of the
data set. Records must be retrieved in ascending sequence.
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.
Chapter 6. Organizing VSAM Data Sets
95
Organizing VSAM Data Sets
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 117.
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 18 on page 97 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.
96
z/OS V1R6.0 DFSMS: Using Data Sets
Organizing VSAM Data Sets
Figure 18. Alternate Index Structure for a Key-Sequenced Data Set
If you ask to access records with the alternate key of BEN, VSAM does the
following:
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.
Chapter 6. Organizing VSAM Data Sets
97
Organizing VSAM Data Sets
Alternate Index Structure for an Entry-Sequenced Data Set
Figure 19 illustrates the structure of an alternate index connected to an
entry-sequenced data set. The salesman’s name is the alternate key in this example.
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 19. 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
98
z/OS V1R6.0 DFSMS: Using Data Sets
Organizing VSAM Data Sets
alternate-key field must be in the first segment of a spanned record. Keys in the
data component of an alternate index are not compressed; the entire key is
represented in the alternate-index data record.
A search for a given alternate key reads all the base cluster records containing this
alternate key. For example, Figure 18 on page 97 and Figure 19 on page 98 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 117. For information about defining a path, see “Defining a Path”
on page 120.
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.
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.
Chapter 6. Organizing VSAM Data Sets
99
Organizing VSAM Data Sets
Any program other than DFSMSdss, REPRO, and any other physical data
copy/move program that does direct input/output to DASD for data sets which
have data in compressed format can compromise data integrity. These programs
must be modified to access the data using VSAM keyed access to permit expansion
of compressed data.
100
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 7. Defining VSAM Data Sets
This chapter covers the following topics.
Topic
Location
Using Cluster Names for Data and Index Components
102
Defining a Data Set with Access Method Services
102
Defining a Data Set with JCL
111
Loading a VSAM Data Set
111
Copying and Merging Data Sets
115
Defining Alternate Indexes
117
Defining a Page Space
121
Checking for Problems in Catalogs and Data Sets
122
Deleting Data Sets
123
This chapter explains how to define VSAM data sets. Other chapters provide
examples and related information:
v For an example of defining a VSAM data set, see Chapter 8, “Defining and
Manipulating VSAM Data Sets: Examples,” on page 125.
v For examples of defining VSAM data sets, see z/OS DFSMS Access Method
Services for Catalogs.
v For information about defining a data set using RLS, see “Locking” on page 223.
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, 2004
101
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.
102
z/OS V1R6.0 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 for Catalogs describes the order in which one of
the catalogs available to the system is selected to contain the to-be-defined catalog
entry. When you define an object, you should ensure that the catalog the system
selects is the catalog you want the object entered.
Data set name duplication is not prevented when a user catalog is imported into a
system. No check is made to determine if the imported catalog contains an entry
name that already exists in another catalog in the system.
Temporary Data Set Names
You can use the access method services ALLOCATE or TSO ALLOCATE command
to define a temporary system-managed VSAM data set. A temporary
system-managed data set can also be allocated directly through JCL.
Temporary system-managed VSAM data sets do not require that you specify a data
set name. If you specify a data set name it must begin with & or &&:
Chapter 7. Defining VSAM Data Sets
103
Defining VSAM Data Sets
DSNAME(&CLUSTER)
See “Examples of Defining Temporary VSAM Data Sets” on page 128 for
information about using the ALLOCATE command to define a temporary
system-managed VSAM data set. See “Temporary VSAM Data Sets” on page 262
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:
104
z/OS V1R6.0 DFSMS: Using Data Sets
Defining VSAM Data Sets
v INDEXED|NONINDEXED|NUMBERED|LINEAR parameter—Specifies the
type of data organization used (key sequenced, entry sequenced, relative record,
or linear).
v RECORDSIZE parameter—Specifies the average and maximum lengths of data
records. The RECORDSIZE parameter is not used for a linear data set.
A variable-length RRDS is defined using NUMBERED and RECORDSIZE, where
the average and maximum record length must be different.
If the actual length of an entry-sequenced, key-sequenced, or variable-length
RRDS record is less than the maximum record length, VSAM saves disk space
by storing the actual record length in the record definition field (RDF). The RDF
is not adjusted for fixed-length RRDSs.
v KEYS parameter—Specifies the length and position of the key field in the
records of a key-sequenced data set.
v CATALOG parameter—Specifies the name and password of the catalog in which
the cluster is to be defined.
v VOLUMES parameter—Specifies the volume serial numbers of the volumes on
which space is allocated for the cluster. You can specify up to 59 DASD volumes.
v RECORDS|KILOBYTES|MEGABYTES|TRACKS|CYLINDERS
parameter—Specifies the amount of space to allocate for the cluster. The
CYLINDERS, TRACKS, MEGABYTES, KILOBYTES, and RECORDS parameters
are permitted for a linear data set. If you specify the RECORDS parameter for a
linear data set, the system allocates space with the number of control intervals
equal to the number of records. (Linear data sets do not have records; they have
objects that are contiguous strings of data.)
v RECATALOG parameter—Specifies if an entry is recreated from information in
the VSAM volume data set (VVDS), or defined for the first time.
v REUSE|NOREUSE parameter—Specifies if the cluster is reusable for temporary
storage of data. See “Reusing a VSAM Data Set as a Work File” on page 114.
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 164.
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 155.
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 113.
v VOLUMES parameter for the index component—Specifies whether to place the
cluster’s index on a separate volume from data.
Chapter 7. Defining VSAM Data Sets
105
Defining VSAM Data Sets
v FREESPACE parameter—Specifies the amount of free space to remain in the
data component of a key-sequenced data set or variable-length RRDS’s control
intervals and control areas when the data records are loaded.
Security and Integrity Parameters
The following access method services parameters provide security and integrity
information. See Chapter 5, “Protecting Data Sets,” on page 53 for more
information about the types of data protection available.
v Passwords—Because passwords are not supported for system-managed data
sets, this information pertains to non-system-managed data sets only. See z/OS
DFSMS Access Method Services for Catalogs.
v AUTHORIZATION parameter—Specifies your own authorization routine to
verify that a requester has the right to gain access to data.
v EXCEPTIONEXIT parameter—Specifies an I/O error-handling routine (the
exception exit routine) that is entered if the program does not specify a SYNAD
exit. See Chapter 16, “Coding VSAM User-Written Exit Routines,” on page 235
for information about VSAM user-written exit routines.
v WRITECHECK parameter—Specifies whether to verify that write operations
have completed and that the data can be read.
v SHAREOPTIONS parameter—Specifies whether and to what extent data is to
be shared among systems, and jobs.
v ERASE parameter—Specifies whether to erase the information a data set
contains when you delete the data set.
To control the erasure of data in a VSAM component whose cluster is RACF
protected and cataloged, you can use an ERASE attribute in a generic or discrete
profile. For information about specifying and using the ERASE option, see
“Erasing DASD Data” on page 60 and “Generic and Discrete Profiles for VSAM
Data Sets” on page 54.
Restriction: IDCAMS ignores the KEYRANGES parameter. 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 175 explains the index options that improve performance.
If a guaranteed space storage class (STORAGECLASS parameter) is assigned to the
data set and volume serial numbers are specified, primary space is allocated on all
specified volumes if the following conditions are met. If these conditions are not
met, the command fails and IGDxxxxI messages are printed:
v All volumes specified belong to the same storage group.
v The storage group to which these volumes belong is in the list of storage groups
selected by the ACS routines for this allocation.
106
z/OS V1R6.0 DFSMS: Using Data Sets
Defining VSAM Data Sets
You can specify space allocation at the cluster or alternate-index level, at the data
level only, or at both the data and index levels. It is best to allocate space at the
cluster or data levels. VSAM allocates space if:
v Allocation is specified at the cluster or alternate index level only, the amount
needed for the index is subtracted from the specified amount. The remainder of
the specified amount is assigned to data.
v Allocation is specified at the data level only, the specified amount is assigned to
data. The amount needed for the index is in addition to the specified amount.
v Allocation is specified at both the data and index levels, the specified data
amount is assigned to data and the specified index amount is assigned to the
index.
v Secondary allocation is specified at the data level, secondary allocation must be
specified at the index level or the cluster level.
VSAM acquires space in increments of control areas. The control area size
generally is based on primary and secondary space allocations. See “Optimizing
Control Area Size” on page 159 for information about optimizing control area size.
Partial Release
Partial release is used to release unused space from the end of an extended format
data set and is specified through SMS management class or by the JCL RLSE
subparameter. All space after the high used RBA is released on a CA boundary up
to the high allocated RBA. If the high used RBA is not on a CA boundary, the high
used amount is rounded to the next CA boundary. Partial release restrictions
include:
v Partial release processing is supported only for extended format data sets.
v Only the data component of the VSAM cluster is eligible for partial release.
v Alternate indexes opened for path or upgrade processing are not eligible for
partial release. The data component of an alternate index when opened as
cluster could be eligible for partial release.
v Partial release processing is not supported for temporary close.
v Partial release processing is not supported for data sets defined with guaranteed
space.
VSAM CLOSE will request partial release processing only if:
v Partial release was specified through SMS management class or by the JCL
SPACE=(,,RLSE) parameter on the DD statement.
v The data set is defined as extended format.
v The data set was opened for OUTPUT processing.
v This is the last ACB closing for the data set (this includes all closes in the
current address space, other address spaces in the system, and other systems).
Small Data Sets
If you allocate space for a data set in a unit smaller than one cylinder, VSAM
allocates space in tracks when defining the data set. For data sets less than 1
cylinder in size, it is best to specify the maximum number of tracks required in the
primary allocation for the data component, 1 track for the sequence set index
(which should not be imbedded), and no secondary allocation for either data or
index.
VSAM checks the smaller of primary and secondary space values against the
specified device’s cylinder size. If the smaller quantity is greater than or equal to
the device’s cylinder size, the control area is set equal to the cylinder size. If the
Chapter 7. Defining VSAM Data Sets
107
Defining VSAM Data Sets
smaller quantity is less than the device’s cylinder size, the size of the control area
is set equal to the smaller space quantity. The minimum control area size is one
track. See “Optimizing Control Area Size” on page 159 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 109 demonstrates how to calculate the size of a data set.
See “Using Index Options” on page 175 for information about index options.
Linear Data Sets
|
|
You must allocate space in tracks, cylinders, records, kilobytes, or megabytes for a
linear data set.
|
|
|
|
|
When you define a linear data set, you can specify a control interval size of 4096 to
32 768 bytes in increments of 4096 bytes. If not an integer multiple of 4096, the
control interval size is rounded up to the next 4096 increment. The system chooses
the best physical record size to use the track size geometry. For example, if you
specify CISIZE(16384), the block size is set to 16 384. If the specified
BUFFERSPACE is greater than 8192 bytes, it is decremented to a multiple of 4096.
If BUFFERSPACE is less than 8192, access method services issues a message and
fails the command.
Using VSAM Extents
A primary space allocation is the initial amount of allocated space. When the primary
amount on the first volume is used up, a secondary amount is allocated on that
volume. Each time a new record does not fit in the allocated space, the system
allocates more space in the secondary space amount. The system repeats allocating
this space until the volume is out of space or the volume extent limit of 123 is
reached.
For nonstriped VSAM data sets, you can specify in the SMS data class parameter
whether to use primary or secondary allocation amounts when extending to a new
volume. You can expand the space for a nonstriped VSAM component to 255
extents.
You can expand the space for a striped VSAM data component to 255 times the
number of stripes. The system reserves the last four extents for extending a
component when the system cannot allocate the last extent in one piece.
For both guaranteed and nonguaranteed space allocations, when you allocate space
for your data set, you can specify both a primary and a secondary allocation.
Guaranteed and nonguaranteed space allocation work similarly until the system
extends the data set to a new volume. The difference is that the guaranteed space
data set uses the “candidate with space” amount that is already allocated on that
volume.
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
108
z/OS V1R6.0 DFSMS: Using Data Sets
Defining VSAM Data Sets
can be allocated on the primary volume, the system uses the “candidate with
space” amount on the next volume. Subsequent extends again use the secondary
amounts to allocate space until the volume is full. Then the system uses the
“candidate with space” amount on the next volume, and so forth.
VSAM Extent Consolidation
The system consolidates adjacent extents for VSAM data sets when extending on
the same volume. VSAM extent consolidation is automatic and requires no action
on your part. If the extents are adjacent, the new extent is incorporated into the
previous extent.
Example: The old extent begins on cylinder 6, track 0, and ends on cylinder 9,
track 14, and the new extent begins on cylinder 10, track 0, and ends on cylinder
12, track 14. The two extents are combined into one extent beginning on cylinder 6,
track 0, and ending on cylinder 12, track 14. Instead of two extents, there is only
one extent. Because VSAM combines the two extents, it does not increment the
extent count, which reduces the amount of extents.
Example: You allocate a VSAM data set with CYLINDERS(3 1). The data set
initially gets three cylinders and an additional cylinder every time the data set is
extended. Suppose you extend this data set five times. If none of the extents are
adjacent, the LISTCAT output shows allocations of cylinders 3,1,1,1,1,1, or a total of
eight cylinders.
Results: Depending on which extents are adjacent, the LISTCAT output might
show allocations of cylinders 5,1,1,1, or cylinders 3,5, or cylinders 3,2,3, as follows:
v For the 5,1,1,1 example, only the first three extents are adjacent.
v For the 3,5 example, the first and second extent are not adjacent, but the third
through eighth extent are adjacent.
v For the 3,2,3 example, the first and second extent are not adjacent, the second
and third extents are adjacent, the third and fourth extents are not adjacent, and
the last three extents are adjacent.
All types of SMS-managed VSAM data sets (KSDS, ESDS, RRDS, VRRDS, and
LDS) use extent consolidation.
Restriction: VSAM does not support extent reduction for the following types of
data sets:
v Key-range data sets
v System data sets such as page spaces
v Catalogs
v
v
v
v
VVDSs
Non-system managed data sets
Imbedded or replicated indexes
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:
Chapter 7. Defining VSAM Data Sets
109
Defining VSAM Data Sets
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.
6.
7.
8.
Maximum number of control intervals per control area (33 × 15)=495.
Number of loaded control intervals per control area = 446 (495 – 10% × 495).
Number of loaded records per cylinder (4 × 446) = 1784.
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 (16
minus 1 for the imbedded sequence set control interval).
Calculating Space for the Index Component
There is no specific formula for calculating the space required for the index
component. Use the access method services command LISTCAT to see how much
space was allocated to the index component.
Using ALTER to Modify Attributes of a Component
After a data set has been defined, you can change some of its attributes using the
access method services command, ALTER. You identify the component by name,
and specify the new attributes. ALTER can also be used to change an
entry-sequenced data set, with the proper attributes, to a linear data set. The
contents of the data set are not modified. See z/OS DFSMS Access Method Services
for Catalogs for an example of changing an entry-sequenced data set to a linear data
set.
You cannot use ALTER to change a fixed-length RRDS into a variable-length RRDS,
or vice versa.
Using ALTER to Rename Data Sets
You can use the ALTER command to rename VSAM data sets and members of
PDSs and PDSEs, and to convert VSAM data sets from non-system managed to
system managed. ALTER can also convert system-managed data sets to non-system
managed. See z/OS DFSMS Access Method Services for Catalogs to determine which
values or attributes you can alter for a particular data set type.
110
z/OS V1R6.0 DFSMS: Using Data Sets
Defining VSAM Data Sets
Defining a Data Set with JCL
SMS must be active on your system before you can use JCL to define a VSAM data
set. Any VSAM data set can be defined using JCL, except for a variable-length
RRDS. Defining a VSAM data set using JCL has certain advantages. It takes less
time to input and it makes syntax for defining the VSAM data set very similar to
that used for accessing it.
DB2 provides striping on partitioned table spaces. Each of the partitions is a
separate linear data set. Striping is used to perform parallel I/O concurrently
against more than one of these partitions. The benefit of striping is only achievable
if multiple partitions do not get allocated on the same volume. You can achieve
volume separation without resorting to the storage class guaranteed space
allocations on system-managed volumes.
Allocate all of the partitions in a single IEFBR14 job step using JCL. If an adequate
number of volumes exist in the storage groups, and the volumes are not above the
allocation threshold, the SMS allocation algorithms with SRM will ensure each
partition is allocated on a separate volume.
DB2 striping is unrelated to VSAM striping (see “Extended-Format VSAM Data
Sets” on page 87). 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 259 for information about the JCL keywords used to define a VSAM data set.
See z/OS MVS JCL Reference and z/OS MVS JCL User’s Guide for information about
JCL keywords and the use of JCL.
Loading a VSAM Data Set
After a data set is defined, you can load records into it from a source data set.
Depending on the type of VSAM data set being loaded, the source data set records
might or might not need to be in a particular order.
v Records being loaded into an entry-sequenced data set do not have to be
submitted in any particular order. Entry-sequenced data set records are
sequenced by their time of arrival rather than by any field in the logical record.
v Fixed-length RRDS records are placed into slots specified either by a
user-supplied or a VSAM-supplied relative record number. The relative record
number is not part of the logical record, so it is not necessary that the records be
submitted in any particular order.
v Records being loaded into a key-sequenced data set must be in ascending order
by key, with no duplicate keys in the input data set.
v Records being loaded into a variable-length RRDS must be in ascending order
by key, with no duplicate keys in the input data set. If they are loaded in
sequential mode, VSAM assigns the relative record number.
With entry-sequenced or key-sequenced data sets, or RRDSs, you can load all the
records either in one job or in several jobs. If you use multiple jobs to load records
into a data set, VSAM stores the records from subsequent jobs in the same manner
that it stored records from preceding jobs, extending the data set as required.
Chapter 7. Defining VSAM Data Sets
111
Defining VSAM Data Sets
Using REPRO to Copy a VSAM Data Set
The REPRO command lets you retrieve records from a sequential,
indexed-sequential, or VSAM data set and store them in VSAM format in a
key-sequenced, entry-sequenced, relative-record, or a sequential data set. The
REPRO command is also used to load data from one linear data set into another
linear data set.
When records are to be stored in key sequence, index entries are created and
loaded into an index component as data control intervals and control areas are
filled. Free space is left as indicated in the cluster definition in the catalog, and, if
indicated in the definition, records are stored on particular volumes according to
key ranges.
VSAM data sets must be cataloged. Sequential and indexed sequential data sets
need not be cataloged. Sequential data sets that are system managed must be
cataloged.
If a sequential or indexed-sequential data set is not cataloged, include the
appropriate volume and unit parameters on your DD statement. Also, supply a
minimum set of DCB parameters when the input data set is sequential or indexed
sequential, and/or the output data set is sequential. The following table shows the
four key parameters:
Parameters
User Can Supply
Default if Not Supplied
DSORG
IS
PS
RECFM
F, FB, V, VB, VS, VBS
U
BLKSIZE
Block size
None
LRECL
Logical record length
BLKSIZE for F or FB BLKSIZE-4 for
V, VB, VS, VBS
The only way to specify the DSORG parameter is to use the DD statement. The
DCB parameters RECFM, BLKSIZE, and LRECL can be supplied using the DSCB
or header label of a standard labeled tape, or by the DD statement. The system can
determine the optimum block size.
If you use REPRO to copy to a sequential data set, you do not need to supply a
block size because the system determines the block size when it opens the data set.
You can optionally supply a BLKSIZE value using JCL or when you define the
output data set.
If you are loading a VSAM data set into a sequential data set, you must remember
that the 3-byte VSAM record definition field (RDF) is not included in the VSAM
record length. When REPRO attempts to copy a VSAM record whose length is
more than the non-VSAM LRECL−4, a recoverable error occurs and the record is
not copied. (Each non-VSAM record has a four-byte prefix that is included in the
length. Thus, the length of each VSAM variable-length record is four bytes less
than the length of the non-VSAM record.)
Access method services does not support records greater than 32 760 bytes for
non-VSAM data sets (LRECL=X is not supported). If the logical record length of a
non-VSAM input data set is greater than 32 760 bytes, or if a VSAM data set
defined with a record length greater than 32 760 is to be copied to a sequential
data set, the REPRO command terminates with an error message.
112
z/OS V1R6.0 DFSMS: Using Data Sets
Defining VSAM Data Sets
Records in an indexed sequential data set that have a fixed-length, unblocked
format with a relative-key position of zero are preceded by the key string when
used as input. The records in the output data set must have a record length
defined that includes the extended length caused by the key string. To copy
“dummy” indexed-sequential records (with X'FF' in the first byte), specify the
DUMMY option in the ENVIRONMENT parameter.
The REPRO operation is terminated if:
v One physical I/O error is found while writing to the output data set
v A total of four errors is found in any combination of the following:
– Logical error while writing to the output data set
– Logical error while reading the input data set
– Physical error while reading the input data set
Related reading: For information about physical and logical errors, see z/OS
DFSMS Macro Instructions for Data Sets.
Using a Program to Load a Data Set
To use your own program to load a key-sequenced data set, first sort the records
(or build them) in key sequence, then store them sequentially (using the PUT
macro). When you are initially loading a data set, direct access is not permitted.
For more information about inserting records into a data set, see “Inserting and
Adding Records” on page 140.
VSAM uses the high-used RBA field to determine whether a data set is empty. An
implicit verify can update the high-used RBA. Immediately after definition of a
data set, the high-used RBA value is zero. An empty data set cannot be verified.
The terms create mode, load mode, and initial data set load are synonyms for the
process of inserting records into an empty VSAM data set. To start loading an
empty VSAM data set, call the VSAM OPEN macro. Following a successful open,
the load continues while records are added and concludes when the data set is
closed.
Restriction: If an entry-sequenced data set fails to load, you cannot open it.
Certain restrictions apply during load mode processing:
v PUT and CHECK are the only macros you can use.
v Do not use improved control interval processing.
v You cannot do update or input processing until the data set has been loaded and
closed.
v Specify only one string in the ACB (STRNO>1 is not permitted).
v Do not specify local shared resources (LSR) or global shared resources (GSR).
v You cannot share the data set.
v Direct processing is not permitted (except relative record keyed direct).
If the design of your application calls for direct processing during load mode, you
can avoid this restriction by following these steps:
1. Open the empty data set for load mode processing.
2. Sequentially write one or more records, which could be dummy records.
3. Close the data set to terminate load mode processing.
4. Reopen the data set for normal processing. You can now resume loading or do
direct processing. When using this method to load a VSAM data set, be
Chapter 7. Defining VSAM Data Sets
113
Defining VSAM Data Sets
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 235.
During load mode, each control area can be preformatted as records are loaded
into it. Preformatting is useful for recovery if an error occurs during loading.
However, performance is better during initial data set load without preformatting.
The RECOVERY parameter of the access method services DEFINE command is
used to indicate that VSAM is to preformat control areas during load mode. In the
case of a fixed-length RRDS and SPEED, a control area in which a record is
inserted during load mode will always be preformatted. With RECOVERY, all
control areas will be preformatted.
Preformatting clears all previous information from the direct access storage area
and writes end-of-file indicators. For VSAM, an end-of-file indicator consists of a
control interval with a CIDF equal to zeros.
v For an entry-sequenced data set, VSAM writes an end-of-file indicator in every
control interval in the control area.
v For a key-sequenced data set, VSAM writes an end-of-file indicator in the first
control interval in the control area following the preformatted control area. (The
preformatted control area contains free control intervals.)
v For a fixed-length RRDS, VSAM writes an end-of-file indicator in the first
control interval in the control area following the preformatted control area. All
RDFs in an empty preformatted control interval are marked “slot empty”.
As records are loaded into a preformatted control area of an entry-sequenced data
set, an end-of-file indicator following the records indicates how far loading has
progressed. You can then resume loading at that point, after verifying the data set.
(You cannot open the data set unless you first verify it.) If an error occurs that
prevents loading from continuing, you can identify the last successfully loaded
record by reading to end of file.
The SPEED parameter does not preform at the data control areas. It writes an
end-of-file indicator only after the last record is loaded. Performance is better if
you use the SPEED parameter and if using extended format data sets. Extended
format data sets may use system-managed buffering. This permits the number of
data buffers to be optimized for load mode processing. This can be used with the
REPRO parameter for a new data set for reorganization or recovery. If an error
occurs that prevents loading from continuing, you cannot identify the last
successfully loaded record and you might have to reload the records from the
beginning. For a key-sequenced data set, the SPEED parameter only affects the
data component.
Rule: Remember that, if you specify SPEED, it will be in effect for load mode
processing. After load mode processing, RECOVERY will be in effect, regardless of
the DEFINE specification.
Reusing a VSAM Data Set as a Work File
VSAM enables you to define reusable data sets to use as work files. Define the
data set as reusable and specify that it be reset when you open it. You also can
reuse a striped VSAM data set.
114
z/OS V1R6.0 DFSMS: Using Data Sets
Defining VSAM Data Sets
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 217.
You can use the REPRO command to do any of the following:
v Copy or merge a VSAM data set into another VSAM data set.
v Copy or merge a sequential data set into another sequential data set.
v Copy an alternate index as a key-sequenced VSAM data set.
v Copy a VSAM data set whose records are fixed length into an empty
fixed-length RRDS.
v Convert a sequential or indexed sequential data set into a VSAM data set.
v Copy a VSAM data set into a sequential data set.
v Copy a data set (other than a catalog) to reorganize it. Data sets are reorganized
automatically.
v Copy individual members of a PDS or PDSE. A PDS or PDSE cannot be copied,
but individual members can be copied.
Chapter 7. Defining VSAM Data Sets
115
Defining VSAM Data Sets
When copying to a key-sequenced data set, the records to be copied must be in
ascending order, with no duplicates in the input data set. All the keys must be
unique. With an entry-sequenced data set, the records to be copied can be in any
order.
Because data is copied as single logical records in either key order or physical
order, automatic reorganization can take place as follows:
v Physical relocation of logical records
v Alteration of a record’s physical position within the data set
v Redistribution of free space throughout the data set
v Reconstruction of the VSAM indexes
If you are copying to or from a sequential data set that is not cataloged, you must
include the appropriate volume and unit parameters on your DD statements. For
more information about these parameters see “Using REPRO to Copy a VSAM
Data Set” on page 112.
Table 10 describes how the data from the input data set is added to the output data
set when the output data set is an empty or nonempty entry-sequenced, sequential,
key-sequenced, or linear data set, or fixed-length or variable-length RRDS.
Table 10. Adding Data to Various Types of Output Data Sets
Type of Data Set
Empty
Nonempty
Entry sequenced
Loads new data set in
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.
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.
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.
116
z/OS V1R6.0 DFSMS: Using Data Sets
Defining VSAM Data Sets
Defining Alternate Indexes
An alternate index is a key-sequenced data set containing index entries organized
by the alternate keys of its associated base data records. It provides another way of
locating records in the data component of a cluster.
An alternate index can be defined over a key-sequenced or entry-sequenced cluster.
An alternate index cannot be defined for a reusable cluster, a fixed- or
variable-length RRDS, a catalog, 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 96 for
information about the structure of an alternate index.
The sequence for building an alternate index is as follows:
1. Define the base cluster, using either the ALLOCATE command, the DEFINE
CLUSTER command, or JCL.
2. Load the base cluster either by using the REPRO command or by writing your
own program to load the data set.
3. Define the alternate index, using the DEFINE ALTERNATEINDEX command.
4. Relate the alternate index to the base cluster, using the DEFINE PATH
command. The base cluster and alternate index are described by entries in the
same catalog.
5. Build the alternate index, using the BLDINDEX command.
VSAM uses three catalog entries to describe an alternate index:
v An alternate index entry describes the alternate index as a key-sequenced cluster.
v A data entry describes the alternate index’s data component.
v An index entry describes the alternate index’s index component.
Except for data class, attributes of the alternate index’s data and index components
can be specified separately from the attributes of the whole alternate index. If
attributes are specified for the whole alternate index and not for the data and
index components, these attributes (except for password and USVR security
attributes) apply to the components as well. If the attributes are specified for the
components, they override any attributes specified for the entire alternate index.
Naming an Alternate Index
You specify an entry name for an alternate index when you define it. You can
specify the entry name as the dsname in a JCL DD statement. For details on how
VSAM can generate component names for you, see “Naming a Cluster” on page
102.
Specifying Alternate Index Information
When you define an alternate index, you specify descriptive information and
performance, security, and data integrity options. The information can apply to the
alternate index’s data component, its index component, or the whole alternate
index. Information for the entire alternate index is specified with the
Chapter 7. Defining VSAM Data Sets
117
Defining VSAM Data Sets
ALTERNATEINDEX parameter and its subparameters. Information for the data
component or the index component is specified with the parameter DATA or
INDEX.
Passwords are not supported for system-managed alternate indexes. To define an
alternate index, you must have RACF alter authority for the base cluster.
Specifying Descriptive Information for an Alternate Index
You need to specify the following descriptive information for an alternate index:
v The name and password of the base cluster related to the alternate index, as
specified in the RELATE parameter. The RELATE entry name must be selected
so that the multilevel alias facility selects the correct catalog. See z/OS DFSMS:
Managing Catalogs for information about the multilevel alias facility and z/OS
DFSMS Access Method Services for Catalogs for information about the order of
catalog search.
v Amount of space to allocate for the alternate index, as specified in the
CYLINDERS|KILOBYTES|MEGABYTES|RECORDS|TRACKS parameter.
v Volume serial numbers of the volumes on which space is allocated for the
alternate index, as designated in the VOLUMES parameter. If you specify the
VOLUMES parameter for system-managed data sets, however, the volumes
designated might or might not be used, and sometimes can result in a failure.
You can indicate nonspecific volumes for a system-managed data set by
designating an asterisk (*) for each volume serial. SMS then determines the
volume serial. The default is one volume. Note that if both specific and
nonspecific volumes are designated, the specified volume serials must be named
first.
v The minimum amount of I/O buffer space that OPEN must provide when the
program processes the alternate index’s data, as designated in the
BUFFERSPACE parameter.
v Name and password of the catalog containing the alternate index’s entries, as
designated in the CATALOG parameter. This must be the same catalog that
contains the base cluster’s entries.
v Data class, for alternate indexes, to take advantage of the attributes assigned by
the storage administrator.
v Length and position of the alternate key field in data records of the base cluster,
as specified in the KEYS parameter.
v Average and maximum lengths of alternate index records, as specified in the
RECORDSIZE parameter.
v Whether the alternate index is reusable, as specified in the REUSE parameter.
v Whether the data set is extended format and whether it has extended
addressability. These characteristics for the alternate index are the same as those
for the cluster.
The performance options and the security and integrity information for the
alternate index are the same as that for the cluster. See “Using Access Method
Services Parameters” on page 104.
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
118
z/OS V1R6.0 DFSMS: Using Data Sets
Defining VSAM Data Sets
example, you would not be able to support as many nonunique keys as you would
if the maximum RECORDSIZE value were 5000.
Building an Alternate Index
When an alternate index is built by BLDINDEX processing, the alternate index’s
volume and the base cluster’s volume must be mounted. Any volumes identified
with the WORKFILES parameter must also be mounted. If one of the data sets
identified by the WORKFILES ddname is system managed, the other data set must
be either a system-managed data set or a non-system-managed data set cataloged
in the catalog determined by the catalog search order. The base cluster cannot be
empty (that is, its high-used RBA value cannot be zero). Each record’s alternate key
value must be unique, unless the alternate index was defined with the
NONUNIQUEKEY attribute.
Access method services opens the base cluster to read the data records sequentially,
sorts the information obtained from the data records, and builds the alternate
index data records.
The base cluster’s data records are read and information is extracted to form the
key-pointer pair:
v When the base cluster is entry sequenced, the alternate-key value and the data
record’s RBA form the key-pointer pair.
v When the base cluster is key sequenced, the alternate-key value and the
primary-key value of the data set record form the key-pointer pair.
The key-pointer pairs are sorted in ascending alternate-key order.
After the key-pointer pairs are sorted into ascending alternate key order, access
method services builds alternate index records for key-pointer pairs. When all
alternate index records are built and loaded into the alternate index, the alternate
index and its base cluster are closed. You cannot build an alternate index over an
extended addressable entry-sequenced data set.
Related reading: For information about calculating the amount of virtual storage
required to sort records, using the BLDINDEX command, and the catalog search
order, see z/OS DFSMS Access Method Services for Catalogs.
Maintaining Alternate Indexes
VSAM assumes alternate indexes are always synchronized with the base cluster
and does not check synchronization during open processing. Therefore, all
structural changes made to a base cluster must be reflected in its alternate index or
indexes. This is called index upgrade.
You can maintain your own alternate indexes or have VSAM maintain them. When
the alternate index is defined with the UPGRADE attribute of the DEFINE
command, VSAM updates the alternate index whenever there is a change to the
associated base cluster. VSAM opens all upgrade alternate indexes for a base
cluster whenever the base cluster is opened for output. If you are using control
interval processing, you cannot use UPGRADE. See Chapter 11, “Processing
Control Intervals,” on page 177.
You can define a maximum of 125 alternate indexes in a base cluster with the
UPGRADE attribute.
Chapter 7. Defining VSAM Data Sets
119
Defining VSAM Data Sets
All the alternate indexes of a given base cluster that have the UPGRADE attribute
belong to the upgrade set. The upgrade set is updated whenever a base data
record is inserted, erased, or updated. The upgrading is part of a request and
VSAM completes it before returning control to your program. If upgrade
processing is interrupted because of a machine or program error so that a record is
missing from the base cluster but its pointer still exists in the alternate index,
record management will synchronize the alternate index with the base cluster by
letting you reinsert the missing base record. However, if the pointer is missing
from the alternate index, that is, the alternate index does not reflect all the base
cluster data records, you must rebuild your alternate index to resolve this
discrepancy.
Note that when you use SHAREOPTIONS 2, 3, and 4, you must continue to ensure
read/write integrity when issuing concurrent requests (such as GETs and PUTs) on
the base cluster and its associated alternate indexes. Failure to ensure read/write
integrity might temporarily cause “No Record Found” or “No Associated Base
Record” errors for a GET request. You can bypass such errors by reissuing the GET
request, but it is best to prevent the errors by ensuring read/write integrity.
If you specify NOUPGRADE in the DEFINE command when the alternate index is
defined, insertions, deletions, and changes made to the base cluster will not be
reflected in the associated alternate index.
When a path is opened for update, the base cluster and all the alternate indexes in
the upgrade set are allocated. If updating the alternate indexes is unnecessary, you
can specify NOUPDATE in the DEFINE PATH command and only the base cluster
is allocated. In that case, VSAM does not automatically upgrade the alternate
index. If two paths are opened with MACRF=DSN specified in the ACB macro, the
NOUPDATE specification of one can be nullified if the other path is opened with
UPDATE specified.
How Reorganization Affects Alternate Indexes
If you reorganize a base cluster, you do not need to rebuild the alternate indexes,
because the relationships between the base cluster and the alternate indexes have
not changed. If you unload a VSAM data set, delete the existing cluster on DASD,
redefine the CLUSTER on DASD, then load the new data set from the unloaded
copy, then you do not need to rebuild the alternate index.
Alternate Index Backups
You can use DFSMShsm to back up a base cluster and its associate alternate
indexes. For more information see z/OS DFSMShsm Managing Your Own Data.
Defining a Path
After an alternate index is defined, you need to establish the relationship between
an alternate index and its base cluster, using the access method services command,
DEFINE PATH. You must name the path and can also give it a password. The path
name refers to the base cluster/alternate index pair. When you access the data set
through the path, you must specify the path name in the DSNAME parameter in
the JCL.
When your program opens a path for processing, both the alternate index and its
base cluster are opened. When data in a key-sequenced base cluster is read or
written using the path’s alternate index, keyed processing is used. RBA processing
is permitted only for reading or writing an entry-sequenced data set’s base cluster.
120
z/OS V1R6.0 DFSMS: Using Data Sets
Defining VSAM Data Sets
Related reading: See z/OS DFSMS Access Method Services for Catalogs for
information about using the DEFINE PATH command.
Defining a Page Space
A page space is a system data set that contains pages of virtual storage. The pages
are stored into and retrieved from the page space by the auxiliary storage manager.
A page space is an entry-sequenced cluster that is preformatted (unlike other data
sets) and is contained on a single volume. You cannot open a page space as a user
data set. A page space has a size limit of 4 GB.
A page space has a maximum size equal to 16 777 215 slots (records). However, the
actual usable page space is much less because it has a size limit of 4 GB.
The considerations for defining a page space are much like those for defining a
cluster. The DEFINE PAGESPACE command has many of the same parameters as
the DEFINE CLUSTER command, so the information you must supply for a page
space is similar to what you would specify for a cluster. A page space data set
cannot be in extended format. For a 3390 DASD, the maximum size of a page
space that you can specify on the DEFINE PAGESPACE with CYLINDERS is 5 825.
You can define a page space in a user catalog, then move the catalog to a new
system, and establish it as the system’s master catalog. For page spaces to be
system managed, they must be cataloged, and you must let the system determine
which catalog to use. Page spaces also cannot be duplicate data sets. The system
cannot use a page space if its entry is in a user catalog.
When you issue a DEFINE PAGESPACE command, the system creates an entry in
the catalog for the page space, then preformats the page space. If an error occurs
during the preformatting process (for example, an I/O error or an allocation error),
the page space’s entry remains in the catalog even though no space for it exists.
Issue a DELETE command to remove the page space’s catalog entry before you
redefine the page space.
Each page space is represented by two entries in the catalog: a cluster entry and a
data entry. (A page space is an entry-sequenced cluster.) Both of these entries
should be password protected if the page space is password protected.
The system recognizes a page space if it is defined as a system data set at system
initialization time or if it is named in SYS1.PARMLIB. To be used as a page space,
it must be defined in a master catalog.
Recommendations:
1. When you define page spaces during system initialization, use the ALTER
command to add passwords to each entry because passwords cannot be
specified during system initialization. The passwords you specify with the
DEFINE PAGESPACE command are put in both the page space’s cluster entry
and its data entry. Unless you ensure that the catalog containing the page space
entry is either password protected or RACF protected, a user can list the
catalog’s contents and find out each entry’s passwords.
2. Passwords are ignored for system-managed data sets. For these, you must have
RACF alter authority.
Related reading:
Chapter 7. Defining VSAM Data Sets
121
Defining VSAM Data Sets
v For information about using the DEFINE PAGESPACE parameter to define the
page size, see z/OS DFSMS Access Method Services for Catalogs.
v For details on specifying information for a data set, especially for
system-managed data sets, see “Specifying Cluster Information” on page 104
and “Using Access Method Services Parameters” on page 104.
v For information about how VSAM handles duplicate data sets, see “Duplicate
Data Set Names” on page 103.
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 115.
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 229.
Related reading: For more information about VERIFY, see “Using VERIFY to
Process Improperly Closed Data Sets” on page 50. For information about using the
DIAGNOSE command to indicate the presence of nonvalid data or relationships in
the BCS and VVDS, see z/OS DFSMS: Managing Catalogs.
Listing Catalog Entries
After you define a catalog or data set, use the access method services command
LISTCAT to list all or part of a catalog’s entries. LISTCAT shows information about
objects defined in the catalog, such as:
v Attributes of the object, including SMS attributes
v Creation and expiration dates
v Protection specification
v Statistics on dynamic usage or data set accessing represented by the entry
v Space allocation
v Volume information
v Structure of the data set
The listing can be customized by limiting the number of entries, and the
information about each entry, that is printed.
You can obtain the same list while using the interactive storage management
facility (ISMF) by issuing the CATLIST line operator on the Data Set List panel.
The list is placed into a data set, which you can view immediately after issuing the
request.
Related reading: See z/OS DFSMS: Using the Interactive Storage Management Facility
for information about the CATLIST line operator.
122
z/OS V1R6.0 DFSMS: Using Data Sets
Defining VSAM Data Sets
Printing the Contents of Data Sets
If a problem occurs, you can use the access method services command PRINT to
print part or all of the contents of a fixed-length or variable-length RRDS; a
key-sequenced, linear, or entry-sequenced VSAM data set; an alternate index; or a
catalog. If you use the relative byte address, you can print part of a linear data set.
Partial printing is rounded up to 4096 byte boundaries. The components of a
key-sequenced data set or an alternate index can be printed individually by
specifying the component name as the data set name. An alternate index is printed
as though it were a key-sequenced cluster.
Entry-sequenced and linear data sets are printed in physical sequential order.
Key-sequenced data sets can be printed in key order or in physical-sequential
order. Fixed-length or variable-length RRDSs are printed in relative record number
sequence. A base cluster can be printed in alternate key sequence by specifying a
path name as the data set name for the cluster.
Only the data content of logical records is printed. System-defined control fields
are not printed. Each record printed is identified by one of the following:
v The relative byte address (RBA) for entry-sequenced data sets.
v The key for indexed-sequential and key-sequenced data sets, and for alternate
indexes
v The record number for fixed-length or variable-length RRDSs.
Related reading: See z/OS MVS Programming: Authorized Assembler Services Guide
for information about program authorization. See “Authorized Program Facility
and Access Method Services” on page 62 for information about using the PRINT
command to print a catalog.
Restriction: If the system finds four logical and/or physical errors while
attempting to read the input, printing ends abnormally.
Deleting Data Sets
Use the access method services DELETE command, described in z/OS DFSMS
Access Method Services for Catalogs, to delete data sets, catalogs, and objects.
DELETE entry name removes the data set from the volume on which it resides, and
the catalog entry for the data set. You can delete the entire cluster, or just the
alternate index, path, or alias, for example. Use DELETE entry name VVR FILE
(ddname) to delete an uncataloged VSAM data set. DELETE entry name VVR FILE
(ddname) removes the VSAM volume record (VVR) from the VSAM volume data
set (VVDS), and the data set control block from the volume table of contents
(VTOC).
Use the ERASE parameter if you want to erase the components of a cluster or
alternate index when deleting it. ERASE overwrites the data set. Use the
NOSCRATCH parameter if you do not want the data set entry (DSCB) removed
from the VTOC. NOSCRATCH nullifies an ERASE parameter on the same DELETE
command.
Use access method services to delete a VSAM cluster or a path which has
associated alternate indexes defined with NOUPGRADE. However, if you perform
the delete using JCL by specifying a DD statement with DISP=(OLD,DELETE), all
volumes that are necessary to delete the alternate index are not allocated. The
delete operation fails with an error message when the job step ends.
Chapter 7. Defining VSAM Data Sets
123
124
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 8. Defining and Manipulating VSAM Data Sets:
Examples
This chapter covers the following topics.
Topic
Location
Example of Defining a VSAM Data Set
126
Examples of Defining Temporary VSAM Data Sets
128
Examples of Defining Alternate Indexes and Paths
129
The following set of examples contain a wide range of functions available through
access method services commands that let you define:
v VSAM data sets
v Temporary VSAM data sets
v Alternate indexes and paths
See z/OS DFSMS Access Method Services for Catalogs for examples of the other
functions available through access method services.
An existing system catalog is assumed to be security protected at the
update-password, control-password, and master-password levels. Because
passwords are not supported for system-managed data sets and catalogs, assume
that you have RACF authority for the operation being performed in the examples
that define or manipulate system-managed data sets and catalogs.
© Copyright IBM Corp. 1987, 2004
125
Defining and Manipulating VSAM Data Sets: Examples
Example of Defining a VSAM Data Set
The following example shows a typical sequence of commands to create a catalog,
define a data set (that is cataloged in the newly created catalog), load the data set
with data, list the data set’s catalog entry, and print the data set:
//DEFINE
//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 LISTCAT ENTRIES(EXAMPL1.KSDS)
IF LASTCC = 0 THEN PRINT INDATASET(EXAMPL1.KSDS)
/*
The following access method services commands are used in this example:
DEFINE USERCATALOG
DEFINE CLUSTER
REPRO
LISTCAT
PRINT
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 259 for
examples of creating VSAM data sets through JCL. See z/OS DFSMS Access Method
Services for Catalogs for more details and examples of these or other access method
services commands.
126
z/OS V1R6.0 DFSMS: Using Data Sets
Defining and Manipulating VSAM Data Sets: Examples
The first DEFINE command defines a user catalog named USERCATX. The
USERCATALOG keyword specifies that a user catalog is to be defined. The
command’s parameters follow.
NAME
NAME is required and names the catalog being defined.
ICFCATALOG
Specifies the catalog format.
CYLINDERS
Specifies the amount of space to be allocated from the volume’s
available space. If it is specified for a system-managed catalog, it
overrides the DATACLAS space specification. A space parameter is
required.
VOLUMES
Specifies the volume to contain the catalog.
If the catalog is system-managed, then the system picks the volume.
SMS ignores the value that is specified in the VOLUMES parameter.
However, if the catalog belongs to a storage class with guaranteed space,
SMS selects the volume that you specify in the VOLUMES parameter.
You also can write an ACS routine that uses the volume specified in the
VOLUMES parameter to select a storage class.
DATA
DATA is required when attributes are to be explicitly specified for the
data component of the cluster.
CYLINDERS
Specifies the amount of space allocated for the data component. A space
parameter is required.
The second DEFINE command defines a key-sequenced data set named
EXAMPL1.KSDS. The command’s parameters are:
CLUSTER
The CLUSTER keyword is required, and specifies that a cluster is to be
defined. The CLUSTER keyword is followed by the parameters specified
for the whole clusters, and, optionally, by the parameters specified
separately for the data and index components.
NAME
NAME is required and specifies the cluster being defined.
VOLUMES
Specifies the volumes that a cluster’s components are allocated space.
You can specify up to 59 volumes per cluster for system-managed
clusters.
DATA
DATA is required when parameters are explicitly specified for the data
component of the cluster.
KILOBYTES
Specifies the amount of space allocated for the data component.
The REPRO command here loads the VSAM key-sequenced data set named
EXAMPL1.KSDS from an existing data set called SOURCE.DATA (that is described
by the INDSET4 DD statement). The command’s parameters are:
INFILE
Identifies the data set containing the source data. The ddname of the DD
statement for this data set must match the name specified on this
parameter.
OUTDATASET
Identifies the name of the data set to be loaded. Access method services
dynamically allocates the data set. The data set is cataloged in the
master catalog.
Chapter 8. Defining and Manipulating VSAM Data Sets: Examples
127
Defining and Manipulating VSAM Data Sets: Examples
Because the cluster component is not password protected, a password is not
required.
If the REPRO operation is successful, the data set’s catalog entry is listed, and the
contents of the data set just loaded are printed.
LISTCAT
Lists catalog entries. The ENTRIES parameter identifies the names of the
entries to be listed.
PRINT
Prints the contents of a data set. The INDATASET parameter is required
and identifies the name of the data set to be printed. Access method
services dynamically allocates the data set. The data set is cataloged in
the master catalog. No password is required because the cluster
component is not password protected.
Examples of Defining Temporary VSAM Data Sets
The following examples uses the ALLOCATE command to define a new temporary
VSAM data set. See “Example 4: Allocate a Temporary VSAM Data Set” on page
265 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 263.
|
|
|
|
|
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) NEW
RECORG(ES) SPACE(1,10) AVGREC(M)
LRECL(256) STORCLAS(TEMP)
/*
The command’s parameters are:
128
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.
z/OS V1R6.0 DFSMS: Using Data Sets
Defining and Manipulating VSAM Data Sets: Examples
STORCLAS
Specifies a storage class for the temporary data set. The STORCLAS
keyword is optional. If you do not specify STORCLAS for the new data
set and your storage administrator has provided an ACS routine, the
ACS routine can select a storage class.
Example 2: Creating a Temporary Data Set with Default
Parameter Values
The following example shows the minimum number of parameters required to
create a temporary non-VSAM sequential data set. If you want to create a
temporary VSAM data set, specify the RECORG parameter.
|
|
|
|
|
|
|
|
|
//ALLOC
//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 section, the access method services DEFINE ALTERNATEINDEX and
DEFINE PATH commands are used to define alternate indexes and a path.
JCL Statements
The IDCUT1 and IDCUT2 DD statements describe the DSNAMES and a volume
containing data space made available to BLDINDEX for defining and using two
sort work data sets in the event an external sort is performed. The data space is
not used by BLDINDEX if enough virtual storage is available to perform an
internal sort.
Chapter 8. Defining and Manipulating VSAM Data Sets: Examples
129
Defining and Manipulating VSAM Data Sets: Examples
Commands
The first DEFINE command defines a VSAM alternate index over the base cluster
EXAMPL1.KSDS.
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.
130
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.
z/OS V1R6.0 DFSMS: Using Data Sets
Defining and Manipulating VSAM Data Sets: Examples
The BLDINDEX command builds an alternate index. Assume that enough virtual
storage is available to perform an internal sort. However, DD statements with the
default ddnames of IDCUT1 and IDCUT2 are provided for two external sort work
data sets if the assumption is incorrect and an external sort must be performed.
INDATASET
The INDATASET parameter identifies the base cluster. Access method
services dynamically allocates the base cluster. The base cluster’s cluster
entry is not password protected even though its data and index
components are.
OUTDATASET
The OUTDATASET parameter identifies the alternate index. Access
method services dynamically allocates the alternate index. The 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.
Chapter 8. Defining and Manipulating VSAM Data Sets: Examples
131
132
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 9. Processing VSAM Data Sets
This chapter covers the following topics.
Topic
Location
Creating an Access Method Control Block
134
Creating an Exit List
134
Opening a Data Set
135
Creating a Request Parameter List
136
Manipulating the Contents of Control Blocks
138
Requesting Access to a Data Set
139
Closing Data Sets
149
Operating in SRB or Cross-Memory Mode
150
Using VSAM Macros in Programs
151
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 205.)
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, 2004
133
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 147.
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 217.
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 138 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).
134
z/OS V1R6.0 DFSMS: Using Data Sets
Processing VSAM Data Sets
v End-of-data-set processing. When your program requests a record beyond the
last record in the data set, your end-of-data-set routine (the EODAD user exit) is
given control. The end of the data set is beyond either the highest addressed or
the highest keyed record, if your program is using addressed or keyed access.
v Journalizing transactions. To journalize the transactions against a data set, you
might specify a journal routine (the JRNAD user exit). To process a
key-sequenced data set using addressed access, you need to know if any RBAs
changed during keyed processing. When you are processing by key, VSAM exits
to your routine for noting RBA changes before writing a control interval in
which there is an RBA change. When journalizing transactions for compressed
data sets, the RBAs and data lengths represent compressed data. VSAM does not
exit to the JRNAD routine for RBA change if the data set is extended
addressable.
v User processing. User processing exits (UPAD) are available to assist subsystems
that need to dispatch new units of work. The UPAD wait exit is given control
before VSAM issues any WAIT SVCs. Use the UPAD post exit to make it easier
to use cross-memory processing. See Table 24 on page 254.
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 138.
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
135
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 177.
Control-interval read access requires only the read password or RACF read
authority, that lets you examine control intervals in the data set it protects.
The read password or RACF read authority does not let you add, change, or
delete records.
– Update access requires the update password, which lets you retrieve, update,
insert, or delete records in the data set it protects.
– Read access requires the read password, that lets you examine records in the
data set it protects. The read password does not permit you to add, change,
or delete records.
Note: RACF protection supersedes password protection for a data set. RACF
checking is bypassed for a caller that is in supervisor state or key 0. For
more information on password and RACF protection, see Chapter 5,
“Protecting Data Sets,” on page 53.
Creating a Request Parameter List
After you have connected your program to a data set, you can issue requests for
access. A request parameter list defines a request. This list identifies the data set to
which the request is directed by naming the ACB macro that defines the data set.
Each request macro (GET, PUT, ERASE, POINT, CHECK, and ENDREQ) gives the
address of the request parameter list that defines the request.
You can use the RPL macro to generate a request parameter list (RPL) when your
program is assembled, or the GENCB macro to build a request parameter list when
your program is run. For information about the advantages and disadvantages of
using GENCB, see “Manipulating the Contents of Control Blocks” on page 138.
When you define your request, specify only the processing options appropriate for
that particular request. Parameters not required for a request are ignored. For
136
z/OS V1R6.0 DFSMS: Using Data Sets
Processing VSAM Data Sets
example, if you switch from direct to sequential retrieval with a request parameter
list, you do not have to zero out the address of the field containing the search
argument (ARG=address).
The following information defines your request:
v Access by address (RBA), key, or relative record number. Address access can be
sequential or direct. Key or relative record number access can be sequential, skip
sequential, or direct. Access can be forward (next sequential record) or backward
(previous sequential record). Access can be for updating or not updating. A
nonupdate direct request to retrieve a record causes VSAM to position to the
following record for subsequent sequential access. For more information about
VSAM positioning, see “POINT Macro for Positioning” on page 143.
v RPLs (including RPLs defined by a chain), either synchronous, so that VSAM
does not give control back to your program until the request completes, or
asynchronous, so that your program can continue to process or issue other
requests while the request is active. With asynchronous requests, your program
must use the CHECK macro to suspend its processing until the request
completes. For more information about synchronous and asynchronous
processing, see “Making Asynchronous Requests” on page 148.
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 177.
You can chain request parameter lists together to define a series of actions for a
single GET or PUT. For example, each parameter list in the chain could contain a
unique search argument and point to a unique work area. A single GET macro
would retrieve a record for each request parameter list in the chain. All RPLs in a
chain must refer to the same ACB.
A chain of request parameter lists is processed serially as a single request.
(Chaining request parameter lists is not the same as processing concurrent requests
in parallel. Processing in parallel requires that VSAM keep track of many positions
in a data set.)
Each request parameter list in a chain should have the same OPTCD
subparameters. Having different subparameters can cause logical errors. You
cannot chain request parameter lists for updating or deleting records—only for
retrieving records or storing new records. You cannot process records in the I/O
buffer with chained request parameter lists. (RPL OPTCD=UPD and RPL
OPTCD=LOC are nonvalid for a chained request parameter list.)
With chained request parameter lists, a POINT, a sequential or skip-sequential
GET, or a direct GET with positioning requested (RPL OPTCD=NSP) causes VSAM
to position itself at the record following the record identified by the last request
parameter list in the chain.
Chapter 9. Processing VSAM Data Sets
137
Processing VSAM Data Sets
When you are using chained RPLs, if an error occurs anywhere in the chain, the
RPLs following the one in error are made available without being processed and
are posted complete with a feedback code of zero.
Manipulating the Contents of Control Blocks
VSAM provides a set of macros, GENCB, TESTCB, MODCB, and SHOWCB, to let
you manipulate the contents of control blocks at execution time. Use these macros
to generate, test, modify, and display the contents of fields in the access method
control block, the exit list, and the request parameter list. You do not have to know
the format of the control block when you use these macros.
The GENCB, MODCB, TESTCB, and SHOWCB macros build a parameter list that
describes, in codes, the actions indicated by the parameters you specify. The
parameter list is passed to VSAM to take the indicated actions. An error can occur
if you specify the parameters incorrectly.
If you issue a MODCB, SHOWCB, or TESTCB for a non-VSAM ACB, unpredictable
results occur.
Generating a Control Block
The GENCB macro can be used to generate an access method control block, an exit
list, or a request parameter list when your program is run. Generating the control
block at execution time with GENCB has the advantage of requiring no reassembly
of the program when you adopt a new version of VSAM in which control block
formats might have changed. If you use the ACB, EXLST, and RPL macros to build
control blocks, and adopt a subsequent release of VSAM in which the control block
format has changed, you have to reassemble your program. GENCB also gives you
the ability to generate multiple copies of the ACB, EXLST, or RPL to be used for
concurrent requests. The disadvantage of using GENCB is that the path length is
longer. It takes more instructions to build a control block using GENCB than to
code the control block directly.
You can use the WAREA parameter to provide an area of storage in which to
generate the control block. This work area has a 64K (X'FFFF') size limit. If you do
not provide storage when you generate control blocks, the ACB, RPL, and EXLST
reside below 16 MB unless LOC=ANY is specified.
Testing the Contents of ACB, EXLST, and RPL Fields
With the TESTCB macro, VSAM compares the contents of a field you specify with
a value that you specify. To show the result of this comparison, VSAM sets the
condition code in the PSW (program status word). Only one keyword can be
specified each time TESTCB is issued. Use TESTCB to find out:
v If an action has been done by VSAM or your program (for example, opening a
data set or activating an exit).
v What kind of a data set is being processed to alter your program logic as a
result of the test.
After issuing a TESTCB macro, examine the PSW condition code. If the TESTCB is
not successful, register 15 contains an error code and VSAM passes control to an
error routine, if one has been specified. For a keyword specified as an option or a
name, you test for an equal or unequal comparison; for a keyword specified as an
address or a number, you test for an equal, unequal, high, low, not-high, or
not-low condition.
138
z/OS V1R6.0 DFSMS: Using Data Sets
Processing VSAM Data Sets
VSAM compares A to B, where A is the contents of the field and B is the value to
compare. A low condition means, for example, A is lower than B — that is, the
value in the control block is lower than the value you specified. If you specify a
list of option codes for a keyword (for example, MACRF=(ADR,DIR)), each of
them must equal the corresponding value in the control block for you to get an
equal condition.
Some of the fields can be tested at any time; others, only after a data set is opened.
The ones that can be tested only after a data set is opened can, for a key-sequenced
data set, pertain either to the data or to the index, as specified in the OBJECT
parameter.
You can display fields using the SHOWCB macro at the same time you test the
fields.
Modifying the Contents of an ACB, EXLST, or RPL
The MODCB macro lets you customize the control blocks generated with the
GENCB macro. The MODCB macro can be used to modify the contents of an
access method control block, an exit list, or a request parameter list. Typical
reasons to modify a request parameter list are to change the length of a record
(RECLEN) when you are processing a data set whose records are not all the same
length, and to change the type of request (OPTCD), such as from direct to
sequential access or from full-key search argument to generic key search argument.
Displaying the Contents of ACB, EXLST, and RPL Fields
The SHOWCB macro causes VSAM to move the contents of various fields in an
access method control block, an exit list, or a request parameter list into your work
area. You might want to learn the reason for an error or to collect statistics about a
data set to permit your program to print a message or keep records of transactions.
Requesting Access to a Data Set
After your program is opened and a request parameter list is built, use the action
request macros GET, PUT, ERASE, POINT, CHECK, and ENDREQ. Each request
macro uses a request parameter list that defines the action to be taken. For
example, when a GET macro points to a request parameter list that specifies
synchronous, sequential retrieval, the next record in sequence is retrieved. When an
ENDREQ macro points to a request parameter list, any current request (for
example, a PUT) for that request parameter list finishes, and the resources held by
the request parameter list are released.
The action request macros lets you do the following tasks:
v Insert new records
v Retrieve existing records
v Point to existing records
v Update existing records
v Delete existing records
v Write buffers
v Retain buffers
v Perform multistring processing
v Perform concurrent requests
v Access records using a path
v Check for completion of asynchronous requests
v End request processing
Chapter 9. Processing VSAM Data Sets
139
Processing VSAM Data Sets
Inserting and Adding Records
Record insertions in VSAM data sets occur in several ways:
v PUT RPL OPTCD=DIR,NSP—Inserting records directly. VSAM remembers its
position for subsequent sequential access.
v PUT RPL OPTCD=DIR,NUP—Inserting a record directly. VSAM does not
remember its position.
v PUT RPL OPTCD=SEQ,NUP or NSP—Inserting records sequentially. VSAM
remembers its position for subsequent sequential access.
v PUT RPL OPTCD=SKP,NUP or NSP—Inserting records in skip sequential order.
VSAM remembers its position for subsequent sequential access.
Insertions into an Entry-Sequenced Data Set
VSAM does not insert new records into an entry-sequenced data set. All records
are added at the end of the data set.
Insertions into a Key-Sequenced Data Set
Insertions into a key-sequenced data set use the free space provided during the
definition of the data set or the free space that develops because of control interval
and control area splits. To create a data set or make mass insertions, use RPL
OPTCD=SEQ,NUP or NSP. RPL OPTCD=SEQ,NUP or NSP inserts the records
sequentially and maintains free space during load mode and during mass
insertions. All the other types use the direct insert strategy. If MACRF=SIS is
specified in the ACB, all inserts use sequential insert strategy.
With addressed access of a key-sequenced data set, VSAM does not insert or add
new records.
Sequential Insertion. If the new record belongs after the last record of the control
interval and the record contains free space, the new record is inserted into the
existing control interval. If the control interval does not contain sufficient free
space, the new record is inserted into a new control interval without a true split.
If the new record does not belong at the end of the control interval and there is
free space in the control interval, it is placed in sequence into the existing control
interval. If adequate free space does not exist in the control interval, a control
interval split occurs at the point of insertion. The new record is inserted into the
original control interval and the following records are inserted into a new control
interval.
Mass Sequential Insertion. When VSAM detects two or more records to be
inserted in sequence into a collating position (between two records) in a data set,
VSAM uses a technique called mass sequential insertion to buffer the records being
inserted, and to reduce I/O operations. Using sequential instead of direct access
takes advantage of this technique. Also extend your data set (resume loading) by
using sequential insertion to add records beyond the highest key or relative record
number. There are possible restrictions to extending a data set into a new control
area depending on the specified share options. See Chapter 12, “Sharing VSAM
Data Sets,” on page 189.
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).
140
z/OS V1R6.0 DFSMS: Using Data Sets
Processing VSAM Data Sets
When several groups of records in sequence are to be mass inserted, each group
can be preceded by a POINT with RPL OPTCD=KGE to establish positioning. KGE
specifies that the key you provide for a search argument must be equal to the key
or relative record number of a record.
Direct Insertion—CI Split. If the control interval has enough available space, the
record is inserted. If the control interval does not have enough space to hold the
record, the entire CI is split, unless the record is the last key in the file. The last
record is always placed in a new, empty CI and does not show up as a CI split.
Direct Insertion—CA Split. If no additional CI is available to allow a CI split, the
CA is split. For the last record in the file, however, the new record is inserted as
the first record in a new, empty CA. This does not show up as a CA split. If the
new record belongs after the last record of the control interval and there is still
space, the new record is added to the end of the existing control interval. If the
control interval does not contain sufficient free space, the new record is inserted
into an unused control interval.
Insertions into a Fixed-Length Relative-Record Data Set
You can insert records into a fixed-length RRDS either sequentially or directly.
Sequential Insertion. Insertions into a fixed-length RRDS go into empty slots.
When a record is inserted sequentially into a fixed-length RRDS it is assigned the
next relative record number in sequence. If the slot is not empty, VSAM sets an
error return code, indicating a duplicate record. The assigned number is returned
in the argument field of the RPL.
Direct Insertion. Direct or skip-sequential insertion of a record into a fixed-length
RRDS places the record as specified by the relative record number in the argument
field of the RPL. You must insert the record into a slot that does not contain a
record. If the slot specified does contain a record, VSAM sets an error return code
in the RPL and rejects the request.
If the insertion is to the end of the control interval, the record is placed in a new
control interval.
Insertions into a Variable-Length Relative-Record Data Set
A variable-length RRDS is processed in the same way as a fixed-length RRDS, with
the following exceptions:
v You must specify the record length in the RECLEN field of the RPL macro.
v Insertions into a variable-length RRDS use the free space provided during the
definition of the data set or the free space that develops because of control
interval and control area splits.
Chapter 9. Processing VSAM Data Sets
141
Processing VSAM Data Sets
As for a fixed-length RRDS, you can insert records into a variable-length RRDS
either sequentially or directly.
Sequential Insertion. When a record is inserted sequentially into a variable-length
RRDS, it is assigned the next available relative record number in sequence. The
assigned number is returned in the argument field of the RPL. Use mass sequential
insertion with a variable-length RRDS.
Direct Insertion. Direct or skip-sequential insertion of a record into a
variable-length RRDS places the record as specified by the relative record number
in the argument field of the RPL. If you specify a duplicate relative record number,
VSAM sets an error return code in the RPL and rejects the request.
Insertions into a Linear Data Set
Linear data sets cannot be processed at the record level. Use of the GET, PUT and
POINT macros is not permitted at the record level. You must use the DIV macro to
process a linear data set. See z/OS MVS Programming: Assembler Services Guide for
information about using DIV.
Retrieving Records
The GET macro is used to retrieve records. To retrieve records for update, use the
GET macro with the PUT macro. When you retrieve records either sequentially or
directly, VSAM returns the length of the retrieved record to the RECLEN field of
the RPL.
Sequential Retrieval
Records can be retrieved sequentially using keyed access or addressed access.
Keyed Sequential Retrieval. The first time your program accesses a data set for
keyed sequential access (RPL OPTCD=(KEY,SEQ)), VSAM is positioned at the first
record in the data set in key sequence if and only if the following is true:
1. Nonshared resources are being used.
2. There have not been any previous requests against the file.
If VSAM picks a string that has been used previously this implicit positioning does
not occur. Therefore, with concurrent or multiple RPL’s, it is best to initiate your
own POINTs and positioning to prevent logic errors.
With shared resources, you must always use a POINT macro to establish position.
A GET macro can then retrieve the record. Certain direct requests can also hold
position. See Table 11 on page 145 for details on when positioning is retained or
released. VSAM checks positioning when processing modes are changed between
requests.
For keyed sequential retrieval of a fixed-length or variable-length RRDS, the
relative record number is treated as a full key. If a deleted record is found during
sequential retrieval, it is skipped and the next record is retrieved. The relative
record number of the retrieved record is returned in the argument field of the RPL.
142
z/OS V1R6.0 DFSMS: Using Data Sets
Processing VSAM Data Sets
Addressed Sequential Retrieval. Retrieval by address is identical to retrieval by
key, except the search argument is a RBA, which must be matched to the RBA of a
record in the data set. When a processing program opens a data set with
nonshared resources for addressed access, VSAM is positioned at the record with
RBA of zero to begin addressed sequential processing. A sequential GET request
causes VSAM to retrieve the data record at which it is positioned, and positions
VSAM at the next record. The address specified for a GET or a POINT must
correspond to the beginning of a data record; otherwise the request is not valid.
Spanned records stored in a key-sequenced data set cannot be retrieved using
addressed retrieval.
You cannot predict the RBAs of compressed records.
GET-previous (backward-sequential) processing is a variation of normal keyed or
addressed-sequential processing. Instead of retrieving the next record in ascending
sequence (relative to current positioning in the data set), GET-previous processing
retrieves the next record in descending sequence. To process records in descending
sequence, specify BWD in the RPL OPTCD parameter. Select GET-previous
processing for POINT, GET, PUT (update only), and ERASE operations. The initial
positioning by POINT, other than POINT LRD, requires that you specify a key. The
following GET-previous processing does not need any specified key to retrieve the
next record in descending sequence.
GET-previous processing is not permitted with control interval or skip-sequential
processing.
POINT Macro for Positioning
You can use the POINT macro to begin retrieving records sequentially at a place
other than the beginning of the data set. The POINT macro places VSAM at the
record with the specified key or relative byte address. However, it does not
provide data access to the record. If you specify a generic key (a leading portion of
the key field), the record pointed to is the first of the records having the same
generic key. The POINT macro can position VSAM for either forward or backward
processing, if FWD or BWD was specified in the RPL OPTCD parameter.
If, after positioning, you issue a direct request through the same request parameter
list, VSAM drops positioning unless NSP or UPD was specified in the RPL OPTCD
parameter.
When a POINT is followed by a VSAM GET/PUT request, both the POINT and
the subsequent request must be in the same processing mode. For example, a
POINT with RPL OPTCD=(KEY,SEQ,FWD) must be followed by GET/PUT with
RPL OPTCD=(KEY,SEQ,FWD); otherwise, the GET/PUT request is rejected.
For skip-sequential retrieval, you must indicate the key of the next record to be
retrieved. VSAM skips to the next record’s index entry by using horizontal pointers
in the sequence set to find the appropriate sequence-set index record and scan its
entries. The key of the next record to be retrieved must always be higher in
sequence than the key of the preceding record retrieved.
If your request fails, with an error code, positioning cannot be maintained. To
determine if positioning is maintained when a logical error occurs, see z/OS
DFSMS Macro Instructions for Data Sets. Positioning is always released when you
specify the ENDREQ macro.
Chapter 9. Processing VSAM Data Sets
143
Processing VSAM Data Sets
Direct Retrieval
Records can also be retrieved directly using keyed access or addressed access.
Keyed Direct Retrieval. For a key-sequenced data set does not depend on prior
positioning. VSAM searches the index from the highest level down to the sequence
set to retrieve a record. Specify the record to be retrieved by supplying one of the
following:
v The exact key of the record
v An approximate key, less than or equal to the key field of the record
v A generic key
You can use an approximate specification when you do not know the exact key. If
a record actually has the key specified, VSAM retrieves it. Otherwise, it retrieves
the record with the next higher key. Generic key specification for direct processing
causes VSAM to retrieve the first record having that generic key. If you want to
retrieve all the records with the generic key, specify RPL OPTCD=NSP in your
direct request. That causes VSAM to position itself at the next record in key
sequence. Then retrieve the remaining records sequentially.
To use direct or skip-sequential access to process a fixed-length or variable-length
RRDS, you must supply the relative record number of the record you want in the
argument field of the RPL macro. For a variable-length RRDS, you also must
supply the record length in the RECLEN field of the RPL macro. If you request a
deleted record, the request causes a no-record-found logical error.
A fixed-length RRDS has no index. VSAM takes the number of the record to be
retrieved and calculates the control interval that contains it and its position within
the control interval.
Addressed Direct Retrieval. Requires the RBA of each individual record is
specified; previous positioning is not applicable.
With direct processing, optionally specify RPL OPTCD=NSP to indicate the
position is maintained following the GET. Your program can then process the
following records sequentially in either a forward or backward direction.
Updating Records
The GET and PUT macros are used to update records. A GET for update retrieves
the record and the following PUT for update stores the record the GET retrieved.
When you update a record in a key-sequenced data set, you cannot alter the
primary-key field.
Changing Record Length
You can update the contents of a record with addressed access, but you cannot
alter the record’s length. To change the length of a record in an entry-sequenced
data set, you must store it either at the end of the data set (as a new record) or in
the place of an inactive record of the same length. You are responsible for marking
the old version of the record as inactive.
Processing the Data Component of a Key-Sequenced Data Set
You can process the data component separately from the index component.
Processing the data component separately lets you print or dump the data
component and the index component of a key-sequenced data set individually.
144
z/OS V1R6.0 DFSMS: Using Data Sets
Processing VSAM Data Sets
However, do not process only the data component if you plan to update the data set.
Always open the cluster when updating a key-sequenced data set.
Deleting Records
After a GET for update retrieves a record, an ERASE macro can delete the record.
The ERASE macro can be used only with a key-sequenced data set or a
fixed-length or variable-length RRDS. When you delete a record in a
key-sequenced data set or variable-length RRDS, the record is physically erased.
The space the record occupied is then available as free space.
You can erase a record from the base cluster of a path only if the base cluster is a
key-sequenced data set. If the alternate index is in the upgrade set in which
UPGRADE was specified when the alternate index was defined, it is modified
automatically when you erase a record. If the alternate key of the erased record is
unique, the alternate index data record with that alternate key is also deleted.
When you erase a record from a fixed-length RRDS, the record is set to binary
zeros and the control information for the record is updated to indicate an empty
slot. Reuse the slot by inserting another record of the same length into it.
With an entry-sequenced data set, you are responsible for marking a record you
consider to be deleted. As far as VSAM is concerned, the record is not deleted.
Reuse the space occupied by a record marked as deleted by retrieving the record
for update and storing in its place a new record of the same length.
Deferring and Forcing Buffer Writing
For integrity reasons, it is sometimes desirable to force the data buffer to be
written after a PUT operation. At other times, it is desirable to defer the writing of
a buffer when possible to improve performance. At the time the PUT is issued, if
the RPL OPTCD specifies direct processing (DIR), and NSP is not specified, forced
writing of the buffer occurs. Otherwise, writing is deferred. An ERASE request
follows the same buffer writing rules as the PUT request. If LSR and GSR deferred
writes are not specified, an ENDREQ macro always forces the current modified
data buffer to be written.
Retaining and Positioning Data Buffers
Some operations retain positioning while others release it. In a similar way, some
operations hold onto a buffer and others release it with its contents. Table 11 shows
which RPL options result in the retention of data buffers and positioning, and
which options result in the release of data buffers and positioning.
Table 11. Effect of RPL Options on Data Buffers and Positioning
RPL Options
Retained
SEQ
*
SKP
*
DIR NSP
*
DIR (no NSP)
Released
*
DIR LOC
*
UPD (with Get)
*
Note:
Chapter 9. Processing VSAM Data Sets
145
Processing VSAM Data Sets
1. A sequential GET request for new control intervals releases the previous buffer.
2. The ENDREQ macro and the ERASE macro with RPL OPTCD=DIR release data
buffers and positioning.
3. Certain options that retain positioning and buffers on normal completion
cannot do so if the request fails with an error code. See z/OS DFSMS Macro
Instructions for Data Sets to determine if positioning is maintained if a logical
error occurs.
The following operation uses but immediately releases a buffer and does not retain
positioning:
GET
RPL OPTCD=(DIR,NUP,MVE)
Processing Multiple Strings
In multiple string processing, there can be multiple independent RPLs within an
address space for the same data set. The data set can have multiple tasks that
share a common control block structure. There are several ACB and RPL
arrangements to indicate that multiple string processing occurs:
v In the first ACB opened, STRNO or BSTRNO is greater than 1.
v Multiple ACBs are opened for the same data set within the same address space
and are connected to the same control block structure.
v Multiple concurrent RPLs are active against the same ACB using asynchronous
requests.
v Multiple RPLs are active against the same ACB using synchronous processing
with each requiring positioning to be held.
If you are doing multiple string update processing, you must consider VSAM
lookaside processing and the rules surrounding exclusive use. Lookaside means
VSAM checks its buffers to see if the control interval is already present when
requesting an index or data control interval.
For GET nonupdate requests, an attempt is made to locate a buffer already in
storage. As a result, a down-level copy of the data can be obtained either from
buffers attached to this string or from secondary storage.
For GET to update requests, the buffer is obtained in exclusive control, and read
from the device for the latest copy of the data. If the buffer is already in exclusive
control of another string, the request fails with an exclusive control feedback code.
If you are using shared resources, the request can be queued, or can return an
exclusive control error.
The exclusive use rules follow:
1. If a given string obtains a record with a GET for update request, the control
interval is not available for update or insert processing by another string.
2. If a given string is in the process of a control area split caused by an update
with length change or an insert, that string obtains exclusive control of the
entire control area being split. Other strings cannot process insert or update
requests against this control area until the split is complete.
If you are using nonshared resources, VSAM does not queue requests that have
exclusive control conflicts, and you are required to clear the conflict. If a conflict is
found, VSAM returns a logical error return code, and you must stop activity and
clear the conflict. If the RPL that caused the conflict had exclusive control of a
146
z/OS V1R6.0 DFSMS: Using Data Sets
Processing VSAM Data Sets
control interval from a previous request, you issue an ENDREQ before you attempt
to clear the problem. Clear the conflict in one of three ways:
v Queue until the RPL holding exclusive control of the control interval releases
that control, then reissue the request.
v Issue an ENDREQ against the RPL holding exclusive control to force it to release
control immediately.
v Use shared resources and issue MRKBFR MARK=RLS.
Note: If the RPL includes a correctly specified MSGAREA and MSGLEN, the
address of the RPL holding exclusive control is provided in the first word of the
MSGAREA. The RPL field, RPLDDDD, contains the RBA of the requested control
interval.
Making Concurrent Requests
With VSAM, you can maintain concurrent positioning for many requests to a data
set.
Strings (sometimes called place holders) are like cursors, each represents a position
in the data set and are like holding your finger in a book to keep the place. The
same ACB is used for all requests, and the data set needs to be opened only once.
This means, for example, you could be processing a data set sequentially using one
RPL, and at the same time, using another RPL, directly access selected records
from the same data set.
Keep in mind, though, that strings are not “owned” by the RPL any longer than
the request holds its position. Once a request gives up its position (for example,
with an ENDREQ), that string is free to be used by another request and must be
repositioned in the data set by the user.
For each request, a string defines the set of control blocks for the exclusive use of
one request. For example, if you use three RPLs, you should specify three strings.
If the number of strings you specify is not sufficient, and you are using NSR, the
operating system dynamically extends the number of strings as needed by the
concurrent requests for the ACB. Strings allocated by dynamic string addition are
not necessarily in contiguous storage.
Dynamic string addition does not occur with LSR and GSR. Instead, you get a
logic error if you have more requests than available strings.
The maximum number of strings that can be defined or added by the system is
255. Therefore, the maximum number of concurrent requests holding position in
one data set at any one time is 255.
Using a Path to Access Records
When you are processing records sequentially using a path, records from the base
cluster are returned according to ascending or, if you are retrieving the previous
record, descending alternate key values. If there are several records with a
nonunique alternate key, those records are returned in the order they were entered
into the alternate index. READNEXT and READPREV returns these nonunique
alternate index records in the same sequence. VSAM sets a return code in the RPL
when there is at least one more record with the same alternate key to be processed.
For example, if there are three data records with the alternate key 1234, the return
code would be set during the retrieval of records one and two and would be reset
during retrieval of the third record.
Chapter 9. Processing VSAM Data Sets
147
Processing VSAM Data Sets
When you use direct or skip-sequential access to process a path, a record from the
base data set is returned according to the alternate key you specified in the
argument field of the RPL macro. If the alternate key is not unique, the record first
entered with that alternate key is returned and a feedback code (duplicate key) is
set in the RPL. To retrieve the remaining records with the same alternate key,
specify RPL OPTCD=NSP when retrieving the first record with a direct request,
and switch to sequential processing.
You can insert and update data records in the base cluster using a path if:
v The PUT request does not result in nonunique alternate keys in an alternate
index (defined with the UNIQUEKEY attribute). However, if a nonunique
alternate key is generated and the NONUNIQUEKEY attribute is specified,
updating can occur.
v You do not change the key of reference between the time the record was
retrieved for update and the PUT is issued.
v You do not change the primary key.
When the alternate index is in the upgrade set, the alternate index is modified
automatically by inserting or updating a data record in the base cluster. If the
updating of the alternate index results in an alternate index record with no
pointers to the base cluster, the alternate-index record is erased.
Rule: When you use SHAREOPTIONS 2, 3, and 4, you must continue to ensure
read/write integrity when issuing concurrent requests (such as GETs and PUTs) on
the base cluster and its associated alternate indexes. Failure to ensure read/write
integrity might temporarily cause “No Record Found” or “No Associated Base
Record” errors for a GET request. Bypass such errors by reissuing the GET request,
but it is best to prevent the errors by ensuring read/write integrity.
Making Asynchronous Requests
In synchronous mode, VSAM does not return to your program from a PUT or GET
operation until it has completed the operation. In asynchronous mode, VSAM
returns control to your program before completing a PUT or a GET. A program in
asynchronous mode can perform other useful work while a VSAM PUT or GET is
completed.
Asynchronous mode can improve throughput with direct processing because it
permits processing to overlap with accesses from and to the direct access device.
When reading records directly, each read often involves a seek on the direct access
device, a slow operation. In synchronous mode, this seek time does not overlap
with other processing.
Specifying Asynchronous Mode
To specify asynchronous mode, you must specify OPTCD=ASY rather than
OPTCD=SYN in the RPL.
Checking for Completion of Asynchronous Requests
Suppose your program is ready to process the next record, but VSAM is still trying
to obtain that record. (The next record is not yet read in from the direct access
device.) You might need to stop execution of the program and wait for VSAM to
complete reading in the record. The CHECK macro stops executing the program
until the operation in progress is complete. You must issue a CHECK macro after
each request for an RPL. If you attempt another request without an intervening
CHECK, that request is rejected.
148
z/OS V1R6.0 DFSMS: Using Data Sets
Processing VSAM Data Sets
Once the request is completed, CHECK releases control to the next instruction in
your program, and frees up the RPL for use by another 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 Release (only for extended format key-sequenced data sets) all space after the
high-used RBA (on a CA boundary) up to the high-allocated RBA if partial
release was specified at open time.
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 50.
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).
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.
Chapter 9. Processing VSAM Data Sets
149
Processing VSAM Data Sets
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.
VSAM operates only in cross-memory or SRB mode for synchronous, supervisor
state requests with shared resources or improved control interval (ICI) access. For
data sets not processed with ICI, an attempt to invoke VSAM asynchronously, in
problem state, or with nonshared resources in either cross-memory or SRB mode
results in a logical error. This error is not generated for ICI.
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
processing is done by suspend and resume. There is no resource wait/post
processing for ICI. See “Improved Control Interval Access” on page 185 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
150
z/OS V1R6.0 DFSMS: Using Data Sets
Processing VSAM Data Sets
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 235 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 20 shows the relationship between JCL and the VSAM macros in a
program.
Chapter 9. Processing VSAM Data Sets
151
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 20. VSAM Macro Relationships
Figure 21 on page 153 is a skeleton program that shows the relationship of VSAM
macros to each other and to the rest of the program.
152
z/OS V1R6.0 DFSMS: Using Data Sets
Processing VSAM Data Sets
START
CSECT
SAVE(14,12)
.
B
INIT
Standard entry code
Branch around file specs
MASACB
ACB
DDNAME=MASDS,AM=VSAM,
MACRF=(KEY,SEQ,OUT),
EXLST=EXITS,
RMODE31=ALL
MASRPL
RPL
ACB=MASACB,
OPTCD=(KEY,SEQ,NUP,MVE,SYN),
AREA=WA,
AREALEN=80,
RECLEN=80
X
X
X
X
EXITS
EXLST
LERAD=LOGER,
JRNAD=JOURN
X
TRANDCB
DCB
DDNAME=TRANDS,
DSORG=PS,
MACRF=GM,
EODAD=EOTRF,
LRECL=80,
BLKSIZE=80,
RECFM=F
X
X
X
X
X
X
INIT
.
.
OPEN
(MASACB,,TRANDCB)
.
GET
TRANDCB,WA
.
PUT
RPL=MASRPL
.
CLOSE (MASACB,,TRANDCB)
.
RETURN (14,12)
Exit routines
.
.
.
DS
CL80
END
EOTRF
LOGER
JOURN
WA
File specs
X
X
X
Program initialization
Connect data sets
Processing loop
Disconnect data sets
Return to calling routine
Work area
Figure 21. Skeleton VSAM Program
Chapter 9. Processing VSAM Data Sets
153
Processing VSAM Data Sets
154
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 10. Optimizing VSAM Performance
This chapter covers the following topics, describing many of the options and
factors that influence or determine the performance of both VSAM and the
operating system.
Topic
Location
Optimizing Control Interval Size
155
Optimizing Control Area Size
159
Optimizing Free Space Distribution
160
Using Index Options
175
Obtaining Diagnostic Information
176
Migrating from the Mass Storage System
176
Using Hiperbatch
176
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 74 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
164.
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 160.
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, 2004
155
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 for Catalogs.
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 76.
Physical Block Size and Track Capacity
Figure 22 shows the relationship between control interval size, physical block size,
and track capacity that is not in extended format.
156
z/OS V1R6.0 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
CI5
PB
PB
CI6
PB
PB
Track 4
PB - Physical block
Figure 22. 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
157
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,
158
z/OS V1R6.0 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 164.
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 following examples are based
on the assumption that the index CI size is large enough to handle all the data CIs
in the CA and 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, its size will be an integral multiple of
tracks, and it 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. For
more information about allocating space for a data set, see “Allocating Space for
VSAM Data Sets” on page 106.
Chapter 10. Optimizing VSAM Performance
159
Optimizing VSAM Performance
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 ties up 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:
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.
160
z/OS V1R6.0 DFSMS: Using Data Sets
Optimizing VSAM Performance
Use LISTCAT or the ACB JRNAD exit to monitor control area splits. See “JRNAD
Exit Routine to Journalize Transactions” on page 241.
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.
Figure 23 shows how free space is determined for a control interval.
Chapter 10. Optimizing VSAM Performance
161
Optimizing VSAM Performance
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 23. 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.
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
162
z/OS V1R6.0 DFSMS: Using Data Sets
Optimizing VSAM Performance
(0 0) after the data set is loaded. For more information about mass insertion see
“Inserting and Adding Records” on page 140.
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.
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.
Chapter 10. Optimizing VSAM Performance
163
Optimizing VSAM Performance
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.
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:
SYSTEM
USER
SO
SW
DO
DW
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.
System-managed buffering with sequential optimization.
System-managed buffering weighted for sequential processing.
System-managed buffering with direct optimization.
System-managed buffering weighted for direct optimization.
v Data class Record Access Bias = SYSTEM or USER
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 257.
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 ACCBIAS=SYSTEM, the default
value, RMODE31=BUFF, is in effect. If you attempt to reference the VSAM buffers
directly (as in LOCATE mode), your program must run in 31-bit addressing mode.
164
z/OS V1R6.0 DFSMS: Using Data Sets
Optimizing VSAM Performance
If your program runs in 24-bit addressing mode and you need to access VSAM
buffers directly, code RMODE31=CB or RMODE31=NONE in the JCL AMP
parameter.
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
For application programs that require 24-bit addresses, the system copies above 16
MB UCBs to below 16 MB private, virtual storage. This copy is known as a
captured UCB. The system automatically captures an above 16 MB UCB at
allocation and releases the UCB at deallocation. With dynamic allocation, you can
choose not to capture a UCB if affected applications can handle above 16 MB
UCBs. The major user of uncaptured UCBs is DB2.
Use the following dynamic allocation options when allocating a 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)—Specify this option to use 4-byte actual
UCB addresses. This option does not require your program to be authorized.
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 use this
option with S99TIOEX.
Related reading: For more information, see z/OS MVS Programming: Authorized
Assembler Services Guide.
Tuning for System-Managed Buffering
VSAM can use a technique called system-managed buffering (SMB) to determine
the number of buffers and the type of buffer management to use for VSAM data
sets. VSAM also determines the number of buffers to locate in Hiperspace™ for use
in direct optimization.
To indicate that VSAM is to use SMB, specify either of the following options:
v Specify the ACCBIAS subparameter of the JCL DD statement AMP parameter
and an appropriate value for record access bias.
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.
Chapter 10. Optimizing VSAM Performance
165
Optimizing VSAM Performance
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 section 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 opening the data set. You can specify virtual buffer size in
kilobytes, from 1K to 2048000K, or in megabytes, from 1M to 2048M. This value
is the total amount of virtual storage that you can address in a single address
space. This value does not specify storage that the system or the access method
requires.
v SMBDFR. This option lets you defer writing buffers to the medium either until
the buffer is required for a different request or until 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, which you specify when you define
the data set. The default for SHAREOPTIONS (1,3) and (2,3) is deferred write.
The default for SHAREOPTIONS (3,3), (4,3), and (x, 4) is nondeferred write. If
the user specifies a value for SMBDFR, this value always takes precedence over
any defaults.
v SMBHWT. This option permits the specification of a whole decimal value from
1-99 for allocating Hiperspace buffers. The allocation is based on a multiple of
the number of virtual buffers that have been allocated.
166
z/OS V1R6.0 DFSMS: Using Data Sets
Optimizing VSAM Performance
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
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.
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
Chapter 10. Optimizing VSAM Performance
167
Optimizing VSAM Performance
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.
A separate pool is built for both data and index components, if applicable, for each
data set. There is no capability to share a single pool by multiple data sets. 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 will be identified. These buffers are
acquired above the 16 MB line unless overridden by the use of the RMODE31
parameter on the AMP=parameter.
The use of the SMBVSP parameter on AMP=parameter can be used to restrict the
size of the pool that is built for the data component. There is no capability to
override 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
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. Data sets that have alternate indexes defined over them are not eligible for DO.
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.
168
z/OS V1R6.0 DFSMS: Using Data Sets
Optimizing VSAM Performance
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.
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
Chapter 10. Optimizing VSAM Performance
169
Optimizing VSAM Performance
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.
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.
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.
170
z/OS V1R6.0 DFSMS: Using Data Sets
Optimizing VSAM Performance
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 24), 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)
Chapter 10. Optimizing VSAM Performance
171
Optimizing VSAM Performance
Figure 24. 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.
172
z/OS V1R6.0 DFSMS: Using Data Sets
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.
Chapter 10. Optimizing VSAM Performance
173
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.
Acquiring Buffers
Data and index buffers are acquired and allocated only when the data set is
opened. VSAM dynamically 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.
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
174
z/OS V1R6.0 DFSMS: Using Data Sets
Optimizing VSAM Performance
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
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
Chapter 10. Optimizing VSAM Performance
175
Optimizing VSAM Performance
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 Reference. 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.
176
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 11. Processing Control Intervals
This chapter covers the following topics.
Topic
Location
Access to a Control Interval
178
Structure of Control Information
179
User Buffering
184
Improved Control Interval Access
185
Control Blocks in Common (CBIC) Option
186
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). 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
185.
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 119.
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, 2004
177
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).
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).
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.
178
z/OS V1R6.0 DFSMS: Using Data Sets
Processing Control Intervals
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 25 shows the relative positions of data, unused space, and control
information in a control interval.
Figure 25. General Format of a Control Interval
For more information about the structure of a control interval, see “Control
Intervals” on page 74.
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.
Chapter 11. Processing Control Intervals
179
Processing Control Intervals
CIDF—Control Interval Definition Field
The CIDF is a 4-byte field that contains two 2-byte binary numbers.
Offset Length
Description
0(0)
2
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(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.
180
z/OS V1R6.0 DFSMS: Using Data Sets
Processing Control Intervals
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.
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.
..xx ....
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.
.... x...
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.
1(1)
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 26 on page 182 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
181
Processing Control Intervals
Figure 26. 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.
182
z/OS V1R6.0 DFSMS: Using Data Sets
Processing Control Intervals
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.
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.
Figure 27 shows contents of the CIDF and RDFs for a spanned record with a length
of 1306 bytes.
Figure 27. Format of Control Information for Spanned Records
Chapter 11. Processing Control Intervals
183
Processing Control Intervals
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.
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) and for PUT
with OPTCD=NUP.
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 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.
184
z/OS V1R6.0 DFSMS: Using Data Sets
Processing Control Intervals
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 150.
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).
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.
Chapter 11. Processing Control Intervals
185
Processing Control Intervals
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
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.
186
z/OS V1R6.0 DFSMS: Using Data Sets
Processing Control Intervals
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.
Chapter 11. Processing Control Intervals
187
Processing Control Intervals
188
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 12. Sharing VSAM Data Sets
This chapter 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 217.
This chapter covers the following topics.
Topic
|
|
|
|
|
Location
Subtask Sharing
190
Cross-Region Sharing
195
Cross-System Sharing
198
Control Block Update Facility (CBUF)
199
Techniques of Data Sharing
201
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 corruption. 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
ensure that your program has exclusive use of the data. You must obtain exclusive
control yourself, using facilities such as ENQ/RESERVE and DEQ.
© Copyright IBM Corp. 1987, 2004
189
Sharing VSAM Data Sets
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 195.
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
190
z/OS V1R6.0 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 28 on page 192 for a diagram of exclusive control conflict
feedback and results of different user requests.
Chapter 12. Sharing VSAM Data Sets
191
Sharing VSAM Data Sets
Figure 28. 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
192
z/OS V1R6.0 DFSMS: Using Data Sets
Sharing VSAM Data Sets
(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.
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 1 and 3 above, 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 29 on page 194, DSN is specified for each ACB, and output processing is
specified.
Chapter 12. Sharing VSAM Data Sets
193
Sharing VSAM Data Sets
CLUSTER.REAL.PATH
CLUSTER.REAL.AIX (UPGRADE)
CLUSTER.REAL
CLUSTER.ALIAS
Figure 29. 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.
194
z/OS V1R6.0 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 28 on page
192 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 ENF-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
195
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
196
z/OS V1R6.0 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.
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.
Chapter 12. Sharing VSAM Data Sets
197
Sharing VSAM Data Sets
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 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.
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:
198
z/OS V1R6.0 DFSMS: Using Data Sets
Sharing VSAM Data Sets
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.
Table 12 on page 200 shows how the SHAREOPTIONS specified in the catalog and
the disposition specified on the DD statement interact to affect the type of
processing.
Chapter 12. Sharing VSAM Data Sets
199
Sharing VSAM Data Sets
Table 12. 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
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.
200
z/OS V1R6.0 DFSMS: Using Data Sets
Sharing VSAM Data Sets
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 section 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.
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
Chapter 12. Sharing VSAM Data Sets
201
Sharing VSAM Data Sets
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(RPLDDDD).
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(RPLDDDD).
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.
202
z/OS V1R6.0 DFSMS: Using Data Sets
Sharing VSAM Data Sets
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.
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 201 for the required procedures for invalidating buffers. To perform
selective buffer invalidation, an internal knowledge of the VSAM control blocks is
required.
Chapter 12. Sharing VSAM Data Sets
203
Sharing VSAM Data Sets
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:
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.
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.
204
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 13. Sharing Resources Among VSAM Data Sets
This chapter covers the following topics.
Topic
Location
Provision of a Resource Pool
205
Management of I/O Buffers for Shared Resources
210
Restrictions and Guidelines for Shared Resources
214
This chapter 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 189.
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, 2004
205
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 expanded storage. The data in a
Hiperspace buffer is preserved unless there is an expanded storage shortage and
the expanded 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.
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.
The separate index resource pools are not supported for GSR.
The Hiperspace buffers (specified in the BLDVRP macro) are not supported for
GSR.
206
z/OS V1R6.0 DFSMS: Using Data Sets
Sharing Resources Among VSAM Data Sets
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
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
Chapter 13. Sharing Resources Among VSAM Data Sets
207
Sharing Resources Among VSAM Data Sets
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.
If the specified number of buffers is not adequate, VSAM will return a logical error
indicating the out-of-buffer condition.
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 138. 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 below 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
BUFRDS
NUIW
STRMAX
UIW
208
z/OS V1R6.0 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 reads to bring data into a buffer.
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 210).
Sharing Resources Among VSAM Data Sets
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
209
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 for Catalogs.) 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.
210
z/OS V1R6.0 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 138.
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 213.
Using WRTBFR can improve performance, if you schedule WRTBFR to overlap
other processing.
Chapter 13. Sharing Resources Among VSAM Data Sets
211
Sharing Resources Among VSAM Data Sets
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
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 146 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 250 and “JRNAD Exit Routine to
Journalize Transactions” on page 241 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 241.
212
z/OS V1R6.0 DFSMS: Using Data Sets
Sharing Resources Among VSAM Data Sets
See “JRNAD Exit Routine to Journalize Transactions” on page 241 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).
Chapter 13. Sharing Resources Among VSAM Data Sets
213
Sharing Resources Among VSAM Data Sets
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
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 DFSMS Checkpoint/Restart for information about
restarting the processing of VSAM data.
214
z/OS V1R6.0 DFSMS: Using Data Sets
Sharing Resources Among VSAM Data Sets
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
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
215
Sharing Resources Among VSAM Data Sets
216
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 14. Using VSAM Record-Level Sharing
This chapter describes how to set up the resources that you need for using VSAM
record-level sharing (RLS) and DFSMS Transactional VSAM (DFSMStvs). This
chapter covers the following topics.
Topic
Location
Controlling Access to VSAM Data Sets
217
Accessing Data Sets Using DFSMStvs and VSAM Record-Level Sharing
217
Specifying Read Integrity
228
Specifying a Timeout Value for Lock Requests
228
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 section describes the use of VSAM data sets for DFSMStvs.
VSAM record-level sharing (RLS) is an access option for VSAM data sets that
allows Customer Information Control System ((CICS) and non-CICS 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.
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.
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
© Copyright IBM Corp. 1987, 2004
217
Using VSAM Record-Level Sharing
ignored and the data set is opened and accessed in non-RLS mode. See “Using
Non-RLS Access to VSAM Data Sets” on page 223 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 30.
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 30. VSAM RLS address and data spaces and requestor address spaces
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. The default
value, ALL, indicates that RLS caches both the data and index parts of the VSAM
data set in the coupling facility. If you specify NONE, then RLS caches only the
index part of the VSAM data set. If you specify UPDATESONLY, then RLS caches
data in the coupling facility only during write operations.
All active systems in a sysplex must have the greater than 4K CF caching feature
before the function is enabled.
218
z/OS V1R6.0 DFSMS: Using Data Sets
Using VSAM Record-Level Sharing
To set up RLS CF caching, use the following values:
v ALL or UPDATESONLY or NONE 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.
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.
v
v
v
v
UPDATESONLY
Indicates that RLS is to place only WRITE requests in the cache
structure.
– 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.
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.
RLS_MaxCfFeatureLevel keyword in the SETSMS command
RLS_MaxCfFeatureLevel keyword in the SET SMSxx command
RLS_MaxCfCacheFeatureLevel in the D SMS,OPTIONS command
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 31 shows the AOR, FOR, and VSAM request flow prior to VSAM RLS.
Chapter 14. Using VSAM Record-Level Sharing
219
Using VSAM Record-Level Sharing
CICS
AOR
CICS
AOR
CICS
AOR
CICS
AOR
VSAM
VSAM
CICS
FOR
VSAM
MVS 1
MVS n
Figure 31. 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 32 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 32. 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.
220
z/OS V1R6.0 DFSMS: Using Data Sets
Using VSAM Record-Level Sharing
Related reading: For more information on using CICS to recover data sets, see
CICS Recovery and Restart Guide. For an overview of CICS, see CICS System
Definition Guide.
Recoverable and Nonrecoverable Data Sets
CICS file control supports recoverable or nonrecoverable 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 logs 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
Chapter 14. Using VSAM Record-Level Sharing
221
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.
Using VSAM RLS Outside of CICS
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 outside of 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.
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.
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
222
z/OS V1R6.0 DFSMS: Using Data Sets
Using VSAM Record-Level Sharing
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
any time, a data set can be open for non-RLS write access or open for RLS access.
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.
Comparing RLS Access and Non-RLS Access
This section 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
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.
Chapter 14. Using VSAM Record-Level Sharing
223
Using VSAM Record-Level Sharing
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. CICS uses 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.
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.
224
z/OS V1R6.0 DFSMS: Using Data Sets
Using VSAM Record-Level Sharing
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 238.
VSAM Options Not Used by RLS
RLS does not support the following options and capabilities:
v Linear data sets
v
v
v
v
v
v
v
v
v
v
v
v
v
Addressed access to a KSDS
Control interval (CNV or ICI) to any VSAM data set type
User buffering (UBF)
Clusters that have been defined with the IMBED option
Key Range data sets
Temporary data sets
GETIX and PUTIX requests
MVS Checkpoint/Restart facility
ACBSDS (system data set) specification
Hiperbatch
Catalogs, VVDS, the JRNAD exit, and any JCL AMP= parameters in JCL
Data that is stored in z/OS UNIX System Services
Striped VSAM data sets
In addition, VSAM RLS has the following restrictions:
v You cannot specify RLS access when accessing a VSAM data set using the ISAM
compatibility interface.
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.
Chapter 14. Using VSAM Record-Level Sharing
225
Using VSAM Record-Level Sharing
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
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
226
z/OS V1R6.0 DFSMS: Using Data Sets
Using VSAM Record-Level Sharing
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.
|
|
|
|
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
Chapter 14. Using VSAM Record-Level Sharing
227
Using VSAM Record-Level Sharing
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.
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.
228
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 15. Checking VSAM Key-Sequenced Data Set
Clusters for Structural Errors
This chapter covers the following topics.
Topic
Location
EXAMINE Command
229
How to Run EXAMINE
230
Samples of Output from EXAMINE Runs
232
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 for Catalogs.
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, 2004
229
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 189.
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.
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
230
z/OS V1R6.0 DFSMS: Using Data Sets
Checking VSAM Key-Sequenced Data Set Clusters for Structural Errors
authorization failure when the check indicated above 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 230).
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
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
Chapter 15. Checking VSAM Key-Sequenced Data Set Clusters for Structural Errors
231
Checking VSAM Key-Sequenced Data Set Clusters for Structural Errors
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 for Catalogs.
Samples of Output from EXAMINE Runs
This section 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.
232
z/OS V1R6.0 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
233
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
234
z/OS V1R6.0 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 section covers general guidelines for coding VSAM user-written exit routines
and specific information about coding the following routines.
Topic
Location
Guidelines for Coding Exit Routines
235
EODAD Exit Routine to Process End of Data
239
EXCEPTIONEXIT Exit Routine
240
JRNAD Exit Routine to Journalize Transactions
241
LERAD Exit Routine to Analyze Logical Errors
247
RLSWAIT Exit Routine
248
SYNAD Exit Routine to Analyze Physical Errors
250
UPAD Exit Routine for User Processing
252
User-Security-Verification Routine
255
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 for Catalogs.
Table 13 on page 236 shows the exit locations available from VSAM.
© Copyright IBM Corp. 1987, 2004
235
Coding VSAM User-Written Exit Routines
Table 13. 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 for Catalogs and be familiar with their contents.
236
z/OS V1R6.0 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
237
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 14 gives the contents of the registers when VSAM exits to the IGW8PNRU
routine.
Table 14. 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.
238
z/OS V1R6.0 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 237.
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 247.
Register Contents
Table 15 gives the contents of the registers when VSAM exits to the EODAD
routine.
Table 15. 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
239
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 237.
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 16 gives the contents of the registers when VSAM exits to the
EXCEPTIONEXIT routine.
Table 16. 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
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.
240
z/OS V1R6.0 DFSMS: Using Data Sets
Coding VSAM User-Written Exit Routines
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 237.
Related reading: For information about how exception exits are established,
changed, or nullified, see z/OS DFSMS Access Method Services for Catalogs.
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 17 gives the contents of the registers when VSAM exits to the JRNAD
routine.
Table 17. 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.
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.
Chapter 16. Coding VSAM User-Written Exit Routines
241
Coding VSAM User-Written Exit Routines
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 18 on page 245.
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
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
242
z/OS V1R6.0 DFSMS: Using Data Sets
Coding VSAM User-Written Exit Routines
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 33 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
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
.
NOCANCEL .
Process the noncancel situation
.
.
CLOSE (DIRACB)
Disconnect KSDS1
DLVRP TYPE=LSR,SHRPOOL=1 Delete the resource pool
.
.
.
RETURN
Return to caller.
.
.
.
DIRACB
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 33. Example of a JRNAD exit (Part 1 of 2)
Chapter 16. Coding VSAM User-Written Exit Routines
243
Coding VSAM User-Written Exit Routines
*
DIRRPL
*
DATAREC
KEYNO
EXITLST
JRNADDR
USEREXIT
EXIT
RPL AM=VSAM,
ACB=DIRACB,
AREA=DATAREC,
AREALEN=128,
ARG=KEYNO,
KEYLEN=4,
OPTCD=(KEY,DIR,FWD,SYN,NUP,WAITX),
RECLEN=128
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
.
.
.
.
.
.
.
.
CLI 20(R1),X’50’
BNE EXIT
MVI 21(R1),X’8C’
.
.
.
.
.
BR R14
END
On entry to this exit routine, R1 points
to the JRNAD parameter list and R14 points
back to VSAM.
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 18 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.
244
z/OS V1R6.0 DFSMS: Using Data Sets
Coding VSAM User-Written Exit Routines
Table 18. 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.
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.
Chapter 16. Coding VSAM User-Written Exit Routines
245
Coding VSAM User-Written Exit Routines
Table 18. 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
16(X'10')
4
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.
Variable, depends on the reason indicator at offset 20:
Offset 20
Contents at offset 16
246
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.
z/OS V1R6.0 DFSMS: Using Data Sets
Coding VSAM User-Written Exit Routines
Table 18. 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'–X'FF'
Reserved.
21(X'15')
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.
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.
Chapter 16. Coding VSAM User-Written Exit Routines
247
Coding VSAM User-Written Exit Routines
Register Contents
Table 19 gives the contents of the registers when VSAM exits to the LERAD exit
routine.
Table 19. 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 237.
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.
248
z/OS V1R6.0 DFSMS: Using Data Sets
Coding VSAM User-Written Exit Routines
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 20 gives the contents of the registers when RLSWAIT is entered in 31–bit
mode.
Table 20. 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,
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.
Chapter 16. Coding VSAM User-Written Exit Routines
249
Coding VSAM User-Written Exit Routines
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 21 gives the contents of the registers when VSAM exits to the SYNAD
routine.
Table 21. 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
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.
250
z/OS V1R6.0 DFSMS: Using Data Sets
Coding VSAM User-Written Exit Routines
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” 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 237.
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.
Example of a SYNAD User-Written Exit Routine
The example in Figure 34 on page 252 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.
Chapter 16. Coding VSAM User-Written Exit Routines
251
Coding VSAM User-Written Exit Routines
ACB1
ACB
EXLST=EXITS
EXITS
RPL1
EXLST
RPL
SYNAD=PHYERR
ACB=ACB1,
MSGAREA=PERRMSG,
MSGLEN=128
PHYERR
*
USING
*,15
.
.
LA
.
.
.
13,SAVE
This routine is nonreentrant.
Register 15 is entry address.
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
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 22 on page 253.
252
z/OS V1R6.0 DFSMS: Using Data Sets
Coding VSAM User-Written Exit Routines
If you are executing in cross-memory mode, you must have a UPAD routine and
RPL must specify WAITX. z/OS DFSMS: Using Data Sets describes cross-memory
mode. The UPAD routine is optional for non-cross-memory mode.
Table 22 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 22. 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 23 shows the register contents passed by VSAM when the UPAD exit routine
is entered.
Table 23. Contents of registers at entry to UPAD exit routine
Register
Contents
0
Unpredictable.
1
Address of a parameter list built by VSAM.
2-12
Unpredictable.
13
Reserved.
14
Return address to VSAM.
15
Entry address of the UPAD routine.
Chapter 16. Coding VSAM User-Written Exit Routines
253
Coding VSAM User-Written Exit Routines
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 24 describes this parameter list.
Table 24. 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
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
254
z/OS V1R6.0 DFSMS: Using Data Sets
Coding VSAM User-Written Exit Routines
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 25 gives the contents of the registers when VSAM gives control to
the USVR.
Chapter 16. Coding VSAM User-Written Exit Routines
255
Coding VSAM User-Written Exit Routines
Table 25. Communication with user-security-verification routine
Register
Contents
0
Unpredictable.
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).
–
256
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:
z/OS V1R6.0 DFSMS: Using Data Sets
0
Authority granted.
not 0
Authority withheld.
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
Location
257
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, 2004
257
Using 31-Bit Addressing Mode with VSAM
v You specify 31-bit parameters by specifying the AMP=(RMODE31=) parameter
in the JCL.
Table 26 summarizes the 31-bit address keyword parameters and their use in the
applicable VSAM macros.
Table 26. 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 164 for information about
creating and accessing buffers that reside above 16 MB.
v See Chapter 13, “Sharing Resources Among VSAM Data Sets,” on page 205 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.
258
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 18. Using Job Control Language for VSAM
This chapter covers the following topics.
Topic
Location
Using JCL Statements and Keywords
259
Creating VSAM Data Sets with JCL
260
Retrieving an Existing VSAM Data Set
266
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 260 and
“Retrieving an Existing VSAM Data Set” on page 266 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 102.
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
189.
© Copyright IBM Corp. 1987, 2004
259
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.
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.
LRECL—Specifies logical record length. Implies a system determined control
interval size.
260
z/OS V1R6.0 DFSMS: Using Data Sets
Using Job Control Language for VSAM
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.
Chapter 18. Using Job Control Language for VSAM
261
Using Job Control Language for VSAM
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.
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 is 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.
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 265 for an example of creating a temporary
VSAM data set.
262
z/OS V1R6.0 DFSMS: Using Data Sets
Using Job Control Language for VSAM
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.
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.
Chapter 18. Using Job Control Language for VSAM
263
Using Job Control Language for VSAM
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.
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.
264
z/OS V1R6.0 DFSMS: Using Data Sets
Using Job Control Language for VSAM
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.
Chapter 18. Using Job Control Language for VSAM
265
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 260.
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.
266
z/OS V1R6.0 DFSMS: Using Data Sets
Using Job Control Language for VSAM
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.
Certain JCL keywords should either not be used, or used only with caution when
processing VSAM data sets. See the VSAM data set section 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.
Chapter 18. Using Job Control Language for VSAM
267
268
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 19. Processing Indexes of Key-Sequenced Data Sets
This chapter covers the following topics.
Topic
Location
Access to a Key-Sequenced Data Set Index
269
Format of an Index Record
273
Key Compression
276
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 177.
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, 2004
269
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 271 shows that a single index control interval contains all the
information necessary to locate a record in a single data control area.
270
z/OS V1R6.0 DFSMS: Using Data Sets
Processing Indexes of Key-Sequenced Data Sets
Index
CI
Free
CI Ptr
list
25
19
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 272 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
271
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
1333
H
D
R
Index set
Sequence set
Control area 1
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.
272
z/OS V1R6.0 DFSMS: Using Data Sets
Processing Indexes of Key-Sequenced Data Sets
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 27 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.
Table 27. 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.
Chapter 19. Processing Indexes of Key-Sequenced Data Sets
273
Processing Indexes of Key-Sequenced Data Sets
Table 27. Format of the Header of an Index Record (continued)
Field
Offset
Length
Description
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.
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.
IXHLV
IXHFSO
12(C)
4
Reserved.
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
Reserved.
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.
274
z/OS V1R6.0 DFSMS: Using Data Sets
Processing Indexes of Key-Sequenced Data Sets
Table 27. Format of the Header of an Index Record (continued)
Field
Offset
Length
Description
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.
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
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.)
Chapter 19. Processing Indexes of Key-Sequenced Data Sets
275
Processing Indexes of Key-Sequenced Data Sets
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
P
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
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.
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.
276
z/OS V1R6.0 DFSMS: Using Data Sets
Processing Indexes of Key-Sequenced Data Sets
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 279 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.
Key 12345 has no front compression because it is the first key in the index record.
Key 12356 has no rear compression because, in the comparison between 12356 and
12357, there are no characters following 6, which is the first character that is
unequal to the corresponding character in the following key.
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 279 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:
Chapter 19. Processing Indexes of Key-Sequenced Data Sets
277
Processing Indexes of Key-Sequenced Data Sets
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.
278
z/OS V1R6.0 DFSMS: Using Data Sets
Processing Indexes of Key-Sequenced Data Sets
Full Key of
Data Record
Index Entry
Eliminated
From Front
F
L
P
3 4
0
4
0
F
3
L
2
P
1
K
12345
1
2
Eliminated
From Rear
None
5
123
none
1235
9
12
none
124
21
1
56
12350
12353
12354
12356
K
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 280 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 271.
Chapter 19. Processing Indexes of Key-Sequenced Data Sets
279
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.
280
z/OS V1R6.0 DFSMS: Using Data Sets
Part 3. Non-VSAM Data Sets and UNIX Files
Chapter 20. Selecting Record Formats for
Non-VSAM Data Sets . . . . . . . . . .
Format Selection . . . . . . . . . . . .
Fixed-Length Record Formats . . . . . . . .
Standard Format . . . . . . . . . . .
Restrictions . . . . . . . . . . . . .
Variable-Length Record Formats . . . . . . .
Format-V Records . . . . . . . . . . .
Block Descriptor Word (BDW) . . . . . .
Record Descriptor Word (RDW) . . . . .
Spanned Format-VS Records (Sequential Access
Method) . . . . . . . . . . . . . .
Restrictions in Processing Spanned Records
with QSAM . . . . . . . . . . . .
Segment Descriptor Word . . . . . . .
Records Longer than 32 760 Bytes . . . .
Null Segments . . . . . . . . . . .
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
Converting the Segment Descriptor Word
Processing Records Longer than 32 760 Bytes
Processing DS/DBS Tapes with QSAM . . .
Processing DS/DBS Tapes with BSAM . . .
Format-U Records . . . . . . . . . . .
Record Format—Device Type Considerations . . .
Using Optional Control Characters . . . . .
Using Direct Access Storage Devices (DASD)
Using Magnetic Tape . . . . . . . . . .
Using a Printer . . . . . . . . . . . .
Table Reference Character . . . . . . .
Record Formats . . . . . . . . . .
Using a Card Reader and Punch . . . . . .
Using a Paper Tape Reader . . . . . . . .
Chapter 21. Specifying and Initializing Data
Control Blocks . . . . . . . . . . .
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) . . . . . . . . .
Large Block Interface (LBI) . . . . . .
System-Determined Block Size. . . . .
Data Set Organization (DSORG) . . . . .
Key Length (KEYLEN) . . . . . . . .
Record Length (LRECL) . . . . . . . .
Record Format (RECFM) . . . . . . .
© Copyright IBM Corp. 1987, 2004
287
287
288
289
289
290
290
291
291
292
293
293
294
294
294
296
297
297
298
300
302
303
304
305
305
305
305
306
307
307
308
308
309
309
310
. 311
312
317
. 318
.
.
.
.
.
.
.
.
.
.
320
320
321
321
322
323
327
328
328
328
Write Validity Check Option (OPTCD=W) . . .
DD Statement Parameters . . . . . . . .
Changing and Testing the DCB and DCBE . . .
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 . . . . .
Using the OPEN Macro to Position Tape
Volumes . . . . . . . . . . . . .
Using the DISP Parameter to Position
Volumes . . . . . . . . . . . . .
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 . . . .
329
329
330
331
331
332
332
332
332
333
334
335
335
335
335
336
336
336
337
338
338
338
339
339
340
340
341
342
343
343
344
344
344
345
346
346
347
347
349
350
350
350
350
351
351
351
Chapter 22. Accessing Records . . . . . . 353
Accessing Data with READ and WRITE . . . . 353
281
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 . . .
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)
Using Parallel Data Access Blocks (PDAB)
Testing for Parallel Processing . . . . . .
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 . . . . . . . . . . . . . . . .
|
353
353
353
355
356
356
356
357
358
359
359
359
360
360
361
362
363
363
364
364
364
Chapter 23. Sharing Non-VSAM Data Sets . . .
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 . . . . . . . . . . . . .
Data Integrity Messages . . . . . . . .
Data Integrity 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
365
Chapter 24. Spooling and Scheduling Data Sets
Job Entry Subsystem . . . . . . . . . . .
SYSIN Data Set . . . . . . . . . . . . .
SYSOUT Data Set . . . . . . . . . . . .
379
379
380
380
Chapter 25. Processing Sequential Data Sets
Creating a Sequential Data Set . . . . . . .
Retrieving a Sequential Data Set . . . . . .
Concatenating Data Sets Sequentially . . . .
Concatenating Like Data Sets . . . . . .
Rules for a Sequential Like Data Set . . .
383
383
384
385
386
386
282
z/OS V1R6.0 DFSMS: Using Data Sets
.
.
.
.
.
368
369
370
370
371
371
372
373
374
374
375
375
377
OPEN/EOV Exit Processing . . . . .
Persistence of DCB and DCBE Fields . .
SMS-Managed Data Sets with Like
Concatenation . . . . . . . . . .
BSAM Block Size with Like Concatenation
Concatenating Unlike Data Sets . . . . .
Modifying Sequential Data Sets . . . . . .
Updating in Place . . . . . . . . . .
Using Overlapped Operations . . . . . .
Extending a Data Set . . . . . . . . .
Multivolume DASD Data Set . . . . .
Extended-Format Sequential Data Sets . .
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 . .
Types of Compression . . . . . . .
Characteristics of 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 . .
Changing Existing BSAM and QSAM
Applications . . . . . . . . . . .
Calculating DASD Space Used . . . .
. 387
. 387
. 388
388
. 390
. 392
. 392
. 392
. 393
. 393
. 393
. 393
. 394
. 395
395
. 396
. 397
. 398
. 399
. 400
400
400
. 401
. 402
. 402
. 402
. 403
. 403
. 404
. 404
. 404
. 404
. 405
Chapter 26. Processing a Partitioned Data Set
(PDS) . . . . . . . . . . . . . . . . 407
Structure of a PDS . . . . . . . . . . . . 407
PDS Directory . . . . . . . . . . . . . 408
Allocating Space for a PDS . . . . . . . . . 411
Calculating Space . . . . . . . . . . . 411
Allocating Space with SPACE and AVGREC . . 412
Creating a PDS . . . . . . . . . . . . . 412
Creating a PDS Member with BSAM or QSAM 413
Converting PDSs . . . . . . . . . . . 413
Copying a PDS or Member to Another Data Set 413
Adding Members . . . . . . . . . . . 414
Processing a Member of a PDS . . . . . . . 416
BLDL—Construct a Directory Entry List . . . 416
DESERV . . . . . . . . . . . . . . 417
FUNC=GET . . . . . . . . . . . . 417
FUNC=GET_ALL . . . . . . . . . . 419
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 . . . . . . . . .
With BSAM and BPAM . . . . . .
With Overlapped Operations . . . .
With QSAM . . . . . . . . . .
Rewriting a Member . . . . . . . .
Concatenating PDSs . . . . . . . . .
Sequential Concatenation . . . . . .
Partitioned Concatenation . . . . . .
Reading a PDS Directory Sequentially . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 27. Processing a Partitioned Data Set
Extended (PDSE) . . . . . . . . . . .
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 . . . . . . . . .
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 . . . . . . .
Use of Noncontiguous Space . . . . . .
Integrated Directory . . . . . . . . .
Full Block Allocation . . . . . . . . .
PDSE Unused Space . . . . . . . . .
Frequency of Data Set Compression . . . .
Extent Growth . . . . . . . . . . .
Logical Block Size . . . . . . . . . .
Physical Block Size (Page Size) . . . . .
Free Space . . . . . . . . . . . .
Fragmentation . . . . . . . . . . .
Summary of PDSE Storage Requirements . . .
Defining a PDSE . . . . . . . . . . . .
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 . . . . .
FUNC=GET . . . . . . . . . . . .
FUNC=GET_ALL . . . . . . . . . .
420
421
422
426
426
427
427
428
429
429
429
429
430
431
431
433
433
433
434
434
435
435
436
437
437
437
438
439
439
439
440
440
440
440
441
441
441
441
441
442
442
442
443
443
444
445
446
446
446
447
448
448
449
451
|
FUNC=GET_NAMES . . . . . . . . .
FUNC=RELEASE . . . . . . . . . .
FUNC=UPDATE . . . . . . . . . .
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 . . . . .
Buffered Data Invalidation—VARY OFFLINE
DFP Share Attributes Callable Service
(IGWLSHR) . . . . . . . . . . . .
Normal or Extended PDSE Sharing . . . . .
Sharing PDSEs in a Single-System
Environment . . . . . . . . . . .
Specifying Normal PDSE Sharing in a
Multiple-System Environment . . . . . .
Specifying Extended PDSE Sharing in a
Multiple-System Environment . . . . . .
Modifying a Member of a PDSE . . . . . . .
Updating in Place . . . . . . . . . . .
With BSAM and BPAM . . . . . . . .
With Overlapped Operations . . . . . .
With QSAM . . . . . . . . . . . .
Extending a PDSE Member . . . . . . . .
Deleting a PDSE Member . . . . . . . .
Renaming a PDSE Member . . . . . . . .
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 . . . . . . . . . .
452
453
454
455
456
457
457
458
459
460
462
462
462
463
464
464
465
465
465
465
466
466
466
466
466
466
467
467
467
468
468
468
469
470
470
470
470
470
Chapter 28. Processing z/OS UNIX Files . .
Accessing the z/OS UNIX File System . . . .
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 . . . . . . . .
Creating a UNIX File with BSAM or QSAM .
Record Processing Considerations . . .
Processing Restrictions . . . . . . .
Creating a UNIX File Using JCL . . . . .
JCL Parameters for UNIX Files . . . . .
Creating a Macro Library in a UNIX Directory
Managing UNIX Files and Directories . . . .
. 473
. 473
474
. 474
. 475
. 475
. 476
. 477
. 477
. 478
. 478
. 479
. 480
481
. 482
Part 3. Non-VSAM Data Sets and UNIX Files
283
Specifying Security Settings for UNIX Files and
Directories . . . . . . . . . . . . .
Permissions for UNIX Files and Directories
RACF Authorization for UNIX Files . . . .
Editing UNIX Files . . . . . . . . . .
Using ISHELL to Manage UNIX Files and
Directories . . . . . . . . . . . . .
Copying UNIX Files or Directories . . . . .
Copying a PDS to a UNIX Directory or a
UNIX Directory to a PDS . . . . . . .
Using the OPUT Command to Copy
Members from a PDS or PDSE to a UNIX
File . . . . . . . . . . . . . . .
Using the OPUTX Command to Copy
Members from a PDS or PDSE to a UNIX
Directory or File . . . . . . . . . .
Using the OCOPY Command to Copy a PDS,
PDSE, or UNIX Member to Another Member .
Using the OGET Command to Copy a UNIX
File to a z/OS Data Set . . . . . . . .
Using the OGETX Command to Copy a
UNIX Directory to a PDS or PDSE . . . .
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 . . . . . . . .
|
482
483
483
483
484
485
z/OS V1R6.0 DFSMS: Using Data Sets
.
.
. 502
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
502
502
503
503
503
504
Chapter 30. Using I/O Device Control Macros
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
505
505
485
485
486
486
486
486
486
487
487
487
488
488
488
488
489
489
489
490
490
490
490
491
Chapter 29. Processing Generation Data
Groups . . . . . . . . . . . . . . . 493
Data Set Organization of Generation Data Sets . . 494
Absolute Generation and Version Numbers . . . 494
Relative Generation Number . . . . . . . . 495
Programming Considerations for Multiple-Step
Jobs . . . . . . . . . . . . . . . . 495
Cataloging Generation Data Groups . . . . . 496
Submitting Multiple Jobs to Update a
Generation Data Group . . . . . . . . . 496
Naming Generation Data Groups for ISO/ANSI
Version 3 or Version 4 Labels . . . . . . . . 497
Creating a New Generation. . . . . . . . . 498
Allocating a Generation Data Set . . . . . . 498
Referring to a Cataloged Data Set . . . . 498
Creating a Model DSCB . . . . . . . . 499
Using DATACLAS and LIKE Keywords . . 500
Passing a Generation Data Set . . . . . . . 501
Rolling In a Generation Data Set . . . . . . 501
284
Controlling Expiration of a Rolled-Off
Generation Data Set . . . . . . .
Creating an ISAM Data Set as Part of a
Generation Data Group . . . . . .
Retrieving a Generation Data Set . . . .
Reclaiming Generation Data Sets . . . .
Turning on GDS Reclaim Processing . .
Turning off GDS Reclaim Processing. .
Building a Generation Data Group Index .
Chapter 31. Using Non-VSAM User-Written Exit
Routines . . . . . . . . . . . . .
General Guidance . . . . . . . . . . .
Programming Considerations . . . . . .
Status Information Following an Input/Output
Operation . . . . . . . . . . . .
Data Event Control Block . . . . . .
Event Control Block . . . . . . . .
EODAD End-of-Data-Set Exit Routine . . . .
Register Contents . . . . . . . . . .
Programming Considerations . . . . . .
SYNAD Synchronous Error Routine Exit . . .
Register Contents . . . . . . . . . .
Programming Considerations . . . . . .
Queued Access Methods . . . . . .
Basic Access Methods . . . . . . .
Returning from the SYNAD routine . . .
ISAM . . . . . . . . . . . . .
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 . .
506
506
507
507
508
509
. 511
. 511
. 512
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
512
513
515
519
519
519
520
523
525
525
526
526
527
527
529
529
530
530
530
531
533
535
535
. 535
. 536
.
.
.
.
.
.
.
536
536
537
538
539
540
541
Open/EOV Nonspecific Tape Volume Mount Exit 545
Open/EOV Volume Security and Verification Exit 548
QSAM Parallel Input Exit . . . . . . . . . 550
User Totaling for BSAM and QSAM . . . . . . 550
Part 3. Non-VSAM Data Sets and UNIX Files
285
286
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 20. Selecting Record Formats for Non-VSAM Data
Sets
This chapter covers the following topics.
Topic
Location
Format Selection
287
Fixed-Length Record Formats
288
Variable-Length Record Formats
290
Undefined-Length Record Format
296
ISO/ANSI Tapes
297
Record Format—Device Type Considerations
305
This chapter 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 323.
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, 2004
287
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 306 and “Table Reference Character”
on page 308.
288
z/OS V1R6.0 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
above 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
289
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.
BDW
Block
Block
LL
LL
Record A Record B Record C
BDW
Record D Record E Record F
Blocked records
ll
RDW
ll
00
Data
a
b
Optional table reference
character
Optional control character
Reserved: 2 bytes
Record length: 2 bytes
Block
Block
Record
BDW
Record A
Record
ll
00
Non-extended BDW (block descriptor word)
0
LL 00
BDW
Figure 44. Nonspanned, Format-V Records
z/OS V1R6.0 DFSMS: Using Data Sets
Record C
Extended BDW
1
Reserved: 2 bytes
Block length: 15 bits
Bit 0 is 0
290
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 322.
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 346). 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
291
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 A
record B
Intermediate
segment of
logical record B
BDW
ll
First
segment
of logical
record
ll
Last segment First segment
of logical
of logical
record B
record C
ll
ll
Data
SDW
BDW
ab
Data
SDW
Intermediate
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
Last
segment
of logical
record
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 290.
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.
292
z/OS V1R6.0 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 291.
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 346) 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
or, when you are using WRITE with tape, from 18 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 28.
Table 28. 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
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
293
Selecting Record Formats for Non-VSAM Data Sets
The remaining bits of the third byte and all of the fourth byte are reserved for
possible future system use and must be 0.
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 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. Here are some techniques for processing records
longer than 32 760 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 760 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 760 bytes. Instead of 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 760 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 760 bytes. (BFTEK=A is ignored when LRECL=X is specified.)
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. (You do not have to be concerned about null
segments unless you have created a data set using null segments.)
Null segments are not recreated in PDSEs. For more information, see “Processing
PDSE Records” on page 436
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
294
z/OS V1R6.0 DFSMS: Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
with variable-length records by splitting the records into segments. Figure 46
shows how these segments can then be written onto more than one track.
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
295
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.
296
z/OS V1R6.0 DFSMS: Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
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:
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 617 for a list of supported
CCSID combinations and “CCSID Decision Tables” on page 629 for a description
of CCSID processing rules.
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
297
Selecting Record Formats for Non-VSAM Data Sets
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″.
– 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 634):
– ISO/ANSI V1 and V3 tapes
– ISO/ANSI V4 tapes without CCSID
– Unlabeled tapes with OPTCD=Q
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 288, 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.
298
z/OS V1R6.0 DFSMS: Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
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 shows the format of fixed-length records for ISO/ANSI tapes and where
control characters and block prefixes are positioned if they exist.
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
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
299
Selecting Record Formats for Non-VSAM Data Sets
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.
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.
300
z/OS V1R6.0 DFSMS: Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
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 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.
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
301
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 303 and
“Processing Records Longer than 32 760 Bytes” on page 304.
Figure 50 on page 303 shows what spanned variable-length records for ISO/ANSI
tapes look like.
302
z/OS V1R6.0 DFSMS: Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
Block
Block
Blocked
Last
First
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
Last
First
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.
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
303
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-DC 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.
304
z/OS V1R6.0 DFSMS: Using Data Sets
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 303.) 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 296
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 section 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 379.
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
305
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:
DA
TA
PR
RD
PC
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.
306
z/OS V1R6.0 DFSMS: Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
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 8 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
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 29 shows how the tape density (DEN) specifies the recording density in bits
per inch per track.
Table 29. 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.
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
307
Selecting Record Formats for Non-VSAM Data Sets
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.
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.
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:
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 306. 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.
308
z/OS V1R6.0 DFSMS: Using Data Sets
Selecting Record Formats for Non-VSAM Data Sets
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.
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 306. 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 359. 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
Chapter 20. Selecting Record Formats for Non-VSAM Data Sets
309
Selecting Record Formats for Non-VSAM Data Sets
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
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).
310
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 21. Specifying and Initializing Data Control Blocks
This chapter covers the following topics.
Topic
Location
Processing Sequential and Partitioned Data Sets
312
Using OPEN to Prepare a Data Set for Processing
317
Selecting Data Set Options
321
Changing and Testing the DCB and DCBE
330
Using CLOSE to End the Processing of a Data Set
332
Opening and Closing Data Sets: Considerations
335
Positioning Volumes
338
Managing SAM Buffer Space
341
Constructing a Buffer Pool
342
Controlling Buffers
346
Choosing Buffering Techniques and GET/PUT Processing Modes
350
Using Buffering Macros with Queued Access Method
350
Using Buffering Macros with Basic Access Method
351
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.
© Copyright IBM Corp. 1987, 2004
311
Data Control Block (DCB)
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.
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
Reference 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 112 on page 518.
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 section 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 section 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.
312
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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
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 305 and “Achieving Device Independence” on page
393. 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
287.
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 535.
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 395.
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.
Chapter 21. Specifying and Initializing Data Control Blocks
313
Data Control Block (DCB)
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
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 308.
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.
314
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
Figure 51 shows the simplest way to read a sequential data set.
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
Chapter 21. Specifying and Initializing Data Control Blocks
315
Data Control Block (DCB)
Figure 52 is the same as Figure 51 on page 315 but converted to be reentrant and
reside above the 16 MB line:
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
316
z/OS V1R6.0 DFSMS: Using Data Sets
*
Data Control Block (DCB)
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 318).
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.
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 27.
Chapter 21. Specifying and Initializing Data Control Blocks
317
Data Control Block (DCB)
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
DD
Statement
or SVC 99
ACS
Routines
2
7
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
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:
|
|
|
|
|
|
318
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
|
|
|
|
|
|
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 390.
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 535 and “JFCBE Exit” on page 540.
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.
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.
Chapter 21. Specifying and Initializing Data Control Blocks
319
Data Control Block (DCB)
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 341.
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. BISAM and QISAM scan mode ignore all the
OPEN processing options. Use OUTPUT or EXTEND when using QISAM load
mode with an indexed sequential data set.
INPUT—BDAM, BPAM, BSAM, QSAM
OUTPUT—BDAM, BPAM, BSAM, QSAM, QISAM (load mode)
EXTEND—BDAM, BPAM (PDSE only), BSAM, QSAM, QISAM (load mode)
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.)
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.
320
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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 330. 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.
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 379.) 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
Chapter 21. Specifying and Initializing Data Control Blocks
321
Data Control Block (DCB)
Installation Exits). If you use LBI, the maximum block size is 32 760 except on
magnetic tape, where the maximum is larger.
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 323 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. 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
and dummy data sets.
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
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.
322
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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 291.
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 398.
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
399.
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 112 on page 518 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.
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.
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:
Chapter 21. Specifying and Initializing Data Control Blocks
323
Data Control Block (DCB)
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 30 describes block size support.
Table 30. 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
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.
324
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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 31 on page 327 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
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.
Chapter 21. Specifying and Initializing Data Control Blocks
325
Data Control Block (DCB)
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.
326
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
The system-determined block size depends on the record format of the tape data
set. Table 31 shows the block sizes that are set for tape data sets.
Table 31. 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)
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),
indexed sequential (IS), 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:
Chapter 21. Specifying and Initializing Data Control Blocks
327
Data Control Block (DCB)
v When creating or processing an indexed sequential organization data set or
creating a direct data set, you must also specify DSORG in the DD statement.
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 437
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
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 306 and z/OS
DFSMS Macro Instructions for Data Sets for information about control characters.
328
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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
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
Reference for more information about allocating system-managed data sets and
using SMS classes.
Chapter 21. Specifying and Initializing Data Control Blocks
329
Data Control Block (DCB)
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
JCL Keywords Used To Override
DSORG
DSNTYPE
KEYLEN
KEYOFF
RECFM
LRECL
BLKSIZE
BLKSZLIM
RECORG
RETPD
SPACE, AVGREC
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,
or while the data set is open. See “DCB OPEN Exit” on page 535 and “Filling in
the DCB” on page 318 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.
330
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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
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.
Chapter 21. Specifying and Initializing Data Control Blocks
331
Data Control Block (DCB)
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 338 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.
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.
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.
332
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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 input to a member of a PDS.
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
333
Data Control Block (DCB)
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, 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.
334
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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 342.
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
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 321 and Figure 56 on page 332 show how to
code simultaneous open and close operations.
Chapter 21. Specifying and Initializing Data Control Blocks
335
Data Control Block (DCB)
Factors to Consider When Allocating Direct Access Data Sets
When the system allocates a new SMS 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. This means the first
GET or first CHECK for a READ causes the EODAD routine to be called.
For data sets other than system managed with DSORG=PS or null, 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. You can use one of the following methods to make the data set
appear null:
1. At allocation time, specify a primary allocation value of zero; such as
SPACE=(TRK,(0,10)) or SPACE=(CYL,(0,50)). This technique does not work with
a VIO data set because creation includes the secondary space amount.
2. After allocation time, put an end-of-file mark at the beginning of the data set,
by running 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 60.
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 365 and “Sharing PDSEs”
on page 462 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.
v Use only one DD statement per job step for a data set that might extend to a
new volume.
Attention: If you specify multiple DD statements in the same job step for an
SMS-managed data set on DASD, and also specify DISP=MOD or
issue the OPEN macro with options EXTEND or OUTINX, a data
integrity exposure occurs when the data set is extended on additional
volumes. This new volume information is not available to the other
DD statements in the job step for the same data set. Therefore, the
data on the new volumes is overlaid if the data set is opened for
output processing using one of the other DD statements in the same
job step and the data set is extended.
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
336
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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 531. 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.
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.
You should close an indexed sequential data set before task termination because, if
an I/O error is detected, the ISAM close routines cannot return the application
program registers to the SYNAD routine, causing unpredictable results.
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
Chapter 21. Specifying and Initializing Data Control Blocks
337
Data Control Block (DCB)
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:
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).
338
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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.
v You turned on the DCB “unlike” attributes bit. See “Concatenating Unlike Data
Sets” on page 390.
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.
Chapter 21. Specifying and Initializing Data Control Blocks
339
Data Control Block (DCB)
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.
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
340
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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. 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
can be used to process a sequential or an indexed 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
Chapter 21. Specifying and Initializing Data Control Blocks
341
Data Control Block (DCB)
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
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 reel tape devices, the real addresses must be 24-bit.
|
|
|
|
|
|
|
|
|
|
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
342
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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.
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.
Chapter 21. Specifying and Initializing Data Control Blocks
343
Data Control Block (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, a buffer
pool is requested by specifying BUFNO. For QSAM, BUFNO can be specified or
permitted to default in the following ways:
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 are using the basic access method to process an indexed sequential or 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
344
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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 and Figure 59 on page 346 show several possible methods of constructing
a buffer pool. They do not consider the method of processing or controlling the
buffers in the pool.
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 on page 346, two buffer pools are constructed explicitly by the
GETPOOL macros.
Chapter 21. Specifying and Initializing Data Control Blocks
345
Data Control Block (DCB)
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 (required by ISAM). 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.
Although only simple buffering can be used to process an indexed sequential data
set, buffer segments and buffers within a buffer pool are controlled automatically
by the operating system.
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
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
346
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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.
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.
Chapter 21. Specifying and Initializing Data Control Blocks
347
Data Control Block (DCB)
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) specifies the address of
the work area into which the system moves the next record from the input buffer.
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.
348
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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), only
GET-locate and PUTX-update are supported.
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.
Chapter 21. Specifying and Initializing Data Control Blocks
349
Data Control Block (DCB)
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 32 summarizes the combinations of buffering techniques
and processing modes you might use:
Table 32. 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
GET-locate
(logical record),
PUT-locate
X
X
System moves record
segment
X
Work area required
X
PUTX-output can be
used
X
Using Buffering Macros with Queued Access Method
This section 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
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
350
z/OS V1R6.0 DFSMS: Using Data Sets
Data Control Block (DCB)
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 section 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.
Chapter 21. Specifying and Initializing Data Control Blocks
351
352
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 22. Accessing Records
This chapter covers the following topics.
Topic
Location
Accessing Data with READ and WRITE
353
Accessing Data with GET and PUT
359
Analyzing I/O Errors
363
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
513. The ECB is described in “Event Control Block” on page 515.
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.
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
© Copyright IBM Corp. 1987, 2004
353
Accessing Records
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).
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.
354
z/OS V1R6.0 DFSMS: Using Data Sets
Accessing Records
Figure 83 on page 425 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.
If an indexed sequential data set is being read, the block is brought into virtual
storage and the address of the record is returned to you in the DECB.
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.
Indexed Sequential
K
Read the data set.
KU
Read for update. The system maintains the device address of the record;
thus, when a WRITE macro returns the record, no index search is required.
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.
Chapter 22. Accessing Records
355
Accessing Records
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
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.
Indexed Sequential
K
Write a block containing an updated record, or replace a record with a
fixed, unblocked record having the same key. The record to be replaced
need not have been read into virtual storage.
KN
Write a new record or change the length of a variable-length record.
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 357 and “DASD
and Tape Performance” on page 397.
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
356
z/OS V1R6.0 DFSMS: Using Data Sets
Accessing Records
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.
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 356 and “DASD and Tape Performance” on page 397.
For BDAM and BISAM, 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.
Example:
1. You have opened an input DCB for BSAM with NCP=2, and an output DCB for
BISAM with NCP=1 and without specifying MACRF=C.
2. You have issued two BSAM READ macros and one BISAM WRITE macro.
3. You now issue the WAIT macro with ECBLIST pointing to the BISAM DECB
and the first BSAM DECB. (Because BSAM requests are serialized, the first
request must run before the second.)
4. When you regain control, inspect the DECBs to see which has completed
(second bit on).
a. If it was BISAM, issue another WRITE macro.
b. If it was BSAM, issue a CHECK macro, then another READ macro.
Chapter 22. Accessing Records
357
Accessing Records
Handling Exceptional Conditions on Tape
In this section 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
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.
358
z/OS V1R6.0 DFSMS: Using Data Sets
Accessing Records
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.
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.
Chapter 22. Accessing Records
359
Accessing Records
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
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.
360
z/OS V1R6.0 DFSMS: Using Data Sets
Accessing Records
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 527.
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 362, not more than three data sets (MAXDCB=3 in the PDAB
macro) are open for parallel processing at a time.
Chapter 22. Accessing Records
361
Accessing Records
...
OPEN
TM
*
BZ
*
GETRTN
EODRTN
DATASET1
DATASET2
DATASET3
DATASET4
DCBQUEUE
SET3XLST
ZEROS
TM
BZ
TM
BZ
GET
LR
...
...
...
PUT
B
L
L
CLOSE
CLC
BL
...
DCB
(DATASET1,(INPUT),DATASET2,(INPUT),DATASET3,
(INPUT),DATASET4,(OUTPUT))
DATASET1+DCBQSWS-IHADCB,DCBPOPEN Opened for
parallel processing
SEQRTN
Branch on no to
sequential routine
DATASET2+DCBQSWS-IHADCB,DCBPOPEN
SEQRTN
DATASET3+DCBQSWS-IHADCB,DCBPOPEN
SEQRTN
DCBQUEUE,TYPE=P
10,1
Save record pointer
X
Record updated in place
DATASET4,(10)
GETRTN
2,DCBQUEUE+PDADCBEP-IHAPDAB
2,0(0,2)
((2))
ZEROS(2),DCBQUEUE+PDANODCB-IHAPDAB Any DCBs left?
GETRTN
Branch if yes
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’,X'92',AL3(DCBQUEUE)
DC
X'0000'
DCBD DSORG=QS
PDABD
...
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
362
z/OS V1R6.0 DFSMS: Using Data Sets
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,283,TA,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. 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
Chapter 22. Accessing Records
363
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, or if the access method is QISAM, 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 9 or later to determine if there are
problems with the disk drive or a problem reading or writing data stored on the
volume. Device Support Facilities also performs service checking of a volume. The
INSPECT command for the Device Support Facilities program can assign alternate
tracks. See Device Support Facilities 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.
364
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 23. Sharing Non-VSAM Data Sets
This chapter covers the following topics.
Topic
Location
PDSEs
374
Direct Data Sets (BDAM)
374
Factors to Consider When Opening and Closing Data Sets
375
Control of Checkpoint Data Sets on Shared DASD Volumes
375
System Use of Search Direct for Input Operations
377
Enhanced Data Integrity for Shared Sequential Data Sets
368
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 GRSplex 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, 2004
365
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 367 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 462. 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 368.
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.
366
z/OS V1R6.0 DFSMS: Using Data Sets
Sharing Non-VSAM Data Sets
Guarantee discrete blocks. When you are using the access methods that provide
blocking and unblocking of records (QSAM, QISAM, and BISAM), 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 566.
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. If,
however, you are processing an indexed sequential data set sequentially using the
SETL and ESETL macros, you must issue the ENQ macro before the SETL macro
and the DEQ macro after the ESETL macro. 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. For an example
of the use of ENQ and DEQ macros with BISAM see Figure 129 on page 591.
No action required. See “Sharing DCBs” on page 570.
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
Chapter 23. Sharing Non-VSAM Data Sets
367
Sharing Non-VSAM Data Sets
macro and an X in the type operand of the READ and WRITE macros. See
“Exclusive Control for Updating” on page 566 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.
Key sequence. Tasks sharing a QISAM load mode DCB must ensure that the
records to be written are presented in ascending key sequence; otherwise, a
sequence check will result in (1) control being passed to the SYNAD routine
identified by the DCB, or (2) if there is no SYNAD routine, termination of the task.
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 indexed
sequential and direct data sets in Figure 65 on page 366 satisfy the requirement.
For sequential and PDSs, the techniques specified in Figure 65 and Figure 66 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 Data Sets,” on page 365.
v Any task that shares a DCB and starts any input or output operations using that
DCB must ensure that all those operations are complete before terminating the
task. A CLOSE macro issued for the DCB ends all input and output operations.
v A DCB can be closed only by the task that opened it.
Shared Direct Access Storage Devices. At some installations, DASDs are shared
by two or more independent computing systems. Tasks run on these systems can
share data sets stored on the device. Accessing a shared data set or the same
storage area on shared DASD by multiple independent systems requires careful
planning. Without proper intersystem communication, data integrity could be
endangered.
To ensure data integrity in a shared DASD environment, your system must have
global resource serialization (GRS) active or a functionally equivalent global
serialization method.
Related reading: For information on data integrity for shared DASD, see z/OS
MVS Programming: Authorized Assembler Services Guide. For details on GRS, see z/OS
MVS Planning: Global Resource Serialization.
Enhanced Data Integrity for Shared Sequential Data Sets
You can concurrently access a shared sequential data set for output or update
processing. In some cases, you can lose or destroy data when you update the data
set, because one user could, at the same time, overwrite another user’s updates.
The enhanced data integrity function prevents this type of data loss. This data
integrity function either ends the program that is opening a sequential data set that
368
z/OS V1R6.0 DFSMS: Using Data Sets
Sharing Non-VSAM Data Sets
is already opened for writing, or it writes only a warning message but allows the
data set to open. Only sequential data sets can use the enhanced data integrity
function.
Related reading: For an overview of the enhanced data integrity function, see z/OS
DFSMSdfp Using DFSMSdfp in the z/OS V1R6 Environment.
Setting Up the Enhanced Data Integrity Function
Before you begin: z/OS DFSMS V1R5 is provided with the data integrity function
inactive. Usually, a system programmer would set up the data integrity function.
When you activate the data integrity function, multiple users no longer have
concurrent output or update access to a sequential data set on DASD.
Determine whether your system requires the data integrity function. Can the
applications allow concurrent access to sequential data sets for output or update,
and still maintain data integrity?
Perform the following steps to set up data integrity processing for your system.
1.
Create a new SYS1.PARMLIB member, IFGPSEDI. The IFGPSEDI member
contains the MODE variable and an optional list of data set names to be
excluded from data integrity processing. IFGPSEDI can be in any data set in
the SYS1.PARMLIB concatenation.
_______________________________________________________________
2.
Set IFGPSEDI to one of the following MODE values. MODE must start in the
first column of the first record.
|
|
MODE(WARN)
The program issues a warning message when an application attempts
to open for output a shared data set that is already open, but it allows
the current open to continue. This situation is called a data integrity
violation.
MODE(ENFORCE)
The program abends when a data integrity violation occurs.
MODE(DISABLE)
Data integrity processing is disabled.
_______________________________________________________________
3.
Use DSN(data_set_name) to specify which data sets, if any, to include in the
exclude list in the IFGPSEDI member.
The data set name can be a partially qualified or fully-qualified name. The
data set name also can contain an asterisk or percent sign.
When you specify MODE(WARN) or MODE(ENFORCE), data integrity processing
bypasses data sets that are in the exclude list in IFGPSEDI. The exclude list
excludes all data sets with that same name in the system. (If the data set is not
system managed, multiple data sets with the same name could exist on
different volumes, so they would be excluded.)
_______________________________________________________________
4.
Once you have created the IFGPSEDI member, activate data integrity
processing by IPLing the system or starting the IFGEDI task. The IFGEDI task
builds a data integrity table from the data in IFGPSEDI.
_______________________________________________________________
Chapter 23. Sharing Non-VSAM Data Sets
369
Sharing Non-VSAM Data Sets
Result: After you activate data integrity processing, message IEC983I displays. The
system issues this message during IPL or after you start the IFGEDI task. This
message indicates whether data integrity processing is active and the mode
(WARN, ENFORCE, or DISABLE).
If the SYS1.PARMLIB member, IFGPSEDI does not exist or it specifies
MODE(DISABLE), data integrity processing is not active and conventional
processing for shared sequential data sets continues.
Recommendation: The best way to identify applications that require data integrity
processing is to activate it in warning mode. Then review the warning messages
for the names of data sets that are identified. After you update the exclude list in
the IFGPSEDI member with the data sets to be protected, consider activating data
integrity processing in enforce mode.
Related reading: For more information on setting IFGPSEDI, see z/OS MVS
Initialization and Tuning Reference.
Synchronizing the Enhanced Data Integrity Function on
Multiple Systems
The data integrity function protects data sets that are shared within a sysplex if all
the systems in the sysplex have the data integrity function active and have the
same IFGPSEDI member data. Each system in a sysplex has its own data integrity
table.
Perform these steps to set up data integrity processing on multiple systems:
1.
Ensure that the data set names in the IFGPSEDI member are identical for each
system in the sysplex or that SYS1.PARMLIB is shared among all the systems
in the sysplex.
_______________________________________________________________
2.
Issue the S IFGEDI command on each system or re-IPL each system to rebuild
its data integrity table.
Until all systems in the sysplex have rebuilt their data integrity table, data
integrity processing might not be in sync. For example, if a data set name is
deleted from IFGPSEDI on one system and the data integrity table rebuilt on
that system, the other systems can still access that data set until their data
integrity tables are rebuilt.
_______________________________________________________________
Result: You know you have set up data integrity processing on multiple systems
when message IEC983I displays on each system.
Enhanced data integrity is not effective for data sets that are shared across multiple
sysplexes.
Using the START IFGEDI Command
|
The system operator can use the START IFGEDI command change the data
integrity mode without updating the IFGPSEDI PARMLIB member. For example, if
the data integrity function is causing problems while in enforce mode, the operator
can temporarily switch the mode to warning or disabled so that the applications
can continue to run.
v To change to warning mode, issue: S IFGEDI,,,WARN
|
|
|
|
|
|
370
z/OS V1R6.0 DFSMS: Using Data Sets
Sharing Non-VSAM Data Sets
|
v To disable the data integrity function, issue: S IFGEDI,,,DISABLE
Bypassing the Enhanced Data Integrity Function for
Applications
Before you begin: Some system applications can maintain their own data integrity
and do not need to use the data integrity function. To bypass data integrity
processing so that those applications can run correctly, perform one of the
following actions:
v Modify the application to ensure that multiple users cannot open or update a
sequential data set at the same time.
v Specify the list of sequential data sets to exclude from data integrity processing
in the IFGPSEDI member.
Attention: If you exclude data sets from data integrity processing, you must
ensure that all applications bypass data integrity processing to avoid
accidental destruction of data when multiple applications attempt to
open the data sets for output. If data integrity problems occur,
examine the SMF 14 and 15 records to see which data sets bypassed
data integrity processing.
v Set the DCBEEXPS flag in the DCBE macro to allow concurrent users to open
the data sets for output or update processing. Set bit 7, DCBEFLG2, to X’01’ by
using the instruction OI DCBEFLG2,DCBEEXPS in the DCBE macro.
To set and honor the DCBEEXPS flag, application programs must meet any one
of the following criteria:
– The application is authorized program facility (APF) authorized.
– The application is running in PSW supervisor state.
– The application is running in system key (0–7) when it opens the data set.
If none of the above are true, the DCBEEXPS flag is ignored.
v If the application is authorized, specify the NODSI flag in the program
properties table (PPT). The NODSI flag bypasses data integrity processing.
v If the application is authorized, dynamically allocate the data set with no data
integrity (NODSI) specified to bypass data integrity processing. In the
DYNALLOC macro, specify NODSI to set the S99NORES flag.
Recommendation: Changes to IFGPSEDI take effect when you restart the IFGEDI
task. If any of the data sets in the exclude list are open when you restart IFGEDI,
this change takes effect after the data sets are closed and reopened.
Related reading: For more information on using dynamic allocation, see the z/OS
MVS Programming: Authorized Assembler Services Guide.
Diagnosing Data Integrity Warnings and Violations
IEC984I and IEC985I display if you specify MODE(WARN) in IFGPSEDI. Monitor
messages IEC984I and IEC985I for possible failures. If you decide to globally
bypass data integrity processing for the data sets that are listed in the message,
include those data set name in the IFGPSEDI SYS1.PARMLIB member. If the data
set is being processed by an application that supports concurrent opens for output,
consider modifying the application to bypass data integrity processing. If the
application does not support concurrent opens, consider preventing concurrent
opens for output.
Chapter 23. Sharing Non-VSAM Data Sets
371
Sharing Non-VSAM Data Sets
If the exclude list is empty (no data set names specified) and IFGPSEDI specifies
MODE(WARN) or MODE(ENFORCE), data integrity processing occurs for all sequential
data sets.
You can set applications to bypass data integrity processing for the data set that is
being opened in the following ways:
v Specify the DCBEEXPS exclude flag in the DCBE macro.
v Specify the SCTNDSI exclude flag in the step control block.
v Dynamically allocate the data set with S99NORES specified. This action sets the
DSABNODI exclude flag for the data set
v Request the NODSI flag in the program properties table for the application
program.
Related reading: For more information on the warning messages and abends for
data integrity processing, and the flags for SMF record types 14 and 15, see the
z/OS DFSMSdfp Diagnosis Reference and z/OS MVS System Management Facilities
(SMF).
Data Integrity Messages
Although the data integrity function is designed to prevent multiple applications
from opening or updating the same sequential data set concurrently, data integrity
processing might miss occasional violations while in warning mode, or if the data
set is excluded from protection. For example, if two applications repeatedly open
and close the same data set for input or output while in warning mode, data
integrity processing might miss the violation, depending on the open/close
sequence. This situation is not a problem when the application is running in
ENFORCE mode.
Table 33 describes the different conditions for when data integrity is disabled and
also for data integrity warnings.
Table 33. Messages for Data Integrity Processing
Mode
Condition
MODE(DISABLE)
Enhanced data integrity is not
active (even if no data set
names are in the enhanced
data integrity table).
Sequential data
sets can be
opened for
output
concurrently.
IFGPSEDI not in
SYS1.PARMLIB
Enhanced data integrity is not
active.
Sequential data
sets can be
opened for
output
concurrently.
MODE(WARN)
If the data set is being opened IEC984I
for input when it is already
opened for output, and the
data set name is not in the
enhanced data integrity table,
and the application does not
bypass enhanced data
integrity.
372
z/OS V1R6.0 DFSMS: Using Data Sets
Message
SMF Record
SMF type 14
SMF14INO flag
Result
The data set is
opened.
Sharing Non-VSAM Data Sets
Table 33. Messages for Data Integrity Processing (continued)
Mode
Condition
MODE(WARN)
MODE(WARN)
MODE(WARN)
Message
SMF Record
Result
If the data set is being opened IEC984I
for output when it is already
opened for output, and the
data set name is not in the
enhanced data integrity table,
and the application does not
bypass enhanced data
integrity.
SMF type 15
The data set is
opened.
If the data set is being opened IEC985I
for input when it is already
opened for output, and the
data set name is in the table
or the application bypasses
enhanced data integrity.
SMF type 14
If the data set is being opened IEC985I
for output when it is already
opened for output, and the
data set name is in the table
or application bypasses
enhanced data integrity.
SMF type 15
SMF14OPO flag
The data set is
opened.
SMF14EXT flag
(if in EDI table) or
SMF14EPS flag
(if bypass requested)
The data set is
opened.
SMF14EXT flag
(if in EDI table) or
SMF14EPS flag
(if bypass requested)
Data Integrity Violations
Table 34 describes the different conditions for data integrity violations.
Note: if the data set is excluded from enhanced data integrity processing for any
reason, the SMF14 and SMF15 records will reflect that fact even for the first open
of the data set. Also, in ENFORCE mode the SMF14OPO and SFM14INO flags are
only set if there is inconsistency in the concurrent opens (the data set was not
excluded during the first open but was excluded during later ones).
|
|
|
|
|
Table 34. Different Conditions for Data Integrity Violations
Mode
Condition
Message or SMF
Record
Result
MODE(ENFORCE)
If the data set is being opened
for output when it is already
opened for output, and the data
set name is not in the enhanced
data integrity table and the
application does not bypass
enhanced data integrity.
ABEND 213-FD
The second open of the data set
for output fails.
MODE(ENFORCE)
If the data set is being opened
for input when it is already
opened for output, and the data
set name is not in the table and
the application does not bypass
enhanced data integrity.
SMF type 14
The second open of the data set
for input is allowed.
If the data set is being opened
for input when it is already
opened for output, and the data
set name is in the table or the
application bypasses enhanced
data integrity.
SMF type 14
MODE(ENFORCE)
SMF14INO flag
The second open of the data set
for input is allowed.
SMF14EXT flag
(if in EDI table),
SMF14EPS flag
(if bypass requested),
SMF14INO flag
Chapter 23. Sharing Non-VSAM Data Sets
373
Sharing Non-VSAM Data Sets
Table 34. Different Conditions for Data Integrity Violations (continued)
Mode
Condition
Message or SMF
Record
Result
MODE(ENFORCE)
If the data set is being opened
for output when it is already
opened for output, and the data
set name is in the enhanced data
integrity table or the application
bypasses enhanced data
integrity.
SMF type 15
The second open of the data set
for output is allowed.
SMF14EXT
(if in EDI table),
SMF14EPS flag
(if bypass requested),
SMF14OPO flag
PDSEs
See “Sharing PDSEs” on page 462 for information about sharing PDSEs.
Direct Data Sets (BDAM)
See “Sharing DCBs” on page 570 for more information on sharing direct data sets
using BDAM.
374
z/OS V1R6.0 DFSMS: Using Data Sets
Sharing Non-VSAM Data Sets
Factors to Consider When Opening and Closing Data Sets
Consider the following factors when opening and closing data sets:
v Two or more DCBs can be open concurrently for output to the same PDSE or
indexed sequential data set.
Two or more DCBs should never be concurrently open for output to the same
data set, except in the following situations:
v
v
v
v
v
– using the basic indexed sequential access method (BISAM).
– using PDSEs.
– using specially written BSAM, BDAM, or EXCP programs with sequential
data sets.
For all data sets except for PDSEs, if, concurrently, one DCB is open for input or
update, and one for output to the same data set on direct access storage devices,
the input or update DCB might be unable to read what the output DCB wrote if
the output DCB extended the data set. For PDSEs, the system dynamically
determines that the data set has been extended.
When an extended format data set is opened for reading, OPEN determines the
number of blocks in the data set as of the previous CLOSE for writing. Any data
added after the open for reading will not be found unless you supply a DCBE
with PASTEOD=YES for the reading DCB. It should be set before reading. For
QSAM you must set PASTEOD=YES before completion of the DCB OPEN exit
routine to ensure that the system recognizes it.
If you want to use the same DD statement for two or more DCBs, you cannot
specify parameters for fields in the first DCB, then obtain the default parameters
for the same fields in any other DCB using the same DD statement. This is true
for both input and output, and is especially important when you are using more
than one access method. Any action on one DCB that alters the JFCB affects the
other DCBs and thus can cause unpredictable results. Therefore, unless the
parameters of all DCBs using one DD statement are the same, you should use
separate DD statements.
Associated data sets for the IBM 3525 Card Punch can be opened in any order,
but all data sets must be opened before any processing can begin. Associated
data sets can be closed in any order, but, after a data set has been closed, I/O
operations cannot be performed on any of the associated data sets.
The OPEN macro gets user control blocks and user storage in the protection key
in which the OPEN macro is issued. Therefore, any task that processes the DCB
(such as Open, Close, or EOV) must be in the same protection key.
Control of Checkpoint Data Sets on Shared DASD Volumes
|
|
A checkpoint data set can be a sequential data set or a PDS, but it cannot be a
VSAM or sequential extended-format data set, a PDSE, or a UNIX file.
When an application program has a checkpoint, the system records information
about the status of that program in a checkpoint data set. Checkpoint data sets
contain system data. To ensure integrity of this data, checkpoint data sets are, by
default, permitted only on nonshared DASD and tape volumes. If a user could
read a checkpoint data set (even one the user owns) then the user might be able to
see information the user is not authorized to read. If a user could modify a
checkpoint data set (including one the user owns) the user might be able to use it
to bypass all security and integrity checks in the system.
Chapter 23. Sharing Non-VSAM Data Sets
375
Sharing Non-VSAM Data Sets
On systems that assure data set integrity across multiple systems, you may be
authorized to create checkpoints on shared DASD through the RACF facility class
“IHJ.CHKPT.volser”, where “volser” is the volume serial of the volume to contain
the checkpoint data set. Data set integrity across multiple systems is provided
when enqueues on the major name “SYSDSN”, minor name “data set name” are
treated as global resources (propagated across all systems in the complex) using
multisystem global resource serialization (GRS) or an equivalent function.
If a checkpoint data set is on shared DASD, DFSMS issues the SAF RACROUTE
macro requesting authorization against a facility class profile of IHJ.CHKPT.volser
during checkpoint (“volser” is the volume serial number where the checkpoint
data set resides).
If the system programmer cannot insure data set integrity on any shared DASD
volumes, the system programmer need not take any further action (for instance, do
not define any profile to RACF which would cover IHJ.CHKPT.volser). You cannot
take checkpoints on shared DASD volumes.
If data set integrity is assured on all shared DASD volumes and the system
programmer wants to perform a checkpoint on any of these volumes, build a
facility class generic profile with a name of IHJ.CHKPT.* with UACC of READ.
If data set integrity cannot be assured on some of the volumes, build discrete
profiles for each of these volumes with profile names of IHJ.CHKPT.volser with
UACC of NONE. These “volume-specific” profiles are in addition to the generic
profiles described above to permit checkpoints on shared DASD volumes for which
data set integrity is assured.
If the system programmer wants to let some, but not all, users to create
checkpoints on the volumes, build the generic profiles with UACC of NONE and
permit READ access only to those specific users or groups of users.
Information in a checkpoint data set includes the location on the disk or tape
where the application is currently reading or writing each open data set. If a data
set that is open at the time of the checkpoint is moved to another location before
the restart, you cannot restart the application from the checkpoint because the
location-dependent information recorded by checkpoint/restart is no longer valid.
There are several system functions (for example, DFSMShsm or DFSMSdss) that
might automatically move a data set without the owner specifically requesting it.
To ensure that all checkpointed data sets remain available for restart, the
checkpoint function sets the unmovable attribute for each SMS-managed sequential
data set that is open during the checkpoint. An exception is the data set containing
the actual recorded checkpoint information (the checkpoint data set), which does
not require the unmovable attribute.
You can move checkpointed data sets when you no longer need them to perform a
restart. DFSMShsm and DFSMSdss FORCECP(days) enable you to use operations
such as migrate, copy, or defrag to move an SMS-managed sequential data set
based on a number of days since the last access. DFSMShsm recall, and DFSMSdss
restore and copy, are operations that turn off the unmovable attribute for the target
data set.
376
z/OS V1R6.0 DFSMS: Using Data Sets
Sharing Non-VSAM Data Sets
See z/OS Security Server RACF Command Language Reference for information about
RACF commands and z/OS Security Server RACF Security Administrator’s Guide for
information about using and planning for RACF options.
If you do not have RACF or an equivalent product, the system programmer can
write an MVS router exit that is invoked by SAF and can be used to achieve the
above functions. See z/OS MVS Programming: Authorized Assembler Services Guide for
information about writing this exit.
System Use of Search Direct for Input Operations
To hasten the input operations required for a data set on DASD, the operating
system uses a technique called search direct in its channel programs. Search direct
reads in the requested record and the count field of the next record. This lets the
operation get the next record directly, along with the count field of the record that
follows it. Search direct (OPTCD=Z) is an obsolete DCB macro and DD statement
option. Now the system generally uses this technique for sequential reading.
When sharing data sets, you must consider the restrictions of search direct. Search
direct can cause unpredictable results when multiple DCBs are open and the data
sets are being shared, and one of the applications is adding records. You might get
the wrong record. Also, you might receive unpredictable results if your application
has a dependency that is incompatible with the use of search direct.
Chapter 23. Sharing Non-VSAM Data Sets
377
378
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 24. Spooling and Scheduling Data Sets
This chapter contains information about the following topics.
Topic
Location
Job Entry Subsystem
379
SYSIN Data Set
380
SYSOUT Data Set
380
Spooling includes two basic functions:
v Input streams are read from the input device and stored on an intermediate
storage device in a format convenient for later processing by the system and by
the user’s program.
v Output streams are similarly stored on an intermediate device until a convenient
time for printing, punching, processing by a TSO/E user or sending over a
network to another system.
With spooling, unit record devices are used at full speed if enough buffers are
available. They are used only for the time needed to read, print, or punch the data.
Without spooling, the device is occupied for the entire time it takes the job to
process. Also, because data is stored instead of being transmitted directly, output
can be queued in any order and scheduled by class and by priority within each
class.
Scheduling provides the highest degree of system availability through the orderly
use of system resources that are the objects of contention.
Job Entry Subsystem
The job entry subsystem (JES) spools and schedules input and output data streams.
It controls all blocking and deblocking of your data to make the best use of system
operation. The BSAM NCP value has an effect on the access method, but a value
greater than 1 does not improve performance. NCP is supported for compatibility
with other data sets. The block size (BLKSIZE) and number of buffers (BUFNO)
specified in your program have no relationship with what is actually used by the
job entry subsystem. Therefore, you can select the blocking factor that best fits
your application program with no effect on the spooling efficiency of the system.
For QSAM applications, move mode is as efficient as locate mode.
SYSIN and SYSOUT data sets cannot be system managed. SYSIN and SYSOUT
must be either BSAM or QSAM data sets and you open and close them in the
same manner as any other data set processed on a unit record device. Because
SYSIN and SYSOUT data sets are spooled on intermediate devices, you should
avoid using device-dependent macros (such as FEOV, CNTRL, PRTOV, or BSP) in
processing these data sets. See “Achieving Device Independence” on page 393. You
can use PRTOV, but it will have no effect. For more information about SYSIN and
SYSOUT parameters see z/OS MVS JCL User’s Guide and z/OS MVS JCL Reference.
Your SYNAD routine is entered if an error occurs during data transmission to or
from an intermediate storage device. Again, because the specific device is
indeterminate, your SYNAD routine code should be device independent. If you
© Copyright IBM Corp. 1987, 2004
379
Spooling and Scheduling Data Sets
specify the DCB open exit routine in an exit list, it will be entered in the usual
manner. See “DCB Exit List” on page 527 for the DCB exit list format and “DCB
OPEN Exit” on page 535.
SYSIN Data Set
You enter data into the system input stream by preceding it with a DD * or a DD
DATA JCL statement. This is called a SYSIN data set. The DD name is not
necessarily SYSIN.
A SYSIN data set cannot be opened by more than one DCB at the same time; that
would result in an S013 ABEND.
If no record format is specified for the SYSIN data set, a record format of fixed is
supplied. Spanned records (RECFM=VS or VBS) cannot be specified for SYSIN.
The minimum record length for SYSIN is 80 bytes. For undefined records, the
entire 80-byte image is treated as a record. Therefore, a read of less than 80 bytes
results in the transfer of the entire 80-byte image to the record area specified in the
READ macro. For fixed and variable-length records, an ABEND results if the
LRECL is less than 80 bytes.
The logical record length value of SYSIN (JFCLRECL field in the JFCB) is filled in
with the logical record length value of the input data set. This logical record length
value is increased by 4 if the record format is variable (RECFM=V or VB).
The logical record length can be a size other than the size of the input device, if
the SYSIN input stream is supplied by an internal reader. JES supplies a value in
the JFCLRECL field of the JFCB if that field is found to be zero.
The block size value (the JFCBLKSI field in the JFCB) is filled in with the block
size value of the input data set. This block size value is increased by 4 if the record
format is variable (RECFM=V or VB). JES supplies a value in the JFCBLKSI field of
the JFCB if that field is found to be 0.
SYSOUT Data Set
Your output data can be printed or punched from an output stream that is called
the SYSOUT data set. Code the SYSOUT parameter in your DD statement and
designate the appropriate output class. For example, SYSOUT=A requests output
class A. Your installation establishes the class-device relationship; a list of devices
assigned to each output class will enable you to select the appropriate one.
JES permits multiple opens to the same SYSOUT data set, and the records are
interspersed. However, you need to ensure that your application serializes the data
set. For more information about serialization see Chapter 23, “Sharing Non-VSAM
Data Sets,” on page 365.
From open to close of a particular data control block you should not change the
DCB indicators of the presence or type of control characters. When directed to disk
or tape, all the DCB’s for a particular data set should have the same type of control
characters. For a SYSOUT data set, the DCBs can have either type of control
character or none. The result depends on the ultimate destination of the data set.
For local printers and punches, each record is processed according to its control
character.
380
z/OS V1R6.0 DFSMS: Using Data Sets
Spooling and Scheduling Data Sets
When you use QSAM with fixed-length blocked records or BSAM, the DCB block
size parameter does not have to be a multiple of logical record length (LRECL) if
the block size is specified in the SYSOUT DD statement. Under these conditions, if
block size is greater than, but not a multiple of, LRECL, the block size is reduced
to the nearest lower multiple of LRECL when the data set is opened.
You can specify blocking for SYSOUT data sets, even though your LRECL is not
known to the system until execution. Therefore, the SYSOUT DD statement of the
go step of a compile-load-go procedure can specify a block size without the block
size being a multiple of LRECL.
You should omit the DEVD parameter in the DCB macro, or you should code
DEVD=DA.
You can use the SETPRT macro to affect the attributes and scheduling of a
SYSOUT data set.
Your program is responsible for printing format, pagination, header control, and
stacker select. You can supply control characters for SYSOUT data sets in the
normal manner by specifying ANSI or machine characters in the DCB. Standard
controls are provided by default if they are not explicitly specified. The length of
output records must not exceed the allowable maximum length for the ultimate
device. Cards can be punched in EBCDIC mode only.
You can supply table reference characters (TRC’s) for SYSOUT data sets by
specifying OPTCD=J in the DCB. When the data set is printed, if the printer does
not support TRC’s then the system discards them.
See ″Processing SYSIN, SYSOUT, and System Data Sets″ under “Coding Processing
Methods” on page 320.
Chapter 24. Spooling and Scheduling Data Sets
381
382
z/OS V1R6.0 DFSMS: Using Data Sets
Chapter 25. Processing Sequential Data Sets
This chapter covers the following topics.
Topic
Location
Creating a Sequential Data Set
383
Retrieving a Sequential Data Set
384
Concatenating Data Sets Sequentially
385
Modifying Sequential Data Sets
392
Achieving Device Independence
393
Improving Performance for Sequential Data Sets
395
Determining the Length of a Block when Reading with BSAM, BPAM, or
BDAM
398
Writing a Short Format-FB Block with BSAM or BPAM
399
Processing Extended-Format Sequential Data Sets
400
You must use sequential data sets for all magnetic tape devices, punched cards,
and printed output. A data set residing on DASD, regardless of organization, can
be processed sequentially. You can also process sequentially data sets created using
BISAM or QISAM. Because the entire data set (prime, index, and overflow areas)
will be processed, you should determine what type of records are involved.
Creating a Sequential Data Set
Use either the QSAM or the BSAM to store and retrieve the records of a sequential
data set. To create a sequential data set on magnetic tape or DASD, take the
following actions:
1. Code DSORG=PS or PSU in the DCB macro.
2. Do one of the following:
v Code a DD statement to describe the data set. See z/OS MVS JCL Reference. If
SMS is implemented on your system, you can specify a data class in the DD
statement or have the ACS routines assign a data class.
v Create the data set using the TSO or access method services ALLOCATE
command. See z/OS DFSMS Access Method Services for Catalogs. If SMS is
implemented on your system, you can specify the DATACLAS parameter or
have the ACS routine assign a data class.
v Call dynamic allocation (SVC 99) from your program. See z/OS MVS
Programming: Authorized Assembler Services Guide. If SMS is implemented on
your system, you can specify the data class text unit or have the ACS
routines assign a data class.
3. Optionally, use a data class to simplify and standardize data attributes. You can
take advantage of a data class for data sets that are system managed or not
system managed.
4. Process the data set with an OPEN macro (the data set is opened for OUTPUT,
OUTIN, OUTINX, or EXTEND), a series of PUT or WRITE and CHECK
macros, and the CLOSE macro.
© Copyright IBM Corp. 1987, 2004
383
Processing a Sequential Data Set
The example in Figure 67 shows that the GET-move and PUT-move require two
movements of the data records.
OPEN
GET
AP
UNPK
OI
PUT
B
ENDJOB
CLOSE
...
COUNT
DS
WORKAREA DS
NUMBER
DC
SAVE14
DS
INDATA
DCB
NEXTREC
OUTDATA
DCB
(INDATA,,OUTDATA,(OUTPUT))
INDATA,WORKAREA
NUMBER,=P’1’
COUNT,NUMBER
COUNT+5,X’F0’
OUTDATA,COUNT
NEXTREC
(INDATA,,OUTDATA)
Move mode
Record count adds 6
Set zone bits
bytes to each record
CL6
CL50
PL4’0’
F
DDNAME=INPUTDD,DSORG=PS,MACRF=(GM),EODAD=ENDJOB,
LRECL=50,RECFM=FB
DDNAME=OUTPUTDD,DSORG=PS,MACRF=(PM),
LRECL=56,RECFM=FB
X
X
...
Figure 67. Creating a Sequential Data Set—Move Mode, Simple Buffering
If the record length (LRECL) does not change during processing, but only one
move is necessary, you can process the record in the input buffer segment. A
GET-locate provides a pointer to the current segment.
Related reading: See “QSAM in an Application” on page 347 for more information.
Retrieving a Sequential Data Set
To retrieve a sequential data set from magnetic tape, DASD, or other types of
devices, take the following actions:
1. Code DSORG=PS or PSU in the DCB macro.
2. Tell the system where your data set is located (by coding a DD statement, or by
calling dynamic allocation (TSO ALLOCATE command or SVC 99)).
3. Process the data set with an OPEN macro (data set is opened for input, INOUT,
RDBACK, or UPDAT), a series of GET or READ macros, and the CLOSE macro.
The example in Figure 68 on page 385 is similar to that in Figure 67. However,
because there is no change in the record length, the records can be processed in the
input buffer. Only one move of each data record is required.
Related reading: See “QSAM in an Application” on page 347 for more information.
384
z/OS V1R6.0 DFSMS: Using Data Sets
Processing a Sequential Data Set
....
OPEN
NEXTREC
GET
LR
AP
UNPK
PUT
MVC
B
ENDJOB
CLOSE
...
NUMBER
DC
INDATA
DCB
OUTDATA
DCB
ERRORDCB DCB
SAVE2
DS
...
(INDATA,,OUTDATA,(OUTPUT),ERRORDCB,(OUTPUT))
INDATA
Locate mode
2,1
Save pointer
NUMBER,=P’1’
0(6,2),NUMBER
Process in input area
OUTDATA
Locate mode
0(50,1),0(2)
Move record to output buffer
NEXTREC
(INDATA,,OUTDATA,,ERRORDCB)
PL4’0’
DDNAME=INPUTDD,DSORG=PS,MACRF=(GL),EODAD=ENDJOB
DDNAME=OUTPUTDD,DSORG=PS,MACRF=(PL)
DDNAME=SYSOUTDD,DSORG=PS,MACRF=(PM),RECFM=V,
BLKSIZE=128,LRECL=124
F
C
Figure 68. Retrieving a Sequential Data Set—Locate Mode, Simple Buffering
Concatenating Data Sets Sequentially
The system can retrieve two or more data sets and process them successively as a
single sequential data set. This is called sequential concatenation. The number of data
sets that you can concatenate with sequential concatenation is variable. It is
governed by the maximum size of the TIOT option. The system programmer
controls the TIOT size with the option ALLOCxx member of SYS1.PARMLIB. The
smallest TIOT value allows 819 single-unit DD statements or 64 DD statements
having the maximum number of units. See z/OS MVS Initialization and Tuning
Reference. When data sets are sequentially concatenated, your program is open to
only one of the data sets at a time. Concatenated data sets cannot be read
backward.
A sequential concatenation can include sequential data sets, PDS members, PDSE
members, and UNIX files. With sequential concatenation, the system treats a PDS,
PDSE, or UNIX member as if it were a sequential data set. The system treats a
striped extended-format data set as if it were a single-volume data set.
Rule: You cannot concatenate VSAM data sets.
End-of-Data-Set (EODAD) Processing. When the change from one data set to
another is made, label exits are taken as required; automatic volume switching is
also performed for multiple volume data sets. When your program reads past the
end of a data set, control passes to your end-of-data-set (EODAD) routine only if
the last data set in the concatenation has been processed.
Consecutive Data Sets on a Tape Volume. To save time when processing two
consecutive sequential data sets on a single tape volume, specify LEAVE in your
OPEN macro, or DISP=(OLD,PASS) in the DD statement, even if you otherwise
would code DISP=(OLD,KEEP).
Reading Directories. You can use BSAM to read PDS and PDSE directories. You
can use BPAM to read UNIX directories and files. For more information, see
Chapter 28, “Processing z/OS UNIX Files,” on page 473.
Restriction: You cannot use BSAM or QSAM to read a UNIX directory.
Chapter 25. Processing Sequential Data Sets
385
Processing a Sequential Data Set
Concatenating Like Data Sets
Concatenation can be thought of as processing a sequence of like or unlike data sets.
The system treats each transition between consecutive data sets as being like or
unlike. The like transitions in the sequence are those that the program can process
correctly without notifying the system to treat the data set as unlike. For example,
you must concatenate data sets with different record formats as unlike unless the
data meets the requirements of a different record format. For example, if all the
format-V records are the same length, you can specify format-F when reading. If
you specify format-U, you can read any format.
If either of the data sets in a transition is system managed, you can treat the
transition as like. However, you must ensure that both data sets meet all like
concatenation rules, or unpredictable results can occur (for example, OPEN
ABENDs).
Your program indicates whether the system is to treat the data sets as like or unlike
by setting the bit DCBOFPPC. The DCB macro assembles this bit as 0, which
indicates like data sets. See “Concatenating Unlike Data Sets” on page 390.
Rules for a Sequential Like Data Set
To be a like data set, a sequential data set must meet all the following conditions:
v All the data sets in a concatenation should have compatible record formats. They
are all processed with the record format of the first data set in the concatenation
(see “Persistence of DCB and DCBE Fields” on page 387). For example a data set
with unblocked records can be treated as having short blocked records. A data
set with fixed-blocked-standard records (format-FBS) can be treated as having
just fixed-blocked records (format-FB), but the reverse cannot work.
Having compatible record formats does not ensure that like processing is
successful. For example, if the record format of the first data set in the
concatenation is fixed (format-F) and a concatenated data set has fixed-blocked
records (format-FB), then unpredictable results, such an I/O errors or open
ABENDs, can occur, but the reverse should work.
The results of concatenating data sets of different characteristics can also depend
on the actual data record size and on whether the data sets are system managed.
For example, you can process two concatenated data sets successfully if the first
data set is format-F with a BLKSIZE and LRECL of 80, the second data set is
format-FB with a BLKSIZE of 800 and an LRECL of 80, the second data set is not
system managed, and the actual data size of all the blocks in the second data set
is 80 bytes. However, if the actual data size of a block is greater than 80 bytes,
an I/O error occurs when the system reads that record from the second data set.
Alternatively, if SMS manages the second data set, the system processes data
from the first data set. An open failure (ABEND 013-60) occurs when EOV
switches to the concatenated data set, however, even though the actual data size
of all the records can be compatible.
If incompatible record formats are detected in the concatenation and BSAM is
being used, the system issues a warning message, see “BSAM Block Size with
Like Concatenation” on page 388.
v LRECL is same as the LRECL of the preceding data set. With format-V or -VB
records, the new data set can have a smaller LRECL than is in the DCB.
v All the data set block sizes should be compatible. For format-F or -FB records,
each block size should be an integral multiple of the same LRECL value.
v If you code the BLKSIZE parameter in the DCB or DCBE macro, or on the first
DD statement, the block size of each data set must be less than or equal to that
block size.
386
z/OS V1R6.0 DFSMS: Using Data Sets
Processing a Sequential Data Set
v
v
v
v
v
Note: If you specify DCB parameters such as BLKSIZE, LRECL, or BUFNO
when allocating a data set after the first one, they have no effect when your
program uses like concatenation, except as described in “BSAM Block Size with
Like Concatenation” on page 388.
You can specify a large BLKSIZE for the first data set to accommodate a later
data set with blocks of that size.
DASD data sets that are accessed by QSAM or BSAM can be concatenated in
any order of block size. If you are using QSAM, you must use system-created
buffers for the data set. The size of each system-created buffer equals the block
sizes rounded up to a multiple of 8. For QSAM the system-created buffers are
used to process all data sets in the concatenation unless the next data set’s
BLKSIZE is larger than the buffers. In that case, the buffers are freed by
end-of-volume processing and new system-created buffers are obtained. This
also means the buffer address returned by GET is only guaranteed valid until
the next GET or FEOV macro is issued, because the buffer pool can have been
freed and a new system-created buffer pool obtained during end-of-volume
concatenation processing. For system-managed data set processing, see
“SMS-Managed Data Sets with Like Concatenation” on page 388. For BSAM
processing see “BSAM Block Size with Like Concatenation” on page 388.
For QSAM, if a data set after the first one is on magnetic tape and has a block
size larger than all prior specifications, the volume must have IBM or ISO/ANSI
standard tape labels or the BLKSIZE must be specified on the DD statement.
For BSAM, if a data set after the first one is on magnetic tape and has a block
size larger than all prior specifications, the BLKSIZE must be specified on the
DD statement.
The device is a DASD, tape, or SYSIN device, as is the device of the preceding
data set. For example, you can concatenate a tape data set to a DASD data set,
or you can concatenate a DASD data set to a tape data set. However, you cannot
concatenate a tape data set to a card reader.
Tip: Regard an extended-format sequential data set as having the same
characteristics as a sequential data set.
If mixed tape and DASD, the POINT or CNTRL macros are not used.
Related reading: For more information, see “Concatenating UNIX Files and
Directories” on page 490 and “Concatenating Extended-Format Data Sets with
Other Data Sets” on page 404.
OPEN/EOV Exit Processing
If the program has a DCB OPEN exit, it is called only at the beginning of the first
data set.
With like concatenation, if the program has an end-of-volume exit, it is called at the
beginning of each volume of each data set except the first volume of the first data
set. If the type of data set does not have volumes, the system treats it as having
one volume.
Persistence of DCB and DCBE Fields
Between the completion of OPEN and the completion of CLOSE with like
concatenation, the system can change certain DCB or DCBE fields that represent
data attributes. Your program and the system do not change the following attribute
fields:
v RECFM
v LRECL for format-F for BSAM and for QSAM XLRI
v BLKSIZE for BSAM (your program can change this)
Chapter 25. Processing Sequential Data Sets
387
Processing a Sequential Data Set
v KEYLEN
v NCP or BUFNO
With like concatenation the system can change the following when switching to
another data set:
v BLKSIZE and BUFL for QSAM
v Field DCBDEVT in the DCB (device type)
v TRTCH (tape recording technique)
v DEN (tape density)
With or without concatenation the system sets LRECL in the DCB for each QSAM
GET macro when reading format-V, format-D, or format-U records, except with
XLRI. GET issues an ABEND if it encounters a record that is longer than LRECL
was at the completion of OPEN.
If your program indicates like concatenation (by taking no special action about
DCBOFPPC) and one of the like concatenation rules is broken, the results are
unpredictable. A typical result is an I/O error, resulting in an ABEND, or entry to
the SYNAD routine. The program might even appear to run correctly.
SMS-Managed Data Sets with Like Concatenation
If SMS-managed data sets are being concatenated, then the system does additional
processing for the transition between data sets. This includes additional checking
of data set attributes. This might result in OPEN issuing an ABEND after
successful completion of the OPEN that the user program issued. A violation of the
like concatenation requirements could result in an ABEND during the open of the
next concatenated data set.
If the open routine for QSAM obtains the buffer pool automatically, the data set
transition process might free the buffer pool and obtain a new one for the next
concatenated data set. The buffer address that GET returns is valid only until the
next GET or FEOV macro runs. The transition process frees the buffer pool and
obtains a new, system-created buffer pool during end-of-volume concatenation
processing. The procedure does not free the buffer pool for the last concatenated
data set unless you coded RMODE31=BUFF. You should also free the
system-created buffer pool before you attempt to reopen the DCB, unless you
coded RMODE31=BUFF.
BSAM Block Size with Like Concatenation
After BSAM OPEN has merged the data set characteristics from the label to the
JFCB and the DCB or DCBE, and before it calls your DCB OPEN exit routine,
OPEN tries to search later DD statements to see if BSAM should use a larger
maximum block size. OPEN searches only if you have enabled a larger block size.
A larger block size is enabled if all three of the following conditions are true:
v BLKSIZE is not coded in the DCB or DCBE before OPEN or in the first JFCB.
Each data set is represented by a JFCB.
v RECFM (record format) in the DCB specifies format-U or blocked records. Any
data set can be fixed-standard blocked.
v You did not set on DCBOFPPC (X'08' in DCBOFLGS, which is at +48 in the
DCB). This is the unlike attributes bit.
If you have enabled a larger block size, OPEN searches later concatenated data sets
for the largest acceptable block size and stores it in the DCB or DCBE. A block size
is acceptable if it comes from a source that does not also have a RECFM or LRECL
inconsistent with the RECFM or LRECL already in the DCB.
388
z/OS V1R6.0 DFSMS: Using Data Sets
Processing a Sequential Data Set
Compatible Characteristics: For format-F records, if a data set has an LRECL
value that differs from the value in the DCB, the block size for that data set is not
considered during OPEN.
For format-V records, if a data set has an LRECL value that is larger than the value
in the DCB, the block size for that data set is not considered during OPEN.
A RECFM value of U in the DCB is consistent with any other RECFM value.
BSAM considers the following RECFM values compatible with the specified record
format for the first data set:
v F or FB—Compatible record formats are F, FB, FS, and FBS.
v V or VB—Compatible record formats are V and VB.
v U—All other record formats are compatible.
If OPEN finds an inconsistent RECFM, it will issue a warning message. OPEN
does not examine DSORG when testing consistency. It does not issue ABEND since
you might not read as far as that data set or you might later turn on the DCB
unlike attributes bit.
Even though RECFMs of concatenated data sets can be considered compatible by
BSAM (and you do not receive the expected warning message) that does not
guarantee they can be successfully processed. It still can be necessary to treat them
as unlike.
BSAM OPEN Processing Before First Data Set: OPEN tests the JFCB for each
data set after the one being opened. The JFCB contains information coded when
the data set was allocated and information that OPEN can have stored there before
it was dynamically reconcatenated.
All of the above processing previously described occurs for any data set that is
acceptable to BSAM. The OPEN that you issue does not read tape labels for data
sets after the first. Therefore, if there is a tape data set after the first that has a
block size larger than all of the prior specifications, the BLKSIZE value must be
specified on the DD statement. The system later reads those tape labels but it is too
late for the system to discover a larger block size at that time.
For each data set whose JFCB contains a block size of 0 and is on permanently
resident DASD, OPEN obtains the data set characteristics from the data set label
(DSCB). If they are acceptable and the block size is larger, OPEN copies the block
size to the DCB or DCBE.
For each JFCB or DSCB that this function of OPEN examines, OPEN turns off the
DCB’s standard bit, if the block size differs from the DCB or DCBE block size and
the DCB has fixed standard.
If DCBBUFL, either from the DCB macro or the first DD statement, is nonzero,
then that value will be an upper limit for BLKSIZE from another data set. No
block size from a later DD statement or DSCB is used during OPEN if it is larger
than that DCBBUFL value. OPEN ignores that larger block size on the assumption
that you will turn on the unlike attributes bit later, will not read to that data set, or
the data set does not actually have blocks that large.
When OPEN finds an inconsistent record format, it issues the following message:
IEC034I INCONSISTENT RECORD FORMATS rrr AND iii,ddname+cccc,dsname
Chapter 25. Processing Sequential Data Sets
389
Processing a Sequential Data Set
In the message, the variables represent the following values.
rrr
Specifies record format established at OPEN.
iii
Specifies record format found to be inconsistent. It is in a JFCB that has a
nonzero BLKSIZE or in a DSCB.
cccc
Specifies the number of the DD statement after the first one, where +1
means the second data set in the concatenation.
Example of BSAM Like Concatenation: Figure 69 shows an example of JCL for a
like concatenation that is read using BSAM. The application could use QSAM
instead of BSAM. QSAM does not require BLKSIZE to be coded because this tape
data set on 3590 has tape labels.
//INPUT DD
...
//
DD
//
DD
*
(instream data set)
DSN=D42.MAIN.DATA,DISP=SHR
DSN=D42.SUPPL.DATA,UNIT=(3590,2),DISP=OLD,BLKSIZE=150000
Figure 69. Like Concatenation Read through BSAM
This example requires the application to use the large block interface because the
BLKSIZE value is so large.
OPEN finds that the block size value for the second DD is larger than for the first
DD, which normally is 80. If the second DD is for a disk data set, its maximum
block size is 32 760. BSAM OPEN for the first DD uses the BLKSIZE from the third
DD because it is the largest.
Concatenating Unlike Data Sets
To concatenate unlike sequential data sets, you must modify the DCBOFLGS field
of the DCB before the end of the current data set is reached. This informs the
system that you are concatenating unlike data sets.
DCBOFPPC is bit 4 of the DCBOFLGS field. Set bit 4, DCBOFPPC, to 1 by using
the instruction OI DCBOFLGS,X'08'. If DCBOFPPC is 1, end-of-volume processing
for each data set issues a close for the data set just read, and an open for the next
concatenated data set. This closing and opening procedure updates the fields in the
DCB and, performs the other functions of CLOSE and OPEN. If the buffer pool
was obtained automatically by the open routine, the procedure also frees the buffer
pool and obtains a new one for the next concatenated data set. The procedure does
not free the buffer pool for the last concatenated data set unless your program
supplied a DCBE with RMODE31=BUFF.
Unless you have some way of determining the characteristics of the next data set
before it is opened, you should not reset the DCBOFLGS field to indicate like
attributes during processing. When you concatenate data sets with unlike attributes
(that is, turn on the DCBOFPPC bit of the DCBOFLGS field), the EOV exit is not
taken for the first volume of any data set. If the program has a DCB OPEN exit it
is called at the beginning of every data set in the concatenation.
If your program turns DCBOFPPC on before issuing OPEN, each time the system
calls your DCB OPEN exit routine or JFCBE exit, DCBESLBI in your DCBE is on
390
z/OS V1R6.0 DFSMS: Using Data Sets
Processing a Sequential Data Set
only if the current data set being started supports large block interface (LBI). If you
want to know in advance if all the data sets support LBI, your program can take
one of the following actions:
v Leave DCBOFPPC off until after OPEN. You do not need it on until your
program attempts to read a record.
v Issue the DEVTYPE macro with INFO=AMCAP. See z/OS DFSMSdfp Advanced
Services.
When a new data set is reached and DCBOFPPC is on, you must reissue the GET
or READ macro that detected the end of the data set because with QSAM, the new
data set can have a longer record length, or with BSAM the new data set can have
a larger block size. You might need to allocate larger buffers. Figure 70 shows a
possible routine for determining when a GET or READ must be reissued.
PROBPROG
DCBEXIT
Open
Set Reread
Switch On
Set Reread
Switch Off
Set Bit 4
of OFLGS
to 1
Return to
Open *
Read and
CHECK
or GET
Reread
Switch
On
Set Reread
Switch Off
Off
Process
*Return is to control program
address in register 14
Figure 70. Reissuing a READ or GET for Unlike Concatenated Data Sets
You might need to take special precautions if the program issues multiple READ
macros without intervening CHECK or WAIT macros for those READS. Do not
issue WAIT or CHECK macros to READ requests that were issued after the READ
that detected end-of-data. These restrictions do not apply to data set to data set
transition of like data sets, because no OPEN or CLOSE operation is necessary
between data sets.
You can code OPTCD=B in the DD statement, or you can code it for dynamic
allocation. You cannot code OPTCD=B in the DCB macro. This parameter has an
effect only during the reading of IBM, ISO, or ANSI standard labelled tapes. In
those cases, it causes the system to treat the portion of the data set on each tape
volume as a complete data set.
In this way, you can read tapes in which the trailer labels incorrectly are
end-of-data instead of end-of-volume.
Chapter 25. Processing Sequential Data Sets
391
Processing a Sequential Data Set
If you specify OPTCD=B in the DD statement for a multivolume tape data set, the
system generates the equivalent of individual concatenated DD statements for each
volume serial number and allocates one tape drive for each volume.
Restriction: If you have a variable-blocked spanned (VBS) data set that spans
volumes in such a way that one segment (for example, the first segment) is at the
end of the first volume and the next segment (for example, the middle segment) is
at the beginning of the next volume, and you attempt to treat these volumes as
separate data sets, the integrity of the data cannot be guaranteed. QSAM will
abend. QSAM’s job is to ensure that it can put all of the segments together. This
restriction will also be based on the data and whether the segments are split up
between volumes.
Modifying Sequential Data Sets
You can modify a sequential data set in three ways:
v By changing the data in existing records (update-in-place).
v By adding new records to the end of a data set (extends the data set).
v Or, by opening for OUTPUT or OUTIN without DISP=MOD (replaces the data
set’s contents). The effect is the same as when creating the data set.
Related reading: See “Creating a Sequential Data Set” on page 383.
Updating in Place
When you update a data set in place, you read, process, and write records back to
their original positions without destroying the remaining records on the track. The
following rules apply:
v You must specify the UPDAT option in the OPEN macro to update the data set.
To perform the update, you can use only the READ, WRITE, CHECK, NOTE,
and POINT macros or you use only GET and PUTX macros. To use PUTX, code
MACRF=(GL,PL) on the DCB macro.
v You cannot delete any record or change its length.
v You cannot add new records.
v The data set must be on a DASD.
v You must rewrite blocks in the same order in which you read them.
A record must be retrieved by a READ or GET macro before it can be updated by
a WRITE or PUTX macro. A WRITE or PUTX macro does not need to be issued
after each READ or GET macro.
The READ and WRITE macros must be execute forms that refer to the same data
event control block (DECB). The DECB must be provided by the list forms of the
READ or WRITE macros.
Restriction: You cannot use the UPDAT option to open a compressed-format data
set, so an update-in-place is not allowed on it.
Related reading: See z/OS DFSMS Macro Instructions for Data Sets for information
about the execute and list forms of the READ and WRITE macros.
Using Overlapped Operations
To overlap I/O and processor activity, you can start several BSAM read or write
operations before checking the first operation for completion. You cannot overlap
392
z/OS V1R6.0 DFSMS: Using Data Sets
Processing a Sequential Data Set
read with write operations, however, because operations of one type must be
checked for completion before operations of the other type are started or resumed.
Note that each pending read or write operation requires a separate DECB. If a
single DECB were used for successive read operations, only the last record read
could be updated.
Related reading: See Figure 84 on page 428 for an example of an ">